From de86f566efa744255644444cdb061265d12e54a5 Mon Sep 17 00:00:00 2001 From: Sarthak Agrawal <68310924+sarthyparty@users.noreply.github.com> Date: Wed, 3 Sep 2025 10:16:01 -0700 Subject: [PATCH 01/17] Update compability doc (#1054) Update compatability doc with Port for ParentRef --- content/ngf/overview/gateway-api-compatibility.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index ab641d44c..f78d051c2 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -146,7 +146,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command **Fields**: - `spec` - - `parentRefs`: Partially supported. Port not supported. + - `parentRefs`: Supported. - `hostnames`: Supported. - `rules` - `matches` @@ -196,7 +196,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command **Fields**: - `spec` - - `parentRefs`: Partially supported. Port not supported. + - `parentRefs`: Supported. - `hostnames`: Supported. - `rules` - `matches` @@ -259,7 +259,7 @@ Fields: **Fields**: - `spec` - - `parentRefs`: Partially supported. Port not supported. + - `parentRefs`: Supported. - `hostnames`: Supported. - `rules` - `backendRefs`: Partially supported. Only one backend ref allowed. From ecb9222fa95f0258120599a073ee82587584d3c0 Mon Sep 17 00:00:00 2001 From: bjee19 <139261241+bjee19@users.noreply.github.com> Date: Mon, 15 Sep 2025 15:49:48 -0700 Subject: [PATCH 02/17] NGF: Update gateway addresses compatibility document (#1109) Update gateway addresses compatibility document. --- content/ngf/overview/gateway-api-compatibility.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index f78d051c2..c64e0872e 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -101,7 +101,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `certificateRefs` - The TLS certificate and key must be stored in a Secret resource of type `kubernetes.io/tls`. Only a single reference is supported. - `options`: Not supported. - `allowedRoutes`: Supported. - - `addresses`: Not supported. + - `addresses`: Valid IPAddresses will be added to the `externalIP` field in the related Services fronting NGINX. + - `type`: Partially supported. Allowed value: `IPAddress`. + - `value`: Partially supported. Dynamic address allocation when value is unspecified is not supported. - `backendTLS`: Not supported. - `allowedListeners`: Not supported. - `status` From 29a305d65ad37b8eb9c5da249a0f5ac7648f77bd Mon Sep 17 00:00:00 2001 From: bjee19 <139261241+bjee19@users.noreply.github.com> Date: Tue, 16 Sep 2025 16:37:03 -0700 Subject: [PATCH 03/17] NGF: Update gateway addresses compatibility document with IP family comment (#1126) Add a small comment on IP families to gateway addresses compatibility document. --- content/ngf/overview/gateway-api-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index c64e0872e..5b9cd9d3e 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -101,7 +101,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `certificateRefs` - The TLS certificate and key must be stored in a Secret resource of type `kubernetes.io/tls`. Only a single reference is supported. - `options`: Not supported. - `allowedRoutes`: Supported. - - `addresses`: Valid IPAddresses will be added to the `externalIP` field in the related Services fronting NGINX. + - `addresses`: Valid IPAddresses will be added to the `externalIP` field in the related Services fronting NGINX. Users should ensure that the IP Family of the address matches the IP Family set in the NginxProxy resource (default is dual, meaning both IPv4 and IPv6), otherwise there may be networking issues. - `type`: Partially supported. Allowed value: `IPAddress`. - `value`: Partially supported. Dynamic address allocation when value is unspecified is not supported. - `backendTLS`: Not supported. From 8d59f4265df29a51a05ed2daab57946e8b327784 Mon Sep 17 00:00:00 2001 From: "Tina U." Date: Wed, 17 Sep 2025 15:14:25 +0100 Subject: [PATCH 04/17] New NGF CLI parameter for Trial period enforcement (#1128) --- content/ngf/reference/cli-help.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/ngf/reference/cli-help.md b/content/ngf/reference/cli-help.md index a25a2faff..e97631e13 100644 --- a/content/ngf/reference/cli-help.md +++ b/content/ngf/reference/cli-help.md @@ -50,6 +50,7 @@ This command runs the NGINX Gateway Fabric control plane. | _usage-report-skip-verify_ | _bool_ | Disable client verification of the NGINX Plus usage reporting server certificate. | | _usage-report-ca-secret_ | _string_ | The name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway) | | _usage-report-client-ssl-secret_ | _string_ | The name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway) | +| _usage-report-enforce-initial-report_ | _bool_ | Enables or disables the 180-day grace period for sending the initial usage report. | | _snippets-filters_ | _bool_ | Enable SnippetsFilters feature. SnippetsFilters allow inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources. | | _nginx-scc_ | _string_ | The name of the SecurityContextConstraints to be used with the NGINX data plane Pods. Only applicable in OpenShift. | | _nginx-one-dataplane-key-secret_ | _string_ | The name of the secret which holds the dataplane key that is required to authenticate with the NGINX One Console. Secret must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). | From 6822326dbadfffefcaa3d69e23a7be2615b0d5d0 Mon Sep 17 00:00:00 2001 From: "Tina U." Date: Thu, 9 Oct 2025 17:57:52 +0100 Subject: [PATCH 05/17] RouteRules and Gateway unsupported fields update (#1268) Added mention about unsupported fields for RouteRules and Gateways Closes nginx/nginx-gateway-fabric#3784 --- .../ngf/overview/gateway-api-compatibility.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/ngf/overview/gateway-api-compatibility.md b/content/ngf/overview/gateway-api-compatibility.md index 924b13130..6ad9b4116 100644 --- a/content/ngf/overview/gateway-api-compatibility.md +++ b/content/ngf/overview/gateway-api-compatibility.md @@ -36,7 +36,10 @@ Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/ - _Not supported_. The resource or field is not yet supported. It will become partially or fully supported in future releases. -{{< call-out "note" >}} It's possible that NGINX Gateway Fabric will never support some resources or fields of the Gateway API. They will be documented on a case by case basis. {{< /call-out >}} +{{< call-out "note" >}} It's possible that NGINX Gateway Fabric will never support some resources or fields of the Gateway API. They will be documented on a case by case basis. + +Please note that while we make every effort to reflect the support status of experimental fields in our code and documentation, there may be instances where this is not explicitly +indicated. Support for such fields is provided on a best-effort basis.{{< /call-out >}} ## Resources @@ -116,6 +119,7 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Gateway is invalid or not supported. - `Programmed/True/Programmed` - `Programmed/False/Invalid` + - `Accepted/True/UnsupportedField`: Custom reason for when the Gateway is accepted but contains an unsupported field - `listeners` - `name`: Supported. - `supportedKinds`: Supported. @@ -165,6 +169,10 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `requestMirror`: Supported. Multiple mirrors can be specified. Percent and fraction-based mirroring are supported. - `extensionRef`: Supported for SnippetsFilters. - `backendRefs`: Partially supported. Backend ref `filters` are not supported. + - `name`: Not supported. + - `timeouts`: Not supported. + - `retry`: Not supported. + - `sessionPersistence`: Not supported. - `status` - `parents` - `parentRef`: Supported. @@ -185,6 +193,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `ResolvedRefs/False/InvalidIPFamily`: Custom reason for when one of the HTTPRoute rules has a backendRef that has an invalid IPFamily. - `ResolvedRefs/False/UnsupportedProtocol` - `PartiallyInvalid/True/UnsupportedValue` + - `Accepted/True/UnsupportedField`: Custom reason for when the HTTPRouteRule is accepted but contains an unsupported field + + {{< call-out "note" >}} If `name`, `timeouts`, `retry` or `sessionPersistence` are defined for a HTTPRoute rule, they will be ignored and rule still will be created. {{< /call-out >}} ### GRPCRoute @@ -210,6 +221,8 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `requestMirror`: Supported. Multiple mirrors can be specified. - `extensionRef`: Supported for SnippetsFilters. - `backendRefs`: Partially supported. Backend ref `filters` are not supported. + - `name`: Not supported. + - `sessionPersistence`: Not supported. - `status` - `parents` - `parentRef`: Supported. @@ -227,6 +240,9 @@ See the [controller]({{< ref "/ngf/reference/cli-help.md#controller">}}) command - `ResolvedRefs/False/BackendNotFound` - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the GRPCRoute rules has a backendRef with an unsupported value. - `PartiallyInvalid/True/UnsupportedValue` + - `Accepted/True/UnsupportedField`: Custom reason for when the GRPCRouteRule is accepted but contains an unsupported field + +{{< call-out "note" >}} If `name` or `sessionPersistence` are defined for a GRPCRoute rule, they will be ignored and rule still will be created. {{< /call-out >}} ### ReferenceGrant From 4b0aa635c92c1ec72a89ca01428103af7386a4cd Mon Sep 17 00:00:00 2001 From: Ciara Stacke <18287516+ciarams87@users.noreply.github.com> Date: Fri, 10 Oct 2025 19:21:14 +0100 Subject: [PATCH 06/17] NGF: Update advanced routing guide for Regex PathType (#1286) feat: Update advanced routing guide for regex path --- .../traffic-management/advanced-routing.md | 63 ++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/content/ngf/traffic-management/advanced-routing.md b/content/ngf/traffic-management/advanced-routing.md index ba52cc477..66c05c594 100644 --- a/content/ngf/traffic-management/advanced-routing.md +++ b/content/ngf/traffic-management/advanced-routing.md @@ -11,7 +11,7 @@ Learn how to deploy multiple applications and HTTPRoutes with request conditions ## Overview -In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request matching by path, headers, query parameters, and method. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) first. +In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request matching by path (including prefix, exact, and regex patterns), headers, query parameters, and method. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< ref "/ngf/traffic-management/basic-routing.md" >}}) first. The following image shows the traffic flow that we will be creating with these rules. @@ -321,6 +321,67 @@ Server name: tea-post-b59b8596b-g586r This request should receive a response from the `tea-post` pod. Any other type of method, such as PATCH, will result in a `404 Not Found` response. +## Path matching types + +NGINX Gateway Fabric supports three types of path matching: + +- **PathPrefix**: Matches based on a URL path prefix split by `/`. For example, `/coffee` matches `/coffee`, `/coffee/`, and `/coffee/latte`. +- **Exact**: Matches the exact path in the request. For example, `/coffee` matches only `/coffee`. +- **RegularExpression**: Matches based on RE2-compatible regular expressions. For example, `/coffee/[a-z]+` matches `/coffee/latte` and `/coffee/mocha` but not `/coffee/123`. + +{{< call-out "note" >}} Regular expression path matching uses the RE2 syntax. Patterns are automatically anchored to the beginning of the path. {{< /call-out >}} + +### Example: Using regex path matching + +To route requests based on regex patterns in the path, use `type: RegularExpression`: + +```yaml +kubectl apply -f - < Date: Tue, 14 Oct 2025 15:10:31 +0100 Subject: [PATCH 07/17] Add details on BuildOS and InferencePoolCount to Product Telemetry docs (#1284) * Add details on BuildOS and InferencePoolCount to Product Telemetry docs * Add InferencePoolCount * Move InferencePool resource into "Count of Resources" section --- content/ngf/overview/product-telemetry.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ngf/overview/product-telemetry.md b/content/ngf/overview/product-telemetry.md index 45237d56d..573460d8a 100644 --- a/content/ngf/overview/product-telemetry.md +++ b/content/ngf/overview/product-telemetry.md @@ -27,13 +27,13 @@ Telemetry data is collected once every 24 hours and sent to a service managed by - **Version:** the version of the NGINX Gateway Fabric Deployment. - **Deployment UID:** the UID of the NGINX Gateway Fabric Deployment. - **Image Build Source:** whether the image was built by GitHub or locally (values are `gha`, `local`, or `unknown`). The source repository of the images is **not** collected. +- **Build OS:** the base operating system the image was built on (values are currently `alpine` or `ubi`). - **Deployment Flags:** a list of NGINX Gateway Fabric Deployment flags that are specified by a user. The actual values of non-boolean flags are **not** collected; we only record that they are either `true` or `false` for boolean flags and `default` or `user-defined` for the rest. -- **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. +- **Count of Resources:** the total count of resources related to NGINX Gateway Fabric. This includes `GatewayClasses`, `Gateways`, `HTTPRoutes`,`GRPCRoutes`, `TLSRoutes`, `InferencePool`, `Secrets`, `Services`, `BackendTLSPolicies`, `ClientSettingsPolicies`, `NginxProxies`, `ObservabilityPolicies`, `UpstreamSettingsPolicies`, `SnippetsFilters`, and `Endpoints`. The data within these resources is **not** collected. - **SnippetsFilters Info** a list of directive-context strings from applied SnippetFilters and a total count per strings. The actual value of any NGINX directive is **not** collected. - **Control Plane Pod Count** the count of NGINX Gateway Fabric Pods. - **Data Plane Pod Count** the count of NGINX data plane Pods. - **NGINX One Console Connection Info** indicates whether the connection to the NGINX One Console is enabled. -This data is used to identify the following information: - The flavors of Kubernetes environments that are most popular among our users. - The number of unique NGINX Gateway Fabric installations. From a03edd0bbe684ad2b4dc6a34d5258773b266c4d4 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Mon, 20 Oct 2025 10:17:37 +0100 Subject: [PATCH 08/17] Add document for installing NGF on Openshift through OperatorHub --- content/ngf/install/openshift.md | 364 +++++++++++++++++++++++++++++++ 1 file changed, 364 insertions(+) create mode 100644 content/ngf/install/openshift.md diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md new file mode 100644 index 000000000..900238d92 --- /dev/null +++ b/content/ngf/install/openshift.md @@ -0,0 +1,364 @@ +--- +title: Install NGINX Gateway Fabric on OpenShift using OperatorHub +description: Deploy NGINX Gateway Fabric on Red Hat OpenShift via OperatorHub and configure it using the NginxGatewayFabric custom resource. +weight: 20 +toc: true +--- + +## Overview + +This guide explains how to install F5 NGINX Gateway Fabric on Red Hat OpenShift using OperatorHub and configure it with the `NginxGatewayFabric` custom resource. + +On this page + +- Prerequisites for OpenShift +- Installing the NGF Operator from OperatorHub +- Creating the NGF instance using the `NginxGatewayFabric` CR +- OpenShift-specific considerations (images, service exposure, SCC) +- Operator-specific configuration options available in the CR +- Validation and troubleshooting + +## Prerequisites + +- A running Red Hat OpenShift cluster with cluster-admin privileges. +- Access to OperatorHub in the OpenShift Web Console. +- `oc` CLI installed and logged in to your cluster. +- Ability to pull images from `ghcr.io` (or a mirrored registry if required by your environment). +- Optional: + - NGINX One dataplane API key if you plan to integrate with NGINX One. + - NGINX Plus entitlements if you plan to run NGF with NGINX Plus. +- Network exposure model decided: + - LoadBalancer Services (recommended where available) + - Or OpenShift Routes/NodePorts (if LoadBalancer is not available) + +## Note on OpenShift support and images + +NGF provides first-class OpenShift support with UBI-based images. Use the `-ubi` tags shown in the CR examples below. Security constraints, such as running as non-root, are handled by defaults compatible with OpenShift SCCs in most environments. If your cluster enforces custom SCCs or policies, see the "Pod scheduling and security" options under operator-specific configuration. + +## Install the NGF Operator from OperatorHub + +Install via the OpenShift Web Console: + +1. Navigate to Operators → OperatorHub. +2. Search for "NGINX Gateway Fabric". +3. Select the NGF Operator (provider: NGINX, Inc) and click Install. +4. Choose an update channel (for example, stable 2.x), installation mode (All namespaces or a specific namespace), and approve automatic updates as desired. +5. Complete the installation. Wait until the Operator shows the "Installed" status. + +If you prefer CLI-based installation (Subscription/OperatorGroup), consult OpenShift documentation for creating `OperatorGroup` and `Subscription` resources in your chosen namespace. The Web Console path above is recommended. + +## Create a project and required secrets + +Create a dedicated project (namespace) for NGF components, for example: + +```bash +oc new-project nginx-gateway-fabric +``` + +## TLS secrets for internal communication + +NGF can generate internal certificates for agent/server by default, or you can provide your own secrets. + +Option A: Let NGF generate the certificates +- Use the default `certGenerator` settings from the sample CR (no additional steps needed). +- `certGenerator.overwrite: false` means NGF will not overwrite existing secrets if present. + +Option B: Provide your own secrets (example) +```bash +# Agent TLS (used by internal agent) +oc create secret tls agent-tls \ + --cert=agent.crt \ + --key=agent.key \ + -n nginx-gateway-fabric + +# Server TLS (used by internal server) +oc create secret tls server-tls \ + --cert=server.crt \ + --key=server.key \ + -n nginx-gateway-fabric +``` + +## Optional: Integrate with NGINX One + +If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key): + +```bash +oc create secret generic nginxone-dataplane-key \ + --from-literal=key=VALUE \ + -n nginx-gateway-fabric +``` + +You will reference this secret in the `spec.nginx.nginxOneConsole.dataplaneKeySecretName` field. + +## Optional: NGINX Plus licensing + +If you plan to use NGINX Plus, you will need to: +- Set `spec.nginx.nginxOneConsole.plus: true` +- Provide appropriate image repository/registry credentials in `imagePullSecret(s)` +- Optionally create a secret for license/entitlement artifacts (name by convention below): + +```bash +# Example license secret name referenced by usage.secretName +oc create secret generic nplus-license \ + --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ + --from-file=nginx-repo.key=/path/to/nginx-repo.key \ + -n nginx-gateway-fabric +``` + +Consult your subscription details for the exact files/registry access used for NGINX Plus images in your environment. + +## Create the NginxGatewayFabric CR + +Minimal example for OpenShift: + +```yaml +apiVersion: gateway.nginx.org/v1alpha1 +kind: NginxGatewayFabric +metadata: + name: ngf + namespace: nginx-gateway-fabric +spec: + # Cluster-wide defaults + clusterDomain: cluster.local + + # Optionally provide cert secrets if you do not want NGF to generate them + certGenerator: + agentTLSSecretName: agent-tls + serverTLSSecretName: server-tls + overwrite: false + ttlSecondsAfterFinished: 30 + + # Data plane (NGINX) + nginx: + replicas: 2 + debug: false + image: + repository: ghcr.io/nginx/nginx-gateway-fabric/nginx + tag: 2.2.0-ubi + pullPolicy: IfNotPresent + service: + type: LoadBalancer + externalTrafficPolicy: Local + metrics: + # metrics are configured under nginxGateway, but data plane health can be probed via readinessProbe + # configure additional metrics/sidecars as needed + readinessProbe: {} + autoscaling: + enable: false + imagePullSecrets: [] + container: + hostPorts: [] + # Optional NGINX One console integration + nginxOneConsole: + dataplaneKeySecretName: "" # set to "nginxone-dataplane-key" if you created it + endpointHost: agent.connect.nginx.com + endpointPort: 443 + skipVerify: false + plus: false + + # Controller + nginxGateway: + gatewayClassName: nginx + gatewayControllerName: gateway.nginx.org/nginx-gateway-controller + image: + repository: ghcr.io/nginx/nginx-gateway-fabric + tag: 2.2.0-ubi + pullPolicy: IfNotPresent + replicas: 1 + metrics: + enable: true + port: 9113 + secure: false + readinessProbe: + enable: true + initialDelaySeconds: 3 + port: 8081 + leaderElection: + enable: true + lockName: "" + productTelemetry: + enable: true + gwAPIExperimentalFeatures: + enable: false + snippetsFilters: + enable: false +``` + +Apply the CR: + +```bash +oc apply -f nginx-gateway-fabric.yaml +``` + +Wait for the Operator to reconcile. It will provision the NGF controller and data plane deployments, services, and related resources. + +## OpenShift-specific exposure options + +- LoadBalancer Service (preferred where available): Use `spec.nginx.service.type: LoadBalancer`. You can also configure: + - `externalTrafficPolicy: Local` to preserve source IPs (useful for client IP-based policies). + - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. + +- Routes / NodePort (if LoadBalancer is not available): + - Set `spec.nginx.service.type: NodePort` and create an OpenShift Route to the NGF front-end service (for HTTP/HTTPS traffic). + - Example (edge termination route; replace service name and ports appropriately): + ```bash + oc create route edge ngf \ + --service=nginx-gateway-fabric-nginx \ + --port=http \ + -n nginx-gateway-fabric + ``` + - For TLS passthrough, use `--passthrough` and target the appropriate service port. + +## Operator-specific configuration options (NginxGatewayFabric spec) + +Below is a summary of key fields exposed by the Operator via the `NginxGatewayFabric` CR. Defaults align with NGF Helm values. + +- Global + - `clusterDomain`: Kubernetes cluster domain (default `cluster.local`). + - `gateways`: Optional list to seed Gateway resources managed by the Operator (empty by default). + +- `certGenerator` + - `agentTLSSecretName` / `serverTLSSecretName`: Secret names for internal agent/server TLS. + - `overwrite`: If true, Operator may overwrite existing secrets during generation. + - `annotations`: Add annotations to generated objects. + - `nodeSelector`, `tolerations`, `topologySpreadConstraints`, `affinity`: Pod scheduling controls for cert jobs. + - `ttlSecondsAfterFinished`: TTL for certificate generation jobs (default 30 seconds). + +- `nginx` (data plane) + - `image`: Repository/tag/pullPolicy. Use `ghcr.io/nginx/nginx-gateway-fabric/nginx` with `2.2.0-ubi` for OpenShift. + - `replicas`: Desired number of data plane replicas. + - `debug`: Enables verbose NGINX debugging. + - `container.hostPorts`: Optional host port bindings (normally disabled on OpenShift). + - `readinessProbe`, `lifecycle`, `resources`, `volumeMounts`: Pod behavior and resources. + - `imagePullSecret` / `imagePullSecrets`: For private registries or NGINX Plus artifacts. + - `kind`: Deployment (default) — data plane runs as a Deployment. + - `service`: + - `type`: `LoadBalancer` | `NodePort` | `ClusterIP` + - `externalTrafficPolicy`: `Local` or `Cluster` + - `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`: Cloud/provider-specific LB tuning. + - `nodePorts`: Fixed NodePorts if you need deterministic port numbers. + - `patches`: Strategic merge patches to customize the Service shape beyond the exposed fields. + - `autoscaling.enable`: If true, enable HPA for the data plane (configure metrics/thresholds according to your policy). + - `pod`: Raw Pod-level overrides (labels, annotations). + - `nginxOneConsole`: + - `dataplaneKeySecretName`: Secret providing the NGINX One dataplane key. + - `endpointHost` / `endpointPort`: NGINX One agent endpoint. + - `skipVerify`: Disable TLS verification (not recommended). + - `patches`: Additional customization patches. + - `plus`: Set `true` when using NGINX Plus data plane. + - `usage`: + - `secretName`: License/usage reporting secret name (e.g., `nplus-license`). + - `endpoint`, `resolver`, `skipVerify`, `clientSSLSecretName`, `caSecretName`, `enforceInitialReport`: Advanced usage/telemetry controls. + +- `nginxGateway` (controller) + - `gatewayClassName`: Name of the GatewayClass to install (default `nginx`). + - `gatewayControllerName`: Controller name (`gateway.nginx.org/nginx-gateway-controller`). + - `image`: Repository/tag/pullPolicy (`ghcr.io/nginx/nginx-gateway-fabric:2.2.0-ubi` recommended for OpenShift). + - `replicas`: Desired controller replica count. + - `metrics`: + - `enable`: Expose controller metrics (default true). + - `port`: Default `9113`. + - `secure`: If true, expose metrics over TLS. + - `readinessProbe`: + - `enable`: Default true. + - `initialDelaySeconds`: Default 3 seconds. + - `port`: Default `8081`. + - `leaderElection`: + - `enable`: Default true. + - `lockName`: Optional. Leave empty for automatic naming. + - `productTelemetry.enable`: Enable product telemetry (default true). + - `gwAPIExperimentalFeatures.enable`: Enable Gateway API experimental features (default false). + - `config.logging.level`: Controller logging verbosity (default `info`). + - `configAnnotations`: Extra annotations to inject into managed resources. + - `extraVolumes` / `extraVolumeMounts`: Mount additional volumes into the controller. + - `gatewayClassAnnotations`: Annotate the installed GatewayClass. + - `labels`, `podAnnotations`: Customize labels and annotations on controller Pods. + - `service`: Customize the controller Service (annotations/labels). + - `serviceAccount`: Customize the controller service account and its annotations. + - `imagePullSecret` / `imagePullSecrets`: Private registry credentials. + - `snippetsFilters.enable`: Enable filters around user-provided NGINX config snippets (default false). + - `terminationGracePeriodSeconds`: Default 30 seconds. + - `topologySpreadConstraints`, `tolerations`, `nodeSelector`, `affinity`: Pod scheduling controls. + +## Pod scheduling and security (OpenShift) + +- Use `nodeSelector`, `tolerations`, and `topologySpreadConstraints` to adhere to your cluster’s workload placement policies. +- OpenShift SCCs typically require running as non-root. NGF UBI images are compatible; avoid setting hostPorts unless you have an SCC permitting them. +- If your environment enforces custom SCCs, bind the appropriate SCC to the NGF service accounts and use `pod`/`serviceAccount` fields to reference them. + +## Validation + +After applying the CR, verify that deployments and services are running: + +```bash +oc get pods -n nginx-gateway-fabric +oc get svc -n nginx-gateway-fabric +``` + +Check the installed GatewayClass: + +```bash +oc get gatewayclass +``` + +Logs for troubleshooting: + +```bash +# Controller logs +oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric + +# Data plane logs +oc logs deploy/ngf-nginx -n nginx-gateway-fabric +``` + +## Optional: Functional check + +Create a simple Gateway and HTTPRoute to validate routing: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: http + namespace: nginx-gateway-fabric +spec: + gatewayClassName: nginx + listeners: + - name: http + port: 80 + protocol: HTTP + hostname: example.com + allowedRoutes: + namespaces: + from: Same +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: echo + namespace: nginx-gateway-fabric +spec: + parentRefs: + - name: http + hostnames: + - example.com + rules: + - backendRefs: + - name: echo + port: 8080 +``` + +Ensure you have a Service/Deployment named `echo` on port 8080. If using a LoadBalancer Service, curl the LB IP (or use an OpenShift Route if you configured one). + +## References + +- Red Hat OperatorHub (OpenShift Web Console → OperatorHub) +- NGINX Gateway Fabric CRD sample (Operator-managed): + https://github.com/nginx/nginx-gateway-fabric/blob/main/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml + +- NGF Helm chart defaults (values): See `helm-charts/nginx-gateway-fabric/values.yaml` in the NGF repository. + +## Notes + +- The Operator-specific options listed above reflect the fields exposed in the `NginxGatewayFabric` CR and their defaults in the referenced sample. Your environment and Operator channel may introduce additional fields or defaults. Always review the installed Operator’s CRD and documentation in your cluster for the authoritative schema. +- If your OpenShift environment does not support external LoadBalancer, prefer Route-based exposure. Configure TLS policies (edge/reencrypt/passthrough) consistent with your application’s needs. From 020f81cd28003ee71165d5d972280d7be762e793 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 14:51:10 +0100 Subject: [PATCH 09/17] Update docs to be in line with style guidelins --- content/ngf/install/openshift.md | 101 +++++++++++++++---------------- go.mod | 2 +- go.sum | 4 +- 3 files changed, 53 insertions(+), 54 deletions(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index 900238d92..fd62902c3 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -1,49 +1,51 @@ --- title: Install NGINX Gateway Fabric on OpenShift using OperatorHub -description: Deploy NGINX Gateway Fabric on Red Hat OpenShift via OperatorHub and configure it using the NginxGatewayFabric custom resource. -weight: 20 +description: Deploy F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub and configure it using the NginxGatewayFabric custom resource. +weight: 500 toc: true +nd-content-type: how-to +nd-product: NGF +nd-docs: DOCS-1851 --- ## Overview -This guide explains how to install F5 NGINX Gateway Fabric on Red Hat OpenShift using OperatorHub and configure it with the `NginxGatewayFabric` custom resource. +This guide explains how to install F5 NGINX Gateway Fabric (NGF) on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. On this page - Prerequisites for OpenShift -- Installing the NGF Operator from OperatorHub -- Creating the NGF instance using the `NginxGatewayFabric` CR -- OpenShift-specific considerations (images, service exposure, SCC) -- Operator-specific configuration options available in the CR -- Validation and troubleshooting +- Install NGINX Gateway Fabric Operator from OperatorHub +- Create the NginxGatewayFabric custom resource +- Review OpenShift considerations (images, service exposure, SCC) +- Configure operator options in the custom resource +- Validate the installation and troubleshoot issues ## Prerequisites -- A running Red Hat OpenShift cluster with cluster-admin privileges. +- A running Red Hat OpenShift cluster with cluster administrator privileges. - Access to OperatorHub in the OpenShift Web Console. -- `oc` CLI installed and logged in to your cluster. +- The oc command-line tool is installed, and you are logged in to your cluster. - Ability to pull images from `ghcr.io` (or a mirrored registry if required by your environment). - Optional: - - NGINX One dataplane API key if you plan to integrate with NGINX One. - - NGINX Plus entitlements if you plan to run NGF with NGINX Plus. + - F5 NGINX One dataplane API key if you plan to integrate with NGINX One. + - F5 NGINX Plus entitlements if you plan to run NGF with NGINX Plus. - Network exposure model decided: - LoadBalancer Services (recommended where available) - Or OpenShift Routes/NodePorts (if LoadBalancer is not available) -## Note on OpenShift support and images +### Review OpenShift support and images -NGF provides first-class OpenShift support with UBI-based images. Use the `-ubi` tags shown in the CR examples below. Security constraints, such as running as non-root, are handled by defaults compatible with OpenShift SCCs in most environments. If your cluster enforces custom SCCs or policies, see the "Pod scheduling and security" options under operator-specific configuration. +NGF provides first-class OpenShift support with Universal Base Image (UBI)-based images. Use the `-ubi` tags shown in the custom resource definition (CRD) examples below. Security constraints, such as running as non-root, are handled by defaults compatible with OpenShift Security Context Constraints (SCCs) in most environments. If your cluster enforces custom SCCs or policies, see the "Pod scheduling and security" options under operator-specific configuration. -## Install the NGF Operator from OperatorHub +## Install NGINX Gateway Fabric Operator from OperatorHub -Install via the OpenShift Web Console: - -1. Navigate to Operators → OperatorHub. -2. Search for "NGINX Gateway Fabric". -3. Select the NGF Operator (provider: NGINX, Inc) and click Install. -4. Choose an update channel (for example, stable 2.x), installation mode (All namespaces or a specific namespace), and approve automatic updates as desired. -5. Complete the installation. Wait until the Operator shows the "Installed" status. +1. Go to the Red Hat Catalog: https://catalog.redhat.com/en +2. Search for "NGINX Gateway Fabric Operator". +3. Select NGINX Gateway Fabric Operator (provider: F5, Inc.). +4. Select **Deploy & use**. +5. Choose the appropriate architecture and release tag. +6. Complete the installation. Wait until the Operator status shows Installed. If you prefer CLI-based installation (Subscription/OperatorGroup), consult OpenShift documentation for creating `OperatorGroup` and `Subscription` resources in your chosen namespace. The Web Console path above is recommended. @@ -51,7 +53,7 @@ If you prefer CLI-based installation (Subscription/OperatorGroup), consult OpenS Create a dedicated project (namespace) for NGF components, for example: -```bash +```shell oc new-project nginx-gateway-fabric ``` @@ -60,11 +62,11 @@ oc new-project nginx-gateway-fabric NGF can generate internal certificates for agent/server by default, or you can provide your own secrets. Option A: Let NGF generate the certificates -- Use the default `certGenerator` settings from the sample CR (no additional steps needed). +- Use the default `certGenerator` settings from the sample custom resource (no additional steps needed). - `certGenerator.overwrite: false` means NGF will not overwrite existing secrets if present. Option B: Provide your own secrets (example) -```bash +```shell # Agent TLS (used by internal agent) oc create secret tls agent-tls \ --cert=agent.crt \ @@ -82,7 +84,7 @@ oc create secret tls server-tls \ If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key): -```bash +```shell oc create secret generic nginxone-dataplane-key \ --from-literal=key=VALUE \ -n nginx-gateway-fabric @@ -95,9 +97,9 @@ You will reference this secret in the `spec.nginx.nginxOneConsole.dataplaneKeySe If you plan to use NGINX Plus, you will need to: - Set `spec.nginx.nginxOneConsole.plus: true` - Provide appropriate image repository/registry credentials in `imagePullSecret(s)` -- Optionally create a secret for license/entitlement artifacts (name by convention below): +- Optionally create a secret for license and entitlement artifacts (name by convention below): -```bash +```shell # Example license secret name referenced by usage.secretName oc create secret generic nplus-license \ --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ @@ -107,7 +109,7 @@ oc create secret generic nplus-license \ Consult your subscription details for the exact files/registry access used for NGINX Plus images in your environment. -## Create the NginxGatewayFabric CR +## Create the NginxGatewayFabric custom resource Minimal example for OpenShift: @@ -184,24 +186,24 @@ spec: enable: false ``` -Apply the CR: +Apply the custom resource: -```bash +```shell oc apply -f nginx-gateway-fabric.yaml ``` Wait for the Operator to reconcile. It will provision the NGF controller and data plane deployments, services, and related resources. -## OpenShift-specific exposure options +## Configure exposure options for OpenShift - LoadBalancer Service (preferred where available): Use `spec.nginx.service.type: LoadBalancer`. You can also configure: - `externalTrafficPolicy: Local` to preserve source IPs (useful for client IP-based policies). - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. -- Routes / NodePort (if LoadBalancer is not available): +- Routes/NodePort (if a LoadBalancer is not available): - Set `spec.nginx.service.type: NodePort` and create an OpenShift Route to the NGF front-end service (for HTTP/HTTPS traffic). - Example (edge termination route; replace service name and ports appropriately): - ```bash + ```shell oc create route edge ngf \ --service=nginx-gateway-fabric-nginx \ --port=http \ @@ -211,7 +213,7 @@ Wait for the Operator to reconcile. It will provision the NGF controller and dat ## Operator-specific configuration options (NginxGatewayFabric spec) -Below is a summary of key fields exposed by the Operator via the `NginxGatewayFabric` CR. Defaults align with NGF Helm values. +Below is a summary of key fields in the `NginxGatewayFabric` custom resource. Defaults align with NGF Helm values. - Global - `clusterDomain`: Kubernetes cluster domain (default `cluster.local`). @@ -238,7 +240,7 @@ Below is a summary of key fields exposed by the Operator via the `NginxGatewayFa - `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`: Cloud/provider-specific LB tuning. - `nodePorts`: Fixed NodePorts if you need deterministic port numbers. - `patches`: Strategic merge patches to customize the Service shape beyond the exposed fields. - - `autoscaling.enable`: If true, enable HPA for the data plane (configure metrics/thresholds according to your policy). + - `autoscaling.enable`: If true, enable the Horizontal Pod Autoscaler (HPA) for the data plane (configure metrics and thresholds according to your policy). - `pod`: Raw Pod-level overrides (labels, annotations). - `nginxOneConsole`: - `dataplaneKeySecretName`: Secret providing the NGINX One dataplane key. @@ -247,7 +249,7 @@ Below is a summary of key fields exposed by the Operator via the `NginxGatewayFa - `patches`: Additional customization patches. - `plus`: Set `true` when using NGINX Plus data plane. - `usage`: - - `secretName`: License/usage reporting secret name (e.g., `nplus-license`). + - `secretName`: License and usage reporting secret name (for example, `nplus-license`). - `endpoint`, `resolver`, `skipVerify`, `clientSSLSecretName`, `caSecretName`, `enforceInitialReport`: Advanced usage/telemetry controls. - `nginxGateway` (controller) @@ -283,27 +285,27 @@ Below is a summary of key fields exposed by the Operator via the `NginxGatewayFa ## Pod scheduling and security (OpenShift) - Use `nodeSelector`, `tolerations`, and `topologySpreadConstraints` to adhere to your cluster’s workload placement policies. -- OpenShift SCCs typically require running as non-root. NGF UBI images are compatible; avoid setting hostPorts unless you have an SCC permitting them. +- OpenShift Security Context Constraints (SCCs) typically require running as non-root. NGF UBI images are compatible; avoid setting hostPorts unless you have an SCC that permits them. - If your environment enforces custom SCCs, bind the appropriate SCC to the NGF service accounts and use `pod`/`serviceAccount` fields to reference them. -## Validation +## Validate the installation -After applying the CR, verify that deployments and services are running: +After applying the custom resource, verify that deployments and services are running: -```bash +```shell oc get pods -n nginx-gateway-fabric oc get svc -n nginx-gateway-fabric ``` Check the installed GatewayClass: -```bash +```shell oc get gatewayclass ``` Logs for troubleshooting: -```bash +```shell # Controller logs oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric @@ -311,7 +313,7 @@ oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric oc logs deploy/ngf-nginx -n nginx-gateway-fabric ``` -## Optional: Functional check +## Perform a functional check (optional) Create a simple Gateway and HTTPRoute to validate routing: @@ -348,17 +350,14 @@ spec: port: 8080 ``` -Ensure you have a Service/Deployment named `echo` on port 8080. If using a LoadBalancer Service, curl the LB IP (or use an OpenShift Route if you configured one). +Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. ## References -- Red Hat OperatorHub (OpenShift Web Console → OperatorHub) -- NGINX Gateway Fabric CRD sample (Operator-managed): - https://github.com/nginx/nginx-gateway-fabric/blob/main/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml - -- NGF Helm chart defaults (values): See `helm-charts/nginx-gateway-fabric/values.yaml` in the NGF repository. +- Red Hat Catalog (https://catalog.redhat.com/en) +- NGINX Gateway Fabric custom resource sample (https://github.com/nginx/nginx-gateway-fabric/blob/main/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml) ## Notes -- The Operator-specific options listed above reflect the fields exposed in the `NginxGatewayFabric` CR and their defaults in the referenced sample. Your environment and Operator channel may introduce additional fields or defaults. Always review the installed Operator’s CRD and documentation in your cluster for the authoritative schema. +- The Operator-specific options listed above reflect the fields exposed in the `NginxGatewayFabric` custom resource and their defaults in the referenced sample. Your environment and Operator channel may introduce additional fields or defaults. Always review the installed Operator’s CRD and documentation in your cluster for the authoritative schema. - If your OpenShift environment does not support external LoadBalancer, prefer Route-based exposure. Configure TLS policies (edge/reencrypt/passthrough) consistent with your application’s needs. diff --git a/go.mod b/go.mod index ce2d2e14a..6d17da87c 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v1.0.11 // indirect +require github.com/nginxinc/nginx-hugo-theme v1.0.15 // indirect diff --git a/go.sum b/go.sum index 62c56ef71..c9fd59c99 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,2 @@ -github.com/nginxinc/nginx-hugo-theme v1.0.11 h1:vsiqkg+Ba7CN05SaY9HEPbPinz3Y1xjNZ/qdhhp7Hrc= -github.com/nginxinc/nginx-hugo-theme v1.0.11/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v1.0.15 h1:X9G9ihCB7ceGXEgJgiYKvMHGCV/xMUBOR3aKAuT7aEA= +github.com/nginxinc/nginx-hugo-theme v1.0.15/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= From 892135f9924f71dff17ebef10d9f5b1d8bb09284 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 15:04:11 +0100 Subject: [PATCH 10/17] Code review updates --- content/ngf/install/openshift.md | 135 +++---------------------------- 1 file changed, 13 insertions(+), 122 deletions(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index fd62902c3..7cd34a6a0 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -95,7 +95,7 @@ You will reference this secret in the `spec.nginx.nginxOneConsole.dataplaneKeySe ## Optional: NGINX Plus licensing If you plan to use NGINX Plus, you will need to: -- Set `spec.nginx.nginxOneConsole.plus: true` +- Set `spec.nginx.plus: true` - Provide appropriate image repository/registry credentials in `imagePullSecret(s)` - Optionally create a secret for license and entitlement artifacts (name by convention below): @@ -120,43 +120,13 @@ metadata: name: ngf namespace: nginx-gateway-fabric spec: - # Cluster-wide defaults - clusterDomain: cluster.local - - # Optionally provide cert secrets if you do not want NGF to generate them - certGenerator: - agentTLSSecretName: agent-tls - serverTLSSecretName: server-tls - overwrite: false - ttlSecondsAfterFinished: 30 - # Data plane (NGINX) nginx: replicas: 2 - debug: false image: repository: ghcr.io/nginx/nginx-gateway-fabric/nginx tag: 2.2.0-ubi pullPolicy: IfNotPresent - service: - type: LoadBalancer - externalTrafficPolicy: Local - metrics: - # metrics are configured under nginxGateway, but data plane health can be probed via readinessProbe - # configure additional metrics/sidecars as needed - readinessProbe: {} - autoscaling: - enable: false - imagePullSecrets: [] - container: - hostPorts: [] - # Optional NGINX One console integration - nginxOneConsole: - dataplaneKeySecretName: "" # set to "nginxone-dataplane-key" if you created it - endpointHost: agent.connect.nginx.com - endpointPort: 443 - skipVerify: false - plus: false # Controller nginxGateway: @@ -167,23 +137,6 @@ spec: tag: 2.2.0-ubi pullPolicy: IfNotPresent replicas: 1 - metrics: - enable: true - port: 9113 - secure: false - readinessProbe: - enable: true - initialDelaySeconds: 3 - port: 8081 - leaderElection: - enable: true - lockName: "" - productTelemetry: - enable: true - gwAPIExperimentalFeatures: - enable: false - snippetsFilters: - enable: false ``` Apply the custom resource: @@ -213,74 +166,17 @@ Wait for the Operator to reconcile. It will provision the NGF controller and dat ## Operator-specific configuration options (NginxGatewayFabric spec) -Below is a summary of key fields in the `NginxGatewayFabric` custom resource. Defaults align with NGF Helm values. - -- Global - - `clusterDomain`: Kubernetes cluster domain (default `cluster.local`). - - `gateways`: Optional list to seed Gateway resources managed by the Operator (empty by default). - -- `certGenerator` - - `agentTLSSecretName` / `serverTLSSecretName`: Secret names for internal agent/server TLS. - - `overwrite`: If true, Operator may overwrite existing secrets during generation. - - `annotations`: Add annotations to generated objects. - - `nodeSelector`, `tolerations`, `topologySpreadConstraints`, `affinity`: Pod scheduling controls for cert jobs. - - `ttlSecondsAfterFinished`: TTL for certificate generation jobs (default 30 seconds). - -- `nginx` (data plane) - - `image`: Repository/tag/pullPolicy. Use `ghcr.io/nginx/nginx-gateway-fabric/nginx` with `2.2.0-ubi` for OpenShift. - - `replicas`: Desired number of data plane replicas. - - `debug`: Enables verbose NGINX debugging. - - `container.hostPorts`: Optional host port bindings (normally disabled on OpenShift). - - `readinessProbe`, `lifecycle`, `resources`, `volumeMounts`: Pod behavior and resources. - - `imagePullSecret` / `imagePullSecrets`: For private registries or NGINX Plus artifacts. - - `kind`: Deployment (default) — data plane runs as a Deployment. - - `service`: - - `type`: `LoadBalancer` | `NodePort` | `ClusterIP` - - `externalTrafficPolicy`: `Local` or `Cluster` - - `loadBalancerClass`, `loadBalancerIP`, `loadBalancerSourceRanges`: Cloud/provider-specific LB tuning. - - `nodePorts`: Fixed NodePorts if you need deterministic port numbers. - - `patches`: Strategic merge patches to customize the Service shape beyond the exposed fields. - - `autoscaling.enable`: If true, enable the Horizontal Pod Autoscaler (HPA) for the data plane (configure metrics and thresholds according to your policy). - - `pod`: Raw Pod-level overrides (labels, annotations). - - `nginxOneConsole`: - - `dataplaneKeySecretName`: Secret providing the NGINX One dataplane key. - - `endpointHost` / `endpointPort`: NGINX One agent endpoint. - - `skipVerify`: Disable TLS verification (not recommended). - - `patches`: Additional customization patches. - - `plus`: Set `true` when using NGINX Plus data plane. - - `usage`: - - `secretName`: License and usage reporting secret name (for example, `nplus-license`). - - `endpoint`, `resolver`, `skipVerify`, `clientSSLSecretName`, `caSecretName`, `enforceInitialReport`: Advanced usage/telemetry controls. - -- `nginxGateway` (controller) - - `gatewayClassName`: Name of the GatewayClass to install (default `nginx`). - - `gatewayControllerName`: Controller name (`gateway.nginx.org/nginx-gateway-controller`). - - `image`: Repository/tag/pullPolicy (`ghcr.io/nginx/nginx-gateway-fabric:2.2.0-ubi` recommended for OpenShift). - - `replicas`: Desired controller replica count. - - `metrics`: - - `enable`: Expose controller metrics (default true). - - `port`: Default `9113`. - - `secure`: If true, expose metrics over TLS. - - `readinessProbe`: - - `enable`: Default true. - - `initialDelaySeconds`: Default 3 seconds. - - `port`: Default `8081`. - - `leaderElection`: - - `enable`: Default true. - - `lockName`: Optional. Leave empty for automatic naming. - - `productTelemetry.enable`: Enable product telemetry (default true). - - `gwAPIExperimentalFeatures.enable`: Enable Gateway API experimental features (default false). - - `config.logging.level`: Controller logging verbosity (default `info`). - - `configAnnotations`: Extra annotations to inject into managed resources. - - `extraVolumes` / `extraVolumeMounts`: Mount additional volumes into the controller. - - `gatewayClassAnnotations`: Annotate the installed GatewayClass. - - `labels`, `podAnnotations`: Customize labels and annotations on controller Pods. - - `service`: Customize the controller Service (annotations/labels). - - `serviceAccount`: Customize the controller service account and its annotations. - - `imagePullSecret` / `imagePullSecrets`: Private registry credentials. - - `snippetsFilters.enable`: Enable filters around user-provided NGINX config snippets (default false). - - `terminationGracePeriodSeconds`: Default 30 seconds. - - `topologySpreadConstraints`, `tolerations`, `nodeSelector`, `affinity`: Pod scheduling controls. +To view all Operator-specific configurations avaialbe, run this command + +```shell +oc explain NginxGatewayFabric +``` + +Example output: + +```shell + +``` ## Pod scheduling and security (OpenShift) @@ -355,9 +251,4 @@ Ensure you have a Service and Deployment named `echo` that expose port 8080. If ## References - Red Hat Catalog (https://catalog.redhat.com/en) -- NGINX Gateway Fabric custom resource sample (https://github.com/nginx/nginx-gateway-fabric/blob/main/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml) - -## Notes - -- The Operator-specific options listed above reflect the fields exposed in the `NginxGatewayFabric` custom resource and their defaults in the referenced sample. Your environment and Operator channel may introduce additional fields or defaults. Always review the installed Operator’s CRD and documentation in your cluster for the authoritative schema. -- If your OpenShift environment does not support external LoadBalancer, prefer Route-based exposure. Configure TLS policies (edge/reencrypt/passthrough) consistent with your application’s needs. +- NGINX Gateway Fabric custom resource sample (https://github.com/nginx/nginx-gateway-fabric/blob/{{< version-ngf >}}/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml) From f0e129ce59da8f9322b829e3c88f95f9e4f42fc5 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 15:21:29 +0100 Subject: [PATCH 11/17] Update document to follow "How-to-guide" format --- content/ngf/install/openshift.md | 425 ++++++++++++++----------------- 1 file changed, 193 insertions(+), 232 deletions(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index 7cd34a6a0..3d2da0591 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -10,245 +10,206 @@ nd-docs: DOCS-1851 ## Overview -This guide explains how to install F5 NGINX Gateway Fabric (NGF) on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. +Use this guide to install F5 NGINX Gateway Fabric (NGF) on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. Install NGF with OperatorHub when you want lifecycle management integrated into OpenShift and a straightforward, recommended path to deploy NGF components. -On this page +## Before you begin -- Prerequisites for OpenShift -- Install NGINX Gateway Fabric Operator from OperatorHub -- Create the NginxGatewayFabric custom resource -- Review OpenShift considerations (images, service exposure, SCC) -- Configure operator options in the custom resource -- Validate the installation and troubleshoot issues - -## Prerequisites +Ensure you have: - A running Red Hat OpenShift cluster with cluster administrator privileges. -- Access to OperatorHub in the OpenShift Web Console. -- The oc command-line tool is installed, and you are logged in to your cluster. - Ability to pull images from `ghcr.io` (or a mirrored registry if required by your environment). -- Optional: +- A decided network exposure model: + - LoadBalancer Services (recommended where available), or + - OpenShift Routes and NodePorts (if a LoadBalancer is not available). + +- Optional integrations - F5 NGINX One dataplane API key if you plan to integrate with NGINX One. - F5 NGINX Plus entitlements if you plan to run NGF with NGINX Plus. -- Network exposure model decided: - - LoadBalancer Services (recommended where available) - - Or OpenShift Routes/NodePorts (if LoadBalancer is not available) - -### Review OpenShift support and images - -NGF provides first-class OpenShift support with Universal Base Image (UBI)-based images. Use the `-ubi` tags shown in the custom resource definition (CRD) examples below. Security constraints, such as running as non-root, are handled by defaults compatible with OpenShift Security Context Constraints (SCCs) in most environments. If your cluster enforces custom SCCs or policies, see the "Pod scheduling and security" options under operator-specific configuration. - -## Install NGINX Gateway Fabric Operator from OperatorHub - -1. Go to the Red Hat Catalog: https://catalog.redhat.com/en -2. Search for "NGINX Gateway Fabric Operator". -3. Select NGINX Gateway Fabric Operator (provider: F5, Inc.). -4. Select **Deploy & use**. -5. Choose the appropriate architecture and release tag. -6. Complete the installation. Wait until the Operator status shows Installed. - -If you prefer CLI-based installation (Subscription/OperatorGroup), consult OpenShift documentation for creating `OperatorGroup` and `Subscription` resources in your chosen namespace. The Web Console path above is recommended. - -## Create a project and required secrets - -Create a dedicated project (namespace) for NGF components, for example: - -```shell -oc new-project nginx-gateway-fabric -``` - -## TLS secrets for internal communication - -NGF can generate internal certificates for agent/server by default, or you can provide your own secrets. - -Option A: Let NGF generate the certificates -- Use the default `certGenerator` settings from the sample custom resource (no additional steps needed). -- `certGenerator.overwrite: false` means NGF will not overwrite existing secrets if present. - -Option B: Provide your own secrets (example) -```shell -# Agent TLS (used by internal agent) -oc create secret tls agent-tls \ - --cert=agent.crt \ - --key=agent.key \ - -n nginx-gateway-fabric - -# Server TLS (used by internal server) -oc create secret tls server-tls \ - --cert=server.crt \ - --key=server.key \ - -n nginx-gateway-fabric -``` - -## Optional: Integrate with NGINX One - -If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key): - -```shell -oc create secret generic nginxone-dataplane-key \ - --from-literal=key=VALUE \ - -n nginx-gateway-fabric -``` - -You will reference this secret in the `spec.nginx.nginxOneConsole.dataplaneKeySecretName` field. - -## Optional: NGINX Plus licensing - -If you plan to use NGINX Plus, you will need to: -- Set `spec.nginx.plus: true` -- Provide appropriate image repository/registry credentials in `imagePullSecret(s)` -- Optionally create a secret for license and entitlement artifacts (name by convention below): - -```shell -# Example license secret name referenced by usage.secretName -oc create secret generic nplus-license \ - --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ - --from-file=nginx-repo.key=/path/to/nginx-repo.key \ - -n nginx-gateway-fabric -``` - -Consult your subscription details for the exact files/registry access used for NGINX Plus images in your environment. - -## Create the NginxGatewayFabric custom resource - -Minimal example for OpenShift: - -```yaml -apiVersion: gateway.nginx.org/v1alpha1 -kind: NginxGatewayFabric -metadata: - name: ngf - namespace: nginx-gateway-fabric -spec: - # Data plane (NGINX) - nginx: - replicas: 2 - image: - repository: ghcr.io/nginx/nginx-gateway-fabric/nginx - tag: 2.2.0-ubi - pullPolicy: IfNotPresent - - # Controller - nginxGateway: - gatewayClassName: nginx - gatewayControllerName: gateway.nginx.org/nginx-gateway-controller - image: - repository: ghcr.io/nginx/nginx-gateway-fabric - tag: 2.2.0-ubi - pullPolicy: IfNotPresent - replicas: 1 -``` - -Apply the custom resource: - -```shell -oc apply -f nginx-gateway-fabric.yaml -``` - -Wait for the Operator to reconcile. It will provision the NGF controller and data plane deployments, services, and related resources. - -## Configure exposure options for OpenShift - -- LoadBalancer Service (preferred where available): Use `spec.nginx.service.type: LoadBalancer`. You can also configure: - - `externalTrafficPolicy: Local` to preserve source IPs (useful for client IP-based policies). - - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. - -- Routes/NodePort (if a LoadBalancer is not available): - - Set `spec.nginx.service.type: NodePort` and create an OpenShift Route to the NGF front-end service (for HTTP/HTTPS traffic). - - Example (edge termination route; replace service name and ports appropriately): - ```shell - oc create route edge ngf \ - --service=nginx-gateway-fabric-nginx \ - --port=http \ - -n nginx-gateway-fabric - ``` - - For TLS passthrough, use `--passthrough` and target the appropriate service port. - -## Operator-specific configuration options (NginxGatewayFabric spec) - -To view all Operator-specific configurations avaialbe, run this command - -```shell -oc explain NginxGatewayFabric -``` - -Example output: - -```shell - -``` - -## Pod scheduling and security (OpenShift) - -- Use `nodeSelector`, `tolerations`, and `topologySpreadConstraints` to adhere to your cluster’s workload placement policies. -- OpenShift Security Context Constraints (SCCs) typically require running as non-root. NGF UBI images are compatible; avoid setting hostPorts unless you have an SCC that permits them. -- If your environment enforces custom SCCs, bind the appropriate SCC to the NGF service accounts and use `pod`/`serviceAccount` fields to reference them. - -## Validate the installation - -After applying the custom resource, verify that deployments and services are running: - -```shell -oc get pods -n nginx-gateway-fabric -oc get svc -n nginx-gateway-fabric -``` - -Check the installed GatewayClass: - -```shell -oc get gatewayclass -``` - -Logs for troubleshooting: - -```shell -# Controller logs -oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric - -# Data plane logs -oc logs deploy/ngf-nginx -n nginx-gateway-fabric -``` - -## Perform a functional check (optional) - -Create a simple Gateway and HTTPRoute to validate routing: - -```yaml -apiVersion: gateway.networking.k8s.io/v1 -kind: Gateway -metadata: - name: http - namespace: nginx-gateway-fabric -spec: - gatewayClassName: nginx - listeners: - - name: http - port: 80 - protocol: HTTP - hostname: example.com - allowedRoutes: - namespaces: - from: Same ---- -apiVersion: gateway.networking.k8s.io/v1 -kind: HTTPRoute -metadata: - name: echo - namespace: nginx-gateway-fabric -spec: - parentRefs: - - name: http - hostnames: - - example.com - rules: - - backendRefs: - - name: echo - port: 8080 -``` - -Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. - -## References +Note: NGF provides first-class OpenShift support with Universal Base Image (UBI)-based images. Use the `-ubi` tags shown in the custom resource definition (CRD) examples. Defaults are compatible with OpenShift Security Context Constraints (SCCs) for non-root operation. If your cluster enforces custom SCCs or policies, bind the appropriate SCC to NGF service accounts. + +## Steps + +### Install NGINX Gateway Fabric Operator from OperatorHub + +1. To install the Operator, do the following: + 1.1. Go to the Red Hat Catalog: https://catalog.redhat.com/en + 1.2. Search for "NGINX Gateway Fabric Operator". + 1.3. Select NGINX Gateway Fabric Operator (provider: F5, Inc.). + 1.4. Select **Deploy & use**. + 1.5. Choose the appropriate architecture and release tag. + 1.6. Complete the installation. Wait until the Operator status shows Installed. + + Result: The NGF Operator is installed and available in your cluster. + +### Create a project + +2. Create a dedicated project (namespace) for NGF components. + ```bash + oc new-project nginx-gateway-fabric + ``` + + Result: The `nginx-gateway-fabric` project is created. + +### Create TLS secrets for internal communication (optional) + +3. If you want NGF to auto-generate internal certificates, skip this step. To provide your own TLS secrets, create the following: + ```bash + # Agent TLS (used by internal agent) + oc create secret tls agent-tls \ + --cert=agent.crt \ + --key=agent.key \ + -n nginx-gateway-fabric + + # Server TLS (used by internal server) + oc create secret tls server-tls \ + --cert=server.crt \ + --key=server.key \ + -n nginx-gateway-fabric + ``` + + Result: The `agent-tls` and `server-tls` secrets are available in the project. + +### Integrate with NGINX One (optional) + +4. If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). + ```bash + oc create secret generic nginxone-dataplane-key \ + --from-literal=key=VALUE \ + -n nginx-gateway-fabric + ``` + Next, reference this secret in `spec.nginx.nginxOneConsole.dataplaneKeySecretName`. + + Result: NGF can authenticate to NGINX One using the dataplane key. + +### Configure NGINX Plus licensing (optional) + +5. If you plan to use NGINX Plus, set `spec.nginx.plus: true`, add image pull credentials, and create a license secret if needed. + ```bash + # Example license secret name referenced by usage.secretName + oc create secret generic nplus-license \ + --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ + --from-file=nginx-repo.key=/path/to/nginx-repo.key \ + -n nginx-gateway-fabric + ``` + + Result: NGF is configured to use NGINX Plus images and license artifacts. + +### Create the NginxGatewayFabric custom resource + +6. Create a minimal `NginxGatewayFabric` custom resource for OpenShift. + ```yaml + apiVersion: gateway.nginx.org/v1alpha1 + kind: NginxGatewayFabric + metadata: + name: ngf + namespace: nginx-gateway-fabric + spec: + # Data plane (NGINX) + nginx: + replicas: 2 + image: + repository: ghcr.io/nginx/nginx-gateway-fabric/nginx + tag: 2.2.0-ubi + pullPolicy: IfNotPresent + + # Controller + nginxGateway: + gatewayClassName: nginx + gatewayControllerName: gateway.nginx.org/nginx-gateway-controller + image: + repository: ghcr.io/nginx/nginx-gateway-fabric + tag: 2.2.0-ubi + pullPolicy: IfNotPresent + replicas: 1 + ``` + Apply the custom resource: + ```bash + oc apply -f nginx-gateway-fabric.yaml + ``` + + Result: The Operator reconciles the custom resource and provisions the NGF controller and data plane. + +### Configure exposure options for OpenShift (optional) + +7. Choose one exposure option: + + - If a LoadBalancer is available, set `spec.nginx.service.type: LoadBalancer`. Optionally set: + - `externalTrafficPolicy: Local` to preserve client source IPs. + - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. + + - If a LoadBalancer is not available, set `spec.nginx.service.type: NodePort`, then create an OpenShift Route to the NGF front-end Service (for HTTP/HTTPS traffic): + ```bash + oc create route edge ngf \ + --service=nginx-gateway-fabric-nginx \ + --port=http \ + -n nginx-gateway-fabric + ``` + For TLS passthrough, add `--passthrough` and target the appropriate Service port. + + Result: NGF is reachable according to your cluster’s exposure model. + +### Validate the installation + +8. Verify that deployments and services are running, and confirm the GatewayClass: + ```bash + oc get pods -n nginx-gateway-fabric + oc get svc -n nginx-gateway-fabric + oc get gatewayclass + ``` + If troubleshooting is required, review logs: + ```bash + # Controller logs + oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric + + # Data plane logs + oc logs deploy/ngf-nginx -n nginx-gateway-fabric + ``` + + Result: NGF components are running and reporting readiness. + +### Perform a functional check (optional) + +9. Create a simple Gateway and HTTPRoute to validate routing: + ```yaml + apiVersion: gateway.networking.k8s.io/v1 + kind: Gateway + metadata: + name: http + namespace: nginx-gateway-fabric + spec: + gatewayClassName: nginx + listeners: + - name: http + port: 80 + protocol: HTTP + hostname: example.com + allowedRoutes: + namespaces: + from: Same + --- + apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: echo + namespace: nginx-gateway-fabric + spec: + parentRefs: + - name: http + hostnames: + - example.com + rules: + - backendRefs: + - name: echo + port: 8080 + ``` + Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. + + Result: Requests to `example.com` route to the `echo` backend through NGF. + +## See also + +- Install NGINX Gateway Fabric with Helm: /ngf/install/helm/ +- Secure certificates for NGF: /ngf/install/secure-certificates/ - Red Hat Catalog (https://catalog.redhat.com/en) - NGINX Gateway Fabric custom resource sample (https://github.com/nginx/nginx-gateway-fabric/blob/{{< version-ngf >}}/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml) From 6cd31ce1329830cfb78abf7729620db74c6f3572 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 15:22:29 +0100 Subject: [PATCH 12/17] Replace `bash` with `shell` --- content/ngf/install/openshift.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index 3d2da0591..8c9055f22 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -45,7 +45,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Create a project 2. Create a dedicated project (namespace) for NGF components. - ```bash + ```shell oc new-project nginx-gateway-fabric ``` @@ -54,7 +54,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Create TLS secrets for internal communication (optional) 3. If you want NGF to auto-generate internal certificates, skip this step. To provide your own TLS secrets, create the following: - ```bash + ```shell # Agent TLS (used by internal agent) oc create secret tls agent-tls \ --cert=agent.crt \ @@ -73,7 +73,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Integrate with NGINX One (optional) 4. If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). - ```bash + ```shell oc create secret generic nginxone-dataplane-key \ --from-literal=key=VALUE \ -n nginx-gateway-fabric @@ -85,7 +85,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Configure NGINX Plus licensing (optional) 5. If you plan to use NGINX Plus, set `spec.nginx.plus: true`, add image pull credentials, and create a license secret if needed. - ```bash + ```shell # Example license secret name referenced by usage.secretName oc create secret generic nplus-license \ --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ @@ -124,7 +124,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) replicas: 1 ``` Apply the custom resource: - ```bash + ```shell oc apply -f nginx-gateway-fabric.yaml ``` @@ -139,7 +139,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. - If a LoadBalancer is not available, set `spec.nginx.service.type: NodePort`, then create an OpenShift Route to the NGF front-end Service (for HTTP/HTTPS traffic): - ```bash + ```shell oc create route edge ngf \ --service=nginx-gateway-fabric-nginx \ --port=http \ @@ -152,13 +152,13 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Validate the installation 8. Verify that deployments and services are running, and confirm the GatewayClass: - ```bash + ```shell oc get pods -n nginx-gateway-fabric oc get svc -n nginx-gateway-fabric oc get gatewayclass ``` If troubleshooting is required, review logs: - ```bash + ```shell # Controller logs oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric From e5642d87c27dcc3b074468f12327d4396305d9e1 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 15:27:47 +0100 Subject: [PATCH 13/17] Fix pre-commit errors --- content/ngf/install/openshift.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index 8c9055f22..b98ac9496 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -45,6 +45,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Create a project 2. Create a dedicated project (namespace) for NGF components. + ```shell oc new-project nginx-gateway-fabric ``` @@ -54,6 +55,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Create TLS secrets for internal communication (optional) 3. If you want NGF to auto-generate internal certificates, skip this step. To provide your own TLS secrets, create the following: + ```shell # Agent TLS (used by internal agent) oc create secret tls agent-tls \ @@ -73,11 +75,13 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Integrate with NGINX One (optional) 4. If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). + ```shell oc create secret generic nginxone-dataplane-key \ --from-literal=key=VALUE \ -n nginx-gateway-fabric ``` + Next, reference this secret in `spec.nginx.nginxOneConsole.dataplaneKeySecretName`. Result: NGF can authenticate to NGINX One using the dataplane key. @@ -85,6 +89,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Configure NGINX Plus licensing (optional) 5. If you plan to use NGINX Plus, set `spec.nginx.plus: true`, add image pull credentials, and create a license secret if needed. + ```shell # Example license secret name referenced by usage.secretName oc create secret generic nplus-license \ @@ -98,6 +103,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Create the NginxGatewayFabric custom resource 6. Create a minimal `NginxGatewayFabric` custom resource for OpenShift. + ```yaml apiVersion: gateway.nginx.org/v1alpha1 kind: NginxGatewayFabric @@ -123,7 +129,9 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) pullPolicy: IfNotPresent replicas: 1 ``` + Apply the custom resource: + ```shell oc apply -f nginx-gateway-fabric.yaml ``` @@ -139,12 +147,14 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. - If a LoadBalancer is not available, set `spec.nginx.service.type: NodePort`, then create an OpenShift Route to the NGF front-end Service (for HTTP/HTTPS traffic): + ```shell oc create route edge ngf \ --service=nginx-gateway-fabric-nginx \ --port=http \ -n nginx-gateway-fabric ``` + For TLS passthrough, add `--passthrough` and target the appropriate Service port. Result: NGF is reachable according to your cluster’s exposure model. @@ -152,12 +162,15 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Validate the installation 8. Verify that deployments and services are running, and confirm the GatewayClass: + ```shell oc get pods -n nginx-gateway-fabric oc get svc -n nginx-gateway-fabric oc get gatewayclass ``` + If troubleshooting is required, review logs: + ```shell # Controller logs oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric @@ -171,6 +184,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) ### Perform a functional check (optional) 9. Create a simple Gateway and HTTPRoute to validate routing: + ```yaml apiVersion: gateway.networking.k8s.io/v1 kind: Gateway @@ -203,6 +217,7 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) - name: echo port: 8080 ``` + Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. Result: Requests to `example.com` route to the `echo` backend through NGF. From 0c077c75a2360e1f7c0288c292f5dd3a4fd11a6f Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 16:13:34 +0100 Subject: [PATCH 14/17] Fix pre-commit errors --- content/ngf/install/build-image.md | 2 +- content/ngf/install/openshift.md | 244 ++++++++++++++--------------- 2 files changed, 118 insertions(+), 128 deletions(-) diff --git a/content/ngf/install/build-image.md b/content/ngf/install/build-image.md index 7e229f4c1..5211f5e17 100644 --- a/content/ngf/install/build-image.md +++ b/content/ngf/install/build-image.md @@ -1,6 +1,6 @@ --- title: Build NGINX Gateway Fabric -weight: 400 +weight: 500 toc: true nd-content-type: how-to nd-product: NGF diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index b98ac9496..c551154ea 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -1,7 +1,7 @@ --- title: Install NGINX Gateway Fabric on OpenShift using OperatorHub description: Deploy F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub and configure it using the NginxGatewayFabric custom resource. -weight: 500 +weight: 400 toc: true nd-content-type: how-to nd-product: NGF @@ -10,101 +10,92 @@ nd-docs: DOCS-1851 ## Overview -Use this guide to install F5 NGINX Gateway Fabric (NGF) on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. Install NGF with OperatorHub when you want lifecycle management integrated into OpenShift and a straightforward, recommended path to deploy NGF components. +This guide details how to install F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. ## Before you begin -Ensure you have: +Before starting, we recommend you have the following: - A running Red Hat OpenShift cluster with cluster administrator privileges. - Ability to pull images from `ghcr.io` (or a mirrored registry if required by your environment). -- A decided network exposure model: - - LoadBalancer Services (recommended where available), or - - OpenShift Routes and NodePorts (if a LoadBalancer is not available). - Optional integrations - - F5 NGINX One dataplane API key if you plan to integrate with NGINX One. - - F5 NGINX Plus entitlements if you plan to run NGF with NGINX Plus. + - F5 NGINX One dataplane API key if you plan to integrate with [F5 NGINX One Console](https://docs.nginx.com/nginx-one/). + - F5 NGINX Plus entitlements if you plan to run NGINX Gateway Fabric with F5 NGINX Plus. -Note: NGF provides first-class OpenShift support with Universal Base Image (UBI)-based images. Use the `-ubi` tags shown in the custom resource definition (CRD) examples. Defaults are compatible with OpenShift Security Context Constraints (SCCs) for non-root operation. If your cluster enforces custom SCCs or policies, bind the appropriate SCC to NGF service accounts. +NGINX Gateway Fabric provides first-class OpenShift support with Universal Base Image (UBI)-based images. Use the `-ubi` tags shown in the custom resource definition (CRD) examples. Defaults are compatible with OpenShift Security Context Constraints (SCCs) for non-root operation. If your cluster enforces custom SCCs or policies, bind the appropriate SCC to NGINX Gateway Fabric service accounts. ## Steps ### Install NGINX Gateway Fabric Operator from OperatorHub -1. To install the Operator, do the following: - 1.1. Go to the Red Hat Catalog: https://catalog.redhat.com/en - 1.2. Search for "NGINX Gateway Fabric Operator". - 1.3. Select NGINX Gateway Fabric Operator (provider: F5, Inc.). - 1.4. Select **Deploy & use**. - 1.5. Choose the appropriate architecture and release tag. - 1.6. Complete the installation. Wait until the Operator status shows Installed. - - Result: The NGF Operator is installed and available in your cluster. + 1. Navigate to the Red Hat Catalog: https://catalog.redhat.com/en + 2. Search for "NGINX Gateway Fabric Operator" in the searchbar at the top + 3. Select NGINX Gateway Fabric Operator + 4. Select **Deploy & use**. + 5. Choose the appropriate architecture and release tag + 6. Complete the installation. Wait until the Operator status shows Installed ### Create a project -2. Create a dedicated project (namespace) for NGF components. - - ```shell - oc new-project nginx-gateway-fabric - ``` +In your cluster, create a dedicated project (namespace) for NGINX Gateway Fabric components. - Result: The `nginx-gateway-fabric` project is created. +```shell +oc new-project nginx-gateway-fabric +``` ### Create TLS secrets for internal communication (optional) -3. If you want NGF to auto-generate internal certificates, skip this step. To provide your own TLS secrets, create the following: +If you want NGINX Gateway Fabric to auto-generate internal certificates, skip this step. To provide your own TLS secrets, create the following: - ```shell - # Agent TLS (used by internal agent) - oc create secret tls agent-tls \ - --cert=agent.crt \ - --key=agent.key \ - -n nginx-gateway-fabric +Agent TLS (used by internal agent) - # Server TLS (used by internal server) - oc create secret tls server-tls \ - --cert=server.crt \ - --key=server.key \ - -n nginx-gateway-fabric - ``` +```shell +oc create secret tls agent-tls \ + --cert=agent.crt \ + --key=agent.key \ + -n nginx-gateway-fabric +``` + +Server TLS (used by internal server) - Result: The `agent-tls` and `server-tls` secrets are available in the project. +```shell +oc create secret tls server-tls \ + --cert=server.crt \ + --key=server.key \ + -n nginx-gateway-fabric +``` ### Integrate with NGINX One (optional) -4. If you want NGF to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). +If you want NGINX Gateway Fabric to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). - ```shell - oc create secret generic nginxone-dataplane-key \ - --from-literal=key=VALUE \ - -n nginx-gateway-fabric - ``` +```shell +oc create secret generic nginxone-dataplane-key \ + --from-literal=key=VALUE \ + -n nginx-gateway-fabric +``` - Next, reference this secret in `spec.nginx.nginxOneConsole.dataplaneKeySecretName`. - - Result: NGF can authenticate to NGINX One using the dataplane key. +Reference this secret in `spec.nginx.nginxOneConsole.dataplaneKeySecretName`. ### Configure NGINX Plus licensing (optional) -5. If you plan to use NGINX Plus, set `spec.nginx.plus: true`, add image pull credentials, and create a license secret if needed. +If you plan to use NGINX Plus, set `spec.nginx.plus: true`, add image pull credentials, and create a license secret if needed. - ```shell - # Example license secret name referenced by usage.secretName - oc create secret generic nplus-license \ - --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ - --from-file=nginx-repo.key=/path/to/nginx-repo.key \ - -n nginx-gateway-fabric - ``` +Example license secret name referenced by `usage.secretName` - Result: NGF is configured to use NGINX Plus images and license artifacts. +```shell +oc create secret generic nplus-license \ + --from-file=nginx-repo.crt=/path/to/nginx-repo.crt \ + --from-file=nginx-repo.key=/path/to/nginx-repo.key \ + -n nginx-gateway-fabric +``` ### Create the NginxGatewayFabric custom resource -6. Create a minimal `NginxGatewayFabric` custom resource for OpenShift. +Create a minimal `NginxGatewayFabric` custom resource for OpenShift. - ```yaml +```yaml apiVersion: gateway.nginx.org/v1alpha1 kind: NginxGatewayFabric metadata: @@ -130,101 +121,100 @@ Note: NGF provides first-class OpenShift support with Universal Base Image (UBI) replicas: 1 ``` - Apply the custom resource: +Apply the custom resource: - ```shell - oc apply -f nginx-gateway-fabric.yaml - ``` +```shell +oc apply -f nginx-gateway-fabric.yaml +``` - Result: The Operator reconciles the custom resource and provisions the NGF controller and data plane. +Result: The Operator reconciles the custom resource and provisions the NGINX Gateway Fabric controller and data plane. ### Configure exposure options for OpenShift (optional) -7. Choose one exposure option: +Choose one exposure option: - - If a LoadBalancer is available, set `spec.nginx.service.type: LoadBalancer`. Optionally set: - - `externalTrafficPolicy: Local` to preserve client source IPs. - - `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. +If a LoadBalancer is available, set `spec.nginx.service.type: LoadBalancer`. Optionally set: - - If a LoadBalancer is not available, set `spec.nginx.service.type: NodePort`, then create an OpenShift Route to the NGF front-end Service (for HTTP/HTTPS traffic): +- `externalTrafficPolicy: Local` to preserve client source IPs. +- `loadBalancerClass`, `loadBalancerIP`, and `loadBalancerSourceRanges` per your environment. - ```shell - oc create route edge ngf \ - --service=nginx-gateway-fabric-nginx \ - --port=http \ - -n nginx-gateway-fabric - ``` +If a LoadBalancer is not available, set `spec.nginx.service.type: NodePort`, then create an OpenShift Route to the NGINX Gateway Fabric front-end Service (for HTTP/HTTPS traffic): - For TLS passthrough, add `--passthrough` and target the appropriate Service port. +```shell +oc create route edge ngf \ + --service=nginx-gateway-fabric-nginx \ + --port=http \ + -n nginx-gateway-fabric +``` - Result: NGF is reachable according to your cluster’s exposure model. +For TLS passthrough, add `--passthrough` and target the appropriate Service port. ### Validate the installation -8. Verify that deployments and services are running, and confirm the GatewayClass: +Verify that deployments and services are running, and confirm the GatewayClass: - ```shell - oc get pods -n nginx-gateway-fabric - oc get svc -n nginx-gateway-fabric - oc get gatewayclass - ``` +```shell +oc get pods -n nginx-gateway-fabric +oc get svc -n nginx-gateway-fabric +oc get gatewayclass +``` - If troubleshooting is required, review logs: +If troubleshooting is required, review logs - ```shell - # Controller logs - oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric +Controller logs - # Data plane logs - oc logs deploy/ngf-nginx -n nginx-gateway-fabric - ``` +```shell +oc logs deploy/ngf-nginx-gateway -n nginx-gateway-fabric +``` - Result: NGF components are running and reporting readiness. +Data plane logs + +```shell +oc logs deploy/ngf-nginx -n nginx-gateway-fabric +``` ### Perform a functional check (optional) 9. Create a simple Gateway and HTTPRoute to validate routing: - ```yaml - apiVersion: gateway.networking.k8s.io/v1 - kind: Gateway - metadata: - name: http - namespace: nginx-gateway-fabric - spec: - gatewayClassName: nginx - listeners: - - name: http - port: 80 - protocol: HTTP - hostname: example.com - allowedRoutes: - namespaces: - from: Same - --- - apiVersion: gateway.networking.k8s.io/v1 - kind: HTTPRoute - metadata: - name: echo - namespace: nginx-gateway-fabric - spec: - parentRefs: - - name: http - hostnames: - - example.com - rules: - - backendRefs: - - name: echo - port: 8080 - ``` - - Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. - - Result: Requests to `example.com` route to the `echo` backend through NGF. +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: http + namespace: nginx-gateway-fabric +spec: + gatewayClassName: nginx + listeners: + - name: http + port: 80 + protocol: HTTP + hostname: example.com + allowedRoutes: + namespaces: + from: Same +--- +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: echo + namespace: nginx-gateway-fabric +spec: + parentRefs: + - name: http + hostnames: + - example.com + rules: + - backendRefs: + - name: echo + port: 8080 +``` + +Ensure you have a Service and Deployment named `echo` that expose port 8080. If you are using a LoadBalancer Service, send a request to the load balancer IP address. Otherwise, use an OpenShift Route as configured. ## See also - Install NGINX Gateway Fabric with Helm: /ngf/install/helm/ -- Secure certificates for NGF: /ngf/install/secure-certificates/ +- Secure certificates for NGINX Gateway Fabric: /ngf/install/secure-certificates/ - Red Hat Catalog (https://catalog.redhat.com/en) - NGINX Gateway Fabric custom resource sample (https://github.com/nginx/nginx-gateway-fabric/blob/{{< version-ngf >}}/operators/config/samples/gateway_v1alpha1_nginxgatewayfabric.yaml) From df1dd08a522a9a555f9f03f1c4ad8e7d28d38624 Mon Sep 17 00:00:00 2001 From: Shaun Date: Fri, 24 Oct 2025 16:49:18 +0100 Subject: [PATCH 15/17] Update content/ngf/install/openshift.md Co-authored-by: Mike Jang <3287976+mjang@users.noreply.github.com> --- content/ngf/install/openshift.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index c551154ea..77c76452e 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -1,5 +1,5 @@ --- -title: Install NGINX Gateway Fabric on OpenShift using OperatorHub +title: Install NGINX Gateway Fabric on OpenShift description: Deploy F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub and configure it using the NginxGatewayFabric custom resource. weight: 400 toc: true From 206474c0309bcb3b1cdd2db7c5bf54ddcf804358 Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 16:52:11 +0100 Subject: [PATCH 16/17] Style updates --- content/ngf/install/openshift.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/ngf/install/openshift.md b/content/ngf/install/openshift.md index 77c76452e..0643534fd 100644 --- a/content/ngf/install/openshift.md +++ b/content/ngf/install/openshift.md @@ -10,7 +10,7 @@ nd-docs: DOCS-1851 ## Overview -This guide details how to install F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub and configure it with the `NginxGatewayFabric` custom resource. +This guide details how to install F5 NGINX Gateway Fabric on Red Hat OpenShift through OperatorHub. You can then configure it with the `NginxGatewayFabric` custom resource. ## Before you begin @@ -66,9 +66,9 @@ oc create secret tls server-tls \ -n nginx-gateway-fabric ``` -### Integrate with NGINX One (optional) +### Integrate with NGINX One Console (optional) -If you want NGINX Gateway Fabric to connect to NGINX One, create a secret for the dataplane key (replace VALUE with your key). +If you want to use NGINX One Console to monitor NGINX Gateway Fabric, create a secret for the dataplane key (replace VALUE with your key). ```shell oc create secret generic nginxone-dataplane-key \ @@ -93,7 +93,7 @@ oc create secret generic nplus-license \ ### Create the NginxGatewayFabric custom resource -Create a minimal `NginxGatewayFabric` custom resource for OpenShift. +Create a minimal `NginxGatewayFabric` custom resource for OpenShift. Include this code in a file named `nginx-gateway-fabric.yaml`. ```yaml apiVersion: gateway.nginx.org/v1alpha1 @@ -175,7 +175,7 @@ oc logs deploy/ngf-nginx -n nginx-gateway-fabric ### Perform a functional check (optional) -9. Create a simple Gateway and HTTPRoute to validate routing: +Create a Gateway and HTTPRoute to validate routing: ```yaml apiVersion: gateway.networking.k8s.io/v1 From 481f9b4a19f97cec42b3d9490758d868d979bb6a Mon Sep 17 00:00:00 2001 From: shaun-nx Date: Fri, 24 Oct 2025 16:54:27 +0100 Subject: [PATCH 17/17] Revert changes to go.mod and go.sum --- go.mod | 2 +- go.sum | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/go.mod b/go.mod index 6d17da87c..ce2d2e14a 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/nginxinc/docs go 1.19 -require github.com/nginxinc/nginx-hugo-theme v1.0.15 // indirect +require github.com/nginxinc/nginx-hugo-theme v1.0.11 // indirect diff --git a/go.sum b/go.sum index c9fd59c99..f8fe75123 100644 --- a/go.sum +++ b/go.sum @@ -1,2 +1,2 @@ -github.com/nginxinc/nginx-hugo-theme v1.0.15 h1:X9G9ihCB7ceGXEgJgiYKvMHGCV/xMUBOR3aKAuT7aEA= -github.com/nginxinc/nginx-hugo-theme v1.0.15/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= +github.com/nginxinc/nginx-hugo-theme v1.0.11 h1:vsiqkg+Ba7CN05SaY9HEPbPinz3Y1xjNZ/qdhhp7Hrc= +github.com/nginxinc/nginx-hugo-theme v1.0.11/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= \ No newline at end of file