diff --git a/content/nic/configuration/global-configuration/mgmt-configmap-resource.md b/content/nic/configuration/global-configuration/mgmt-configmap-resource.md index bd52fcdcf..a260a2d56 100644 --- a/content/nic/configuration/global-configuration/mgmt-configmap-resource.md +++ b/content/nic/configuration/global-configuration/mgmt-configmap-resource.md @@ -35,13 +35,13 @@ that make sense for your setup: |ConfigMap Key | Description | Default | | ---| ---| ---| -|*license-token-secret-name* | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | N/A | +|*license-token-secret-name* | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. Store the base64-encoded JWT in the `license.jwt` key. The secret can be a standard `Opaque` secret or an `nginx.com/license` secret. If the `license.jwt` key is absent, NGINX Ingress Controller rejects the secret. | N/A | |*ssl-verify* | Configures the [ssl_verify](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_verify) directive, which enables or disables verification of the usage reporting endpoint certificate. | `true` | |*enforce-initial-report* | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | `false` | |*usage-report-endpoint* | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NIM. | `product.connect.nginx.com` | |*usage-report-interval* | Configures the interval of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This specifies the frequency that usage reports are sent. This field takes an [NGINX time](https://nginx.org/en/docs/syntax.html). | `1h` | |*usage-report-proxy-host* | Configures the host name of the [proxy](https://nginx.org/en/docs/ngx_mgmt_module.html#proxy) directive with optional port. | N/A | -|*ssl-trusted-certificate-secret-name* | Configures the secret used to create the file(s) referenced the in [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.org/ca`, where the `ca.crt` key contains a base64 encoded trusted cert, and the optional `ca.crl` key can contain a base64 encoded CRL. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | +|*ssl-trusted-certificate-secret-name* | Configures the secret used to create the file(s) referenced in the [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. Store the base64-encoded trusted certificate in the `ca.crt` key, and an optional base64-encoded CRL in the `ca.crl` key. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. If the `ca.crt` key is absent, NGINX Ingress Controller rejects the secret. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | |*ssl-certificate-secret-name* | Configures the secret used to create the `ssl_certificate` and `ssl_certificate_key` directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `kubernetes.io/tls`| N/A | |*resolver-addresses* | Configures addresses used in the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive. This field takes a comma separated list of addresses. | N/A | |*resolver-ipv6* | Configures whether the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive will look up IPv6 addresses. | `true` | diff --git a/content/nic/configuration/policy-resource/policy-reference.md b/content/nic/configuration/policy-resource/policy-reference.md index 7e480044d..5ec205153 100644 --- a/content/nic/configuration/policy-resource/policy-reference.md +++ b/content/nic/configuration/policy-resource/policy-reference.md @@ -14,6 +14,17 @@ f5-audience: developer, operator This reference describes the fields and merging behavior for each Policy type. +{{< call-out class="note" >}} + +From version ``, NGINX Ingress Controller validates each referenced secret by its data keys, not by its `type`. Wherever a section below shows an `nginx.org/*` or `nginx.com/*` type, you can provide either of these: + +- A standard `Opaque` Kubernetes secret that holds the required keys, so you can reuse a secret that your existing credential tooling (for example, cert-manager, External Secrets Operator, or a GitOps pipeline) already produces. +- A secret of the NGINX-specific type shown for that field. + +Existing `nginx.org/*` and `nginx.com/*` secrets remain supported and aren't deprecated. When a required key is absent, or when a certificate or key doesn't parse, NGINX Ingress Controller rejects the secret. Add the missing key, or fix the certificate or key, to clear the rejection. NGINX Ingress Controller never rejects a secret because of the `type`. + +{{< /call-out >}} + ## AccessControl The access control policy configures NGINX to deny or allow requests from clients with the specified IP addresses or subnets. @@ -257,7 +268,7 @@ apiVersion: v1 kind: Secret metadata: name: api-key-secret -type: nginx.org/apikey +type: Opaque data: client1: cGFzc3dvcmQ= # password ``` @@ -269,7 +280,7 @@ data: |``suppliedIn`` | `header` or `query`. | | Yes | |``suppliedIn.header`` | An array of headers that the API Key may appear in. | ``string[]`` | No | |``suppliedIn.query`` | An array of query params that the API Key may appear in. | ``string[]`` | No | -|``clientSecret`` | The name of the Kubernetes secret that stores the API Key(s). It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/apikey``, and the API Key(s) must be stored in a key: val format where each key is a unique clientID and each value is a unique base64 encoded API Key | ``string`` | Yes | +|``clientSecret`` | The name of the Kubernetes secret that stores the API keys. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/apikey` secret. Store each API key as a key-value pair, where each key is a unique clientID and each value is a unique base64-encoded API key. | ``string`` | Yes | {{% /table %}} @@ -334,7 +345,7 @@ This feature uses the NGINX [ngx_http_auth_basic_module](https://nginx.org/en/do |Field | Description | Type | Required | | ---| ---| ---| --- | -|``secret`` | The name of the Kubernetes secret that stores the Htpasswd configuration. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/htpasswd``, and the config must be stored in the secret under the key ``htpasswd``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | Yes | +|``secret`` | The name of the Kubernetes secret that stores the Htpasswd configuration. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/htpasswd` secret. Store the configuration under the key `htpasswd`. | ``string`` | Yes | |``realm`` | The realm for the basic authentication. | ``string`` | No | {{% /table %}} @@ -398,7 +409,7 @@ This feature uses the NGINX Plus [ngx_http_auth_jwt_module](https://nginx.org/en |Field | Description | Type | Required | | ---| ---| ---| --- | -|``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/jwk``, and the JWK must be stored in the secret under the key ``jwk``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | Yes | +|``secret`` | The name of the Kubernetes secret that stores the JWK. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/jwk` secret. Store the JWK under the key `jwk`. | ``string`` | Yes | |``realm`` | The realm of the JWT. | ``string`` | Yes | |``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | @@ -456,7 +467,7 @@ Subrequests may not function as expected and may cause issues when fetching JWKs |``sniName`` | The SNI name to use when connecting to the remote server. If not set, NGINX Ingress Controller uses the hostname from the ``jwksURI``. | ``string`` | No | -- | |``sslVerify`` | Turns on verification of the JWKS server SSL certificate. | ``bool`` | No | `false` | |``sslVerifyDepth`` | Sets the verification depth in the JWKS server certificates chain. | ``int`` | No | `1` | -|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate for JWKS server verification. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``. | ``string`` | No | -- | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate for JWKS server verification. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | No | -- | {{% /table %}} @@ -491,14 +502,14 @@ ingressMTLS: verifyDepth: 1 ``` -Below is an example of `ingress-mtls-secret` using the secret type `nginx.org/ca`: +Below is an example of `ingress-mtls-secret` as a standard `Opaque` secret: ```yaml kind: Secret metadata: name: ingress-mtls-secret apiVersion: v1 -type: nginx.org/ca +type: Opaque data: ca.crt: ``` @@ -547,7 +558,7 @@ You can use only one of these configuration options at a time. {{< /call-out >}} -1. Add the `ca.crl` field to the `nginx.org/ca` secret type, which accepts a base64 encoded certificate revocation list. +1. Add the `ca.crl` field to the secret. The field accepts a base64-encoded certificate revocation list. Example: @@ -556,7 +567,7 @@ You can use only one of these configuration options at a time. metadata: name: ingress-mtls-secret apiVersion: v1 - type: nginx.org/ca + type: Opaque data: ca.crt: ca.crl: @@ -566,7 +577,7 @@ You can use only one of these configuration options at a time. {{< call-out class="note" >}} - Use this configuration option only when your CRL is larger than 1 MiB. Otherwise, use the `nginx.org/ca` secret type to manage your CRL. + Use this configuration option only when your CRL is larger than 1 MiB. Otherwise, add the `ca.crl` key to the secret to manage your CRL. {{< /call-out >}} @@ -600,7 +611,7 @@ See the Kubernetes documentation on [volumes](https://kubernetes.io/docs/concept |Field | Description | Type | Required | | ---| ---| ---| --- | -|``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | Yes | +|``clientCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | Yes | |``verifyClient`` | Verification for the client. Possible values are ``"on"``, ``"off"``, ``"optional"``, ``"optional_no_ca"``. The default is ``"on"``. | ``string`` | No | |``verifyDepth`` | Sets the verification depth in the client certificates chain. The default is ``1``. | ``int`` | No | |``crlFileName`` | The file name of the Certificate Revocation List. NGINX Ingress Controller looks for this file in `/etc/nginx/secrets`. | ``string`` | No | @@ -643,8 +654,8 @@ This feature uses the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/ht |Field | Description | Type | Required | | ---| ---| ---| --- | -|``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. The secret must be of the type ``kubernetes.io/tls``, the certificate must be stored in the secret under the key ``tls.crt``, and the key must be stored under the key ``tls.key``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | No | -|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | No | +|``tlsSecret`` | The name of the Kubernetes secret that stores the TLS certificate and key. It must be in the same namespace as the Policy resource. Use a `kubernetes.io/tls` secret, with the certificate under the key `tls.crt` and the key under `tls.key`. If either key is absent, or the certificate and key don't form a valid pair, NGINX Ingress Controller rejects the secret. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | No | |``verifyServer`` | Turns on verification of the upstream HTTPS server certificate. | ``bool`` | No | |``verifyDepth`` | Sets the verification depth in the proxied HTTPS server certificates chain. The default is ``1``. | ``int`` | No | |``sessionReuse`` | Turns on reuse of SSL sessions to the upstreams. The default is ``true``. | ``bool`` | No | @@ -716,7 +727,7 @@ An example ExternalAuth policy for VirtualServer resources is available in the G |``sslEnabled`` | Turns on HTTPS when proxying requests to the external authentication server. The default is ``false``. | ``bool`` | No | |``sslVerify`` | Turns on verification of the external authentication server's SSL certificate. The default is ``false``. | ``bool`` | No | |``sslVerifyDepth`` | Sets the verification depth in the external authentication server certificates chain. The default is ``1``. | ``int`` | No | -|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate for external authentication server certificate verification. Can include an optional namespace prefix as ``/``. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored under the key ``ca.crt``. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate for external authentication server certificate verification. Can include an optional namespace prefix as ``/``. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | No | |``sniName`` | The server name used for SNI and certificate verification when connecting to the external authentication server over TLS. If not specified, defaults to ``..svc`` derived from ``authServiceName``. | ``string`` | No | {{% /table %}} @@ -800,7 +811,7 @@ The OIDC policy defines a few internal locations that you can't customize: `/_jw |Field | Description | Type | Required | | ---| ---| ---| --- | |``clientID`` | The client ID provided by your OpenID Connect provider. | ``string`` | Yes | -|``clientSecret`` | The name of the Kubernetes secret that stores the client secret provided by your OpenID Connect provider. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/oidc``, and the secret stored under the key ``client-secret``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. If you enable PKCE, don't configure this field. | ``string`` | Yes | +|``clientSecret`` | The name of the Kubernetes secret that stores the client secret provided by your OpenID Connect provider. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/oidc` secret. Store the client secret under the key `client-secret`. If you turn on PKCE, don't configure this field. | ``string`` | Yes | |``authEndpoint`` | URL for the authorization endpoint provided by your OpenID Connect provider. | ``string`` | Yes | |``authExtraArgs`` | A list of extra URL arguments to pass to the authorization endpoint provided by your OpenID Connect provider. Arguments must be URL encoded, multiple arguments may be included in the list, for example ``[ arg1=value1, arg2=value2 ]`` | ``string[]`` | No | |``tokenEndpoint`` | URL for the token endpoint provided by your OpenID Connect provider. | ``string`` | Yes | @@ -814,7 +825,7 @@ The OIDC policy defines a few internal locations that you can't customize: `/_jw |``pkceEnable`` | Turns on Proof Key for Code Exchange. The OpenID client needs to be in public mode. `clientSecret` is not used in this mode. | ``boolean`` | No | |``sslVerify`` | Use this option to turn on TLS verification when calls are made to the IDP endpoints. | ``boolean`` | No | |``verifyDepth`` | Sets the verification depth in the proxied HTTPS server certificates chain. The default is ``1``. | ``int`` | No | -|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret must be of the type ``nginx.org/ca``, and the certificate must be stored in the secret under the key ``ca.crt``. Otherwise, NGINX Ingress Controller rejects the secret as invalid. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores the CA certificate. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | No | {{% /table %}} @@ -911,7 +922,7 @@ On a VirtualServer, if you apply both an `oidc` policy and an `oidcNative` polic | --- | --- | --- | --- | --- | | `issuer` | The Issuer Identifier URL of the OpenID Provider. Must use the `https` scheme and exactly match the value of `issuer` in the OpenID Provider metadata. | `string` | Yes | -- | | `clientID` | The client ID provided by your OpenID Connect provider. | `string` | Yes | -- | -| `clientSecret` | The name of the Kubernetes secret that stores the client secret. Must be of type `nginx.org/oidc` with the secret stored under the key `client-secret` and must be in the same namespace as the Policy resource. Not required when PKCE is enabled with a public client. | `string` | No | -- | +| `clientSecret` | The name of the Kubernetes secret that stores the client secret. It must be in the same namespace as the Policy resource. The secret can be a standard `Opaque` secret or an `nginx.org/oidc` secret. Store the client secret under the key `client-secret`. Not required when PKCE is turned on with a public client. | `string` | No | -- | | `configURL` | The URL of the OpenID Provider Configuration Information (discovery endpoint). Must include a path and use the `http` or `https` scheme. If not set, defaults to `/.well-known/openid-configuration`. | `string` | No | `/.well-known/openid-configuration` | | `scope` | Space-separated list of OpenID Connect scopes. Must contain `openid`. Example: `"openid profile email"`. | `string` | No | `openid` | | `redirectURI` | Overrides the default redirect URI path used for the authorization callback. | `string` | No | `/oidc_callback_` | @@ -924,7 +935,7 @@ On a VirtualServer, if you apply both an `oidc` policy and an `oidcNative` polic | `logoutTokenHint` | Adds the `id_token_hint` argument to the provider's logout endpoint when redirecting the user during logout. Required by some providers. | `bool` | No | `false` | | `sessionTimeout` | Duration after which the session expires unless refreshed. Example: `"8h"`, `"30m"`. | `string` | No | `8h` | | `userInfoEnable` | Turns on downloading of the UserInfo data and makes UserInfo claims available through `$oidc_claim_` variables. | `bool` | No | `false` | -| `trustedCertSecret` | The name of the Kubernetes secret that stores the CA certificate for verifying the provider's TLS certificate. Must be of type `nginx.org/ca` with the certificate stored under key `ca.crt`. | `string` | No | -- | +| `trustedCertSecret` | The name of the Kubernetes secret that stores the CA certificate for verifying the provider's TLS certificate. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | `string` | No | -- | | `sslVerify` | Turns on verification of the OpenID Provider's TLS certificate. Set to false to skip verification (dev/test only). | `bool` | No | `true` | | `sslName` | Overrides the TLS SNI name and Host header used when connecting to the OpenID Provider. Must be a valid DNS name and can't include a port. When unset, the hostname of the endpoint being called is used, taken from the provider's discovery metadata. | `string` | No | -- | | `sslVerifyDepth` | Verification depth in the OpenID Provider TLS certificate chain. | `int` | No | `1` | @@ -1250,8 +1261,8 @@ For details and examples, see [Connect F5 WAF for NGINX to bundle sources]({{< r |``namespace`` | Management-plane namespace or tenant. Required for ``N1C``. Not used for ``NIM`` or ``HTTPS``. | ``string`` | No | |``enablePolling`` | Must be explicitly set. When ``true``, NIC re-fetches the bundle at ``pollInterval``. When ``false``, NIC fetches the bundle once at policy creation or update. | ``bool`` | Yes | |``pollInterval`` | How often to re-fetch when ``enablePolling`` is ``true``. Minimum ``1m``, default ``5m``. | ``string`` | No | -|``secret`` | Secret in the same namespace as the Policy. For ``N1C``/``NIM``, use ``nginx.com/waf-bundle`` (token or username/password). For ``HTTPS``, use ``kubernetes.io/tls`` for client mTLS (``tls.crt`` and ``tls.key``). | ``string`` | No | -|``trustedCertSecret`` | Name of an ``nginx.org/ca`` Secret containing a custom CA certificate (``ca.crt``) for verifying the server TLS certificate. Must be in the same namespace as the Policy. | ``string`` | No | +|``secret`` | Secret in the same namespace as the Policy. For `N1C` and `NIM`, use a standard `Opaque` secret or an `nginx.com/waf-bundle` secret, with the credentials under `token`, or under `username` and `password`. For `HTTPS`, use a `kubernetes.io/tls` secret for client mTLS, with `tls.crt` and `tls.key`. | ``string`` | No | +|``trustedCertSecret`` | The name of the Kubernetes secret that stores a custom CA certificate for verifying the server TLS certificate. It must be in the same namespace as the Policy. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. Store the certificate under the key `ca.crt`. | ``string`` | No | |``insecureSkipVerify`` | Turns off TLS certificate verification. Not recommended for production. | ``bool`` | No | |``verifyChecksum`` | Turns on SHA-256 verification of the downloaded bundle. HTTPS only. | ``bool`` | No | |``timeout`` | Time limit for a single bundle fetch request. Default ``60s``. | ``string`` | No | diff --git a/content/nic/install/helm/parameters.md b/content/nic/install/helm/parameters.md index 012376501..6277fe7f6 100644 --- a/content/nic/install/helm/parameters.md +++ b/content/nic/install/helm/parameters.md @@ -29,7 +29,7 @@ The [values.schema.json](https://github.com/nginx/kubernetes-ingress/blob/main/c | **controller.kind** | The kind of the NGINX Ingress Controller installation - deployment, daemonset, or statefulset. | deployment | | **controller.annotations** | Allows for setting of `annotations` for deployment, daemonset, or statefulset. | {} | | **controller.nginxplus** | Deploys NGINX Ingress Controller for NGINX Plus. | false | -| **controller.mgmt.licenseTokenSecretName** | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | license-token | +| **controller.mgmt.licenseTokenSecretName** | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. Store the base64-encoded JWT in the `license.jwt` key. The secret can be a standard `Opaque` secret or an `nginx.com/license` secret. | license-token | | **controller.mgmt.enforceInitialReport** | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | false | | **controller.mgmt.usageReport.endpoint** | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NGINX Instance Manager . | product.connect.nginx.com | | **controller.mgmt.usageReport.interval** | Configures the interval of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This specifies the frequency that usage reports are sent. Only seconds(s), minutes(m), and hours(h) are allowed and must be between 60s and 24h. | 1h | @@ -40,7 +40,7 @@ The [values.schema.json](https://github.com/nginx/kubernetes-ingress/blob/main/c | **controller.mgmt.resolver.valid** | Configures an [NGINX time](https://nginx.org/en/docs/syntax.html) that the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive will override the TTL value of responses from nameservers with. | N/A | | **controller.mgmt.resolver.addresses** | Configures addresses used in the mgmt block [resolver](https://nginx.org/en/docs/ngx_mgmt_module.html#resolver) directive. This field takes a list of addresses. | N/A | | **controller.mgmt.sslCertificateSecretName** | Configures the secret used to create the `ssl_certificate` and `ssl_certificate_key` directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `kubernetes.io/tls` | N/A | -| **controller.mgmt.sslTrustedCertificateSecretName** | Configures the secret used to create the file(s) referenced the in [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.org/ca`, where the `ca.crt` key contains a base64 encoded trusted cert, and the optional `ca.crl` key can contain a base64 encoded CRL. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | +| **controller.mgmt.sslTrustedCertificateSecretName** | Configures the secret used to create the file(s) referenced in the [ssl_trusted_certifcate](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_trusted_certificate), and [ssl_crl](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directives. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. Store the base64-encoded trusted certificate in the `ca.crt` key, and an optional base64-encoded CRL in the `ca.crl` key. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret. If the optional `ca.crl` key is supplied, it will configure the NGINX `ssl_crl` directive. | N/A | | **controller.mgmt.configMapName** | Allows changing the name of the MGMT config map. The name should not include a namespace| Autogenerated | | **controller.nginxReloadTimeout** | The timeout in milliseconds which the NGINX Ingress Controller will wait for a successful NGINX reload after a change or at the initial start. | 60000 | | **controller.hostNetwork** | Enables NGINX Ingress Controller pods to use the host's network namespace. | false | diff --git a/content/nic/install/helm/plus.md b/content/nic/install/helm/plus.md index 353b7ca8a..a81011aa5 100644 --- a/content/nic/install/helm/plus.md +++ b/content/nic/install/helm/plus.md @@ -37,7 +37,7 @@ These commands should be run in the same directory as your **license.jwt** file. Create a secret for the NGINX Plus license: ```shell -kubectl create secret generic nplus-license --from-file=license.jwt --type=nginx.com/license +kubectl create secret generic nplus-license --from-file=license.jwt ``` Create a secret for the F5 registry: @@ -98,7 +98,7 @@ JWTs are sensitive information and should be stored securely. Delete them after Once you have obtained your license JWT, create a Kubernetes secret using `kubectl create`: ```shell -kubectl create secret generic nplus-license --from-file license.jwt +kubectl create secret generic nplus-license --from-file=license.jwt ``` {{< details summary="Example output" >}} diff --git a/content/nic/install/license-secret.md b/content/nic/install/license-secret.md index 6051609a8..7e67356aa 100644 --- a/content/nic/install/license-secret.md +++ b/content/nic/install/license-secret.md @@ -29,12 +29,12 @@ The JWT is required for validating your subscription and reporting telemetry dat The JWT needs to be configured before deploying NGINX Ingress Controller. -It must be stored in a Kubernetes Secret of type `nginx.com/license` in the same namespace as your NGINX Ingress Controller pod(s). +From NGINX Ingress Controller ``, store the JWT in a Kubernetes secret. Put it in the same namespace as your NGINX Ingress Controller pods. NGINX Ingress Controller validates the secret by its `license.jwt` key, so the secret can be a standard `Opaque` secret or an `nginx.com/license` secret. If the `license.jwt` key is absent, NGINX Ingress Controller rejects the secret. Add the key to resolve it. Create the Secret with the following command: ```shell -kubectl create secret generic license-token --from-file=license.jwt= --type=nginx.com/license -n +kubectl create secret generic license-token --from-file=license.jwt= -n ``` Once created, you can download the `.jwt` file. @@ -54,7 +54,6 @@ kubectl create secret generic license-token \ --save-config \ --dry-run=client \ --from-file=license.jwt= \ ---type=nginx.com/license \ -o yaml | \ kubectl apply -f - ``` @@ -123,13 +122,12 @@ To use Client Auth with NGINX Instance Manager, first create a Secret of type `k kubectl create secret tls ssl-certificate --cert= --key= -n ``` -To provide a SSL trusted certificate, and an optional Certificate Revocation List, create a Secret of type `nginx.org/ca` in the Namespace that the NIC Pod(s) are in. +To provide an SSL trusted certificate and an optional certificate revocation list, create a secret. Put it in the same namespace as the NGINX Ingress Controller pods. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret: ```shell kubectl create secret generic ssl-trusted-certificate \ --from-file=ca.crt= \ - --from-file=ca.crl= \ # optional - --type=nginx.org/ca + --from-file=ca.crl= # optional ``` Providing an optional CRL (certificate revocation list) will configure the [`ssl_crl`](https://nginx.org/en/docs/ngx_mgmt_module.html#ssl_crl) directive. diff --git a/content/nic/install/plm-installation.md b/content/nic/install/plm-installation.md index 59bd61d0f..26a63c425 100644 --- a/content/nic/install/plm-installation.md +++ b/content/nic/install/plm-installation.md @@ -125,8 +125,7 @@ kubectl create secret docker-registry regcred \ kubectl create secret generic license-token \ --namespace nginx-ingress \ - --from-file=license.jwt=nginx-repo.jwt \ - --type=nginx.com/license + --from-file=license.jwt=nginx-repo.jwt ``` Add the NGINX Helm repository: diff --git a/content/nic/install/waf-helm.md b/content/nic/install/waf-helm.md index 46bbf0f7c..dd36cbc71 100644 --- a/content/nic/install/waf-helm.md +++ b/content/nic/install/waf-helm.md @@ -152,10 +152,11 @@ kubectl create secret \ kubectl create secret \ generic license-token \ - --from-file=license.jwt=./nginx-repo.jwt \ - --type=nginx.com/license + --from-file=license.jwt=./nginx-repo.jwt ``` +This creates a standard `Opaque` secret. An `nginx.com/license` secret also works. + Install the required CRDs for NGINX Ingress Controller: ```shell diff --git a/content/nic/integrations/app-protect-waf-v5/bundle-sources.md b/content/nic/integrations/app-protect-waf-v5/bundle-sources.md index b87c2e74b..c116fd044 100644 --- a/content/nic/integrations/app-protect-waf-v5/bundle-sources.md +++ b/content/nic/integrations/app-protect-waf-v5/bundle-sources.md @@ -43,13 +43,12 @@ Complete end-to-end NGINX Ingress Controller with F5 WAF for NGINX bundle source ### Create a credentials Secret -Create a Secret of type `nginx.com/waf-bundle` in the same namespace as the Policy. The Secret must contain a `token` key with your NGINX One Console API token: +Create a secret in the same namespace as the Policy to hold your NGINX One Console API token. From NGINX Ingress Controller ``, the secret can be a standard `Opaque` secret or an `nginx.com/waf-bundle` secret. If the `token` key is absent, NGINX Ingress Controller rejects the secret. Store the token under the key `token`: To create an API token, see [Authentication]({{< ref "/nginx-one-console/api/authentication.md" >}}). ```shell kubectl create secret generic n1c-credentials \ - --type=nginx.com/waf-bundle \ --from-literal=token= ``` @@ -114,7 +113,7 @@ For complete HTTPS setup manifests, see the [bundle server files](https://github kubectl describe policy waf-policy ``` - Look for a `Normal` event confirming the bundle was fetched. If you see a `Warning` event, check the message for the cause — common issues include an incorrect `policyName`, an invalid token, or a policy that has not been published yet. + Look for a `Normal` event confirming the bundle was fetched. If you see a `Warning` event, check the message for the cause — common issues include an incorrect `policyName`, an invalid token, or a policy that has not been published yet. NGINX Ingress Controller also rejects a secret that is missing the required `token` key. 1. Send a legitimate request to confirm traffic flows normally: @@ -199,7 +198,7 @@ kubectl exec -it -- cat /var/log/messages ### Create a credentials Secret -Create a Secret of type `nginx.com/waf-bundle` in the same namespace as the Policy. Use a `token` key for bearer auth, or `username` and `password` keys for basic auth: +Create a secret in the same namespace as the Policy. The secret can be a standard `Opaque` secret or an `nginx.com/waf-bundle` secret. If neither the `token` key nor the `username` and `password` keys are present, NGINX Ingress Controller rejects the secret. For bearer auth, store the token under the key `token`. For basic auth, store the credentials under the keys `username` and `password`: If you use bearer auth, get an access token using your configured authentication flow. For supported methods, see [API Overview]({{< ref "/nim/fundamentals/api-overview.md#authentication" >}}). @@ -209,7 +208,6 @@ If you use bearer auth, get an access token using your configured authentication ```shell kubectl create secret generic nim-credentials \ - --type=nginx.com/waf-bundle \ --from-literal=token= ``` @@ -219,7 +217,6 @@ kubectl create secret generic nim-credentials \ ```shell kubectl create secret generic nim-credentials \ - --type=nginx.com/waf-bundle \ --from-literal=username= \ --from-literal=password= ``` @@ -286,7 +283,7 @@ For complete end-to-end manifests, see the [waf-management-plane examples](https kubectl describe policy waf-policy ``` - Look for a `Normal` event confirming the bundle was fetched. If you see a `Warning` event, check the message for the cause — common issues include an incorrect `policyName`, authentication failure, or a bundle that has not been compiled yet. + Look for a `Normal` event confirming the bundle was fetched. If you see a `Warning` event, check the message for the cause — common issues include an incorrect `policyName`, authentication failure, or a bundle that has not been compiled yet. NGINX Ingress Controller also rejects a secret with neither the `token` key nor the `username` and `password` keys. 1. Send a legitimate request to confirm traffic flows normally: @@ -405,11 +402,10 @@ After compiling your policy with the [F5 WAF compiler]({{< ref "/waf/configure/c Skip this step if your HTTPS server uses a publicly trusted certificate. -- **Custom CA certificate** — If your server uses a self-signed or internal CA, create a Secret of type `nginx.org/ca` with a `ca.crt` key, and reference it in `trustedCertSecret`: +- **Custom CA certificate** — If your server uses a self-signed or internal CA, create a secret with a `ca.crt` key. If the `ca.crt` key is absent, NGINX Ingress Controller rejects the secret. Reference it in `trustedCertSecret`. The secret can be a standard `Opaque` secret or an `nginx.org/ca` secret: ```shell kubectl create secret generic bundle-ca-cert \ - --type=nginx.org/ca \ --from-file=ca.crt= ``` diff --git a/content/nic/overview/design.md b/content/nic/overview/design.md index afe870f41..da41cc732 100644 --- a/content/nic/overview/design.md +++ b/content/nic/overview/design.md @@ -86,7 +86,7 @@ The previous diagram depicts NGINX Ingress Controller using NGINX. NGINX Ingress - To configure NGINX Plus, NGINX Ingress Controller uses [configuration reloads](#reloading-nginx) and the [NGINX Plus API](http://nginx.org/en/docs/http/ngx_http_api_module.html#api). This allows NGINX Ingress Controller to dynamically change the upstream servers. - 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 Controller writes JWKs from the secrets of the type `nginx.org/jwk`, and NGINX workers read them. +- In addition to TLS certs and keys, NGINX Ingress Controller writes JWKs from secrets that contain a `jwk` key, and NGINX workers read them. ## The NGINX Ingress Controller process @@ -241,7 +241,7 @@ Ultimately, NGINX Ingress Controller ensures the NGINX config on the filesystem ##### LocalSecretStore -[_LocalSecretStore_](https://github.com/nginx/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`). +[_LocalSecretStore_](https://github.com/nginx/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 (`tls.crt` and `tls.key`), CAs (`ca.crt`), JWKs (`jwk`), and client secrets for an OIDC provider (`client-secret`). 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).