From db7c78f3627fbbb8291364e4609ef27cd4caacd7 Mon Sep 17 00:00:00 2001 From: Shaun Date: Thu, 14 Mar 2024 18:20:22 +0000 Subject: [PATCH] Developer documentation for generating telemetry schema (#5250) --- Makefile | 5 +++ .../command-line-arguments.md | 2 +- .../installing-nic/installation-with-helm.md | 10 ++--- docs/developer/telemetry-schema-generation.md | 37 +++++++++++++++++++ internal/telemetry/data.avdl | 6 +-- internal/telemetry/exporter.go | 6 +-- 6 files changed, 54 insertions(+), 12 deletions(-) create mode 100644 docs/developer/telemetry-schema-generation.md diff --git a/Makefile b/Makefile index c6febb797c..fdc5b3732e 100644 --- a/Makefile +++ b/Makefile @@ -87,6 +87,11 @@ update-crds: ## Update CRDs kustomize build config/crd/app-protect-dos --load-restrictor='LoadRestrictionsNone' >deploy/crds-nap-dos.yaml kustomize build config/crd/app-protect-waf --load-restrictor='LoadRestrictionsNone' >deploy/crds-nap-waf.yaml +.PHONY: telemetry-schema +telemetry-schema: ## Generate the telemetry Schema + go generate internal/telemetry/exporter.go + gofumpt -w internal/telemetry/*_generated.go + .PHONY: certificate-and-key certificate-and-key: ## Create default cert and key ./build/generate_default_cert_and_key.sh diff --git a/docs/content/configuration/global-configuration/command-line-arguments.md b/docs/content/configuration/global-configuration/command-line-arguments.md index 33c13fa7c9..7a0726d9f5 100644 --- a/docs/content/configuration/global-configuration/command-line-arguments.md +++ b/docs/content/configuration/global-configuration/command-line-arguments.md @@ -538,7 +538,7 @@ The default value is `true`. ### -enable-telemetry-reporting -Enable gathering and reporting of product related telemetry. +Enable gathering and reporting of software telemetry. The default value is `true`. diff --git a/docs/content/installation/installing-nic/installation-with-helm.md b/docs/content/installation/installing-nic/installation-with-helm.md index 8d6a7eafb4..4c2211a74d 100644 --- a/docs/content/installation/installing-nic/installation-with-helm.md +++ b/docs/content/installation/installing-nic/installation-with-helm.md @@ -22,11 +22,11 @@ h2 { - A [Kubernetes Version Supported by the Ingress Controller](https://docs.nginx.com/nginx-ingress-controller/technical-specifications/#supported-kubernetes-versions) - Helm 3.0+. - If you’d like to use NGINX Plus: - - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/nic-images/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` or `controller.serviceAccount.imagePullSecretsNames` parameter. - - Alternatively, pull an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}). - - Alternatively, you can build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}}). - - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. -- If you’d like to use App Protect DoS, please install App Protect DoS Arbitrator [helm chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart). Make sure to install in the same namespace as the NGINX Ingress Controller. Note that if you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because it is not possible to install more than one Arbitrator in a single namespace. + - To pull from the F5 Container registry, configure a docker registry secret using your JWT token from the MyF5 portal by following the instructions from [here](https://docs.nginx.com/nginx-ingress-controller/installation/nic-images/using-the-jwt-token-docker-secret). Make sure to specify the secret using `controller.serviceAccount.imagePullSecretName` or `controller.serviceAccount.imagePullSecretsNames` parameter. + - Alternatively, pull an NGINX Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/nic-images/pulling-ingress-controller-image" >}}). + - Alternatively, you can NGINX build an Ingress Controller image with NGINX Plus and push it to your private registry by following the instructions from [here]({{< relref "installation/building-nginx-ingress-controller.md" >}}). + - Update the `controller.image.repository` field of the `values-plus.yaml` accordingly. +- To use App Protect DoS, install the App Protect DoS Arbitrator [Helm Chart](https://github.com/nginxinc/nap-dos-arbitrator-helm-chart) in the same namespace as the NGINX Ingress Controller. If you install multiple NGINX Ingress Controllers in the same namespace, they will need to share the same Arbitrator because there can only be one Arbitrator in a single namespace. ## CRDs diff --git a/docs/developer/telemetry-schema-generation.md b/docs/developer/telemetry-schema-generation.md new file mode 100644 index 0000000000..6998c14f6a --- /dev/null +++ b/docs/developer/telemetry-schema-generation.md @@ -0,0 +1,37 @@ +# Telemetry Schema Generation + +This document outlines how to update the `data.avdl` schema file in `internal/telemetry` +This document also details reasons why the schema file would need to be updated. + +## Updating the schema +In the root of the project, run the below Make command +``` +make telemetry-schema +``` + +Depending on what kind of update was made, different files will be updated, +- `internal/telemetry/nicresourcecounts_attributes_generated.go` + This file is updated if properties in NICResourceCounts are added, updated or deleted. + +- `internal/telemetry/data_attributes_generated.go` + This file is update if properties of the Data struct in the [telemetry-exporter](https://github.com/nginxinc/telemetry-exporter) library are added, updated or deleted. + +- `internal/telemetry/data.avdl` + This file is updated if either the NICResourceCounts or the Data struct is updated. + +## Reasons to update the Schema file +1. A new data point is being collected + +We may choose to collect a count of a new resource managed by the Ingress Controller. +In this case, the `NICResourceCounts` struct in `internal/telemetry/exporter.go` would be updated +``` +type NICResourceCounts struct { + // MyNewResources is the number of MyNewResources resources managed by the Ingress Controller. + MyNewResources int64 +} +``` + +2. An existing data point has been updated or delete + +This may either be a data point under `NICResourceCounts`, or a field in the common `Data` struct in [telemetry-exporter](https://github.com/nginxinc/telemetry-exporter) library. +For example, we may change the name of, or delete, `MyNewResources` used in the first example. diff --git a/internal/telemetry/data.avdl b/internal/telemetry/data.avdl index 8ce86fdee4..a425c62759 100644 --- a/internal/telemetry/data.avdl +++ b/internal/telemetry/data.avdl @@ -33,13 +33,13 @@ It is the UID of the `kube-system` Namespace. */ /** ClusterNodeCount is the number of nodes in the cluster. */ long? ClusterNodeCount = null; - /** VirtualServer is the number of VirtualServer managed by the Ingress Controller. */ + /** VirtualServers is the number of VirtualServer resources managed by the Ingress Controller. */ long? VirtualServers = null; - /** VirtualServerRoutes is the number of VirtualServerRoutes managed by the Ingress Controller. */ + /** VirtualServerRoutes is the number of VirtualServerRoute resources managed by the Ingress Controller. */ long? VirtualServerRoutes = null; - /** TransportServers is the number of TransportServers managed by the Ingress Controller. */ + /** TransportServers is the number of TransportServer resources by the Ingress Controller. */ long? TransportServers = null; } diff --git a/internal/telemetry/exporter.go b/internal/telemetry/exporter.go index e827ca353b..01cd2a9800 100644 --- a/internal/telemetry/exporter.go +++ b/internal/telemetry/exporter.go @@ -62,11 +62,11 @@ type Data struct { // //go:generate go run -tags=generator github.com/nginxinc/telemetry-exporter/cmd/generator -type NICResourceCounts type NICResourceCounts struct { - // VirtualServer is the number of VirtualServer managed by the Ingress Controller. + // VirtualServers is the number of VirtualServer resources managed by the Ingress Controller. VirtualServers int64 - // VirtualServerRoutes is the number of VirtualServerRoutes managed by the Ingress Controller. + // VirtualServerRoutes is the number of VirtualServerRoute resources managed by the Ingress Controller. VirtualServerRoutes int64 - // TransportServers is the number of TransportServers managed by the Ingress Controller. + // TransportServers is the number of TransportServer resources by the Ingress Controller. TransportServers int64 // Replicas is the number of NIC replicas.