From b02313837aca1474692be4d5138e495cc7d36eb3 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Fri, 2 Jun 2023 16:41:34 +0100 Subject: [PATCH 01/37] Initial draft of tutorial and manifest --- deployments/deployment/cluster-connector.yaml | 132 ++++++++++++++++++ docs/content/usage-reporting.md | 128 +++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 deployments/deployment/cluster-connector.yaml create mode 100644 docs/content/usage-reporting.md diff --git a/deployments/deployment/cluster-connector.yaml b/deployments/deployment/cluster-connector.yaml new file mode 100644 index 0000000000..71aec71a08 --- /dev/null +++ b/deployments/deployment/cluster-connector.yaml @@ -0,0 +1,132 @@ +apiVersion: v1 +kind: Namespace +metadata: + name: nginx-cluster-connector +--- +apiVersion: v1 +kind: ServiceAccount +metadata: + name: nginx-cluster-connector + namespace: nginx-cluster-connector +--- +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: nginx-cluster-connector +rules: + - apiGroups: + - "" + resources: + - pods + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - secrets + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - nodes + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - namespaces + verbs: + - get + - list + - watch + - apiGroups: + - "" + resources: + - events + verbs: + - create + - patch + - list + - apiGroups: + - coordination.k8s.io + resources: + - leases + verbs: + - get + - list + - watch + - update + - create +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: nginx-cluster-connector +subjects: + - kind: ServiceAccount + name: nginx-cluster-connector + namespace: nginx-cluster-connector +roleRef: + kind: ClusterRole + name: nginx-cluster-connector + apiGroup: rbac.authorization.k8s.io +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nginx-cluster-connector + namespace: nginx-cluster-connector +spec: + replicas: 1 + selector: + matchLabels: + app: nginx-cluster-connector + template: + metadata: + labels: + app: cluster-connector + spec: + serviceAccountName: cluster-connector + automountServiceAccountToken: true + containers: + - image: nginx-cluster-connector:0.0.1 + imagePullPolicy: IfNotPresent + name: nginx-cluster-connector + resources: + requests: + cpu: "100m" + memory: "128Mi" + #limits: + # cpu: "1" + # memory: "1Gi" + securityContext: + runAsUser: 101 #nginx + runAsNonRoot: true + capabilities: + drop: + - ALL + env: + - name: POD_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + - name: POD_NAME + valueFrom: + fieldRef: + fieldPath: metadata.name + args: + - -nms-server-address=apigw.nms.svc.cluster.local + - -nms-server-port=443 + - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth + - -cluster-display-name=my-cluster +# - -v=3 +# - -skip-tls-verify +# - -min-update-interval=24h + diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md new file mode 100644 index 0000000000..10339bdf6c --- /dev/null +++ b/docs/content/usage-reporting.md @@ -0,0 +1,128 @@ +--- +title: Usage Reporting +description: | +How to enable usage reporting for NGINX Ingress Controller and how to view the usage data through the API.weight: 1800 +doctypes: ["concept"] +toc: true +docs: ["???"] +--- + + +This document outlines how to enable usage reporting for NGINX Ingress Controller and how to view the usage data through the API. + +## Overview + +The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. + +NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. + +To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). + +### Requirements + +To deploy the NGINX Cluster Connector, you must have the following: + +| Requirements | Notes | +|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | +| NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | +| Docker 23 or later | https://docs.docker.com/get-docker/ | +| Kubernetes 1.22 or later | Ensure your client can access the Kubernetes API server. | +| kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | +| OpenSSL 3.0.0 or later | For converting credentials string to base64. Alternatively, you can use any online tools available. https://www.openssl.org/source/ | + +In addition to the software requirements, you must have the following: +- Access to NGINX Management Suite with username and password for basic authentication +- Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. + +### Deploying the NGINX Cluster Connector + +1. Basic authentication is required to connect the NGINX Management Suite API. A base64 representation of the username and password is required to create the Kubernetes secret. 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: + ``` + > echo -n 'foo' | base64 + Zm9v + > echo -n 'bar' | base64 + YmFy + ``` + +2. In order to make the credential available to NGINX Cluster Connector, create a Kubernetes secret by creating a file named `nms-basic-auth.yaml` with the following content, using the base64 representation of the username and password obtained in step 1: + ``` + 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' obtained in step 1 + password: YmFy # base64 representation of 'bar' obtained in step 1 + ``` + In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. +3. If the namespace `nginx-cluster-connector` does not exist, create the namespace: + ``` + > kubectl create namespace nginx-cluster-connector + ``` +4. Deploy the Kubernetes secret: + ``` + > kubectl apply -f nms-basic-auth.yaml + ``` + To change the username and password, update the secret and apply the changes to the Kubernetes cluster. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. + +5. Download the [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the args section in `deployment.yaml` to edit the following values; + ``` + args: + - -nms-server-address=https://k8s-usage.example.com + - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth + ``` + The `nms-server-address` should be the address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. + For more information on the command-line flags, see [Configuration](#configuration). + +6. To deploy the Nginx Cluster Connector, run the following command to deploy the application to your Kubernetes cluster: + ``` + > kubectl apply -f cluster-connector.yaml + ``` + + +## Viewing Usage Data + +#TODO: instructions how to get the UUID. +``` +curl -k --user "foo:bar" https://k8s-usage.example.com/usage/{uuid} +``` + + +## Uninstall +To remove the Nginx Cluster Connector from your Kubernetes cluster, run the following command: +``` +kubectl delete -f deployment.yaml +``` + +## Cammand-line Arguments +The NGINX Cluster Connector supports several command-line arguments. +Below we describe the available command-line arguments: + +### -nms-server-address `` +The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. +Default `apigw.nms.svc.cluster.local`. + +### -nms-server-port `` +The port of the NGINX Management Suite host +Default `443`. + +### -nms-basic-auth-secret `` +Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. +Format `/`. + +### -cluster-display-name `` +The display name of the Kubernetes cluster. + +### -skip-tls-verify +Skip TLS verification for the NMS server. **For testing purposes with NMS server with self-assigned certificate.** + +### -min-update-interval `` +The minimum interval between updates to the NMS. +Default `24h`. + +### -proxy +Use a proxy server to connect to the Kubernetes API started by the "kubectl proxy" command. **For testing purposes only.** + From bfccc41e0788fa924d492db141283f7eb77ab871 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 2 Jun 2023 15:42:48 +0000 Subject: [PATCH 02/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- deployments/deployment/cluster-connector.yaml | 1 - docs/content/usage-reporting.md | 13 ++++++------- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/deployments/deployment/cluster-connector.yaml b/deployments/deployment/cluster-connector.yaml index 71aec71a08..40be717e93 100644 --- a/deployments/deployment/cluster-connector.yaml +++ b/deployments/deployment/cluster-connector.yaml @@ -129,4 +129,3 @@ spec: # - -v=3 # - -skip-tls-verify # - -min-update-interval=24h - diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 10339bdf6c..c1315c8cd1 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -12,11 +12,11 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. +The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. -To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). +To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). ### Requirements @@ -44,7 +44,7 @@ In addition to the software requirements, you must have the following: > echo -n 'bar' | base64 YmFy ``` - + 2. In order to make the credential available to NGINX Cluster Connector, create a Kubernetes secret by creating a file named `nms-basic-auth.yaml` with the following content, using the base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 @@ -57,7 +57,7 @@ In addition to the software requirements, you must have the following: username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` - In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. + In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 3. If the namespace `nginx-cluster-connector` does not exist, create the namespace: ``` > kubectl create namespace nginx-cluster-connector @@ -102,12 +102,12 @@ The NGINX Cluster Connector supports several command-line arguments. Below we describe the available command-line arguments: ### -nms-server-address `` -The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. +The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. Default `apigw.nms.svc.cluster.local`. ### -nms-server-port `` The port of the NGINX Management Suite host -Default `443`. +Default `443`. ### -nms-basic-auth-secret `` Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. @@ -125,4 +125,3 @@ Default `24h`. ### -proxy Use a proxy server to connect to the Kubernetes API started by the "kubectl proxy" command. **For testing purposes only.** - From 2c691938f7acb8e9bec512a28890c71c93ead3ea Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Fri, 2 Jun 2023 17:12:29 +0100 Subject: [PATCH 03/37] update docs --- docs/content/usage-reporting.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index c1315c8cd1..9c1cba8b70 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -12,11 +12,11 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. +The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. -To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). +To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). ### Requirements @@ -32,7 +32,7 @@ To deploy the NGINX Cluster Connector, you must have the following: | OpenSSL 3.0.0 or later | For converting credentials string to base64. Alternatively, you can use any online tools available. https://www.openssl.org/source/ | In addition to the software requirements, you must have the following: -- Access to NGINX Management Suite with username and password for basic authentication +- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password. - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. ### Deploying the NGINX Cluster Connector @@ -44,8 +44,8 @@ In addition to the software requirements, you must have the following: > echo -n 'bar' | base64 YmFy ``` - -2. In order to make the credential available to NGINX Cluster Connector, create a Kubernetes secret by creating a file named `nms-basic-auth.yaml` with the following content, using the base64 representation of the username and password obtained in step 1: + +2. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in the username and password under `data`, with base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 kind: Secret @@ -57,18 +57,18 @@ In addition to the software requirements, you must have the following: username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` - In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. + Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 3. If the namespace `nginx-cluster-connector` does not exist, create the namespace: ``` > kubectl create namespace nginx-cluster-connector ``` -4. Deploy the Kubernetes secret: +4. Deploy the Kubernetes secret created in step 2 to the Kubernetes cluster: ``` > kubectl apply -f nms-basic-auth.yaml ``` - To change the username and password, update the secret and apply the changes to the Kubernetes cluster. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. + If you want to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. -5. Download the [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the args section in `deployment.yaml` to edit the following values; +5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the following the args section: ``` args: - -nms-server-address=https://k8s-usage.example.com @@ -77,13 +77,14 @@ In addition to the software requirements, you must have the following: The `nms-server-address` should be the address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). -6. To deploy the Nginx Cluster Connector, run the following command to deploy the application to your Kubernetes cluster: +6. To deploy the Nginx Cluster Connector, save the file above and run the following command to deploy it to your Kubernetes cluster: ``` > kubectl apply -f cluster-connector.yaml ``` ## Viewing Usage Data +The NGINX Cluster Connector reports 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 in the following endpoint: #TODO: instructions how to get the UUID. ``` @@ -91,23 +92,22 @@ curl -k --user "foo:bar" https://k8s-usage.example.com/usage/{uuid} ``` -## Uninstall +## Uninstall the NGINX Cluster Connector To remove the Nginx Cluster Connector from your Kubernetes cluster, run the following command: ``` kubectl delete -f deployment.yaml ``` -## Cammand-line Arguments -The NGINX Cluster Connector supports several command-line arguments. -Below we describe the available command-line arguments: +## Command-line Arguments +The NGINX Cluster Connector supports several command-line arguments. The command-line arguments 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: ### -nms-server-address `` -The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. +The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. Default `apigw.nms.svc.cluster.local`. ### -nms-server-port `` The port of the NGINX Management Suite host -Default `443`. +Default `443`. ### -nms-basic-auth-secret `` Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. @@ -125,3 +125,4 @@ Default `24h`. ### -proxy Use a proxy server to connect to the Kubernetes API started by the "kubectl proxy" command. **For testing purposes only.** + From 9c141db30f71aaf307d82f6804df89927035595e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 2 Jun 2023 16:13:10 +0000 Subject: [PATCH 04/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/usage-reporting.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 9c1cba8b70..1e6fc71068 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -12,11 +12,11 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. +The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. -To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). +To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). ### Requirements @@ -44,7 +44,7 @@ In addition to the software requirements, you must have the following: > echo -n 'bar' | base64 YmFy ``` - + 2. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in the username and password under `data`, with base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 @@ -57,7 +57,7 @@ In addition to the software requirements, you must have the following: username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` - Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. + Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 3. If the namespace `nginx-cluster-connector` does not exist, create the namespace: ``` > kubectl create namespace nginx-cluster-connector @@ -102,12 +102,12 @@ kubectl delete -f deployment.yaml The NGINX Cluster Connector supports several command-line arguments. The command-line arguments 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: ### -nms-server-address `` -The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. +The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. Default `apigw.nms.svc.cluster.local`. ### -nms-server-port `` The port of the NGINX Management Suite host -Default `443`. +Default `443`. ### -nms-basic-auth-secret `` Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. @@ -125,4 +125,3 @@ Default `24h`. ### -proxy Use a proxy server to connect to the Kubernetes API started by the "kubectl proxy" command. **For testing purposes only.** - From e4597e63033608266b0a8003842a6d32d343c6fb Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 6 Jun 2023 11:31:01 +0100 Subject: [PATCH 05/37] update usage viewing --- docs/content/usage-reporting.md | 59 ++++++++++++++++++++++++++++++--- 1 file changed, 54 insertions(+), 5 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 1e6fc71068..46363e2b32 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -29,11 +29,11 @@ To deploy the NGINX Cluster Connector, you must have the following: | Docker 23 or later | https://docs.docker.com/get-docker/ | | Kubernetes 1.22 or later | Ensure your client can access the Kubernetes API server. | | kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | -| OpenSSL 3.0.0 or later | For converting credentials string to base64. Alternatively, you can use any online tools available. https://www.openssl.org/source/ | In addition to the software requirements, you must have the following: -- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password. +- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/k8s-usage` endpoints - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. +- The Kubernetes cluster should have access to the NGINX container registry where the NGINX Cluster Connector image is hosted at `registry.nginx.com/nginx-cluster-connector`. Alternatively, you can pull this down and push the image to a private container registry that your cluster has access to. ### Deploying the NGINX Cluster Connector @@ -71,7 +71,7 @@ In addition to the software requirements, you must have the following: 5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the following the args section: ``` args: - - -nms-server-address=https://k8s-usage.example.com + - -nms-server-address=https://nms.example.com - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` The `nms-server-address` should be the address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. @@ -86,9 +86,58 @@ In addition to the software requirements, you must have the following: ## Viewing Usage Data The NGINX Cluster Connector reports 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 in the following endpoint: -#TODO: instructions how to get the UUID. ``` -curl -k --user "foo:bar" https://k8s-usage.example.com/usage/{uuid} +curl -k --user "foo:bar" https://nms.example.com/k8s-usage/ +{ + "items": [ + { + "metadata": { + "displayName": "my-cluster", + "uid": "d290f1ee-6c54-4b01-90e6-d701748f0851", + "createTime": "2023-01-27T09:12:33.001Z", + "updateTime": "2023-01-29T10:12:33.001Z", + "monthReturned": "May" + }, + "node_count": 4, + "max_node_count": 5, + "pod_details": { + "current_pod_counts": { + "pod_count": 15, + "waf_count": 5, + "dos_count": 0 + }, + "max_pod_counts": { + "max_pod_count": 25, + "max_waf_count": 7, + "max_dos_count": 1 + } + } + }, + { + "metadata": { + "displayName": "my-cluster2", + "uid": "12tgb8ug-g8ik-bs7h-gj3j-hjitk672946hb", + "createTime": "2023-01-25T09:12:33.001Z", + "updateTime": "2023-01-26T10:12:33.001Z", + "monthReturned": "May" + }, + "node_count": 3, + "max_node_count": 3, + "pod_details": { + "current_pod_counts": { + "pod_count": 5, + "waf_count": 5, + "dos_count": 0 + }, + "max_pod_counts": { + "max_pod_count": 15, + "max_waf_count": 5, + "max_dos_count": 0 + } + } + } + ] +} ``` From 4c5762bf049a24257f56c744600275ecdb798c5c Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 6 Jun 2023 13:23:58 +0100 Subject: [PATCH 06/37] update usage viewing --- docs/content/usage-reporting.md | 59 +++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 46363e2b32..cf33b65b94 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -22,22 +22,33 @@ To use the NGINX Cluster Connector, you must have access to NGINX Management Sui To deploy the NGINX Cluster Connector, you must have the following: -| Requirements | Notes | -|-----------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| -| NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | -| NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | -| Docker 23 or later | https://docs.docker.com/get-docker/ | -| Kubernetes 1.22 or later | Ensure your client can access the Kubernetes API server. | -| kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | +| Requirements | Notes | +|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------| +| NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | +| NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | +| Docker 23 or later | https://docs.docker.com/get-docker/ | +| Kubernetes 1.22 or later | Ensure you can access the Kubernetes API, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. | +| kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | In addition to the software requirements, you must have the following: - Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/k8s-usage` endpoints - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. - The Kubernetes cluster should have access to the NGINX container registry where the NGINX Cluster Connector image is hosted at `registry.nginx.com/nginx-cluster-connector`. Alternatively, you can pull this down and push the image to a private container registry that your cluster has access to. +### Setting up user accounts in NGINX Management Suite + +The NGINX Cluster Connector uses the NGINX Management Suite API to report the number of NGINX Ingress Controller nodes in the cluster. To use the NGINX Management Suite API, you must have a user account with the correct role. + +1. Create a role following the steps in [Create a Role](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#create-role) section of the NGINX Management Suite documentation. Select these permissions in step 6 for the role: + - Module: Instance Manager + - Feature: Nginx Plus Usage + - Access: CRUD + +2. 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. + ### Deploying the NGINX Cluster Connector -1. Basic authentication is required to connect the NGINX Management Suite API. A base64 representation of the username and password is required to create the Kubernetes secret. 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: +1. Basic authentication is required to connect the NGINX Management Suite API. If you do not have a user account, create one following the above section . A base64 representation of the username and password is required to create the Kubernetes secret. 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: ``` > echo -n 'foo' | base64 Zm9v @@ -83,11 +94,11 @@ In addition to the software requirements, you must have the following: ``` -## Viewing Usage Data +## Viewing Usage Data from the NGINX Management Suite API The NGINX Cluster Connector reports 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 in the following endpoint: ``` -curl -k --user "foo:bar" https://nms.example.com/k8s-usage/ +> curl -k --user "foo:bar" https://nms.example.com/k8s-usage/ { "items": [ { @@ -139,7 +150,35 @@ curl -k --user "foo:bar" https://nms.example.com/k8s-usage/ ] } ``` +You can specify `displayName` for the cluster in the response with the `-cluster-display-name` command-line argument when you deploy the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. +You can also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: +``` +> curl -k --user "foo:bar" https://nms.example.com/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 +{ + "metadata": { + "displayName": "my-cluster", + "uid": "d290f1ee-6c54-4b01-90e6-d701748f0851", + "createTime": "2023-01-27T09:12:33.001Z", + "updateTime": "2023-01-29T10:12:33.001Z", + "monthReturned": "May" + }, + "node_count": 4, + "max_node_count": 5, + "pod_details": { + "current_pod_counts": { + "pod_count": 15, + "waf_count": 5, + "dos_count": 0 + }, + "max_pod_counts": { + "max_pod_count": 25, + "max_waf_count": 7, + "max_dos_count": 1 + } + } +} +``` ## Uninstall the NGINX Cluster Connector To remove the Nginx Cluster Connector from your Kubernetes cluster, run the following command: From 0a66abf0d5ba4e6b1fa67b38427ad7f27fcd6875 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 7 Jun 2023 13:40:56 +0100 Subject: [PATCH 07/37] update docs --- docs/content/usage-reporting.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index cf33b65b94..b02a84bfe1 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -12,13 +12,13 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. +The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). -### Requirements +## Requirements To deploy the NGINX Cluster Connector, you must have the following: @@ -31,11 +31,12 @@ To deploy the NGINX Cluster Connector, you must have the following: | kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | In addition to the software requirements, you must have the following: -- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/k8s-usage` endpoints -- Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. -- The Kubernetes cluster should have access to the NGINX container registry where the NGINX Cluster Connector image is hosted at `registry.nginx.com/nginx-cluster-connector`. Alternatively, you can pull this down and push the image to a private container registry that your cluster has access to. +- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/api/platform/v1/k8s-usage` endpoints +- Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. +- Access to public internet to pull the image, since the image is hosted in the NGINX container registry at `registry.nginx.com/cluster-connector`. Alternatively, you can pull the image down and push it to a private container registry that your cluster has access to. +[//]: # ( TODO: Update the image and tag after published) -### Setting up user accounts in NGINX Management Suite +## Setting up user accounts in NGINX Management Suite The NGINX Cluster Connector uses the NGINX Management Suite API to report the number of NGINX Ingress Controller nodes in the cluster. To use the NGINX Management Suite API, you must have a user account with the correct role. @@ -46,7 +47,7 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu 2. 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. -### Deploying the NGINX Cluster Connector +## Deploying the NGINX Cluster Connector 1. Basic authentication is required to connect the NGINX Management Suite API. If you do not have a user account, create one following the above section . A base64 representation of the username and password is required to create the Kubernetes secret. 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: ``` @@ -79,13 +80,13 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu ``` If you want to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. -5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the following the args section: +5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the following under `args` section ``` args: - - -nms-server-address=https://nms.example.com + - -nms-server-address=https://nms.example.com/api/platform/v1/k8s-usage - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` - The `nms-server-address` should be the address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. + The `-nms-server-address` should be the address of the NGINX Management Suite host. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). 6. To deploy the Nginx Cluster Connector, save the file above and run the following command to deploy it to your Kubernetes cluster: @@ -98,7 +99,7 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu The NGINX Cluster Connector reports 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 in the following endpoint: ``` -> curl -k --user "foo:bar" https://nms.example.com/k8s-usage/ +> curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage { "items": [ { @@ -150,11 +151,11 @@ The NGINX Cluster Connector reports the number of NGINX Ingress Controller insta ] } ``` -You can specify `displayName` for the cluster in the response with the `-cluster-display-name` command-line argument when you deploy the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. +You can specify `displayName` for the cluster in the response with the `-cluster-display-name` command-line argument when you deploy the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. You can also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: ``` -> curl -k --user "foo:bar" https://nms.example.com/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 +> curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 { "metadata": { "displayName": "my-cluster", @@ -180,10 +181,10 @@ You can also query the usage data for a specific cluster by specifying the clust } ``` -## Uninstall the NGINX Cluster Connector +## Uninstalling the NGINX Cluster Connector To remove the Nginx Cluster Connector from your Kubernetes cluster, run the following command: ``` -kubectl delete -f deployment.yaml +kubectl delete -f cluster-connector.yaml ``` ## Command-line Arguments From 53443463d065f7182b832c51aaa98184cf61f864 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 7 Jun 2023 13:45:06 +0100 Subject: [PATCH 08/37] Update docs/content/usage-reporting.md Co-authored-by: Alan Dooley Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index b02a84bfe1..1e9f0d0269 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -1,7 +1,8 @@ --- title: Usage Reporting description: | -How to enable usage reporting for NGINX Ingress Controller and how to view the usage data through the API.weight: 1800 +How to enable usage reporting for NGINX Ingress Controller and view the usage data through the API. +weight: 1800 doctypes: ["concept"] toc: true docs: ["???"] From a7949efb9128805111d874482b0a8128554d1680 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 7 Jun 2023 13:45:19 +0100 Subject: [PATCH 09/37] Update docs/content/usage-reporting.md Co-authored-by: Alan Dooley Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 1e9f0d0269..0d66a1b5de 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -21,7 +21,7 @@ To use the NGINX Cluster Connector, you must have access to NGINX Management Sui ## Requirements -To deploy the NGINX Cluster Connector, you must have the following: +To deploy Usage Reporting, you must have the following: | Requirements | Notes | |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------| From 7b57526b05a33c026bdc0c4a58a6756ccff5cb8f Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 7 Jun 2023 13:45:37 +0100 Subject: [PATCH 10/37] Update docs/content/usage-reporting.md Co-authored-by: Alan Dooley Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 0d66a1b5de..dd648d4858 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -5,7 +5,6 @@ How to enable usage reporting for NGINX Ingress Controller and view the usage da weight: 1800 doctypes: ["concept"] toc: true -docs: ["???"] --- From 8d8f4976a660b7fcf448d41c50e5991fcc37ccaa Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 7 Jun 2023 16:48:43 +0100 Subject: [PATCH 11/37] move fcp manifest --- docs/content/usage-reporting.md | 2 +- .../shared-examples/usage-reporting}/cluster-connector.yaml | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename {deployments/deployment => examples/shared-examples/usage-reporting}/cluster-connector.yaml (100%) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index dd648d4858..9f4bc1e399 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -80,7 +80,7 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu ``` If you want to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. -5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/deployments/deployment/cluster-connector.yaml). Edit the following under `args` section +5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under `args` section ``` args: - -nms-server-address=https://nms.example.com/api/platform/v1/k8s-usage diff --git a/deployments/deployment/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml similarity index 100% rename from deployments/deployment/cluster-connector.yaml rename to examples/shared-examples/usage-reporting/cluster-connector.yaml From f74746ad2095b86e8446f360843441808da4ca01 Mon Sep 17 00:00:00 2001 From: Brian Ehlert Date: Wed, 7 Jun 2023 13:19:38 -0700 Subject: [PATCH 12/37] Update usage-reporting.md Signed-off-by: Brian Ehlert --- docs/content/usage-reporting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 9f4bc1e399..e6b4a3c68b 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -5,6 +5,7 @@ How to enable usage reporting for NGINX Ingress Controller and view the usage da weight: 1800 doctypes: ["concept"] toc: true +docs: "DOCS- --- From e3c06410334ff6c9d8613ce598b658a0ecaaf5c7 Mon Sep 17 00:00:00 2001 From: Brian Ehlert Date: Wed, 7 Jun 2023 13:22:28 -0700 Subject: [PATCH 13/37] Update usage-reporting.md Signed-off-by: Brian Ehlert --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index e6b4a3c68b..414721f840 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -5,7 +5,7 @@ How to enable usage reporting for NGINX Ingress Controller and view the usage da weight: 1800 doctypes: ["concept"] toc: true -docs: "DOCS- +docs: "DOCS-1228 --- From ffec999566ece2d1470a392981f5fdb939eed3a5 Mon Sep 17 00:00:00 2001 From: Brian Ehlert Date: Wed, 7 Jun 2023 13:44:32 -0700 Subject: [PATCH 14/37] Update usage-reporting.md Signed-off-by: Brian Ehlert --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 414721f840..192e08a6e9 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -5,7 +5,7 @@ How to enable usage reporting for NGINX Ingress Controller and view the usage da weight: 1800 doctypes: ["concept"] toc: true -docs: "DOCS-1228 +docs: "DOCS-1228" --- From 9328fd4403c3baf2f60ec811c4e607143cb1e801 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Thu, 8 Jun 2023 12:59:13 +0100 Subject: [PATCH 15/37] update docs according to feedback --- docs/content/usage-reporting.md | 33 ++++++++----------- .../usage-reporting/cluster-connector.yaml | 2 +- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 192e08a6e9..b27ef6d270 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -27,19 +27,17 @@ To deploy Usage Reporting, you must have the following: |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | | NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | -| Docker 23 or later | https://docs.docker.com/get-docker/ | | Kubernetes 1.22 or later | Ensure you can access the Kubernetes API, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. | -| kubectl 1.22 or later | https://kubernetes.io/docs/tasks/tools/#kubectl | In addition to the software requirements, you must have the following: - Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/api/platform/v1/k8s-usage` endpoints - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. -- Access to public internet to pull the image, since the image is hosted in the NGINX container registry at `registry.nginx.com/cluster-connector`. Alternatively, you can pull the image down and push it to a private container registry that your cluster has access to. +- Access to public internet to pull the image, since the image is hosted in the NGINX container registry at `public-registry.nginx.com/cluster-connector`. Alternatively, you can pull the image down and push it to a private container registry that your cluster has access to. [//]: # ( TODO: Update the image and tag after published) ## Setting up user accounts in NGINX Management Suite -The NGINX Cluster Connector uses the NGINX Management Suite API to report the number of NGINX Ingress Controller nodes in the cluster. To use the NGINX Management Suite API, you must have a user account with the correct role. +The cluster connector needs a user account to send usage data to NIM. This is how you create one for the Cluster Connector to use. 1. Create a role following the steps in [Create a Role](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#create-role) section of the NGINX Management Suite documentation. Select these permissions in step 6 for the role: - Module: Instance Manager @@ -50,7 +48,7 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu ## Deploying the NGINX Cluster Connector -1. Basic authentication is required to connect the NGINX Management Suite API. If you do not have a user account, create one following the above section . A base64 representation of the username and password is required to create the Kubernetes secret. 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: +1. 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 as 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: ``` > echo -n 'foo' | base64 Zm9v @@ -58,7 +56,11 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu YmFy ``` -2. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in the username and password under `data`, with base64 representation of the username and password obtained in step 1: +2. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: + ``` + > kubectl create namespace nginx-cluster-connector + ``` +3. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in the username and password under `data`, with base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 kind: Secret @@ -71,26 +73,22 @@ The NGINX Cluster Connector uses the NGINX Management Suite API to report the nu password: YmFy # base64 representation of 'bar' obtained in step 1 ``` Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. -3. If the namespace `nginx-cluster-connector` does not exist, create the namespace: - ``` - > kubectl create namespace nginx-cluster-connector - ``` 4. Deploy the Kubernetes secret created in step 2 to the Kubernetes cluster: ``` > kubectl apply -f nms-basic-auth.yaml ``` If you want to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. -5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under `args` section +5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under `args` section and then save the file: ``` args: - - -nms-server-address=https://nms.example.com/api/platform/v1/k8s-usage + - -nms-server-address=https://nms.example.com/api/platform/v1 - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` The `-nms-server-address` should be the address of the NGINX Management Suite host. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). -6. To deploy the Nginx Cluster Connector, save the file above and run the following command to deploy it to your Kubernetes cluster: +6. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: ``` > kubectl apply -f cluster-connector.yaml ``` @@ -152,7 +150,7 @@ The NGINX Cluster Connector reports the number of NGINX Ingress Controller insta ] } ``` -You can specify `displayName` for the cluster in the response with the `-cluster-display-name` command-line argument when you deploy the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. +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 the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. You can also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: ``` @@ -207,11 +205,8 @@ Format `/`. The display name of the Kubernetes cluster. ### -skip-tls-verify -Skip TLS verification for the NMS server. **For testing purposes with NMS server with self-assigned certificate.** +Skip TLS verification for the NMS server. **For testing purposes with NMS server using self-assigned certificate.** ### -min-update-interval `` The minimum interval between updates to the NMS. -Default `24h`. - -### -proxy -Use a proxy server to connect to the Kubernetes API started by the "kubectl proxy" command. **For testing purposes only.** +Default `24h`. \ No newline at end of file diff --git a/examples/shared-examples/usage-reporting/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml index 40be717e93..f9331954ab 100644 --- a/examples/shared-examples/usage-reporting/cluster-connector.yaml +++ b/examples/shared-examples/usage-reporting/cluster-connector.yaml @@ -96,7 +96,7 @@ spec: serviceAccountName: cluster-connector automountServiceAccountToken: true containers: - - image: nginx-cluster-connector:0.0.1 + - image: public-registry.nginx.com/cluster-connector:0.0.1 #TODO: update with correct image tag after publishing imagePullPolicy: IfNotPresent name: nginx-cluster-connector resources: From e7e39614fda6265ccb9a9dad90d465ea72f92327 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Jun 2023 11:59:36 +0000 Subject: [PATCH 16/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index b27ef6d270..1c817d0373 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -209,4 +209,4 @@ Skip TLS verification for the NMS server. **For testing purposes with NMS server ### -min-update-interval `` The minimum interval between updates to the NMS. -Default `24h`. \ No newline at end of file +Default `24h`. From 371d77ec511f5e9562f4526962c755e3dd9035ff Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Thu, 8 Jun 2023 13:05:35 +0100 Subject: [PATCH 17/37] update phrasing --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 1c817d0373..bbecc46054 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -60,7 +60,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho ``` > kubectl create namespace nginx-cluster-connector ``` -3. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in the username and password under `data`, with base64 representation of the username and password obtained in step 1: +3. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 kind: Secret From bfce49a5bf6982c1a0618e122080502813ad85c9 Mon Sep 17 00:00:00 2001 From: Brian Ehlert Date: Thu, 8 Jun 2023 12:00:06 -0700 Subject: [PATCH 18/37] Update usage-reporting.md edited rather than going back and forth Signed-off-by: Brian Ehlert --- docs/content/usage-reporting.md | 50 ++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 19 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index bbecc46054..68c8f36841 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -13,11 +13,11 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -The Flexible Consumption Program (FCP) is a new pricing offer for NGINX Ingress Controller. The pricing model is based on the number of NGINX Ingress Controller instances in a cluster. The number is reported to NGINX Management Suite, which is used to calculate the license cost. +As a requirement for the Flexible Consumption Program (FCP) licensing option, there is a requirement to track the deployments of NGINX Ingress Controller according to the pricing dimensions of the program. The NGINX Management Suite is used as a data aggregation point for the reporting component called the cluster connector. -NGINX Cluster Connector is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster where NGINX Ingress Controller is deployed. +NGINX Cluster Connector is a Kubernetes controller that sends reporting data to the NGINX Management Suite. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster(s) where NGINX Ingress Controller is deployed. -To use the NGINX Cluster Connector, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). +To use the NGINX Cluster Connector, you must have NGINX Management Suite installed and running in your data center. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). The NGINX Management Suite component is included in your subscription and should be available to download through your MyF5.com account. ## Requirements @@ -30,9 +30,9 @@ To deploy Usage Reporting, you must have the following: | Kubernetes 1.22 or later | Ensure you can access the Kubernetes API, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. | In addition to the software requirements, you must have the following: -- Access to NGINX Management Suite with username and password for basic authentication, including the URL, username, and password, with the access to the `/api/platform/v1/k8s-usage` endpoints +- Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. -- Access to public internet to pull the image, since the image is hosted in the NGINX container registry at `public-registry.nginx.com/cluster-connector`. Alternatively, you can pull the image down and push it to a private container registry that your cluster has access to. +- Access to public internet to pull the cluster connector image. This image is hosted in the NGINX container registry at `public-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. [//]: # ( TODO: Update the image and tag after published) ## Setting up user accounts in NGINX Management Suite @@ -44,11 +44,22 @@ The cluster connector needs a user account to send usage data to NIM. This is ho - Feature: Nginx Plus Usage - Access: CRUD -2. 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. +2. 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. ## Deploying the NGINX Cluster Connector -1. 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 as 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: +### Define a namespace + +3. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: + ``` + > kubectl create namespace nginx-cluster-connector + ``` + +### Define the credential for the NIM API + +In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. + +4. 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: ``` > echo -n 'foo' | base64 Zm9v @@ -56,11 +67,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho YmFy ``` -2. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: - ``` - > kubectl create namespace nginx-cluster-connector - ``` -3. In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 1: +5. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 1: ``` apiVersion: v1 kind: Secret @@ -72,23 +79,28 @@ The cluster connector needs a user account to send usage data to NIM. This is ho username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` - Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. -4. Deploy the Kubernetes secret created in step 2 to the Kubernetes cluster: +Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. + +If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. + +6. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: ``` > kubectl apply -f nms-basic-auth.yaml ``` - If you want to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. -5. Download the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under `args` section and then save the file: +If you need to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. + +7. Download and save the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: ``` args: - -nms-server-address=https://nms.example.com/api/platform/v1 - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` - The `-nms-server-address` should be the address of the NGINX Management Suite host. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. - For more information on the command-line flags, see [Configuration](#configuration). -6. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: +The `-nms-server-address` should be the address of the NGINX Management Suite host. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. +For more information on the command-line flags, see [Configuration](#configuration). + +8. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: ``` > kubectl apply -f cluster-connector.yaml ``` From 54891f14d3d226a6cfa11a38b8449bfc5e9a2353 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 8 Jun 2023 19:00:23 +0000 Subject: [PATCH 19/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/usage-reporting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 68c8f36841..9a240c0f0f 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -57,7 +57,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho ### Define the credential for the NIM API -In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. +In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. 4. 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: ``` @@ -79,7 +79,7 @@ In order to make the credential available to NGINX Cluster Connector, we need to username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` -Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. +Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. From f84668e886ea283c882e8d16be8d1fa31fe91eef Mon Sep 17 00:00:00 2001 From: Brian Ehlert Date: Thu, 8 Jun 2023 12:02:19 -0700 Subject: [PATCH 20/37] Update usage-reporting.md whoops fixes Signed-off-by: Brian Ehlert --- docs/content/usage-reporting.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 9a240c0f0f..22583b327a 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -55,7 +55,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho > kubectl create namespace nginx-cluster-connector ``` -### Define the credential for the NIM API +### Define the credential for the NMS API In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. @@ -67,7 +67,7 @@ In order to make the credential available to NGINX Cluster Connector, we need to YmFy ``` -5. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 1: +5. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 4: ``` apiVersion: v1 kind: Secret @@ -90,6 +90,8 @@ If you are using a different namespace, please change the namespace in the `meta If you need to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. +### Deploy the cluster connector + 7. Download and save the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: ``` args: From 9a853873187647f90447d7258695b9cf746212fb Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Tue, 13 Jun 2023 16:34:00 +0100 Subject: [PATCH 21/37] update docs and example manifest --- docs/content/usage-reporting.md | 8 ++------ .../usage-reporting/cluster-connector.yaml | 18 +++++++++--------- 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 22583b327a..01dc68d90b 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -99,7 +99,7 @@ If you need to update the basic-auth credentials to NMS server in the future, up - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` -The `-nms-server-address` should be the address of the NGINX Management Suite host. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. +The `-nms-server-address` should be the address of the usage reporting API, which should be the combination of NMS server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). 8. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: @@ -205,11 +205,7 @@ The NGINX Cluster Connector supports several command-line arguments. The command ### -nms-server-address `` The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. -Default `apigw.nms.svc.cluster.local`. - -### -nms-server-port `` -The port of the NGINX Management Suite host -Default `443`. +Default `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. ### -nms-basic-auth-secret `` Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. diff --git a/examples/shared-examples/usage-reporting/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml index f9331954ab..63ef7d1450 100644 --- a/examples/shared-examples/usage-reporting/cluster-connector.yaml +++ b/examples/shared-examples/usage-reporting/cluster-connector.yaml @@ -91,12 +91,12 @@ spec: template: metadata: labels: - app: cluster-connector + app: nginx-cluster-connector spec: - serviceAccountName: cluster-connector + serviceAccountName: nginx-cluster-connector automountServiceAccountToken: true containers: - - image: public-registry.nginx.com/cluster-connector:0.0.1 #TODO: update with correct image tag after publishing + - image: public-registry.nginx.com/cluster-connector/cluster-connector:0.0.1 #TODO: update with correct image tag after publishing imagePullPolicy: IfNotPresent name: nginx-cluster-connector resources: @@ -122,10 +122,10 @@ spec: fieldRef: fieldPath: metadata.name args: - - -nms-server-address=apigw.nms.svc.cluster.local - - -nms-server-port=443 + - -nms-server-address=https://apigw.nms.svc.cluster.local:443/api/platform/v1 - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth - - -cluster-display-name=my-cluster -# - -v=3 -# - -skip-tls-verify -# - -min-update-interval=24h +# - -cluster-display-name=my-cluster +# - -v=3 +# - -skip-tls-verify +# - -min-update-interval=24h + From e940dc8d9dfdc05c170ee593816b185c290cd93e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 13 Jun 2023 15:34:36 +0000 Subject: [PATCH 22/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- examples/shared-examples/usage-reporting/cluster-connector.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/shared-examples/usage-reporting/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml index 63ef7d1450..a824a4c079 100644 --- a/examples/shared-examples/usage-reporting/cluster-connector.yaml +++ b/examples/shared-examples/usage-reporting/cluster-connector.yaml @@ -128,4 +128,3 @@ spec: # - -v=3 # - -skip-tls-verify # - -min-update-interval=24h - From 510da2f482e95fc5831fb127043c67768a761867 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Thu, 15 Jun 2023 12:47:08 +0100 Subject: [PATCH 23/37] update format and file name --- docs/content/usage-reporting.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 01dc68d90b..dccf66fbb7 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -50,7 +50,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho ### Define a namespace -3. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: +1. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: ``` > kubectl create namespace nginx-cluster-connector ``` @@ -59,7 +59,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. -4. 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: +2. 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: ``` > echo -n 'foo' | base64 Zm9v @@ -67,7 +67,7 @@ In order to make the credential available to NGINX Cluster Connector, we need to YmFy ``` -5. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 4: +3. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 4: ``` apiVersion: v1 kind: Secret @@ -79,11 +79,11 @@ In order to make the credential available to NGINX Cluster Connector, we need to username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` -Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. + Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. + + If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. -If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. - -6. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: +4. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: ``` > kubectl apply -f nms-basic-auth.yaml ``` @@ -92,7 +92,7 @@ If you need to update the basic-auth credentials to NMS server in the future, up ### Deploy the cluster connector -7. Download and save the deployment file [nginx-cluster.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: +5. Download and save the deployment file [cluster-connector.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: ``` args: - -nms-server-address=https://nms.example.com/api/platform/v1 @@ -102,7 +102,7 @@ If you need to update the basic-auth credentials to NMS server in the future, up The `-nms-server-address` should be the address of the usage reporting API, which should be the combination of NMS server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). -8. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: +6. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: ``` > kubectl apply -f cluster-connector.yaml ``` From 0e3db4b16e8f1c7f15d873448717799d2b16f37c Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 15 Jun 2023 11:47:42 +0000 Subject: [PATCH 24/37] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index dccf66fbb7..8a73b307f3 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -80,7 +80,7 @@ In order to make the credential available to NGINX Cluster Connector, we need to password: YmFy # base64 representation of 'bar' obtained in step 1 ``` Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. - + If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 4. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: From f85b44ae85fb0e6638af99e2ed4ecf0edab37975 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 12:16:43 +0100 Subject: [PATCH 25/37] Update docs/content/usage-reporting.md Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 8a73b307f3..1e5c201413 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -15,7 +15,7 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle As a requirement for the Flexible Consumption Program (FCP) licensing option, there is a requirement to track the deployments of NGINX Ingress Controller according to the pricing dimensions of the program. The NGINX Management Suite is used as a data aggregation point for the reporting component called the cluster connector. -NGINX Cluster Connector is a Kubernetes controller that sends reporting data to the NGINX Management Suite. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster(s) where NGINX Ingress Controller is deployed. +NGINX Cluster Connector is a Kubernetes controller that sends reporting data to the NGINX Management Suite. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster(s) where NGINX Ingress Controller is deployed. To use the NGINX Cluster Connector, you must have NGINX Management Suite installed and running in your data center. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). The NGINX Management Suite component is included in your subscription and should be available to download through your MyF5.com account. From b18d5f6d3e6f51372543ce354a61482790c206b2 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 12:20:03 +0100 Subject: [PATCH 26/37] Update docs/content/usage-reporting.md Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 1e5c201413..880250fbe5 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -164,7 +164,7 @@ The NGINX Cluster Connector reports the number of NGINX Ingress Controller insta ] } ``` -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 the Cluster Connector . See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. +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 the Cluster Connector. See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. You can also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: ``` From 5ed1a96bb0258ae72cb3b85aee6843ca4cba63ed Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 12:22:22 +0100 Subject: [PATCH 27/37] Update examples/shared-examples/usage-reporting/cluster-connector.yaml Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- examples/shared-examples/usage-reporting/cluster-connector.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/shared-examples/usage-reporting/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml index a824a4c079..679347b6f6 100644 --- a/examples/shared-examples/usage-reporting/cluster-connector.yaml +++ b/examples/shared-examples/usage-reporting/cluster-connector.yaml @@ -96,7 +96,7 @@ spec: serviceAccountName: nginx-cluster-connector automountServiceAccountToken: true containers: - - image: public-registry.nginx.com/cluster-connector/cluster-connector:0.0.1 #TODO: update with correct image tag after publishing + - image: docker-registry.nginx.com/cluster-connector/cluster-connector:0.1.0 #TODO: update with correct image tag after publishing imagePullPolicy: IfNotPresent name: nginx-cluster-connector resources: From af95fe1205247189ec450b1706e948f0aa3b364a Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 12:22:58 +0100 Subject: [PATCH 28/37] Update docs/content/usage-reporting.md Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 880250fbe5..50d3bd2f4b 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -1,7 +1,6 @@ --- title: Usage Reporting -description: | -How to enable usage reporting for NGINX Ingress Controller and view the usage data through the API. +description: "How to enable usage reporting for NGINX Ingress Controller and view the usage data through the API." weight: 1800 doctypes: ["concept"] toc: true From 6199c5b027feb6211a45818a863293a304f6249a Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 12:42:49 +0100 Subject: [PATCH 29/37] update according to review --- docs/content/usage-reporting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 50d3bd2f4b..844cab849f 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -12,7 +12,7 @@ This document outlines how to enable usage reporting for NGINX Ingress Controlle ## Overview -As a requirement for the Flexible Consumption Program (FCP) licensing option, there is a requirement to track the deployments of NGINX Ingress Controller according to the pricing dimensions of the program. The NGINX Management Suite is used as a data aggregation point for the reporting component called the cluster connector. +To use the Flexible Consumption Program (FCP) licensing option, there is a requirement to track the deployments of NGINX Ingress Controller according to the pricing dimensions of the program. The NGINX Management Suite is used as a data aggregation point for the reporting component called the cluster connector. NGINX Cluster Connector is a Kubernetes controller that sends reporting data to the NGINX Management Suite. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster(s) where NGINX Ingress Controller is deployed. @@ -26,7 +26,6 @@ To deploy Usage Reporting, you must have the following: |-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | | NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | -| Kubernetes 1.22 or later | Ensure you can access the Kubernetes API, with the ability to deploy a Kubernetes Deployment and a Kubernetes secret. | In addition to the software requirements, you must have the following: - Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. @@ -214,7 +213,7 @@ Format `/`. The display name of the Kubernetes cluster. ### -skip-tls-verify -Skip TLS verification for the NMS server. **For testing purposes with NMS server using self-assigned certificate.** +Skip TLS verification for the NGINX Management Suite server. **For testing purposes with NMS server using self-assigned certificate.** ### -min-update-interval `` The minimum interval between updates to the NMS. From 62581a5d7ecfedde051f10a3b6279e587e5d64d2 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 14:14:13 +0100 Subject: [PATCH 30/37] Update docs/content/usage-reporting.md Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 844cab849f..013df4d437 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -28,7 +28,7 @@ To deploy Usage Reporting, you must have the following: | NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | In addition to the software requirements, you must have the following: -- Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. +- Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. - Access to public internet to pull the cluster connector image. This image is hosted in the NGINX container registry at `public-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. [//]: # ( TODO: Update the image and tag after published) From 8bf25a76652b030a01b44403e90cabbcd03d2b24 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Wed, 21 Jun 2023 15:10:17 +0100 Subject: [PATCH 31/37] Update docs/content/usage-reporting.md Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 013df4d437..5482bd22a7 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -30,7 +30,7 @@ To deploy Usage Reporting, you must have the following: In addition to the software requirements, you must have the following: - Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. -- Access to public internet to pull the cluster connector image. This image is hosted in the NGINX container registry at `public-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. +- Access to public internet to pull the cluster connector image. This image is hosted in the NGINX container registry at `docker-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. [//]: # ( TODO: Update the image and tag after published) ## Setting up user accounts in NGINX Management Suite From ccc1bacdf3e40e46acab8417b8e0282305f16a4c Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 21 Jun 2023 15:59:01 +0100 Subject: [PATCH 32/37] Apply suggestions from code review Co-authored-by: Luca Comellini Signed-off-by: Alan Dooley --- docs/content/usage-reporting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 5482bd22a7..6a3f9b5dae 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -35,7 +35,7 @@ In addition to the software requirements, you must have the following: ## Setting up user accounts in NGINX Management Suite -The cluster connector needs a user account to send usage data to NIM. This is how you create one for the Cluster Connector to use. +The cluster connector needs a user account to send usage data to NGINX Instance Manager. This is how you create one for the Cluster Connector to use. 1. Create a role following the steps in [Create a Role](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#create-role) section of the NGINX Management Suite documentation. Select these permissions in step 6 for the role: - Module: Instance Manager @@ -50,7 +50,7 @@ The cluster connector needs a user account to send usage data to NIM. This is ho 1. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: ``` - > kubectl create namespace nginx-cluster-connector + kubectl create namespace nginx-cluster-connector ``` ### Define the credential for the NMS API @@ -97,7 +97,7 @@ If you need to update the basic-auth credentials to NMS server in the future, up - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth ``` -The `-nms-server-address` should be the address of the usage reporting API, which should be the combination of NMS server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. +The `-nms-server-address` should be the address of the usage reporting API, which should be the combination of NMS server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. For more information on the command-line flags, see [Configuration](#configuration). 6. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: From 17ecb3209b107dfd41fd8246227e451289343a82 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 21 Jun 2023 16:51:52 +0100 Subject: [PATCH 33/37] Fix Usage Reporting nouns, improve phrasing of sections This commit makes a number of changes to the frontmatter of the page and the phrasing of specific sections for clarity and readability. It also removes the caret character from the shell commands, which should make it easier for the reader to copy & paste from the examples. --- docs/content/usage-reporting.md | 92 +++++++++++++++------------------ 1 file changed, 42 insertions(+), 50 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 6a3f9b5dae..028ffc4655 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -1,71 +1,64 @@ --- -title: Usage Reporting -description: "How to enable usage reporting for NGINX Ingress Controller and view the usage data through the API." +title: Enabling Usage Reporting +description: "This page outlines how to enable Usage Reporting for the NGINX Ingress Controller and how to view the usage data through the API." weight: 1800 doctypes: ["concept"] toc: true -docs: "DOCS-1228" --- - -This document outlines how to enable usage reporting for NGINX Ingress Controller and how to view the usage data through the API. - ## Overview -To use the Flexible Consumption Program (FCP) licensing option, there is a requirement to track the deployments of NGINX Ingress Controller according to the pricing dimensions of the program. The NGINX Management Suite is used as a data aggregation point for the reporting component called the cluster connector. - -NGINX Cluster Connector is a Kubernetes controller that sends reporting data to the NGINX Management Suite. The NGINX Cluster Connector is deployed as a Kubernetes Deployment in the same cluster(s) where NGINX Ingress Controller is deployed. +Usage Reporting is a Kubernetes controller that connects to the NGINX Management Suite and reports the number of NGINX Ingress Controller nodes in the cluster. It is installed as a Kubernetes Deployment in the same cluster as the NGINX Ingress Controller whose nodes you would like reported. -To use the NGINX Cluster Connector, you must have NGINX Management Suite installed and running in your data center. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). The NGINX Management Suite component is included in your subscription and should be available to download through your MyF5.com account. +To use Usage Reporting, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.nginx.com/products/nginx-management-suite/). Usage Reporting is a requirement of the new Flexible Consumption Program for NGINX Ingress Controller, used to calculate costs. ## Requirements To deploy Usage Reporting, you must have the following: -| Requirements | Notes | -|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------| -| NGINX Ingress Controller 3.1.0 or later | https://docs.nginx.com/nginx-ingress-controller | -| NGINX Management Suite 2.11 or later | https://docs.nginx.com/nginx-management-suite | +* [NGINX Ingress Controller 3.1.0](https://docs.nginx.com/nginx-ingress-controller) or later +* [NGINX Management Suite 2.11](https://docs.nginx.com/nginx-management-suite) or later -In addition to the software requirements, you must have the following: -- Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and the cluster connector username, and password. The cluster connector user account must have access to the `/api/platform/v1/k8s-usage` endpoint. +In addition to the software requirements, you will need: +- Access to an NGINX Management Suite username and password for basic authentication. You will need the URL of your NGINX Management Suite system, and a username and password for Usage Reporting. The Usage Reporting user account must have access to the `/api/platform/v1/k8s-usage` endpoint. - Access to the Kubernetes cluster where the NGINX Ingress Controller is deployed, with the ability to deploy a Kubernetes Deployment and a Kubernetes Secret. -- Access to public internet to pull the cluster connector image. This image is hosted in the NGINX container registry at `docker-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. -[//]: # ( TODO: Update the image and tag after published) +- Access to public internet to pull the Usage Reporting image. This image is hosted in the NGINX container registry at `docker-registry.nginx.com/cluster-connector`. You can pull the image and push it to a private container registry for deployment. -## Setting up user accounts in NGINX Management Suite +[//]: # ( TODO: Update the image and tag after publish) -The cluster connector needs a user account to send usage data to NGINX Instance Manager. This is how you create one for the Cluster Connector to use. +## Adding 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. 1. Create a role following the steps in [Create a Role](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#create-role) section of the NGINX Management Suite documentation. Select these permissions in step 6 for the role: - Module: Instance Manager - - Feature: Nginx Plus Usage + - Feature: NGINX Plus Usage - Access: CRUD 2. 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. -## Deploying the NGINX Cluster Connector +## Deploying Usage Reporting -### Define a namespace +### Creating a Namespace -1. Create a Kubernetes namespace `nginx-cluster-connector` for the NGINX Cluster Connector: +1. Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: ``` kubectl create namespace nginx-cluster-connector ``` -### Define the credential for the NMS API +### Passing the Credential to the NGINX Management Suite API -In order to make the credential available to NGINX Cluster Connector, we need to create a Kubernetes secret. +To make the credential available to Usage Reporting, we need to create a Kubernetes secret. 2. 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: ``` - > echo -n 'foo' | base64 - Zm9v - > echo -n 'bar' | base64 - YmFy + echo -n 'foo' | base64 + # Zm9v + echo -n 'bar' | base64 + # YmFy ``` -3. Copying the following content to a text editor, and fill in under `data` the base64 representation of the username and password obtained in step 4: +3. 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: ``` apiVersion: v1 kind: Secret @@ -77,40 +70,39 @@ In order to make the credential available to NGINX Cluster Connector, we need to username: Zm9v # base64 representation of 'foo' obtained in step 1 password: YmFy # base64 representation of 'bar' obtained in step 1 ``` - Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for the NGINX Cluster Connector. + Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` and the secret name is `nms-basic-auth`. The namespace is the default namespace for Usage Reporting. - If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that the cluster connector only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. + If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that Usage Reporting only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 4. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: - ``` - > kubectl apply -f nms-basic-auth.yaml + ```shell + kubectl apply -f nms-basic-auth.yaml ``` -If you need to update the basic-auth credentials to NMS server in the future, update the `username` and `password` fields, and apply the changes by running the command again. The NGINX Cluster Connector will automatically detect the changes and use the new username and password without redeploying the NGINX Cluster Connector. - -### Deploy the cluster connector +If you need to update the basic-auth credentials for NGINX Management Suite in the future, update the `username` and `password` fields, and apply the changes by running the command again. Usage Reporting will automatically detect the changes, using the new username and password without redeployment. 5. Download and save the deployment file [cluster-connector.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.1.1/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 ``` -The `-nms-server-address` should be the address of the usage reporting API, which should be the combination of NMS server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 2, i.e `nginx-cluster-connector/nms-basic-auth`. -For more information on the command-line flags, see [Configuration](#configuration). +The `-nms-server-address` should be the address of the Usage Reporting API, which will be the combination of NGINX Management Suite server hostname and the URI `api/platform/v1`. The `nms-basic-auth-secret` should be the namespace/name of the secret created in step 3: `nginx-cluster-connector/nms-basic-auth`. -6. To deploy the Nginx Cluster Connector, run the following command to deploy it to your Kubernetes cluster: - ``` - > kubectl apply -f cluster-connector.yaml +For more information, read the [Command-line Arguments](#command-line-arguments) section. + +6. To deploy Usage Reporting, run the following command to deploy it to your Kubernetes cluster: + ```shell + kubectl apply -f cluster-connector.yaml ``` ## Viewing Usage Data from the NGINX Management Suite API -The NGINX Cluster Connector reports 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 in the following endpoint: +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: ``` -> curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage +curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage { "items": [ { @@ -162,11 +154,11 @@ The NGINX Cluster Connector reports the number of NGINX Ingress Controller insta ] } ``` -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 the Cluster Connector. See [Command-line Arguments](#Command-line Arguments) for more information. From this response, you can see the cluster uid corresponding to the cluster name. +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 also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: ``` -> curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 +curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 { "metadata": { "displayName": "my-cluster", @@ -192,8 +184,8 @@ You can also query the usage data for a specific cluster by specifying the clust } ``` -## Uninstalling the NGINX Cluster Connector -To remove the Nginx Cluster Connector from your Kubernetes cluster, run the following command: +## Uninstalling Usage Reporting +To remove Usage Reporting from your Kubernetes cluster, run the following command: ``` kubectl delete -f cluster-connector.yaml ``` From a09cb0e1eb0e671acd502beee04b20b2d717c1c0 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 21 Jun 2023 17:07:15 +0100 Subject: [PATCH 34/37] Update docs/content/usage-reporting.md Signed-off-by: Alan Dooley --- docs/content/usage-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 028ffc4655..7e31bdbd53 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -191,7 +191,7 @@ kubectl delete -f cluster-connector.yaml ``` ## Command-line Arguments -The NGINX Cluster Connector supports several command-line arguments. The command-line arguments 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. The command-line arguments 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: ### -nms-server-address `` The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. From ed267de97819692def07de114381c44735e844bc Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:03:38 +0100 Subject: [PATCH 35/37] update according to review --- docs/content/usage-reporting.md | 2 +- examples/shared-examples/usage-reporting/cluster-connector.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 7e31bdbd53..8fd45a671b 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -16,7 +16,7 @@ To use Usage Reporting, you must have access to NGINX Management Suite. For more To deploy Usage Reporting, you must have the following: -* [NGINX Ingress Controller 3.1.0](https://docs.nginx.com/nginx-ingress-controller) or later +* [NGINX Ingress Controller 3.2.0](https://docs.nginx.com/nginx-ingress-controller) or later * [NGINX Management Suite 2.11](https://docs.nginx.com/nginx-management-suite) or later In addition to the software requirements, you will need: diff --git a/examples/shared-examples/usage-reporting/cluster-connector.yaml b/examples/shared-examples/usage-reporting/cluster-connector.yaml index 679347b6f6..f51aba51cf 100644 --- a/examples/shared-examples/usage-reporting/cluster-connector.yaml +++ b/examples/shared-examples/usage-reporting/cluster-connector.yaml @@ -96,7 +96,7 @@ spec: serviceAccountName: nginx-cluster-connector automountServiceAccountToken: true containers: - - image: docker-registry.nginx.com/cluster-connector/cluster-connector:0.1.0 #TODO: update with correct image tag after publishing + - image: docker-registry.nginx.com/cluster-connector/cluster-connector:0.1.0 imagePullPolicy: IfNotPresent name: nginx-cluster-connector resources: From 35f04acfa24f8153ea704491b89e3b175f312f62 Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:17:47 +0100 Subject: [PATCH 36/37] update nouns --- docs/content/usage-reporting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index 8fd45a671b..f788496dab 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -205,8 +205,8 @@ Format `/`. The display name of the Kubernetes cluster. ### -skip-tls-verify -Skip TLS verification for the NGINX Management Suite server. **For testing purposes with NMS server using self-assigned certificate.** +Skip TLS verification for the NGINX Management Suite server. **For testing purposes with NGINX Management Suite server using self-assigned certificate.** ### -min-update-interval `` -The minimum interval between updates to the NMS. +The minimum interval between updates to the NGINX Management Suite. **For testing purposes only.** Default `24h`. From 57296a60b58619f9e0f6b0e247ce3b70c7ec260e Mon Sep 17 00:00:00 2001 From: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> Date: Fri, 23 Jun 2023 11:42:31 +0100 Subject: [PATCH 37/37] Update code highlighting Co-authored-by: Luca Comellini Signed-off-by: Haywood Shannon <5781935+haywoodsh@users.noreply.github.com> --- docs/content/usage-reporting.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index f788496dab..e26fa75b97 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -42,7 +42,7 @@ Usage Reporting needs a user account to send usage data to NGINX Instance Manage ### Creating a Namespace 1. Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: - ``` + ```console kubectl create namespace nginx-cluster-connector ``` @@ -51,7 +51,7 @@ Usage Reporting needs a user account to send usage data to NGINX Instance Manage To make the credential available to Usage Reporting, we need to create a Kubernetes secret. 2. 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: - ``` + ```console echo -n 'foo' | base64 # Zm9v echo -n 'bar' | base64 @@ -59,7 +59,7 @@ To make the credential available to Usage Reporting, we need to create a Kuberne ``` 3. 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: @@ -75,7 +75,7 @@ To make the credential available to Usage Reporting, we need to create a Kuberne If you are using a different namespace, please change the namespace in the `metadata` section of the file above. Note that Usage Reporting only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. 4. Deploy the Kubernetes secret created in step 5 to the Kubernetes cluster: - ```shell + ```console kubectl apply -f nms-basic-auth.yaml ``` @@ -93,7 +93,7 @@ The `-nms-server-address` should be the address of the Usage Reporting API, whic For more information, read the [Command-line Arguments](#command-line-arguments) section. 6. To deploy Usage Reporting, run the following command to deploy it to your Kubernetes cluster: - ```shell + ```console kubectl apply -f cluster-connector.yaml ``` @@ -101,7 +101,7 @@ For more information, read the [Command-line Arguments](#command-line-arguments) ## 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: -``` +```json curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage { "items": [ @@ -157,7 +157,7 @@ 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 also query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: -``` +```json curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 { "metadata": { @@ -186,7 +186,7 @@ curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee ## Uninstalling Usage Reporting To remove Usage Reporting from your Kubernetes cluster, run the following command: -``` +```console kubectl delete -f cluster-connector.yaml ```