diff --git a/content/nic/configuration/global-configuration/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index 499f7733a..3db2a3e56 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -235,7 +235,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic |*otel-exporter-header-value* | The value of a custom HTTP header to add to telemetry export request. `otel-exporter-endpoint` and `otel-exporter-header-name` required. | N/A | *"custom-value"* | |*otel-service-name* | Sets the `service.name` attribute of the OTel resource. `otel-exporter-endpoint` required. | N/A | *"nginx-ingress-controller:nginx"* | | *otel-trace-in-http* | Enables [OpenTelemetry](https://opentelemetry.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Set this to *"false"* to enable OpenTelemetry for individual routes with snippets. `otel-exporter-endpoint` required. | *"false"* | *"true"* | -|*opentracing* | Removed in v5.0.0. Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs]({{< ref "/nic/installation/integrations/opentracing.md" >}}) for more information. | *False* | | +|*opentracing* | Removed in v5.0.0. Enables [OpenTracing](https://opentracing.io) globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the [docs]({{< ref "/nic/logging-and-monitoring/opentracing.md" >}}) for more information. | *False* | | |*opentracing-tracer* | Removed in v5.0.0. Sets the path to the vendor tracer binary plugin. | N/A | | |*opentracing-tracer-config* | Removed in v5.0.0. Sets the tracer configuration in JSON format. | N/A | | |*app-protect-compressed-requests-action* | Sets the *app_protect_compressed_requests_action* [global directive](/nginx-app-protect/configuration/#global-directives). | *drop* | | diff --git a/content/nic/logging-and-monitoring/_index.md b/content/nic/logging-and-monitoring/_index.md index c2e745897..cfa385b92 100644 --- a/content/nic/logging-and-monitoring/_index.md +++ b/content/nic/logging-and-monitoring/_index.md @@ -1,9 +1,6 @@ --- -title: Logging And Monitoring +title: Logging and monitoring description: weight: 1500 url: /nginx-ingress-controller/logging-and-monitoring -menu: - docs: - parent: NGINX Ingress Controller --- diff --git a/content/nic/logging-and-monitoring/logging.md b/content/nic/logging-and-monitoring/logging.md index 2407b99a8..97c725a64 100644 --- a/content/nic/logging-and-monitoring/logging.md +++ b/content/nic/logging-and-monitoring/logging.md @@ -1,15 +1,19 @@ --- -title: Logging +title: Logs available from NGINX Ingress Controller toc: true -weight: 1800 +weight: 100 nd-content-type: reference nd-product: NIC nd-docs: DOCS-613 --- -This document gives an overview of logging provided by NGINX Ingress Controller. +This document gives an overview of logging provided by F5 NGINX Ingress Controller. -NGINX Ingress Controller exposes the logs of the Ingress Controller process (the process that generates NGINX configuration and reloads NGINX to apply it) and NGINX access and error logs. All logs are sent to the standard output and error of the NGINX Ingress Controller process. To view the logs, you can execute the `kubectl logs` command for an Ingress Controller pod. For example: +NGINX Ingress Controller exposes the logs of the Ingress Controller process (The process that generates NGINX configuration and reloads NGINX to apply it) and NGINX access and error logs. + +All logs are sent to the standard output and error of the NGINX Ingress Controller process. To view the logs, you can execute the `kubectl logs` command for an Ingress Controller pod. + +For example: ```shell kubectl logs -n nginx-ingress @@ -17,13 +21,17 @@ kubectl logs -n nginx-ingress ## NGINX Ingress Controller Process Logs -The NGINX Ingress Controller process logs are configured through the `-log-level` command-line argument of the NGINX Ingress Controller, which sets the log level. The default value is `info`. Other options include: `trace`, `debug`, `info`, `warning`, `error` and `fatal`. The value `debug` is useful for troubleshooting: you will be able to see how NGINX Ingress Controller gets updates from the Kubernetes API, generates NGINX configuration and reloads NGINX. +The NGINX Ingress Controller process logs are configured through the `-log-level` command-line argument of the NGINX Ingress Controller, which sets the log level. + +The default value is `info`. Other options include: `trace`, `debug`, `info`, `warning`, `error` and `fatal`. + +The value `debug` is useful for troubleshooting: you will be able to see how NGINX Ingress Controller gets updates from the Kubernetes API, generates NGINX configuration and reloads NGINX. -See also the doc about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). +Read more about NGINX Ingress Controller [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). ## NGINX Logs -The NGINX includes two logs: +NGINX includes two logs: - *Access log*, where NGINX writes information about client requests in the access log right after the request is processed. The access log is configured via the [logging-related]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#logging" >}}) ConfigMap keys: - `log-format` for HTTP and HTTPS traffic. @@ -32,4 +40,4 @@ The NGINX includes two logs: Additionally, you can disable access logging with the `access-log-off` ConfigMap key. - *Error log*, where NGINX writes information about encountered issues of different severity levels. It is configured via the `error-log-level` [ConfigMap key]({{< ref "/nic/configuration/global-configuration.md#configmap-resource#logging" >}}). To enable debug logging, set the level to `debug` and also set the `-nginx-debug` [command-line argument]({{< ref "/nic/configuration/global-configuration.md#command-line-arguments" >}}), so that NGINX is started with the debug binary `nginx-debug`. -See also the doc about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide. +Read more about [NGINX logs]({{< ref "/nginx/admin-guide/monitoring/logging.md" >}}) from NGINX Admin guide. diff --git a/content/nic/logging-and-monitoring/opentelemetry.md b/content/nic/logging-and-monitoring/opentelemetry.md new file mode 100644 index 000000000..c86779b21 --- /dev/null +++ b/content/nic/logging-and-monitoring/opentelemetry.md @@ -0,0 +1,105 @@ +--- +# We use sentence case and present imperative tone +title: "Enable OpenTelemetry" +# Weights are assigned in increments of 100: determines sorting order +weight: 300 +# Creates a table of contents and sidebar, useful for large documents +toc: true +# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this +nd-content-type: how-to +# Intended for internal catalogue and search, case sensitive: +# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +nd-product: NIC +--- + +This topic describes how to enable [OpenTelemetry](https://opentelemetry.io/) for F5 NGINX Ingress Controller using the [native NGINX module](https://nginx.org/en/docs/ngx_otel_module.html). + +## Before you begin + +To complete this guide, you need the following pre-requisites: + +- An [NGINX Ingress Controller installation]({{< ref "/nic/installation/" >}}) with OpenTelemetry (v5.1.0+) + +## Load the OpenTelemetry module + +To enable OpenTelemetry, you must first load the module by adding the [_otel-exporter-endpoint_ ConfigMap key]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#modules" >}}), which takes an endpoint argument. + +The following is an example of a OpenTelemetry collector running in your cluster as the target for exporting data: + +```yaml +otel-exporter-endpoint: "http://otel-collector.default.svc.cluster.local:4317" +``` + +A complete ConfigMap example with all OpenTelemetry options could look as follows: + +{{< ghcode "https://raw.githubusercontent.com/nginx/kubernetes-ingress/refs/heads/main/examples/shared-examples/otel/nginx-config.yaml" >}} + +## Enable OpenTelemetry + +Once you have loaded the module, you can now enable OpenTelemetry. + +You can configure it globally for all resources, or on a per resource basis. + +### Global + +To enable OpenTelemetry for all resources, set the _otel-trace-in-http_ ConfigMap key to `true`: + +```yaml +otel-trace-in-http: "true" +``` + +### Per resource + +You can configure OpenTelemetry on a per resource basis in NGINX Ingress Controller. + +For this functionality, you must [enable snippets]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-snippets.md" >}}) with the `-enable-snippets` command-line argument. + +Based on the state of global configuration, you can selectively enable or disable metrics for each resource. + +#### Enable a specific resource or path + +With OpenTelemetry **disabled** globally, you can enable it for a specific resource using the server snippet annotation: + +```yaml +nginx.org/server-snippets: | + otel_trace on; +``` + +You can enable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}). + +Use the server snippet annotation for the paths of a specific Minion Ingress resource: + +```yaml +nginx.org/location-snippets: | + otel_trace on; +``` + +#### Disable a specific resource or path + +With OpenTelemetry **enabled** globally, you can disable it for a specific resource using the server snippet annotation: + + ```yaml +nginx.org/server-snippets: | + otel_trace off; +``` + +You can disable it for specific paths using [Mergeable Ingress resources]({{< ref "/nic/configuration/ingress-resources/cross-namespace-configuration.md" >}}). + +Use the server snippet annotation for the paths of a specific Minion Ingress resource: + +```yaml +nginx.org/location-snippets: | + otel_trace off; +``` + +## Customize OpenTelemetry + +{{< call-out "note" >}} + +You cannot modify the additional directives in the _otel_exporter_ block using snippets. + +{{< /call-out >}} + +You can customize OpenTelemetry through the supported [OpenTelemetry module directives](https://nginx.org/en/docs/ngx_otel_module.html). + +Use the `location-snippets` ConfigMap keys or annotations to insert those directives into the generated NGINX configuration. \ No newline at end of file diff --git a/content/nic/installation/integrations/opentracing.md b/content/nic/logging-and-monitoring/opentracing.md similarity index 91% rename from content/nic/installation/integrations/opentracing.md rename to content/nic/logging-and-monitoring/opentracing.md index 2937594cb..9892313fa 100644 --- a/content/nic/installation/integrations/opentracing.md +++ b/content/nic/logging-and-monitoring/opentracing.md @@ -1,18 +1,24 @@ --- -nd-docs: DOCS-618 -doctypes: -- '' -title: OpenTracing (Removed in v5.0.0) +title: Enable OpenTracing (Removed in v5.0.0) toc: true -weight: 500 +weight: 700 +nd-content-type: how-to +nd-product: NIC +nd-docs: DOCS-618 --- -OpenTracing support has been removed from v5.0.0 of F5 NGINX Ingress Controller. - -Learn how to use OpenTracing with F5 NGINX Ingress Controller. +This topic describes how to OpenTracing with F5 NGINX Ingress Controller. NGINX Ingress Controller supports [OpenTracing](https://opentracing.io/) with the third-party module [opentracing-contrib/nginx-opentracing](https://github.com/opentracing-contrib/nginx-opentracing). +{{< call-out "warning" >}} + +OpenTracing support has been removed from v5.0.0 of NGINX Ingress Controller. + +From v5.1.0 onwards, you should follow the guidance in [Configure OpenTelemetry]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}). + +{{< /call-out >}} + ## Prerequisites 1. Use a NGINX Ingress Controller image that contains OpenTracing. diff --git a/content/nic/logging-and-monitoring/prometheus.md b/content/nic/logging-and-monitoring/prometheus.md index 17f32abe5..0bca69823 100644 --- a/content/nic/logging-and-monitoring/prometheus.md +++ b/content/nic/logging-and-monitoring/prometheus.md @@ -1,17 +1,41 @@ --- -nd-docs: DOCS-614 -doctypes: -- concept -title: Prometheus +title: Enable Prometheus metrics toc: true -weight: 2000 +weight: 400 +nd-content-type: how-to +nd-product: NIC +nd-docs: DOCS-614 --- -NGINX Ingress Controller exposes metrics in the [Prometheus](https://prometheus.io/) format. Those include NGINX/NGINX Plus and the Ingress Controller metrics. +This topic describes how to enable [Prometheus metrics](https://prometheus.io/) for F5 NGINX Ingress Controller. + +The metrics exposed include NGINX Ingress Controller data, as well as NGINX Open Source and NGINX Plus. ## Enabling Metrics +### Using Helm + +To enable Prometheus metrics when using *Helm* to install NGINX Ingress Controller, configure the `prometheus.*` parameters of the Helm chart. + +See the [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md" >}}) topic. + +#### Using ServiceMonitor + +When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters. +When these resources are deployed, Prometheus metrics exposed by NGINX Ingress Controller can be captured and enumerated using a `Prometheus` resource alongside a Prometheus Operator deployment. + +To view metrics captured this way, you will need: + +* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/) +* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository: + +```shell +LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name) +curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f - +``` + ### Using Manifests + If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics: 1. Run the Ingress Controller with the `-enable-prometheus-metrics` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument). @@ -32,23 +56,6 @@ If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the prometheus.io/scheme: http ``` -### Using Helm - -If you're using *Helm* to install the Ingress Controller, to enable Prometheus metrics, configure the `prometheus.*` parameters of the Helm chart. See the [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md" >}}) doc. - -### Using ServiceMonitor - -When deploying with *Helm*, you can deploy a `Service` and `ServiceMonitor` resource using the `prometheus.service.*` and `prometheus.serviceMonitor.*` parameters. -When these resources are deployed, Prometheus metrics exposed by NGINX Ingress Controller can be captured and enumerated using a `Prometheus` resource alongside a Prometheus Operator deployment. - -To view metrics captured this way, the following is required: -* The latest ServiceMonitor CRD from the [prometheus-operator](https://github.com/prometheus-operator/prometheus-operator) repository: -```shell -LATEST=$(curl -s https://api.github.com/repos/prometheus-operator/prometheus-operator/releases/latest | jq -cr .tag_name) -curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$LATEST/example/prometheus-operator-crd/monitoring.coreos.com_servicemonitors.yaml | kubectl create -f - -``` -* A working [Prometheus resource and Prometheus Operator](https://prometheus-operator.dev/docs/getting-started/introduction/) - ## Available Metrics The Ingress Controller exports the following metrics: diff --git a/content/nic/logging-and-monitoring/service-insight.md b/content/nic/logging-and-monitoring/service-insight.md index b2908d27c..35b4c89a8 100644 --- a/content/nic/logging-and-monitoring/service-insight.md +++ b/content/nic/logging-and-monitoring/service-insight.md @@ -1,7 +1,7 @@ --- -title: Service Insight +title: Enable Service Insight toc: true -weight: 2100 +weight: 600 nd-content-type: how-to nd-product: NIC nd-docs: DOCS-1180 diff --git a/content/nic/logging-and-monitoring/status-page.md b/content/nic/logging-and-monitoring/status-page.md index 0357f0fb1..8d7c42983 100644 --- a/content/nic/logging-and-monitoring/status-page.md +++ b/content/nic/logging-and-monitoring/status-page.md @@ -1,7 +1,7 @@ --- -title: Status Page +title: View the NGINX status page toc: true -weight: 1900 +weight: 200 nd-content-type: how-to nd-product: NIC nd-docs: DOCS-615 diff --git a/content/nic/releases.md b/content/nic/releases.md index bb9d4c584..ae1a4e1b6 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -14,11 +14,11 @@ This NGINX Ingress Controller release brings initial connectivity to the NGINX O This release also includes the ability to configure Rate Limiting for your APIs based on a specific NGINX variable and its value. This allows you more granular control over how frequently specific users access your resources. -Lastly, in our previous v5.0.0 release, we removed support for Open Tracing. This release replaces that observability capability with native NGINX Open Telemetry traces, allowing you to monitor the internal traffic of your applications. +Lastly, in our previous v5.0.0 release, we removed support for OpenTracing. This release replaces that observability capability with native [NGINX OpenTelemetry]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}) traces, allowing you to monitor the internal traffic of your applications. ### Features -- [7642](https://github.com/nginx/kubernetes-ingress/pull/7642) Add OpenTelemetry support -- [7916](https://github.com/nginx/kubernetes-ingress/pull/7916) Add support for NGINX Agent version 3 and Connecting to NGINX One Console +- [7642](https://github.com/nginx/kubernetes-ingress/pull/7642) Add [OpenTelemetry support]({{< ref "/nic/logging-and-monitoring/opentelemetry.md" >}}) +- [7916](https://github.com/nginx/kubernetes-ingress/pull/7916) Add support for NGINX Agent version 3 and NGINX One Console - [7884](https://github.com/nginx/kubernetes-ingress/pull/7884) Tiered rate limits with variables - [7765](https://github.com/nginx/kubernetes-ingress/pull/7765) Add OIDC PKCE configuration through Policy - [7832](https://github.com/nginx/kubernetes-ingress/pull/7832) Add request_method to rate-limit Policy @@ -63,17 +63,21 @@ versions: 1.25-1.33. Added support for [NGINX Plus R34]({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), users needing to use a forward proxy for license verification are now able to make use of the [`proxy`](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directives available in F5 NGINX Plus. -{{< important >}} -With the removal of the OpenTracing dynamic module from [NGINX Plus R34](({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), NGINX Ingress Controller also removes full OpenTracing support. This will affect users making use of OpenTracing with the ConfigMap, `server-snippets` & `location-snippets` parameters. Support for tracing with [OpenTelemetry]({{< ref "/nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) will come in a future release. -{{< /important >}} +{{< call-out "warning" >}} + +With the removal of the OpenTracing dynamic module from [NGINX Plus R34]({{< ref "/nginx/releases.md#nginxplusrelease-34-r34" >}}), NGINX Ingress Controller also removes full OpenTracing support. This will affect users making use of OpenTracing with the ConfigMap, `server-snippets` & `location-snippets` parameters. Support for tracing with [OpenTelemetry]({{< ref "/nginx/admin-guide/dynamic-modules/opentelemetry.md" >}}) will come in a future release. + +{{< /call-out >}} We have extended the rate-limit Policy to allow tiered rate limit groups with JWT claims. This will also allow users to apply different rate limits to their `VirtualServer` or `VirtualServerRoutes` with the value of a JWT claim. See [here](https://github.com/nginx/kubernetes-ingress/tree/v5.0.0/examples/custom-resources/rate-limit-tiered-jwt-claim/) for a working example. We introduced NGINX Plus Zone Sync as a managed service within NGINX Ingress Controller in this release. In previous releases, we had examples using `stream-snippets` for OIDC support, users can now enable `zone-sync` without the need for `snippets`. NGINX Plus Zone Sync is available when utilising two or more replicas, it supports OIDC & rate limiting. -{{< note >}} +{{< call-out "note" >}} + For users who have previously installed OIDC or used the `zone_sync` directive with `stream-snippets`, please see the note in the [Configmap resources]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#zone-sync" >}}) topic to use the new `zone-sync` ConfigMap option. -{{< /note >}} + +{{< /call-out >}} Open Source NGINX Ingress Controller architectures `armv7`, `s390x` & `ppc64le` are deprecated and will be removed in the next minor release. @@ -215,14 +219,14 @@ versions: 1.25-1.32. 25 Nov 2024 -{{< note >}} +{{< call-out "note" >}} In our next major release, `v4.0.0`, the default log library for NGINX Ingress Controller will be changed from `golang/glog` to `log/slog`. This will mean that logs generated by NGINX Ingress Controller will be in a structured format with the option to choose a `string` or `json` output. This will not affect logs generated by NGINX. To ensure backwards compatibility, we will ensure the existing log format, `glog`, will be maintained through a configuration option for the next 3 releases. -{{< /note >}} +{{< /call-out >}} -{{< important >}} +{{< call-out "important" >}} CRD version removal notice. In our next major release, `v4.0.0`, support for the following apiVersions for these listed CRDs will be dropped: 1. `k8s.nginx.org/v1alpha` for `GlobalConfiguration` @@ -233,7 +237,7 @@ Prior to upgrading, **please ensure** that any of these resources deployed as `a If a resource of `kind: GlobalConfiguration`, `kind: Policy` or `kind: TransportServer` are deployed as `apiVersion: k8s.nginx.org/v1alpha1`, these resources will be **deleted** when upgrading from, at least, `v3.4.0` to `v4.0.0` When `v4.0.0` is released, the release notes will contain the required upgrade steps to go from `v3.X.X` to `v4.X.X` -{{< /important >}} +{{< /call-out >}} ### Fixes - [6838](https://github.com/nginx/kubernetes-ingress/pull/6838) Update oidc_template and conf