From f03eee56d72fe2a3a5b56f662e5f6bd921ed076b Mon Sep 17 00:00:00 2001 From: Saylor Berman Date: Mon, 12 Aug 2024 15:21:05 -0600 Subject: [PATCH] Add high level doc for data plane config Problem: As a user, I want to know how I can configure global settings for nginx. Solution: Add a doc that talks about how global data plane config can be set. --- .github/workflows/docs-build-push.yml | 18 +++- .../how-to/control-plane-configuration.md | 32 ++----- .../how-to/data-plane-configuration.md | 90 +++++++++++++++++++ .../how-to/upgrade-apps-without-downtime.md | 2 +- 4 files changed, 114 insertions(+), 28 deletions(-) create mode 100644 site/content/how-to/data-plane-configuration.md diff --git a/.github/workflows/docs-build-push.yml b/.github/workflows/docs-build-push.yml index 6097c7d455..16e0e97328 100644 --- a/.github/workflows/docs-build-push.yml +++ b/.github/workflows/docs-build-push.yml @@ -18,12 +18,28 @@ on: paths: - "site/**" +concurrency: + group: ${{ github.ref_name }}-docs-push + cancel-in-progress: true + permissions: contents: read jobs: + vars: + runs-on: ubuntu-22.04 + outputs: + azure_creds: ${{ steps.vars.outputs.defined }} + steps: + - name: "Check if variable is set" + env: + AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS_DOCS }} + if: "${{ env.AZURE_CREDENTIALS != '' }}" + run: echo "defined=true" >> $GITHUB_OUTPUT + call-docs-build-push: - if: ${{ github.event.repository.fork == false }} + needs: [vars] + if: ${{ github.event.repository.fork == false && needs.vars.outputs.azure_creds == 'true' }} uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@03a9a3808fcb77cd0c19d7fa5d59b25565dd1d6d # v1.0.2 permissions: pull-requests: write # needed to write preview url comment to PR diff --git a/site/content/how-to/control-plane-configuration.md b/site/content/how-to/control-plane-configuration.md index 293679185a..5c0a9b2b71 100644 --- a/site/content/how-to/control-plane-configuration.md +++ b/site/content/how-to/control-plane-configuration.md @@ -5,7 +5,7 @@ toc: true docs: "DOCS-1416" --- -Learn how to dynamically update the Gateway Fabric control plane configuration. +Learn how to dynamically update the NGINX Gateway Fabric control plane configuration. ## Overview @@ -22,42 +22,22 @@ If the resource is invalid to the OpenAPI schema, the Kubernetes API server will Additionally, the control plane updates the status of the resource (if it exists) to reflect whether it is valid or not. -### Spec - -{{< bootstrap-table "table table-striped table-bordered" >}} -| name | description | type | required | -|---------|-----------------------------------------------------------------|--------------------------|----------| -| logging | Logging defines logging related settings for the control plane. | [logging](#speclogging) | no | -{{< /bootstrap-table >}} - -### Spec.Logging - -{{< bootstrap-table "table table-striped table-bordered" >}} -| name | description | type | required | -|-------|------------------------------------------------------------------------|--------|----------| -| level | Level defines the logging level. Supported values: info, debug, error. | string | no | -{{< /bootstrap-table >}} +**For a full list of configuration options that can be set, see the `NginxGateway spec` in the [API reference]({{< relref "reference/api.md" >}}).** ## Viewing and Updating the Configuration -{{< note >}} For the following examples, the name `nginx-gateway-config` should be updated to the name of the resource created for your installation. {{< /note >}} +{{< note >}} For the following examples, the name `ngf-config` should be updated to the name of the resource created for your installation.{{< /note >}} -To view the current configuration: +To view the current configuration and its status: ```shell -kubectl -n nginx-gateway get nginxgateways nginx-gateway-config -o yaml +kubectl -n nginx-gateway describe nginxgateways ngf-config ``` To update the configuration: ```shell -kubectl -n nginx-gateway edit nginxgateways nginx-gateway-config +kubectl -n nginx-gateway edit nginxgateways ngf-config ``` This will open the configuration in your default editor. You can then update and save the configuration, which is applied automatically to the control plane. - -To view the status of the configuration: - -```shell -kubectl -n nginx-gateway describe nginxgateways nginx-gateway-config -``` diff --git a/site/content/how-to/data-plane-configuration.md b/site/content/how-to/data-plane-configuration.md new file mode 100644 index 0000000000..63db414eff --- /dev/null +++ b/site/content/how-to/data-plane-configuration.md @@ -0,0 +1,90 @@ +--- +title: "Data plane configuration" +weight: 400 +toc: true +docs: "DOCS-000" +--- + +Learn how to dynamically update the NGINX Gateway Fabric global data plane configuration. + +## Overview + +NGINX Gateway Fabric can dynamically update the global data plane configuration without restarting. The data plane configuration is a global configuration for nginx that has options that are not available using the standard Gateway API resources. This includes such things as setting an OpenTelemetry collector config, disabling http2, or changing the IP family. + +The data plane configuration is stored in the NginxProxy custom resource, which is a cluster-scoped resource that is attached to the `nginx` GatewayClass. + +By default, the NginxProxy resource is not created when installing NGINX Gateway Fabric. However, you can set configuration options in the `nginx.config` Helm values, and the resource will be created and attached when NGINX Gateway Fabric is installed using Helm. You can also [manually create and attach](#manually-creating-the-configuration) the resource after NGINX Gateway Fabric is already installed. + +If installed using the Helm chart, the NginxProxy resource is named `-proxy-config`. + +**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< relref "reference/api.md" >}}).** + +{{}}Some global configuration also requires an [associated policy]({{< relref "overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< relref "/how-to/monitoring/tracing.md" >}}), for example).{{}} + +## Viewing and Updating the Configuration + +If the `NginxProxy` resource already exists, you can view and edit it. + +{{< note >}} For the following examples, the name `ngf-proxy-config` should be updated to the name of the resource created for your installation.{{< /note >}} + +To view the current configuration: + +```shell +kubectl describe nginxproxies ngf-proxy-config +``` + +To update the configuration: + +```shell +kubectl edit nginxproxies ngf-proxy-config +``` + +This will open the configuration in your default editor. You can then update and save the configuration, which is applied automatically to the data plane. + +To view the status of the configuration, check the GatewayClass that it is attached to: + +```shell +kubectl describe gatewayclasses nginx +``` + +If everything is valid, the `ResolvedRefs` condition should be `True`. Otherwise, you will see an `InvalidParameters` condition in the status. + +## Manually Creating the Configuration + +If the `NginxProxy` resource doesn't exist, you can create it and attach it to the GatewayClass. + +The following command creates a basic `NginxProxy` configuration that sets the IP family to `ipv4` instead of the default value of `dual`: + +```yaml +kubectl apply -f - <