From eec328651a773d6f35f97af79afb7fe3fb5965b8 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 14 Jun 2024 15:59:32 +0100 Subject: [PATCH] Update top level documentation pages for style consistency (#5754) This commit changes the top level pages of documentation to adhere with newer style guide conventions. * Horizontal rules at the end of sections * Sentence case for page titles and headings * Note formatting * Link introduction phrasing Co-authored-by: Venktesh Shivam Patel --- docs/content/overview/about.md | 2 + docs/content/overview/product-telemetry.md | 13 +++ docs/content/technical-specifications.md | 2 + docs/content/usage-reporting.md | 110 +++++++++++++++++++++ 4 files changed, 127 insertions(+) diff --git a/docs/content/overview/about.md b/docs/content/overview/about.md index 51415a7a82..c10f45d0f3 100644 --- a/docs/content/overview/about.md +++ b/docs/content/overview/about.md @@ -10,6 +10,8 @@ This document describes the F5 NGINX Ingress Controller, an Ingress Controller i --- +--- + NGINX Ingress Controller is an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}) implementation for NGINX and NGINX Plus that can load balance Websocket, gRPC, TCP and UDP applications. It supports standard [Ingress]({{< relref "glossary.md#ingress">}}) features such as content-based routing and TLS/SSL termination. Several NGINX and NGINX Plus features are available as extensions to Ingress resources through [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) and the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) resource. NGINX Ingress Controller supports the [VirtualServer and VirtualServerRoute resources]({{< relref "configuration/virtualserver-and-virtualserverroute-resources">}}) as alternatives to Ingress, enabling traffic splitting and advanced content-based routing. It also supports TCP, UDP and TLS Passthrough load balancing using [TransportServer resources]({{< relref "configuration/transportserver-resource">}}). diff --git a/docs/content/overview/product-telemetry.md b/docs/content/overview/product-telemetry.md index 39c92802c2..08cdbd3aba 100644 --- a/docs/content/overview/product-telemetry.md +++ b/docs/content/overview/product-telemetry.md @@ -1,15 +1,20 @@ --- title: Product telemetry +title: Product telemetry toc: true weight: 500 --- Learn why, what and how F5 NGINX Ingress Controller collects telemetry. +--- +Learn why, what and how F5 NGINX Ingress Controller collects telemetry. + --- ## Overview +NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users. This data is used to triage development work, prioritizing features and functionality that will benefit the most people. NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users. This data is used to triage development work, prioritizing features and functionality that will benefit the most people. Product telemetry is enabled by default, collected once every 24 hours. It's then sent to a service managed by F5 over HTTPS. @@ -17,7 +22,11 @@ Product telemetry is enabled by default, collected once every 24 hours. It's the {{< note >}} If you would prefer not to send any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller. {{< /note >}} --- +{{< note >}} If you would prefer not to send any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller. {{< /note >}} +--- + +## Data collected ## Data collected These are the data points collected and reported by NGINX Ingress Controller: @@ -60,6 +69,8 @@ These are the data points collected and reported by NGINX Ingress Controller: --- +--- + ## Opt out Product telemetry can be disabled when installing NGINX Ingress Controller. @@ -76,6 +87,8 @@ helm upgrade --install ... --set controller.telemetryReporting.enable=false --- +--- + ### Manifests When installing NGINX Ingress Controller with Manifests, set the `-enable-telemetry-reporting` flag to `false` diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 901f485b9d..4249620c68 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -72,6 +72,8 @@ _NGINX Plus images include NGINX Plus R32._ --- +--- + #### **F5 Container registry** NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Get the NGINX Ingress Controller image with JWT]({{}}) and [Get the F5 Registry NGINX Ingress Controller image]({{}}) topics. diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index ab1934ec2b..d8df156ebf 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -3,12 +3,16 @@ docs: DOCS-1445 doctypes: - concept title: Enable Usage Reporting +title: Enable Usage Reporting toc: true weight: 1800 --- This page describes how to enable Usage Reporting for F5 NGINX Ingress Controller and how to view usage data through the API. +--- +This page describes how to enable Usage Reporting for F5 NGINX Ingress Controller and how to view usage data through the API. + --- ## Overview @@ -17,6 +21,9 @@ Usage Reporting is a Kubernetes controller that connects to the NGINX Management To use Usage Reporting, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.f5.com/products/nginx/instance-manager/). Usage Reporting is a requirement of the new Flexible Consumption Program for NGINX Ingress Controller. +--- +To use Usage Reporting, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.f5.com/products/nginx/instance-manager/). Usage Reporting is a requirement of the new Flexible Consumption Program for NGINX Ingress Controller. + --- ## Requirements @@ -36,6 +43,9 @@ In addition to the software requirements, you will need: --- +## Add a user account to NGINX Management Suite +--- + ## Add a user account to NGINX Management Suite Usage Reporting needs a user account to send usage data to NGINX Instance Manager: these are the steps involved. @@ -48,17 +58,29 @@ Usage Reporting needs a user account to send usage data to NGINX Instance Manage 1. Create a user account following the steps in [Add Users](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#add-users) section of the NGINX Management Suite documentation. In step 6, assign the user to the role created above. Note that currently only "basic auth" authentication is supported for usage reporting purposes. --- +1. Create a user account following the steps in [Add Users](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#add-users) section of the NGINX Management Suite documentation. In step 6, assign the user to the role created above. Note that currently only "basic auth" authentication is supported for usage reporting purposes. +--- + +## Deploy Usage Reporting ## Deploy Usage Reporting +### Create a namespace ### Create a namespace +Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: ```shell kubectl create namespace nginx-cluster-connector ``` + ```shell + kubectl create namespace nginx-cluster-connector + ``` + +--- +### Pass the credential to the NGINX Management Suite API --- ### Pass the credential to the NGINX Management Suite API @@ -67,8 +89,19 @@ To make the credential available to Usage Reporting, create a Kubernetes secret. Both the username and password are stored in the Kubernetes Secret and need to be converted to base64. In this example the username will be `foo` and the password will be `bar`. +To obtain the base64 representation of a string, use the following command: +To make the credential available to Usage Reporting, create a Kubernetes secret. The username and password created in the previous section are required to connect the NGINX Management Suite API. + +Both the username and password are stored in the Kubernetes Secret and need to be converted to base64. In this example the username will be `foo` and the password will be `bar`. + To obtain the base64 representation of a string, use the following command: +```shell +echo -n 'foo' | base64 +# Zm9v +echo -n 'bar' | base64 +# YmFy +``` ```shell echo -n 'foo' | base64 # Zm9v @@ -76,8 +109,20 @@ echo -n 'bar' | base64 # YmFy ``` +Add the following content to a text editor, and insert the base64 representations of the username and password (Obtained in the previous step) to the `data` parameter: Add the following content to a text editor, and insert the base64 representations of the username and password (Obtained in the previous step) to the `data` parameter: +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: nms-basic-auth + namespace: nginx-cluster-connector +type: kubernetes.io/basic-auth +data: + username: Zm9v # base64 representation of 'foo' + password: YmFy # base64 representation of 'bar' +``` ```yaml apiVersion: v1 kind: Secret @@ -99,7 +144,19 @@ If you are using a different namespace, change the namespace in the `metadata` s --- ### Deploy the Kubernetes secret to the Kubernetes cluster +Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` (The default namespace) and the secret name is `nms-basic-auth`. +If you are using a different namespace, change the namespace in the `metadata` section of the file above. + +{{< note >}} Usage Reporting only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. {{< /note >}} + +--- + +### Deploy the Kubernetes secret to the Kubernetes cluster + +```shell +kubectl apply -f nms-basic-auth.yaml +``` ```shell kubectl apply -f nms-basic-auth.yaml ``` @@ -108,6 +165,11 @@ If you need to update the basic-auth credentials for NGINX Management Suite in t Download and save the deployment file [cluster-connector.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v{{< nic-version >}}/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: +```yaml + args: + - -nms-server-address=https://nms.example.com/api/platform/v1 + - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth +``` ```yaml args: - -nms-server-address=https://nms.example.com/api/platform/v1 @@ -121,6 +183,7 @@ Download and save the deployment file [cluster-connector.yaml](https://raw.githu It can be created with the command `oc create -f scc.yaml`, using the file found in `shared-examples/` {{< /note >}} +For more information, read the [Command-line arguments](#command-line-arguments) section of this page. For more information, read the [Command-line arguments](#command-line-arguments) section of this page. --- @@ -128,22 +191,37 @@ For more information, read the [Command-line arguments](#command-line-arguments) ### Finish deployment To deploy Usage Reporting, run the following command to deploy it to your Kubernetes cluster: +--- + +### Finish deployment +To deploy Usage Reporting, run the following command to deploy it to your Kubernetes cluster: + +```shell +kubectl apply -f cluster-connector.yaml +``` ```shell kubectl apply -f cluster-connector.yaml ``` --- +## Viewing usage data from the NGINX Management Suite API +--- + ## Viewing usage data from the NGINX Management Suite API Usage Reporting sends the number of NGINX Ingress Controller instances and nodes in the cluster to NGINX Management Suite. To view the usage data, query the NGINX Management Suite API. The usage data is available at the following endpoint: +```shell + ```shell curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage ``` ```json +``` +```json { "items": [ { @@ -198,12 +276,16 @@ curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage If you want a friendly name for each cluster in the response, You can specify the `displayName` for the cluster with the `-cluster-display-name` command-line argument when you deploy Usage Reporting. In the response, you can see the cluster `uid` corresponding to the cluster name. For more information, read the [Command-line Arguments](#command-line-arguments) section. +You can query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: You can query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: +```shell ```shell curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 ``` ```json +``` +```json { "metadata": { "displayName": "my-cluster", @@ -231,6 +313,9 @@ curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee --- +## Uninstall Usage Reporting +--- + ## Uninstall Usage Reporting To remove Usage Reporting from your Kubernetes cluster, run the following command: @@ -242,7 +327,15 @@ kubectl delete -f cluster-connector.yaml --- ## Command-line arguments +--- + +## Command-line arguments + +Usage Reporting supports several command-line arguments, which can be specified in the `args` section of the Kubernetes deployment file. +The following is a list of the supported command-line arguments and their usage: + +--- Usage Reporting supports several command-line arguments, which can be specified in the `args` section of the Kubernetes deployment file. The following is a list of the supported command-line arguments and their usage: @@ -254,6 +347,9 @@ The following is a list of the supported command-line arguments and their usage: The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. Default: `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. +--- +Default: `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. + --- ### -nms-basic-auth-secret `` @@ -261,6 +357,9 @@ Default: `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. Format: `/`. +--- +Format: `/`. + --- ### -cluster-display-name `` @@ -269,12 +368,19 @@ The display name of the Kubernetes cluster. --- +--- + ### -skip-tls-verify Skip TLS verification for the NGINX Management Suite server. {{< warning >}} This argument is intended for using a self-assigned certificate for testing purposes only. {{< /warning >}} +--- +Skip TLS verification for the NGINX Management Suite server. + +{{< warning >}} This argument is intended for using a self-assigned certificate for testing purposes only. {{< /warning >}} + --- ### -min-update-interval `` @@ -283,3 +389,7 @@ The minimum interval between updates to the NGINX Management Suite. Default: `24h`. {{< warning >}} This argument is intended for testing purposes only. {{< /warning >}} +The minimum interval between updates to the NGINX Management Suite. +Default: `24h`. + +{{< warning >}} This argument is intended for testing purposes only. {{< /warning >}}