From ffc13a133ebbe42c5c517f699651af6b840368a0 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Fri, 14 Jun 2024 15:59:32 +0100 Subject: [PATCH] Update top level documentation pages for style consistency (#5754) This commit changes the top level pages of documentation to adhere with newer style guide conventions. * Horizontal rules at the end of sections * Sentence case for page titles and headings * Note formatting * Link introduction phrasing Co-authored-by: Venktesh Shivam Patel --- docs/content/community.md | 4 +- docs/content/glossary.md | 8 +- docs/content/overview/about.md | 5 +- docs/content/overview/design.md | 64 ++++++-- docs/content/overview/nginx-plus.md | 8 +- docs/content/overview/product-telemetry.md | 23 +-- docs/content/technical-specifications.md | 56 +++++-- docs/content/usage-reporting.md | 172 +++++++++++++-------- 8 files changed, 231 insertions(+), 109 deletions(-) diff --git a/docs/content/community.md b/docs/content/community.md index f4acbd2f8d..595f256263 100644 --- a/docs/content/community.md +++ b/docs/content/community.md @@ -1,11 +1,11 @@ --- docs: DOCS-1447 -title: Community and Contribution +title: Community and contributing toc: true weight: 2200 --- -There are a few ways to get involved with the NGINX Ingress Controller community and contribute to the project. +There are a few ways to get involved with the F5 NGINX Ingress Controller community and contribute to the project. # Community diff --git a/docs/content/glossary.md b/docs/content/glossary.md index 0a7bacdfd0..c1b1412b7a 100644 --- a/docs/content/glossary.md +++ b/docs/content/glossary.md @@ -5,6 +5,10 @@ title: Glossary weight: 10000 --- +This is a glossary of terms related to F5 NGINX Ingress Controller and Kubernetes as a whole. + +--- + ## Ingress {#ingress} _Ingress_ refers to an _Ingress Resource_, a Kubernetes API object which allows access to [Services](https://kubernetes.io/docs/concepts/services-networking/service/) within a cluster. They are managed by an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}). @@ -17,8 +21,10 @@ _Ingress_ resources enable the following functionality: For additional information, please read the official [Kubernetes Ingress Documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/). +--- + ## Ingress Controller {#ingress-controller} *Ingress Controllers* are applications within a Kubernetes cluster that enable [Ingress]({{< relref "glossary.md#ingress">}}) resources to function. They are not automatically deployed with a Kubernetes cluster, and can vary in implementation based on intended use, such as load balancing algorithms for Ingress resources. -[How NGINX Ingress Controller is Designed]({{< relref "overview/design">}}) explains the technical details of the F5 NGINX Ingress Controller. +[The design of NGINX Ingress Controller]({{< relref "overview/design.md">}}) explains the technical details of NGINX Ingress Controller. diff --git a/docs/content/overview/about.md b/docs/content/overview/about.md index 6a5efcf5f5..c282a69bd3 100644 --- a/docs/content/overview/about.md +++ b/docs/content/overview/about.md @@ -8,9 +8,10 @@ weight: 100 This document describes the F5 NGINX Ingress Controller, an Ingress Controller implementation for NGINX and NGINX Plus. +--- + NGINX Ingress Controller is an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}) implementation for NGINX and NGINX Plus that can load balance Websocket, gRPC, TCP and UDP applications. It supports standard [Ingress]({{< relref "glossary.md#ingress">}}) features such as content-based routing and TLS/SSL termination. Several NGINX and NGINX Plus features are available as extensions to Ingress resources through [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) and the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) resource. NGINX Ingress Controller supports the [VirtualServer and VirtualServerRoute resources]({{< relref "configuration/virtualserver-and-virtualserverroute-resources">}}) as alternatives to Ingress, enabling traffic splitting and advanced content-based routing. It also supports TCP, UDP and TLS Passthrough load balancing using [TransportServer resources]({{< relref "configuration/transportserver-resource">}}). -To learn more about NGINX Ingress Controller, please read the [How NGINX Ingress Controller is Designed -]({{< relref "overview/design">}}) and [Extensibility with NGINX Plus]({{< relref "overview/nginx-plus">}}) pages. +To learn more about NGINX Ingress Controller, please read the [The design of NGINX Ingress Controller]({{< relref "overview/design.nd">}}) and [Extensibility with NGINX Plus]({{< relref "overview/nginx-plus.md">}}) topics. diff --git a/docs/content/overview/design.md b/docs/content/overview/design.md index dafb7dc8c4..528fdeabf7 100644 --- a/docs/content/overview/design.md +++ b/docs/content/overview/design.md @@ -2,7 +2,7 @@ docs: DOCS-609 doctypes: - reference -title: How NGINX Ingress Controller is Designed +title: The design of NGINX Ingress Controller toc: true weight: 200 --- @@ -18,7 +18,9 @@ We assume that the reader is familiar with core Kubernetes concepts, such as Pod For conciseness in diagrams, NGINX Ingress Controller is often labelled "IC" on this page. -## NGINX Ingress Controller at a High Level +--- + +## NGINX Ingress Controller at a high level This figure depicts an example of NGINX Ingress Controller exposing two web applications within a Kubernetes cluster to clients on the internet: @@ -38,7 +40,9 @@ The figure shows: The yellow and purple arrows represent connections related to the client traffic, and the black arrows represent access to the Kubernetes API. -## The NGINX Ingress Controller Pod +--- + +## The NGINX Ingress Controller pod The NGINX Ingress Controller pod consists of a single container, which includes the following: @@ -52,7 +56,6 @@ The following is an architectural diagram depicting how those processes interact This table describes each connection, starting with its type: - {{< bootstrap-table "table table-bordered table-striped table-responsive" >}} | # | Protocols | Description | | --- | --- | --- | @@ -79,6 +82,8 @@ This table describes each connection, starting with its type: |21|HTTP| _Admin_ can connect to the [NGINX stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) using port 8080 via an _NGINX worker_. By default, NGINX only allows connections from `localhost`. {{% /bootstrap-table %}} +--- + ### Differences with NGINX Plus The previous diagram depicts NGINX Ingress Controller using NGINX. NGINX Ingress Controller with NGINX Plus has the following differences: @@ -87,7 +92,9 @@ The previous diagram depicts NGINX Ingress Controller using NGINX. NGINX Ingress - Instead of the stub status metrics, the extended metrics available from the NGINX Plus API are used. - In addition to TLS certs and keys, NGINX Ingress Controllerf writes JWKs from the secrets of the type `nginx.org/jwk`, and NGINX workers read them. -## The NGINX Ingress Controller Process +--- + +## The NGINX Ingress Controller process This section covers the architecture of the NGINX Ingress Controller process, including: @@ -95,7 +102,9 @@ This section covers the architecture of the NGINX Ingress Controller process, in - A summary of how NGINX Ingress Controller works in relation to others Kubernetes Controllers. - The different components of the IC process. -### Processing a New Ingress Resource +--- + +### Processing a new Ingress resource The following diagram depicts how NGINX Ingress Controller processes a new Ingress resource. The the NGINX master and worker processes are represented as a single rectangle, _NGINX_ for simplicity. VirtualServer and VirtualServerRoute resources are indicated similarly. @@ -114,7 +123,9 @@ Processing a new Ingress resource involves the following steps: each step corres 1. _NGINX_ reads the _configuration files_. 1. The _Control Loop_ emits an event for the Ingress resource and updates its status. If the reload fails, the event includes the error message. -### NGINX Ingress Controller is a Kubernetes Controller +--- + +### NGINX Ingress Controller is a Kubernetes controller With the context from the previous sections, we can generalize how NGINX Ingress Controller works: @@ -147,7 +158,9 @@ NGINX Ingress Controller can watch additional Custom Resources, which are less c - [NGINX App Protect resources]({{< relref "installation/integrations/app-protect-dos/configuration" >}}) (APPolicies, APLogConfs, APUserSigs) - IngressLink resource (only one resource) -## NGINX Ingress Controller Process Components +--- + +## NGINX Ingress Controller process components In this section, we describe the components of the NGINX Ingress Controller process and how they interact, including: @@ -158,7 +171,7 @@ In this section, we describe the components of the NGINX Ingress Controller proc NGINX Ingress Controller is written in [Go](https://golang.org/) and relies heavily on the [Go client for Kubernetes](https://github.com/kubernetes/client-go). Where relevant, we include links to the source code on GitHub. -### Resource Caches +### Resource caches In an earlier section, [Processing a New Ingress Resource](#processing-a-new-ingress-resource), we mentioned that NGINX Ingress Controller has a cache of the resources in the cluster that stays in sync with the Kubernetes API by watching them for changes. @@ -172,7 +185,9 @@ We also mentioned that once the cache is updated, it notifies the control loop a - The _Workqueue_ always tries to drain itself: if there is an element at the front, the queue will remove the element and send it to the _Controller_ by calling a callback function (See the arrow _4. Send_). - The _Controller_ is the primary component of NGINX Ingress Controller, which represents the _Control Loop_, explained in [The Control Loop](#the-control-loop) section. To process a workqueue element, the _Controller_ component gets the latest version of the resource from the _Store_ (See the arrow _5. Get_), reconfigures _NGINX_ according to the resource (See the arrow _6. Reconfigure*_, updates the resource status, and emits an event via the _Kubernetes API_ (See the arrow _7. Update status and emit event_). -### The Control Loop +--- + +### The control loop This section discusses the main components of NGINX Ingress Controller, which comprise the control loop: @@ -192,7 +207,9 @@ The following diagram shows how the three components interact: {{}} -#### The Controller Sync Method +--- + +#### The Controller sync method The Controller [sync](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/controller.go#L663) method is called by the _Workqueue_ to process a change of a resource. The method determines the _kind_ of the resource and calls the appropriate _sync_ method (Such as _syncIngress_ for Ingress resources). @@ -213,16 +230,20 @@ To explain how the sync methods work, we will examine the most important one: th 1. The reload status is propagated from _Manager_ to _processChanges_, and is either a success or a failure with an error message. 1. _processChanges_ calls _updateRegularIngressStatusAndEvent_ to update the status of the Ingress resource and emit an event with the status of the reload: both make an API call to the Kubernetes API. -**Additional Notes**: +**Additional notes**: - Many details are not included for conciseness: the source code provides the most granular detail. - The _syncVirtualServer_, _syncVirtualServerRoute_, and _syncTransportServer_ methods are similar to _syncIngress_, while other sync methods are different. However, those methods typically find the affected Ingress, VirtualServer, and TransportServer resources and regenerate the configuration for them. - The _Workqueue_ has only a single worker thread that calls the sync method synchronously, meaning the _Control Loop_ processes only one change at a time. -#### Helper Components +--- + +#### Helper components There are two additional helper components crucial for processing changes: _Configuration_ and _LocalSecretStore_. +--- + ##### Configuration [_Configuration_](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/configuration.go#L320) holds the latest valid state of the NGINX Ingress Controller load balancing configuration resources: Ingresses, VirtualServers, VirtualServerRoutes, TransportServers, and GlobalConfiguration. @@ -238,16 +259,22 @@ Additionally, the _Configuration_ ensures that only one Ingress/VirtualServer/Tr Ultimately, NGINX Ingress Controller ensures the NGINX config on the filesystem reflects the state of the objects in the _Configuration_ at any point in time. +--- + ##### LocalSecretStore [_LocalSecretStore_](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/secrets/store.go#L32) (of the _SecretStore_ interface) holds the valid Secret resources and keeps the corresponding files on the filesystem in sync with them. Secrets are used to hold TLS certificates and keys (type `kubernetes.io/tls`), CAs (`nginx.org/ca`), JWKs (`nginx.org/jwk`), and client secrets for an OIDC provider (`nginx.org/oidc`). When _Controller_ processes a change to a configuration resource like Ingress, it creates an extended version of a resource that includes the dependencies (Such as Secrets) necessary to generate the NGINX configuration. _LocalSecretStore_ allows _Controller_ to reference the filesystem for a secret using the secret key (namespace/name). +--- + ## Reloading NGINX The following sections describe how NGINX reloads and how NGINX Ingress Controller specifically affects this process. +--- + ### How NGINX reloads work Reloading NGINX is necessary to apply new configuration changes and occurs with these steps: @@ -257,6 +284,9 @@ Reloading NGINX is necessary to apply new configuration changes and occurs with 1. The administrator verifies the reload has successfully finished. The [NGINX documentation](https://nginx.org/en/docs/control.html#reconfiguration) has more details about reloading. + +--- + #### How to reload NGINX and confirm success The NGINX binary (`nginx`) supports the reload operation with the `-s reload` option. When you run this option: @@ -273,6 +303,8 @@ Once the reload operation has been invoked with `nginx -s reload`, there is no w NGINX reloads take roughly 200ms. The factors affecting reload time are configuration size and details, the number of TLS certificates/keys, enabled modules, and available CPU resources. +--- + #### Potential problems Most of the time, if `nginx -s reload` executes, the reload will also succeed. In the rare case a reload fails, the NGINX master process will print the an error message. This is an example: @@ -285,6 +317,8 @@ The operation is graceful; reloading doesn't lead to any traffic loss by NGINX. Old NGINX workers will not shut down until all connections are terminated either by clients or backends, unless you configure [worker_shutdown_timeout](https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). Since both the old and new NGINX worker processes coexist during a reload, reloading can lead to two spikes in memory utilization. With a lack of available memory, the NGINX master process can fail to create new worker processes. +--- + ### Reloading in NGINX Ingress Controller NGINX Ingress Controller reloads NGINX to apply configuration changes. @@ -301,7 +335,9 @@ Reloads occur with this sequence of steps: The [NGINX Ingress Controller Control Loop](#the-control-loop) stops during a reload so that it cannot affect configuration files or reload NGINX until the current reload succeeds or fails. -### When NGINX Ingress Controller Reloads NGINX +--- + +### When NGINX Ingress Controller reloads NGINX NGINX Ingress Controller reloads NGINX every time the Control Loop processes a change that affects the generated NGINX configuration. In general, every time a monitored resource is changed, NGINX Ingress Controller will regenerate the configuration and reload NGINX. diff --git a/docs/content/overview/nginx-plus.md b/docs/content/overview/nginx-plus.md index d809b1ddd3..1aa0d61fe6 100644 --- a/docs/content/overview/nginx-plus.md +++ b/docs/content/overview/nginx-plus.md @@ -6,10 +6,12 @@ title: Extensibility with NGINX Plus weight: 300 --- -This document explains how F5 NGINX Plus can extend the functionality of the F5 NGINX Ingress Controller. +This document explains how F5 NGINX Plus can extend the functionality of F5 NGINX Ingress Controller. NGINX Ingress Controller works with [NGINX](https://nginx.org/) as well as [NGINX Plus](https://www.nginx.com/products/nginx/), a commercial closed source version of NGINX which has additional features and support from NGINX Inc. NGINX Ingress Controller can leverage functionality from NGINX Plus to extend its base capabilities. +--- + ## Additional features - _Real-time metrics_: Metrics for NGINX Plus and application performance are available through the API or the [NGINX Status Page]({{< relref "logging-and-monitoring/status-page">}}). These metrics can also be exported to [Prometheus]({{< relref "logging-and-monitoring/prometheus">}}). @@ -20,10 +22,12 @@ NGINX Ingress Controller works with [NGINX](https://nginx.org/) as well as [NGIN For a comprehensive guide of NGINX Plus features available with Ingress resources, see the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) and [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) documentation. -{{< note >}}NGINX Plus features are configured for Ingress resources using Annotations that start with `nginx.com`.{{< /note >}} +{{< note >}} NGINX Plus features are configured for Ingress resources using Annotations that start with `nginx.com`. {{< /note >}} For a comprehensive guide of NGINX Plus features available with custom resources, see the [Policy]({{< relref "configuration/policy-resource" >}}), [VirtualServer]({{< relref "configuration/virtualserver-and-virtualserverroute-resources" >}}) and [TransportServer]({{< relref "configuration/transportserver-resource" >}}) documentation. +--- + ## Dynamic reconfiguration NGINX Ingress Controller updates the configuration of the load balancer to reflect changes every time the number of pods exposed through an Ingress resource changes. When using NGINX, the configuration file must be changed then reloaded. diff --git a/docs/content/overview/product-telemetry.md b/docs/content/overview/product-telemetry.md index d6ed533cd1..0af3d9b9c2 100644 --- a/docs/content/overview/product-telemetry.md +++ b/docs/content/overview/product-telemetry.md @@ -1,23 +1,24 @@ --- -title: Product Telemetry +title: Product telemetry toc: true weight: 500 --- -Learn why NGINX Ingress Controller collects telemetry, and understand how and what it gathers. +Learn why, what and how F5 NGINX Ingress Controller collects telemetry. + +--- ## Overview -NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users. -This data is used to triage development work, prioritizing features and functionality that will benefit the most people. +NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users. This data is used to triage development work, prioritizing features and functionality that will benefit the most people. Product telemetry is enabled by default, collected once every 24 hours. It's then sent to a service managed by F5 over HTTPS. -{{< note >}} -If you would prefer to avoid sending any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller. -{{< /note >}} +{{< note >}} If you would prefer not to send any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller. {{< /note >}} + +--- -## Data Collected +## Data collected These are the data points collected and reported by NGINX Ingress Controller: @@ -56,20 +57,24 @@ These are the data points collected and reported by NGINX Ingress Controller: - **IsPlus** Represents whether NGINX is Plus or OSS - **InstallationFlags** List of command line arguments configured for NGINX Ingress Controller +--- + ## Opt out Product telemetry can be disabled when installing NGINX Ingress Controller. ### Helm +When installing or upgrading NGINX Ingress Controller with Helm, set the `controller.telemetry.enable` option to `false`. -When installing or upgrading NGINX Ingress Controller with Helm, set the `controller.telemetry.enable` option to `false` This can be set directly in the `values.yaml` file, or using the `--set` option ```shell helm upgrade --install ... --set controller.telemetry.enable=false ``` +--- + ### Manifests When installing NGINX Ingress Controller with Manifests, set the `-enable-telemetry-reporting` flag to `false` diff --git a/docs/content/technical-specifications.md b/docs/content/technical-specifications.md index 22263fd40f..525b64936c 100644 --- a/docs/content/technical-specifications.md +++ b/docs/content/technical-specifications.md @@ -2,24 +2,28 @@ docs: DOCS-617 doctypes: - concept -title: Technical Specifications +title: Technical specifications toc: true weight: 200 --- -This page describes technical specifications for NGINX Ingress Controller, such as its version compatibility with Kubernetes and other NGINX software. +This page describes technical specifications for F5 NGINX Ingress Controller, such as its version compatibility with Kubernetes and other NGINX software. -## Supported NGINX Ingress Controller Versions +--- + +## Supported NGINX Ingress Controller versions -We recommend upgrading to the latest release of NGINX Ingress Controller. We provide software updates for the most recent release. We provide technical support for F5 customers who are using the most recent version of NGINX Ingress Controller, and any version released within two years of the current release. +We recommend using the latest release of NGINX Ingress Controller. We provide software updates for the most recent release. We provide technical support for F5 customers who are using the most recent version of NGINX Ingress Controller, and any version released within two years of the current release. -Release 3.0.0 provides support for the `discovery.k8s.io/v1` API version of EndpointSlice, available from Kubernetes 1.21 onwards. -Release 2.4.2 is compatible with the Kubernetes Ingress v1 API, available in Kubernetes 1.19 and later. -Release 1.12 supports the Ingress v1beta1 API and continues to receive security fixes to support environments running Kubernetes versions older than 1.19. The v1beta1 Ingress API was deprecated in Kubernetes release 1.19, and removed in the Kubernetes 1.22. +- Release 3.0.0 provides support for the `discovery.k8s.io/v1` API version of EndpointSlice, available from Kubernetes 1.21 onwards. +- Release 2.4.2 is compatible with the Kubernetes Ingress v1 API, available in Kubernetes 1.19 and later. +- Release 1.12 supports the Ingress v1beta1 API and continues to receive security fixes to support environments running Kubernetes versions older than 1.19. The v1beta1 Ingress API was deprecated in Kubernetes release 1.19, and removed in the Kubernetes 1.22. -## Supported Kubernetes Versions +--- -We explicitly test NGINX Ingress Controller on a range of Kubernetes platforms for each release, and we list them in the [release notes]({{< relref "/releases.md" >}}). We provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider, and which passes the [Kubernetes conformance tests](https://www.cncf.io/certification/software-conformance/). +## Supported Kubernetes versions + +We test NGINX Ingress Controller on a range of Kubernetes platforms for each release, and list them in the [release notes]({{< relref "/releases.md" >}}). We provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider, and that passes the [Kubernetes conformance tests](https://www.cncf.io/certification/software-conformance/). {{< bootstrap-table "table table-bordered table-striped table-responsive" >}} | NIC Version | Supported Kubernetes Version | NIC Helm Chart Version | NIC Operator Version | NGINX / NGINX Plus version | @@ -41,7 +45,9 @@ We explicitly test NGINX Ingress Controller on a range of Kubernetes platforms f | 1.9.1 | 1.18 - 1.16 | 0.7.1 | 0.0.7 | 1.19.3 / R22 | {{% /bootstrap-table %}} -## Supported Docker Images +--- + +## Supported Docker images We provide the following Docker images, which include NGINX or NGINX Plus bundled with the Ingress Controller binary. @@ -57,13 +63,17 @@ _All images include NGINX 1.27.0._ |Ubi-based image | ``nginxcontrib/nginx:1.27.0-ubi``,
based on on ``redhat/ubi9-minimal`` | | ``nginx/nginx-ingress:3.5.2-ubi`` | arm64
amd64
ppc64le
s390x | {{% /bootstrap-table %}} +--- + ### Images with NGINX Plus _NGINX Plus images include NGINX Plus R31._ +--- + #### **F5 Container registry** -NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com` - see [Getting the NGINX Ingress Controller Image with JWT]({{}}) and [Getting the F5 Registry NGINX Ingress Controller Image]({{}}). +NGINX Plus images are available through the F5 Container registry `private-registry.nginx.com`, explained in the [Get the NGINX Ingress Controller image with JWT]({{}}) and [Get the F5 Registry NGINX Ingress Controller image]({{}}) topics. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| F5 Container Registry Image | Architectures | @@ -81,9 +91,13 @@ NGINX Plus images are available through the F5 Container registry `private-regis |Ubi-based image with NGINX App Protect WAF and DoS | ``redhat/ubi8`` | NGINX App Protect WAF and DoS

NGINX Plus JavaScript module | `nginx-ic-nap-dos/nginx-plus-ingress:3.5.2-ubi` | amd64 | {{% /bootstrap-table %}} +--- + #### **AWS Marketplace** -We also provide NGINX Plus images through the AWS Marketplace. Please see [Using the AWS Marketplace Ingress Controller Image]({{< relref "/installation/nic-images/using-aws-marketplace-image.md" >}}) for details on how to set up the required IAM resources in your EKS cluster. +NGINX Plus images are available through the AWS Marketplace. + +View the [Use the AWS Marketplace Ingress Controller image]({{< relref "/installation/nic-images/using-aws-marketplace-image.md" >}}) topic for details on how to set up the required IAM resources in your EKS cluster. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| AWS Marketplace Link | Architectures | @@ -94,8 +108,12 @@ We also provide NGINX Plus images through the AWS Marketplace. Please see [Using |Debian-based image with NGINX App Protect WAF and DoS | ``debian:11-slim`` | NGINX App Protect WAF and DoS

NGINX Plus JavaScript and OpenTracing modules

OpenTracing tracers for Jaeger

Zipkin and Datadog | [F5 NGINX Ingress Controller with F5 NGINX App Protect DoS](https://aws.amazon.com/marketplace/pp/prodview-sghjw2csktega) | amd64 | {{% /bootstrap-table %}} +--- + #### **Google Cloud Marketplace** -We also provide NGINX Plus images through the Google Cloud Marketplace. Please see [Using the GCP Marketplace NGINX Ingress Controller Image]({{< relref "/installation/nic-images/using-gcp-marketplace-package.md" >}}) for details on how to use them. +NGINX Plus images are available through the Google Cloud Marketplace. + +View the [Use the GCP Marketplace NGINX Ingress Controller image]({{< relref "/installation/nic-images/using-gcp-marketplace-package.md" >}}) topic for details on how to use them. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| GCP Marketplace Link | Architectures | @@ -105,7 +123,7 @@ We also provide NGINX Plus images through the Google Cloud Marketplace. Please s {{% /bootstrap-table %}} #### **Microsoft Azure Marketplace** -We also provide NGINX Plus image through the Microsoft Azure Marketplace. +NGINX Plus images are available through the Microsoft Azure Marketplace. {{< bootstrap-table "table table-striped table-bordered table-responsive" >}} |
Name
|
Base image
|
Third-party modules
| Azure Marketplace Link | Architectures | @@ -113,13 +131,17 @@ We also provide NGINX Plus image through the Microsoft Azure Marketplace. |Debian-based image | ``debian:12-slim`` | NGINX Plus JavaScript and OpenTracing modules

OpenTracing tracers for Jaeger

Zipkin and Datadog | [F5 NGINX Ingress Controller](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/nginxinc.nginx_ingress_premium) | amd64 | {{% /bootstrap-table %}} -### Custom Images +--- + +### Custom images -You can customize an existing Dockerfile or use it as a reference to create a new one, which is necessary for the following cases: +You can customize an existing Dockerfile or use it as a reference to create a new one, which is necessary when: - Choosing a different base image. - Installing additional NGINX modules. -## Supported Helm Versions +--- + +## Supported Helm versions NGINX Ingress Controller can be [installed]({{< relref "/installation/installing-nic/installation-with-helm.md" >}}) using Helm 3.0 or later. diff --git a/docs/content/usage-reporting.md b/docs/content/usage-reporting.md index bcb86fa2d1..ce23bc7c3b 100644 --- a/docs/content/usage-reporting.md +++ b/docs/content/usage-reporting.md @@ -2,18 +2,22 @@ docs: DOCS-1445 doctypes: - concept -title: Enabling Usage Reporting +title: Enable Usage Reporting toc: true weight: 1800 --- -This page describes how to enable Usage Reporting for NGINX Ingress Controller and how to view the usage data through the API. +This page describes how to enable Usage Reporting for F5 NGINX Ingress Controller and how to view usage data through the API. + +--- ## Overview 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 NGINX Ingress Controller whose nodes you would like reported. -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. +To use Usage Reporting, you must have access to NGINX Management Suite. For more information, see [NGINX Management Suite](https://www.f5.com/products/nginx/instance-manager/). Usage Reporting is a requirement of the new Flexible Consumption Program for NGINX Ingress Controller. + +--- ## Requirements @@ -30,7 +34,9 @@ In addition to the software requirements, you will need: [//]: # ( TODO: Update the image and tag after publish) -## Adding a User Account to NGINX Management Suite +--- + +## Add a user account to NGINX Management Suite Usage Reporting needs a user account to send usage data to NGINX Instance Manager: these are the steps involved. @@ -39,81 +45,101 @@ Usage Reporting needs a user account to send usage data to NGINX Instance Manage - 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. +1. Create a user account following the steps in [Add Users](https://docs.nginx.com/nginx-management-suite/admin-guides/access-control/set-up-rbac/#add-users) section of the NGINX Management Suite documentation. In step 6, assign the user to the role created above. Note that currently only "basic auth" authentication is supported for usage reporting purposes. -## Deploying Usage Reporting +--- -### Creating a Namespace +## Deploy Usage Reporting -1. Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: +### Create a namespace - ```shell - kubectl create namespace nginx-cluster-connector - ``` +Create the Kubernetes namespace `nginx-cluster-connector` for Usage Reporting: -### Passing the Credential to the NGINX Management Suite API + ```shell + kubectl create namespace nginx-cluster-connector + ``` -To make the credential available to Usage Reporting, we need to create a Kubernetes secret. +--- + +### Pass the credential to the NGINX Management Suite API + +To make the credential available to Usage Reporting, create a Kubernetes secret. The username and password created in the previous section are required to connect the NGINX Management Suite API. -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: +Both the username and password are stored in the Kubernetes Secret and need to be converted to base64. In this example the username will be `foo` and the password will be `bar`. + +To obtain the base64 representation of a string, use the following command: + +```shell +echo -n 'foo' | base64 +# Zm9v +echo -n 'bar' | base64 +# YmFy +``` - ```shell - echo -n 'foo' | base64 - # Zm9v - echo -n 'bar' | base64 - # YmFy - ``` +Add the following content to a text editor, and insert the base64 representations of the username and password (Obtained in the previous step) to the `data` parameter: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: nms-basic-auth + namespace: nginx-cluster-connector +type: kubernetes.io/basic-auth +data: + username: Zm9v # base64 representation of 'foo' + password: YmFy # base64 representation of 'bar' +``` -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: +Save this in a file named `nms-basic-auth.yaml`. In the example, the namespace is `nginx-cluster-connector` (The default namespace) and the secret name is `nms-basic-auth`. - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: nms-basic-auth - namespace: nginx-cluster-connector - type: kubernetes.io/basic-auth - data: - username: Zm9v # base64 representation of 'foo' obtained in step 1 - password: YmFy # base64 representation of 'bar' obtained in step 1 - ``` +If you are using a different namespace, change the namespace in the `metadata` section of the file above. - 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. +{{< note >}} Usage Reporting only supports basic-auth secret type in `data` format, not `stringData`, with the username and password encoded in base64. {{< /note >}} - 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: +### Deploy the Kubernetes secret to the Kubernetes cluster - ```shell - kubectl apply -f nms-basic-auth.yaml - ``` +```shell +kubectl apply -f nms-basic-auth.yaml +``` 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.5.2/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: +Download and save the deployment file [cluster-connector.yaml](https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/v3.5.2/examples/shared-examples/usage-reporting/cluster-connector.yaml). Edit the following under the `args` section and then save the file: - ```yaml - args: - - -nms-server-address=https://nms.example.com/api/platform/v1 - - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth - ``` +```yaml + args: + - -nms-server-address=https://nms.example.com/api/platform/v1 + - -nms-basic-auth-secret=nginx-cluster-connector/nms-basic-auth +``` -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`. +- `-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` +- `nms-basic-auth-secret` should be the namespace/name of the secret created in step 3: `nginx-cluster-connector/nms-basic-auth`. -For more information, read the [Command-line Arguments](#command-line-arguments) section. +For more information, read the [Command-line arguments](#command-line-arguments) section of this page. -6. To deploy Usage Reporting, run the following command to deploy it to your Kubernetes cluster: +--- - ```shell - kubectl apply -f cluster-connector.yaml - ``` +### Finish deployment + +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 +## 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 + +```shell curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage +``` +```json { "items": [ { @@ -168,10 +194,12 @@ 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: +You can query the usage data for a specific cluster by specifying the cluster uid in the endpoint, for example: -```json +```shell curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee-6c54-4b01-90e6-d701748f0851 +``` +```json { "metadata": { "displayName": "my-cluster", @@ -197,7 +225,9 @@ curl --user "foo:bar" https://nms.example.com/api/platform/v1/k8s-usage/d290f1ee } ``` -## Uninstalling Usage Reporting +--- + +## Uninstall Usage Reporting To remove Usage Reporting from your Kubernetes cluster, run the following command: @@ -205,29 +235,47 @@ To remove Usage Reporting from your Kubernetes cluster, run the following comman kubectl delete -f cluster-connector.yaml ``` -## Command-line Arguments +--- + +## Command-line arguments -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: +Usage Reporting supports several command-line arguments, which can be specified in the `args` section of the Kubernetes deployment file. + +The following is a list of the supported command-line arguments and their usage: + +--- ### -nms-server-address `` The address of the NGINX Management Suite host. IPv4 addresses and hostnames are supported. -Default `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. +Default: `http://apigw.nms.svc.cluster.local/api/platform/v1/k8s-usage`. + +--- ### -nms-basic-auth-secret `` Secret for basic authentication to the NGINX Management Suite API. The secret must be in `kubernetes.io/basic-auth` format using base64 encoding. -Format `/`. +Format: `/`. + +--- ### -cluster-display-name `` The display name of the Kubernetes cluster. +--- + ### -skip-tls-verify -Skip TLS verification for the NGINX Management Suite server. **For testing purposes with NGINX Management Suite server using self-assigned certificate.** +Skip TLS verification for the NGINX Management Suite server. + +{{< warning >}} This argument is intended for using a self-assigned certificate for testing purposes only. {{< /warning >}} + +--- ### -min-update-interval `` -The minimum interval between updates to the NGINX Management Suite. **For testing purposes only.** -Default `24h`. +The minimum interval between updates to the NGINX Management Suite. +Default: `24h`. + +{{< warning >}} This argument is intended for testing purposes only. {{< /warning >}}