diff --git a/.github/workflows/docs-build-push.yml b/.github/workflows/docs-build-push.yml deleted file mode 100644 index ffff97d78b..0000000000 --- a/.github/workflows/docs-build-push.yml +++ /dev/null @@ -1,63 +0,0 @@ -name: Build and deploy documentation -on: - workflow_dispatch: - inputs: - environment: - description: 'Environment to deploy to' - required: true - default: 'preview' - type: choice - options: - - preview - - dev - - staging - - prod - hugo_theme_override: - description: "Hugo theme version (Leave blank for latest)" - required: false - default: "" - type: string - pull_request: - branches: - - "*" - paths: - - "site/**" - -concurrency: - group: ${{ github.ref_name }}-docs-push - cancel-in-progress: true - -permissions: - contents: read - -jobs: - vars: - runs-on: ubuntu-24.04 - outputs: - azure_creds: ${{ steps.vars.outputs.defined }} - steps: - - name: Check if variable is set - id: vars - env: - AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS_DOCS }} - if: "${{ env.AZURE_CREDENTIALS != '' }}" - run: echo "defined=true" >> $GITHUB_OUTPUT - - call-docs-build-push: - needs: [vars] - if: ${{ github.event.repository.fork == false && needs.vars.outputs.azure_creds == 'true' }} - uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@9c59fab05a8131f4d691ba6ea2b6a119f3ef832a # v1.0.7 - permissions: - pull-requests: write # Required to add the preview URL comment - contents: read - with: - production_url_path: "/nginx-gateway-fabric" - preview_url_path: "/previews/nginx-gateway-fabric" - docs_source_path: "public/nginx-gateway-fabric" - docs_build_path: "./site" - doc_type: "hugo" - environment: ${{ inputs.environment }} - force_hugo_theme_version: ${{ inputs.hugo_theme_override }} - secrets: - AZURE_CREDENTIALS: ${{ secrets.AZURE_CREDENTIALS_DOCS }} - AZURE_KEY_VAULT: ${{ secrets.AZURE_KEY_VAULT_DOCS }} diff --git a/.gitignore b/.gitignore index 4dbda581d7..40bb4be096 100644 --- a/.gitignore +++ b/.gitignore @@ -61,3 +61,7 @@ internal/mode/static/nginx/modules/coverage # temporary files used for manifest generation config/base/deploy.yaml config/base/deploy.yaml.bak + +# Temporary API documentation file, which should be committed +# to the main documentation repository instead +docs/api/content.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 141929153f..5428414b42 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,7 +46,7 @@ Follow our [Installation Instructions](https://docs.nginx.com/nginx-gateway-fabr - We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies. - We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit tests. -- The documentation website is found under `site/`. +- The documentation is managed in [the NGINX documentation repository](https://github.com/nginx/documentation). ## Contributing @@ -97,7 +97,7 @@ Before beginning development, familiarize yourself with the following documents: conventions to follow when writing Go code for the project. - [Architecture](https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-architecture/): A high-level overview of the project's architecture. - [Design Principles](/docs/developer/design-principles.md): An overview of the project's design principles. -- [NGINX Gateway Fabric Documentation](/site/README.md): An explanation of the documentation tooling and conventions. +- [The NGINX documentation repository](https://github.com/nginx/documentation): The repository for NGINX documentation, which is used for the website. ## F5 Contributor License Agreement (CLA) diff --git a/Makefile b/Makefile index 39554f3f2b..bf3d52d10f 100644 --- a/Makefile +++ b/Makefile @@ -141,7 +141,7 @@ generate-manifests: ## Generate manifests using Helm. ./scripts/generate-manifests.sh generate-api-docs: ## Generate API docs - go run github.com/ahmetb/gen-crd-api-reference-docs@$(GEN_CRD_API_REFERENCE_DOCS_VERSION) -config site/config/api/config.json -template-dir site/config/api -out-file site/content/reference/api.md -api-dir "github.com/nginx/nginx-gateway-fabric/apis" + go run github.com/ahmetb/gen-crd-api-reference-docs@$(GEN_CRD_API_REFERENCE_DOCS_VERSION) -config docs/api/config.json -template-dir docs/api -out-file docs/api/content.md -api-dir "github.com/nginx/nginx-gateway-fabric/apis" .PHONY: generate-helm-docs generate-helm-docs: ## Generate the Helm chart documentation diff --git a/README.md b/README.md index 96461179b0..26a3df593f 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Learn about our [design principles](/docs/developer/design-principles.md) and [a ## Getting Started -1. [Quick Start on a kind cluster](https://docs.nginx.com/nginx-gateway-fabric/get-started/). +1. [Get started using a kind cluster](https://docs.nginx.com/nginx-gateway-fabric/get-started/). 2. [Install](https://docs.nginx.com/nginx-gateway-fabric/installation/) NGINX Gateway Fabric. 3. Deploy various [examples](examples). 4. Read our [How-to guides](https://docs.nginx.com/nginx-gateway-fabric/how-to/). diff --git a/docs/README.md b/docs/README.md index 516d7c9108..b40e1fd4ae 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,3 +8,4 @@ _Please note: You can find the user documentation for NGINX Gateway Fabric in th - [Developer](developer/): Docs for developers of the project. Contains guides relating to processes and workflows. - [Proposals](proposals/): Enhancement proposals for new features. +- [API](api/): The files for generating API documentation, used in the Makefile diff --git a/site/config/api/config.json b/docs/api/config.json similarity index 100% rename from site/config/api/config.json rename to docs/api/config.json diff --git a/site/config/api/members.tpl b/docs/api/members.tpl similarity index 100% rename from site/config/api/members.tpl rename to docs/api/members.tpl diff --git a/site/config/api/pkg.tpl b/docs/api/pkg.tpl similarity index 95% rename from site/config/api/pkg.tpl rename to docs/api/pkg.tpl index c5250235f7..e21eeb5968 100644 --- a/site/config/api/pkg.tpl +++ b/docs/api/pkg.tpl @@ -2,7 +2,9 @@ --- title: "API reference" weight: 100 -toc: false +type: reference +product: NGF +docs: DOCS-000 --- ## Overview diff --git a/site/config/api/type.tpl b/docs/api/type.tpl similarity index 100% rename from site/config/api/type.tpl rename to docs/api/type.tpl diff --git a/site/.gitignore b/site/.gitignore deleted file mode 100644 index 919b131ed5..0000000000 --- a/site/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -public -.hugo_build.lock -resources diff --git a/site/.markdownlint.json b/site/.markdownlint.json deleted file mode 100644 index f25d51518a..0000000000 --- a/site/.markdownlint.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "MD009": false, - "MD012": false, - "MD010": false, - "MD013": false, - "MD004": { - "style": "dash" - }, - "MD022": false, - "MD033": false, - "MD041": false, - "MD003": false, - "MD002": false, - "MD024": { - "siblings_only": true - }, - "MD046": false, - "MD001": false, - "MD049": false, - "MD055": false, - "MD056": false -} diff --git a/site/Makefile b/site/Makefile deleted file mode 100644 index bb62ce8b67..0000000000 --- a/site/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -HUGO?=hugo -HUGO_VERSION?=$(shell hugo version 2>/dev/null | awk '{print $$2}' | cut -d '.' -f 2) -HUGO_IMG?=hugomods/hugo:std-go-git-0.134.3 - -THEME_MODULE = github.com/nginxinc/nginx-hugo-theme - -ifeq ($(shell [ $(HUGO_VERSION) -gt 133 2>/dev/null ] && echo true || echo false), true) - $(info Hugo is available and has a version greater than 133. Proceeding with build.) -else - $(warning Hugo is not available or using a version less than 134. Attempting to use docker. HUGO_VERSION=$(HUGO_VERSION)) - HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} /src/hugo-entrypoint.sh - ifeq (, $(shell docker version 2> /dev/null)) - $(error Hugo (>0.134) or Docker are required to build the local previews.) - endif -endif - -MARKDOWNLINT?=markdownlint -MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest - -ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) -ifeq (, $(shell docker version 2> /dev/null)) -else - MARKDOWNLINT=docker run --rm -i -v ${CURDIR}:/src --workdir /src ${MARKDOWNLINT_IMG} -endif -endif - -MARKDOWNLINKCHECK?=markdown-link-check -MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable - -ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) -ifeq (, $(shell docker version 2> /dev/null)) -else - MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} -endif -endif - - -.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check - -docs: - ${HUGO} - -watch: - ${HUGO} --bind 0.0.0.0 -p 1313 server --disableFastRender - -drafts: - ${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender - -clean: - [ -d "public" ] && rm -rf "public" - -hugo-get: - hugo mod get -u github.com/nginxinc/nginx-hugo-theme - -hugo-tidy: - hugo mod tidy - -hugo-update: hugo-get hugo-tidy - -lint-markdown: - ${MARKDOWNLINT} -c .markdownlint.yaml -- content - -link-check: - ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') diff --git a/site/README.md b/site/README.md deleted file mode 100644 index 5128219d77..0000000000 --- a/site/README.md +++ /dev/null @@ -1,164 +0,0 @@ -# NGINX Gateway Fabric Documentation - -This directory contains all of the user documentation for NGINX Gateway Fabric, as well as the requirements for building and publishing the documentation. - -We write our documentation in Markdown. We build it with [Hugo](https://gohugo.io) and our custom [NGINX Hugo theme](https://github.com/nginxinc/nginx-hugo-theme). We set up previews and deployments using our [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow. - -## Setup - -Hugo is the only requirement for building documentation, but the repository's integration tooling uses markdownlint-cli. - -> **Note**: We currently use [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production. - -Although not a strict requirement, markdown-link-check is also used in documentation development. - -If you have [Docker](https://www.docker.com/get-started/) installed, there are fallbacks for all in the [Makefile](Makefile), meaning you do need to install them. - -- [Installing Hugo](https://gohugo.io/getting-started/installing/) -- [Installing markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli?tab=readme-ov-file#installation) -- [Installing markdown-link-check](https://github.com/tcort/markdown-link-check?tab=readme-ov-file#installation). - -The configuration files are as follows: - -- *Hugo*: `config/default/config.toml` -- *markdownlint-cli*: `.markdownlint.json` -- *markdown-link-check* `md-linkcheck-config.json` - -## Repository guidelines - -Documentation follows the conventions of the regular codebase: use the following guides. - -- [Pull Request Guidelines](../docs/developer/pull-request.md) -- [Branching and Workflow](../docs/developerr/branching-and-workflow.md) -- [Release Process](../docs/developer/developer/release-process.md) - -To work on documentation, create a feature branch in a forked repository then target `main` with your pull requests, which is the default repository branch. - -The documentation is published from the latest public release branch. If your changes require immediate publication, create a pull request to cherry-pick changes from `main` to the public release branch. - -## Developing documentation locally - -To build the documentation locally, use the `make` command in the documentation folder with these targets: - -```text -make docs - Builds the documentation -make watch - Runs a local Hugo server to automatically preview changes -make drafts - Runs a local Hugo server, and displays documentation marked as drafts -make clean - Removes the output 'public' directory created by Hugo -make hugo-get - Updates the go module file with the latest version of the theme -make hugo-tidy - Removes unnecessary dependencies from the go module file -make hugo-update - Runs the hugo-get and hugo-tidy targets in sequence -make lint-markdown - Runs markdownlint on the content folder -make link-check - Runs markdown-link-check on all Markdown files -``` - -## Adding new documentation - -### Generate a new documentation file using Hugo - -To create a new documentation file containing the pre-configured Hugo front-matter with the task template, **run the following command in the documentation directory**: - -`hugo new /.` - -For example: - -```shell -hugo new getting-started/install.md -``` - -The default template -- task -- should be used for most documentation. To create documentation using the other content templates, you can use the `--kind` flag: - -```shell -hugo new tutorials/deploy.md --kind tutorial -``` - -The available content templates (`kind`) are: - -- concept: Help a user learn about a specific feature or feature set. -- tutorial: Walk a user through an example use case scenario. -- reference: Describes an API, command line tool, configuration options, etc. -- troubleshooting: Guide a user towards solving a specific problem. -- openapi: A template with the requirements to render an openapi.yaml specification. - -## Documentation formatting - -### Basic markdown formatting - -There are multiple ways to format text: for consistency and clarity, these are our conventions: - -- Bold: Two asterisks on each side - `**Bolded text**`. -- Italic: One underscore on each side - `_Italicized text_`. -- Unordered lists: One dash - `- Unordered list item`. -- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`. - -> **Note**: The ordered notation automatically enumerates lists when built by Hugo. - -Close every section with a horizontal line by using three dashes: `---`. - -### How to format internal links - -Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/). - -- Although file extensions are optional for Hugo, we include them as best practice for page anchors. -- Relative paths are preferred, but just the filename is permissible. -- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website. - -Here are two examples: - -```md -To install , refer to the [installation instructions]({{< ref "install.md" >}}). -To install , refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}). -``` - -### How to add images - -Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation. - -1. Add the image to the `/static/img` directory. -1. Add the `img` shortcode: - `{{< img src="" >}}` - - **Do not include a forward slash at the beginning of the file path.** - - This will break the image when it's rendered: read about the [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more. - -> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure). - -### Using Hugo shortcodes - -[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to format callouts, add images, and reuse content across different pages. - -For example, to use the `note` callout: - -```md -{{< note >}}Provide the text of the note here.{{< /note >}} -``` - -The callout shortcodes support multi-line blocks: - -```md -{{< caution >}} -You should probably never do this specific thing in a production environment. - -If you do, and things break, don't say we didn't warn you. -{{< /caution >}} -``` - -Supported callouts: - -- `caution` -- `important` -- `note` -- `see-also` -- `tip` -- `warning` - -Here are some other shortcodes: - -- `fa`: Inserts a Font Awesome icon -- `collapse`: Make a section collapsible -- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions -- `table`: Add scrollbars to wide tables for browsers with smaller viewports -- `link`: Link to a file, prepending its path with the Hugo baseUrl -- `openapi`: Loads an OpenAPI specifcation and render it as HTML using ReDoc -- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory -- `raw-html`: Include a block of raw HTML -- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location. diff --git a/site/config/_default/config.toml b/site/config/_default/config.toml deleted file mode 100644 index 2359305a03..0000000000 --- a/site/config/_default/config.toml +++ /dev/null @@ -1,67 +0,0 @@ -title = "NGINX Gateway Fabric" -enableGitInfo = true -baseURL = "/" -staticDir = ["static"] -languageCode = "en-us" -description = "NGINX Gateway Fabric." -refLinksErrorLevel = "ERROR" -enableRobotsTXT = "true" -#canonifyURLs = true -pluralizeListTitles = false -pygmentsCodeFences = true -pygmentsUseClasses = true - -[caches] - [caches.modules] - maxAge = -1 - -[module] -[[module.imports]] - path="github.com/nginxinc/nginx-hugo-theme" - -[markup] - [markup.highlight] - codeFences = true - guessSyntax = true - hl_Lines = "" - lineNoStart = 1 - lineNos = false - lineNumbersInTable = true - noClasses = true - style = "monokai" - tabWidth = 4 - [markup.goldmark] - [markup.goldmark.extensions] - definitionList = true - footnote = true - linkify = true - strikethrough = true - table = true - taskList = true - typographer = true - [markup.goldmark.parser] - attribute = true - autoHeadingID = true - autoHeadingIDType = "gitlab" - [markup.goldmark.renderer] - hardWraps = false - unsafe = true - xhtml = false - -[params] - useSectionPageLists = "false" - buildtype = "webdocs" - RSSLink = "/index.xml" - author = "NGINX Inc." # add your company name - github = "nginx" # add your github profile name - twitter = "@nginx" # add your twitter profile - #email = "" - noindex_kinds = [ - "taxonomy", - "taxonomyTerm" - ] - logo = "NGINX-Gateway-Fabric-product-icon.svg" - -sectionPagesMenu = "docs" - -ignoreFiles = [ "\\.sh$", "\\.DS_Store$", "\\.git.*$", "\\.txt$", "\\/config\\/.*", "README\\.*"] diff --git a/site/config/development/config.toml b/site/config/development/config.toml deleted file mode 100644 index 6d96e11dfa..0000000000 --- a/site/config/development/config.toml +++ /dev/null @@ -1,4 +0,0 @@ -baseURL = "https://docs-dev.nginx.com/nginx-gateway-fabric" -title = "DEV -- NGINX Gateway Fabric" -publishDir = "public/nginx-gateway-fabric" -canonifyURLs = false diff --git a/site/config/docker/config.toml b/site/config/docker/config.toml deleted file mode 100644 index 98082a86de..0000000000 --- a/site/config/docker/config.toml +++ /dev/null @@ -1 +0,0 @@ -enableGitInfo = false diff --git a/site/config/production/config.toml b/site/config/production/config.toml deleted file mode 100644 index 864fe5a2a3..0000000000 --- a/site/config/production/config.toml +++ /dev/null @@ -1,4 +0,0 @@ -baseURL = "/nginx-gateway-fabric" -title = "NGINX Gateway Fabric" -publishDir = "public/nginx-gateway-fabric" -canonifyURLs = false diff --git a/site/config/staging/config.toml b/site/config/staging/config.toml deleted file mode 100644 index 60ad87efda..0000000000 --- a/site/config/staging/config.toml +++ /dev/null @@ -1,4 +0,0 @@ -baseURL = "https://docs-staging.nginx.com/nginx-gateway-fabric" -title = "STAGING -- NGINX Gateway Fabric" -publishDir = "public/nginx-gateway-fabric" -canonifyURLs = false diff --git a/site/content/_index.md b/site/content/_index.md deleted file mode 100644 index 999aa3155e..0000000000 --- a/site/content/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "Welcome to the NGINX Gateway Fabric documentation" -description: -weight: 300 -linkTitle: "NGINX Gateway Fabric" -menu: docs ---- diff --git a/site/content/changelog.md b/site/content/changelog.md deleted file mode 100644 index cd22389b78..0000000000 --- a/site/content/changelog.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Changelog" -description: "No description" -weight: 10000 -toc: true -draft: true -docs: "DOCS-1358" ---- diff --git a/site/content/get-started.md b/site/content/get-started.md deleted file mode 100644 index 13bc1de073..0000000000 --- a/site/content/get-started.md +++ /dev/null @@ -1,524 +0,0 @@ ---- -title: Get started -toc: true -weight: 200 -docs: DOCS-000 ---- - -This is a guide for getting started with NGINX Gateway Fabric. It explains how to: - -- Set up a [kind (Kubernetes in Docker)](https://kind.sigs.k8s.io/) cluster -- Install [NGINX Gateway Fabric](https://github.com/nginx/nginx-gateway-fabric) with [NGINX](https://nginx.org/) -- Test NGINX Gateway Fabric with an example application - -By following the steps in order, you will finish with a functional NGINX Gateway Fabric cluster. - ---- - -## Before you begin - -To complete this guide, you need the following prerequisites installed: - -- [Go 1.16](https://go.dev/dl/) or newer, which is used by kind -- [Docker](https://docs.docker.com/get-started/get-docker/), for creating and managing containers -- [kind](https://kind.sigs.k8s.io/#installation-and-usage), which allows for running a local Kubernetes cluster using Docker -- [kubectl](https://kubernetes.io/docs/tasks/tools/), which provides a command line interface (CLI) for interacting with Kubernetes clusters -- [Helm 3.0](https://helm.sh/docs/intro/install/) or newer to install NGINX Gateway Fabric -- [curl](https://curl.se/), to test the example application - -## Set up a kind cluster - -Create the file _cluster-config.yaml_ with the following contents, noting the highlighted lines: - -```yaml {linenos=true, hl_lines=[6, 9]} -apiVersion: kind.x-k8s.io/v1alpha4 -kind: Cluster -nodes: -- role: control-plane - extraPortMappings: - - containerPort: 31437 - hostPort: 8080 - protocol: TCP - - containerPort: 31438 - hostPort: 8443 - protocol: TCP -``` - -{{< warning >}} -Take note of the two _containerPort_ values. They are necessary for later configuring a _NodePort_. -{{< /warning >}} - -Run the following command: - -```shell -kind create cluster --config cluster-config.yaml -``` - -```text -Creating cluster "kind" ... - ✓ Ensuring node image (kindest/node:v1.31.0) 🖼 - ✓ Preparing nodes 📦 - ✓ Writing configuration 📜 - ✓ Starting control-plane 🕹️ - ✓ Installing CNI 🔌 - ✓ Installing StorageClass 💾 -Set kubectl context to "kind-kind" -You can now use your cluster with: - -kubectl cluster-info --context kind-kind - -Thanks for using kind! 😊 -``` - -{{< note >}} -If you have cloned [the NGINX Gateway Fabric repository](https://github.com/nginx/nginx-gateway-fabric/tree/main), you can also create a kind cluster from the root folder with the following *make* command: - -```shell -make create-kind-cluster -``` - -{{< /note >}} - ---- - -## Install NGINX Gateway Fabric - -### Add Gateway API resources - -Use `kubectl` to add the API resources for NGINX Gateway Fabric with the following command: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.0" | kubectl apply -f - -``` - -```text -customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io created -customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io created -customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io created -customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io created -customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created -``` - -{{< note >}} -To use experimental features, you'll need to install the API resources from the experimental channel instead. - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl apply -f - -``` - -{{< /note >}} - ---- - -### Install the Helm chart - -Use `helm` to install NGINX Gateway Fabric with the following command: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false -``` - -```text -Pulled: ghcr.io/nginx/charts/nginx-gateway-fabric:1.6.0 -Digest: sha256:9bbd1a2fcbfd5407ad6be39f796f582e6263512f1f3a8969b427d39063cc6fee -NAME: ngf -LAST DEPLOYED: Mon Oct 21 14:45:14 2024 -NAMESPACE: nginx-gateway -STATUS: deployed -REVISION: 1 -TEST SUITE: None -``` - -{{< note >}} -If you installed the API resources from the experimental channel during the last step, you will need to enable the _nginxGateway.gwAPIExperimentalFeatures_ option: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false --set nginxGateway.gwAPIExperimentalFeatures.enable=true -``` - -{{< /note >}} - ---- - -### Set up a NodePort - -Create the file _nodeport-config.yaml_ with the following contents: - -{{< note >}} -The highlighted _nodePort_ values should equal the _containerPort_ values from _cluster-config.yaml_ [when you created the kind cluster](#set-up-a-kind-cluster). -{{< /note >}} - -```yaml {linenos=true, hl_lines=[20, 25]} -apiVersion: v1 -kind: Service -metadata: - name: nginx-gateway - namespace: nginx-gateway - labels: - app.kubernetes.io/name: nginx-gateway-fabric - app.kubernetes.io/instance: ngf - app.kubernetes.io/version: "1.6.0" -spec: - type: NodePort - selector: - app.kubernetes.io/name: nginx-gateway-fabric - app.kubernetes.io/instance: ngf - ports: - - name: http - port: 80 - protocol: TCP - targetPort: 80 - nodePort: 31437 - - name: https - port: 443 - protocol: TCP - targetPort: 443 - nodePort: 31438 -``` - -Apply it using `kubectl`: - -```shell -kubectl apply -f nodeport-config.yaml -``` - -```text -service/nginx-gateway created -``` - -{{< warning >}} -The NodePort resource must be deployed in the same namespace as NGINX Gateway Fabric. - -If you are making customizations, ensure your `labels:` and `selectors:` also match the labels of the NGINX Gateway Fabric Deployment. -{{< /warning >}} - ---- - -## Create an example application - -In the previous section, you deployed NGINX Gateway Fabric to a local cluster. This section shows you how to deploy a simple web application to test that NGINX Gateway Fabric works. - -{{< note >}} -The YAML code in the following sections can be found in the [cafe-example folder](https://github.com/nginx/nginx-gateway-fabric/tree/main/examples/cafe-example) of the GitHub repository. -{{< /note >}} - ---- - -### Create the application resources - -Create the file _cafe.yaml_ with the following contents: - -{{< ghcode `https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/cafe.yaml`>}} - -Apply it using `kubectl`: - -```shell -kubectl apply -f cafe.yaml -``` - -```text -deployment.apps/coffee created -service/coffee created -deployment.apps/tea created -service/tea created -``` - -Verify that the new pods are in the `default` namespace: - -```shell -kubectl -n default get pods -``` - -```text -NAME READY STATUS RESTARTS AGE -coffee-6db967495b-wk2mm 1/1 Running 0 10s -tea-7b7d6c947d-d4qcf 1/1 Running 0 10s -``` - ---- - -### Create Gateway and HTTPRoute resources - -Create the file _gateway.yaml_ with the following contents: - -{{< ghcode `https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/gateway.yaml`>}} - -Apply it using `kubectl`: - -```shell -kubectl apply -f gateway.yaml -``` - -```text -gateway.gateway.networking.k8s.io/gateway created -``` - -Create the file _cafe-routes.yaml_ with the following contents: - -{{< ghcode `https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/refs/heads/main/examples/cafe-example/cafe-routes.yaml`>}} - -Apply it using `kubectl`: - -```shell -kubectl apply -f cafe-routes.yaml -``` - -```text -httproute.gateway.networking.k8s.io/coffee created -httproute.gateway.networking.k8s.io/tea created -``` - ---- - -### Verify the configuration - -You can check that all of the expected services are available using `kubectl get`: - -```shell -kubectl get service --all-namespaces -``` - -```text -NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -default coffee ClusterIP 10.96.18.163 80/TCP 2m51s -default kubernetes ClusterIP 10.96.0.1 443/TCP 4m41s -default tea ClusterIP 10.96.169.132 80/TCP 2m51s -kube-system kube-dns ClusterIP 10.96.0.10 53/UDP,53/TCP,9153/TCP 4m40s -nginx-gateway nginx-gateway NodePort 10.96.186.45 80:31437/TCP,443:31438/TCP 3m6s -``` - -You can also use `kubectl describe` on the new resources to check their status: - -```shell -kubectl describe httproutes -``` - -```text -Name: coffee -Namespace: default -Labels: -Annotations: -API Version: gateway.networking.k8s.io/v1 -Kind: HTTPRoute -Metadata: - Creation Timestamp: 2024-10-21T13:46:51Z - Generation: 1 - Resource Version: 821 - UID: cc591089-d3aa-44d3-a851-e2bbfa285029 -Spec: - Hostnames: - cafe.example.com - Parent Refs: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Section Name: http - Rules: - Backend Refs: - Group: - Kind: Service - Name: coffee - Port: 80 - Weight: 1 - Matches: - Path: - Type: PathPrefix - Value: /coffee -Status: - Parents: - Conditions: - Last Transition Time: 2024-10-21T13:46:51Z - Message: The route is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-10-21T13:46:51Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Namespace: default - Section Name: http -Events: - - -Name: tea -Namespace: default -Labels: -Annotations: -API Version: gateway.networking.k8s.io/v1 -Kind: HTTPRoute -Metadata: - Creation Timestamp: 2024-10-21T13:46:51Z - Generation: 1 - Resource Version: 823 - UID: d72d2a19-1c4d-48c4-9808-5678cff6c331 -Spec: - Hostnames: - cafe.example.com - Parent Refs: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Section Name: http - Rules: - Backend Refs: - Group: - Kind: Service - Name: tea - Port: 80 - Weight: 1 - Matches: - Path: - Type: Exact - Value: /tea -Status: - Parents: - Conditions: - Last Transition Time: 2024-10-21T13:46:51Z - Message: The route is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-10-21T13:46:51Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Namespace: default - Section Name: http -Events: -``` - -```shell -kubectl describe gateways -``` - -```text -Name: gateway -Namespace: default -Labels: -Annotations: -API Version: gateway.networking.k8s.io/v1 -Kind: Gateway -Metadata: - Creation Timestamp: 2024-10-21T13:46:36Z - Generation: 1 - Resource Version: 824 - UID: 2ae8ec42-70eb-41a4-b249-3e47177aea48 -Spec: - Gateway Class Name: nginx - Listeners: - Allowed Routes: - Namespaces: - From: Same - Hostname: *.example.com - Name: http - Port: 80 - Protocol: HTTP -Status: - Addresses: - Type: IPAddress - Value: 10.244.0.5 - Conditions: - Last Transition Time: 2024-10-21T13:46:51Z - Message: Gateway is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-10-21T13:46:51Z - Message: Gateway is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Listeners: - Attached Routes: 2 - Conditions: - Last Transition Time: 2024-10-21T13:46:51Z - Message: Listener is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-10-21T13:46:51Z - Message: Listener is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Last Transition Time: 2024-10-21T13:46:51Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Last Transition Time: 2024-10-21T13:46:51Z - Message: No conflicts - Observed Generation: 1 - Reason: NoConflicts - Status: False - Type: Conflicted - Name: http - Supported Kinds: - Group: gateway.networking.k8s.io - Kind: HTTPRoute - Group: gateway.networking.k8s.io - Kind: GRPCRoute -Events: -``` - ---- - -## Test NGINX Gateway Fabric - -By configuring the cluster with the ports `31437` and `31438`, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service. - -You can use `curl` to test the new services by targeting the hostname (_cafe.example.com_) with the _/coffee_ and _/tea_ paths: - -```shell -curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/coffee -``` - -```text -Server address: 10.244.0.6:8080 -Server name: coffee-6db967495b-wk2mm -Date: 21/Oct/2024:13:52:13 +0000 -URI: /coffee -Request ID: fb226a54fd94f927b484dd31fb30e747 -``` - -```shell -curl --resolve cafe.example.com:8080:127.0.0.1 http://cafe.example.com:8080/tea -``` - -```text -Server address: 10.244.0.7:8080 -Server name: tea-7b7d6c947d-d4qcf -Date: 21/Oct/2024:13:52:17 +0000 -URI: /tea -Request ID: 43882f2f5794a1ee05d2ea017a035ce3 -``` - ---- - -## See also - -- [Install NGINX Gateway Fabric]({{< ref "/installation/installing-ngf/" >}}), for additional ways to install NGINX Gateway Fabric -- [How-to guides]({{< ref "/how-to/" >}}), for configuring your cluster -- [Traffic management]({{< ref "/how-to/traffic-management/" >}}), for more in-depth traffic management configuration diff --git a/site/content/how-to/_index.md b/site/content/how-to/_index.md deleted file mode 100644 index 8d72a5689e..0000000000 --- a/site/content/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "How-to guides" -weight: 400 ---- diff --git a/site/content/how-to/control-plane-configuration.md b/site/content/how-to/control-plane-configuration.md deleted file mode 100644 index 6c9b06d88a..0000000000 --- a/site/content/how-to/control-plane-configuration.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Control plane configuration" -toc: true -weight: 400 -type: how-to -product: NGF -docs: DOCS-1416 ---- - -Learn how to dynamically update the NGINX Gateway Fabric control plane configuration. - -## Overview - -NGINX Gateway Fabric can dynamically update the control plane configuration without restarting. The control plane configuration is stored in the NginxGateway custom resource, created during the installation of NGINX Gateway Fabric. - -NginxGateway is deployed in the same namespace as the controller (Default: `nginx-gateway`). The resource's default name is based on your [installation method]({{< relref "/installation/installing-ngf" >}}): - -- Helm: `-config` -- Manifests: `nginx-gateway-config` - -The control plane only watches this single instance of the custom resource. - -If the resource is invalid to the OpenAPI schema, the Kubernetes API server will reject the changes. If the resource is deleted or deemed invalid by NGINX Gateway Fabric, a warning event is created in the `nginx-gateway` namespace, and the default values will be used by the control plane for its configuration. - -Additionally, the control plane updates the status of the resource (if it exists) to reflect whether it is valid or not. - -**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 `ngf-config` should be updated to the name of the resource created for your installation.{{< /note >}} - -To view the current configuration and its status: - -```shell -kubectl -n nginx-gateway describe nginxgateways ngf-config -``` - -```text -... -Status: - Conditions: - Last Transition Time: 2024-08-13T19:22:14Z - Message: NginxGateway is valid - Observed Generation: 1 - Reason: Valid - Status: True - Type: Valid -``` - -To update the configuration: - -```shell -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. diff --git a/site/content/how-to/data-plane-configuration.md b/site/content/how-to/data-plane-configuration.md deleted file mode 100644 index d12fa03fa7..0000000000 --- a/site/content/how-to/data-plane-configuration.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -title: "Data plane configuration" -toc: true -weight: 500 -type: how-to -product: NGF -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, changing the IP family, or setting the NGINX error log level. - -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. - -When 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 -``` - -```text -... -Status: - Conditions: - ... - Message: parametersRef resource is resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs -``` - -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 - <}}). - -{{< note >}}For `debug` logging to work, NGINX needs to be built with `--with-debug` or "in debug mode". NGINX Gateway Fabric can easily -be [run with NGINX in debug mode](#run-nginx-gateway-fabric-with-nginx-in-debug-mode) upon startup through the addition -of a few arguments. {{}} - -### Run NGINX Gateway Fabric with NGINX in debug mode - -To run NGINX Gateway Fabric with NGINX in debug mode, follow the [installation document]({{< relref "installation/installing-ngf" >}}) with these additional steps: - -Using Helm: Set `nginx.debug` to true. - -Using Kubernetes Manifests: Under the `nginx` container of the deployment manifest, add `-c` and `rm -rf /var/run/nginx/*.sock && nginx-debug -g 'daemon off;'` -as arguments and add `/bin/sh` as the command. The deployment manifest should look something like this: - -```text -... -- args: - - -c - - rm -rf /var/run/nginx/*.sock && nginx-debug -g 'daemon off;' - command: - - /bin/sh -... -``` - -## Configure PROXY protocol and RewriteClientIP settings - -When a request is passed through multiple proxies or load balancers, the client IP is set to the IP address of the server that last handled the request. To preserve the original client IP address, you can configure `RewriteClientIP` settings in the `NginxProxy` resource. `RewriteClientIP` has the fields: _mode_, _trustedAddresses_ and _setIPRecursively_. - -**Mode** determines how the original client IP is passed through multiple proxies and the way the load balancer is set to receive it. It can have two values: - - 1. `ProxyProtocol` is a protocol that carries connection information from the source requesting the connection to the destination for which the connection was requested. - 2. `XForwardedFor` is a multi-value HTTP header that is used by proxies to append IP addresses of the hosts that passed the request. - -The choice of mode depends on how the load balancer fronting NGINX Gateway Fabric receives information. - -**TrustedAddresses** are used to specify the IP addresses of the trusted proxies that pass the request. These can be in the form of CIDRs, IPs, or hostnames. For example, if a load balancer is forwarding the request to NGINX Gateway Fabric, the IP address of the load balancer should be specified in the `trustedAddresses` list to inform NGINX that the forwarded request is from a known source. - -**SetIPRecursively** is a boolean field used to enable recursive search when selecting the client's address from a multi-value header. It is applicable in cases where we have a multi-value header containing client IPs to select from, i.e., when using `XForwardedFor` mode. - -The following command creates an `NginxProxy` resource with `RewriteClientIP` settings that set the mode to ProxyProtocol and sets a CIDR in the list of trusted addresses to find the original client IP address. - -```yaml -kubectl apply -f - <}}). - -{{< note >}} When sending curl requests to a server expecting proxy information, use the flag `--haproxy-protocol` to avoid broken header errors. {{< /note >}} diff --git a/site/content/how-to/monitoring/_index.md b/site/content/how-to/monitoring/_index.md deleted file mode 100644 index 58123fbf0c..0000000000 --- a/site/content/how-to/monitoring/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Monitoring and troubleshooting" -weight: 300 ---- diff --git a/site/content/how-to/monitoring/dashboard.md b/site/content/how-to/monitoring/dashboard.md deleted file mode 100644 index 835363d65e..0000000000 --- a/site/content/how-to/monitoring/dashboard.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "NGINX Plus dashboard" -weight: 300 -toc: true -docs: "DOCS-1417" ---- - -Learn how to view the NGINX Plus dashboard to see real-time metrics. - -## Overview - -The NGINX Plus dashboard offers a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. The dashboard is enabled by default for NGINX Gateway Fabric deployments that use NGINX Plus as the data plane. The dashboard is available on port 8765. - -To access the dashboard: - -1. Use port-forwarding to forward connections to port 8765 on your local machine to port 8765 on the NGINX Gateway Fabric pod (replace `` with the actual name of the pod). - - ```shell - kubectl port-forward 8765:8765 -n nginx-gateway - ``` - -1. Open your browser to [http://127.0.0.1:8765/dashboard.html](http://127.0.0.1:8765/dashboard.html) to access the dashboard. - -The dashboard will look like this: - -{{}} - - -{{< note >}}The [API](https://nginx.org/en/docs/http/ngx_http_api_module.html), which the dashboard uses to get the metrics, is also accessible using the `/api` path.{{< /note >}} diff --git a/site/content/how-to/monitoring/prometheus.md b/site/content/how-to/monitoring/prometheus.md deleted file mode 100644 index 17746ba719..0000000000 --- a/site/content/how-to/monitoring/prometheus.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: "Prometheus metrics" -weight: 100 -toc: true -docs: "DOCS-1418" ---- - -This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available. - -## Overview - -NGINX Gateway Fabric metrics are displayed in [Prometheus](https://prometheus.io/) format. These metrics are served through a metrics server orchestrated by the controller-runtime package on HTTP port `9113`. When installed, Prometheus automatically scrapes this port and collects metrics. [Grafana](https://grafana.com/) can be used for rich visualization of these metrics. - -{{}} -Metrics are served over HTTP by default. Enabling HTTPS will secure the metrics endpoint with a self-signed certificate. When using HTTPS, adjust the Prometheus Pod scrape settings by adding the `insecure_skip_verify` flag to handle the self-signed certificate. For further details, refer to the [Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#tls_config). -{{}} - -## Installing Prometheus and Grafana - -{{< note >}}These installations are for demonstration purposes and have not been tuned for a production environment.{{< /note >}} - -### Prometheus - -```shell -helm repo add prometheus-community https://prometheus-community.github.io/helm-charts -helm repo update -helm install prometheus prometheus-community/prometheus -n monitoring --create-namespace --set server.global.scrape_interval=15s -``` - -Once running, you can access the Prometheus dashboard by using port-forwarding in the background: - -```shell -kubectl port-forward -n monitoring svc/prometheus-server 9090:80 & -``` - -Visit [http://127.0.0.1:9090](http://127.0.0.1:9090) to view the dashboard. - -### Grafana - - -```shell -helm repo add grafana https://grafana.github.io/helm-charts -helm repo update -helm install grafana grafana/grafana -n monitoring --create-namespace -``` - -Once running, you can access the Grafana dashboard by using port-forwarding in the background: - -```shell -kubectl port-forward -n monitoring svc/grafana 3000:80 & -``` - -Visit [http://127.0.0.1:3000](http://127.0.0.1:3000) to view the Grafana UI. - -The username for login is `admin`. The password can be acquired by running: - -```shell -kubectl get secret -n monitoring grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo -``` - -#### Configuring Grafana - -In the Grafana UI menu, go to `Connections` then `Data sources`. Add your Prometheus service (`http://prometheus-server.monitoring.svc`) as a data source. - -Download the following sample dashboard and Import as a new Dashboard in the Grafana UI. - -- {{< download "grafana-dashboard.json" "ngf-grafana-dashboard.json" >}} - -## Available metrics in NGINX Gateway Fabric - -NGINX Gateway Fabric provides a variety of metrics for monitoring and analyzing performance. These metrics are categorized as follows: - -### NGINX/NGINX Plus metrics - -NGINX metrics cover specific NGINX operations such as the total number of accepted client connections. For a complete list of available NGINX/NGINX Plus metrics, refer to the [NGINX Prometheus Exporter developer docs](https://github.com/nginx/nginx-prometheus-exporter#exported-metrics). - -These metrics use the `nginx_gateway_fabric` namespace and include the `class` label, indicating the NGINX Gateway class. For example, `nginx_gateway_fabric_connections_accepted{class="nginx"}`. - -### NGINX Gateway Fabric metrics - -Metrics specific to NGINX Gateway Fabric include: - -- `nginx_reloads_total`: Counts successful NGINX reloads. -- `nginx_reload_errors_total`: Counts NGINX reload failures. -- `nginx_stale_config`: Indicates if NGINX Gateway Fabric couldn't update NGINX with the latest configuration, resulting in a stale version. -- `nginx_reloads_milliseconds`: Time in milliseconds for NGINX reloads. -- `event_batch_processing_milliseconds`: Time in milliseconds to process batches of Kubernetes events. - -All these metrics are under the `nginx_gateway_fabric` namespace and include a `class` label set to the Gateway class of NGINX Gateway Fabric. For example, `nginx_gateway_fabric_nginx_reloads_total{class="nginx"}`. - -### Controller-runtime metrics - -Provided by the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) library, these metrics include: - -- General resource usage like CPU and memory. -- Go runtime metrics such as the number of Go routines, garbage collection duration, and Go version. -- Controller-specific metrics, including reconciliation errors per controller, length of the reconcile queue, and reconciliation latency. - -## Change the default metrics configuration - -You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Manifests. - -### Using Helm - -If you're setting up NGINX Gateway Fabric with Helm, you can adjust the `metrics.*` parameters to fit your needs. For detailed options and instructions, see the [Helm README](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.0/charts/nginx-gateway-fabric/README.md). - -### Using Kubernetes manifests - -For setups using Kubernetes manifests, change the metrics configuration by editing the NGINX Gateway Fabric manifest that you want to deploy. You can find some examples in the [deploy](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.0/deploy) directory. - -#### Disabling metrics - -If you need to disable metrics: - -1. Set the `-metrics-disable` [command-line argument]({{< relref "reference/cli-help.md">}}) to `true` in the NGINX Gateway Fabric Pod's configuration. Remove any other `-metrics-*` arguments. -2. In the Pod template for NGINX Gateway Fabric, delete the metrics port entry from the container ports list: - - ```yaml - - name: metrics - containerPort: 9113 - ``` - -3. Also, remove the following annotations from the NGINX Gateway Fabric Pod template: - - ```yaml - annotations: - prometheus.io/scrape: "true" - prometheus.io/port: "9113" - ``` - -#### Changing the default port - -To change the default port for metrics: - -1. Update the `-metrics-port` [command-line argument]({{< relref "reference/cli-help.md">}}) in the NGINX Gateway Fabric Pod's configuration to your chosen port number. -2. In the Pod template, change the metrics port entry to reflect the new port: - - ```yaml - - name: metrics - containerPort: - ``` - -3. Modify the `prometheus.io/port` annotation in the Pod template to match the new port: - - ```yaml - annotations: - <...> - prometheus.io/port: "" - <...> - ``` - -#### Enabling HTTPS for metrics - -For enhanced security with HTTPS: - -1. Enable HTTPS security by setting the `-metrics-secure-serving` [command-line argument]({{< relref "reference/cli-help.md">}}) to `true` in the NGINX Gateway Fabric Pod's configuration. - -2. Add an HTTPS scheme annotation to the Pod template: - - ```yaml - annotations: - <...> - prometheus.io/scheme: "https" - <...> - ``` diff --git a/site/content/how-to/monitoring/tracing.md b/site/content/how-to/monitoring/tracing.md deleted file mode 100644 index 3b440a33c4..0000000000 --- a/site/content/how-to/monitoring/tracing.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: "Tracing" -weight: 200 -toc: true -docs: "DOCS-000" ---- - -Learn how to configure tracing in NGINX Gateway Fabric. - -## Overview - -NGINX Gateway Fabric supports tracing using [OpenTelemetry](https://opentelemetry.io/). The official [NGINX OpenTelemetry Module](https://github.com/nginxinc/nginx-otel) instruments the NGINX data plane to export traces to a configured collector. Tracing data can be used with an OpenTelemetry Protocol (OTLP) exporter, such as the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). This collector can then export data to one or more upstream collectors like [Jaeger](https://www.jaegertracing.io/), [DataDog](https://docs.datadoghq.com/tracing/), and many others. This is called the [Agent model](https://opentelemetry.io/docs/collector/deployment/agent/). - -This guide explains how to enable tracing on HTTPRoutes using NGINX Gateway Fabric. It uses the OpenTelemetry Collector and Jaeger to process and collect the traces. - -## Install the collectors - -The first step is to install the collectors. NGINX Gateway Fabric will be configured to export to the OpenTelemetry Collector, which is configured to export to Jaeger. This model allows the visualization collector (Jaeger) to be swapped with something else, or to add more collectors without needing to reconfigure NGINX Gateway Fabric. It is also possible to configure NGINX Gateway Fabric to export directly to Jaeger. - -Create the namespace: - -```shell -kubectl create namespace tracing -``` - -Download the following files containing the configurations for the collectors: - -- {{< download "otel-collector.yaml" "otel-collector.yaml" >}} -- {{< download "jaeger.yaml" "jaeger.yaml" >}} - -{{< note >}}These collectors are for demonstration purposes and are not tuned for production use.{{< /note >}} - -Then install them: - -```shell -kubectl apply -f otel-collector.yaml -f jaeger.yaml -n tracing -``` - -Ensure the Pods are running: - -```shell -kubectl -n tracing get pods -``` - -```text -NAME READY STATUS RESTARTS AGE -jaeger-8469f69b86-bfpk9 1/1 Running 0 9s -otel-collector-f786b7dfd-h2x9l 1/1 Running 0 9s -``` - -Once running, you can access the Jaeger dashboard by using port-forwarding in the background: - -```shell -kubectl port-forward -n tracing svc/jaeger 16686:16686 & -``` - -Visit [http://127.0.0.1:16686](http://127.0.0.1:16686) to view the dashboard. - -## Enable tracing - -To enable tracing, you must configure two resources: - -- `NginxProxy`: This resource contains global settings relating to the NGINX data plane. It is created and managed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/), and is referenced in the `parametersRef` field of the GatewayClass. This resource can be created and linked when we install NGINX Gateway Fabric using its helm chart, or it can be added later. This guide installs the resource using the helm chart, but the resource can also be created for an existing deployment. - - The `NginxProxy` resource contains configuration for the collector, and applies to all Gateways and routes under the GatewayClass. It does not enable tracing, but is a prerequisite to the next piece of configuration. - -- `ObservabilityPolicy`: This resource is a [Direct Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) that targets HTTPRoutes or GRPCRoutes. It is created by the [application developer](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/) and enables tracing for a specific route or routes. It requires the `NginxProxy` resource to exist in order to complete the tracing configuration. - -For all the possible configuration options for these resources, see the [API reference]({{< relref "reference/api.md" >}}). - -### Install NGINX Gateway Fabric with global tracing configuration - -{{< note >}}Ensure that you [install the Gateway API resources]({{< relref "installation/installing-ngf/helm.md#installing-the-gateway-api-resources" >}}).{{< /note >}} - -Referencing the previously deployed collector, create the following `values.yaml` file for installing NGINX Gateway Fabric: - -```yaml -cat < values.yaml -nginx: - config: - telemetry: - exporter: - endpoint: otel-collector.tracing.svc:4317 - spanAttributes: - - key: cluster-attribute-key - value: cluster-attribute-value -EOT -``` - -The span attribute will be added to all tracing spans. - -To install: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway -f values.yaml -``` - -You should see the following configuration: - -```shell -kubectl get nginxproxies.gateway.nginx.org ngf-proxy-config -o yaml -``` - -```yaml -apiVersion: gateway.nginx.org/v1alpha1 -kind: NginxProxy -metadata: - name: ngf-proxy-config -spec: - telemetry: - exporter: - endpoint: otel-collector.tracing.svc:4317 - spanAttributes: - - key: cluster-attribute-key - value: cluster-attribute-value -``` - -```shell -kubectl get gatewayclasses.gateway.networking.k8s.io nginx -o yaml -``` - -```yaml -apiVersion: gateway.networking.k8s.io/v1 -kind: GatewayClass -metadata: - name: nginx -spec: - controllerName: gateway.nginx.org/nginx-gateway-controller - parametersRef: - group: gateway.nginx.org - kind: NginxProxy - name: ngf-proxy-config -status: - conditions: - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: GatewayClass is accepted - observedGeneration: 1 - reason: Accepted - status: "True" - type: Accepted - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: Gateway API CRD versions are supported - observedGeneration: 1 - reason: SupportedVersion - status: "True" - type: SupportedVersion - - lastTransitionTime: "2024-05-22T15:18:35Z" - message: parametersRef resource is resolved - observedGeneration: 1 - reason: ResolvedRefs - status: "True" - type: ResolvedRefs -``` - -If you already have NGINX Gateway Fabric installed, then you can create the `NginxProxy` resource and link it to the GatewayClass `parametersRef`: - -```shell -kubectl edit gatewayclasses.gateway.networking.k8s.io nginx -``` - -Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -You can now create the application, route, and tracing policy. - -### Create the application and route - -Create the basic **coffee** application: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -``` - -You should receive a response from the coffee Pod. - -```text -Server address: 10.244.0.69:8080 -Server name: coffee-6b8b6d6486-k5w5w -URI: /coffee -``` - -You shouldn't see any information from the [Jaeger dashboard](http://127.0.0.1:16686) yet: you need to create the `ObservabilityPolicy`. - -### Create the ObservabilityPolicy - -To enable tracing for the coffee HTTPRoute, create the following policy: - -```yaml -kubectl apply -f - <:`. - -{{}} - -

- -Select a trace to view the attributes. - -{{}} - -The trace includes the attribute from the global NginxProxy resource as well as the attribute from the ObservabilityPolicy. - -## Further reading - -- [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work. -- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the policies mentioned in this guide diff --git a/site/content/how-to/monitoring/troubleshooting.md b/site/content/how-to/monitoring/troubleshooting.md deleted file mode 100644 index 5c8cc89e4c..0000000000 --- a/site/content/how-to/monitoring/troubleshooting.md +++ /dev/null @@ -1,478 +0,0 @@ ---- -title: "Troubleshooting" -weight: 400 -toc: true -docs: "DOCS-1419" ---- - -This topic describes possible issues when using NGINX Gateway Fabric and general troubleshooting techniques. When possible, suggested workarounds are provided. - -### General troubleshooting - -When investigating a problem or requesting help, there are important data points that can be collected to help understand what issues may exist. - -#### Resource status - -To check the status of a resource, use `kubectl describe`. This example checks the status of the `coffee` HTTPRoute, which has an error: - -```shell -kubectl describe httproutes.gateway.networking.k8s.io coffee -n nginx-gateway -``` - -```text -... -Status: - Parents: - Conditions: - Last Transition Time: 2024-05-31T17:20:51Z - Message: The route is accepted - Observed Generation: 4 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-05-31T17:20:51Z - Message: spec.rules[0].backendRefs[0].name: Not found: "bad-backend" - Observed Generation: 4 - Reason: BackendNotFound - Status: False - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Namespace: default - Section Name: http -``` - -If a resource has errors relating to its configuration or relationship to other resources, they can likely be read in the status. The `ObservedGeneration` in the status should match the `ObservedGeneration` of the resource. Otherwise, this could mean that the resource hasn't been processed yet or that the status failed to update. - -If no `Status` is written on the resource, further debug by checking if the referenced resources exist and belong to NGINX Gateway Fabric. - -#### Events - -Events created by NGINX Gateway Fabric or other Kubernetes components could indicate system or configuration issues. To see events: - -```shell -kubectl get events -n nginx-gateway -``` - -For example, a warning event when the NginxGateway configuration CRD is deleted: - -```text -kubectl -n nginx-gateway get event -LAST SEEN TYPE REASON OBJECT MESSAGE -5s Warning ResourceDeleted nginxgateway/ngf-config NginxGateway configuration was deleted; using defaults -``` - -#### Get shell access to NGINX container - -Getting shell access to containers allows developers and operators to view the environment of a running container, see its logs or diagnose any problems. To get shell access to the NGINX container, use `kubectl exec`: - -```shell -kubectl exec -it -n nginx-gateway -c nginx -- /bin/sh -``` - -#### Logs - -Logs from the NGINX Gateway Fabric control plane and data plane can contain information that isn't available to status or events. These can include errors in processing or passing traffic. - -{{< note >}} -You can see logs for a crashed or killed container by adding the `-p` flag to the `kubectl logs` commands below. -{{< /note >}} - -1. Container Logs - - To see logs for the control plane container: - - ```shell - kubectl -n nginx-gateway logs -c nginx-gateway - ``` - - To see logs for the data plane container: - - ```shell - kubectl -n nginx-gateway logs -c nginx - ``` - -1. Error Logs - - For the _nginx-gateway_ container, you can `grep` the logs for the word `error`: - - ```shell - kubectl -n nginx-gateway logs -c nginx-gateway | grep error - ``` - - For the _nginx_ container you can `grep` for various [error](https://nginx.org/en/docs/ngx_core_module.html#error_log) logs. For example, to search for all logs logged at the `emerg` level: - - ```shell - kubectl -n nginx-gateway logs -c nginx | grep emerg - ``` - - For example, if a variable is too long, NGINX may display such an error message: - - ```text - kubectl logs -n nginx-gateway ngf-nginx-gateway-fabric-bb8598998-jwk2m -c nginx | grep emerg - 2024/06/13 20:04:17 [emerg] 27#27: too long parameter, probably missing terminating """ character in /etc/nginx/conf.d/http.conf:78 - ``` - -1. Access Logs - - NGINX access logs record all requests processed by the NGINX server. These logs provide detailed information about each request, which can be useful for troubleshooting and analyzing web traffic. - Access logs can be viewed with the above method of using `kubectl logs`, or by viewing the access log file directly. To do that, get shell access to your NGINX container using these [steps](#get-shell-access-to-nginx-container). The access logs are located in the file `/var/log/nginx/access.log` in the NGINX container. - -1. Modify Log Levels - - To modify log levels for the control plane in NGINX Gateway Fabric, edit the `NginxGateway` configuration. This can be done either before or after deploying NGINX Gateway Fabric. Refer to this [guide](https://docs.nginx.com/nginx-gateway-fabric/how-to/control-plane-configuration/) to do so. - To check error logs, modify the log level to `error` to view error logs. Similarly, change the log level to `debug` and `grep` for the word `debug` to view debug logs. - -#### Understanding the generated NGINX configuration - -Understanding the NGINX configuration is key for fixing issues because it shows how NGINX handles requests. This helps tweak settings to make sure NGINX behaves the way you want it to for your application. To see your current configuration, you can open a shell in the _nginx_ container by following these [steps](#get-shell-access-to-nginx-container) and run `nginx -T`. To understand the usage of NGINX directives in the configuration file, consult this list of [NGINX directives](https://nginx.org/en/docs/dirindex.html). - -In this section, we will see how the configuration gets updated as we configure different Services, Deployments and HTTPRoutes with NGINX Gateway Fabric. In the configuration file, you'll often find several server blocks, each assigned to specific ports and server names. NGINX selects the appropriate server for a request and evaluates the URI against the location directives within that block. -When only a Gateway resource is defined, but no Services or HTTPRoutes are configured, NGINX generates a basic configuration. This includes a default server listening on the ports specified in the Gateway listeners, handling all incoming requests. Additionally, there are blocks to manage errors with status codes 500 or 503. - -This is a default `server` block listening on port 80: - -```text -server { - listen 80 default_server; - - default_type text/html; - return 404; -} -``` - -Once a HTTPRoute with path matches and rules are defined, nginx.conf is updated accordingly to determine which location block will manage incoming requests. To demonstrate how `nginx.conf` is changed, create some resources: - -1. A Gateway with single listener with the hostname `*.example.com` on port 80. -2. A simple `coffee` application. -3. An HTTPRoute that exposes the `coffee` application outside the cluster using the listener created in step 1. The path and rule matches create different location blocks in `nginx.conf` to route requests as needed. - -For example, this `coffee` route matches requests with path `/coffee` and type `prefix`. Examine how the `nginx.conf` is modified: - -```yaml -apiVersion: gateway.networking.k8s.io/v1 -kind: HTTPRoute -metadata: - name: coffee -spec: - parentRefs: - - name: gateway - sectionName: http - hostnames: - - "cafe.example.com" - rules: - - matches: - - path: - type: PathPrefix - value: /coffee - backendRefs: - - name: coffee - port: 80 -``` - -The modified `nginx.conf`: - -```shell -server { - listen 80 default_server; - - default_type text/html; - return 404; -} - -server { - listen 80; - - server_name cafe.example.com; - - - location /coffee/ { - proxy_set_header Host "$gw_api_compliant_host"; - proxy_set_header X-Forwarded-For "$proxy_add_x_forwarded_for"; - proxy_set_header Upgrade "$http_upgrade"; - proxy_set_header Connection "$connection_upgrade"; - proxy_http_version 1.1; - proxy_pass http://default_coffee_80$request_uri; - } - - location = /coffee { - proxy_set_header Host "$gw_api_compliant_host"; - proxy_set_header X-Forwarded-For "$proxy_add_x_forwarded_for"; - proxy_set_header Upgrade "$http_upgrade"; - proxy_set_header Connection "$connection_upgrade"; - proxy_http_version 1.1; - proxy_pass http://default_coffee_80$request_uri; - } - - location / { - return 404 ""; - } - -} -upstream default_coffee_80 { - random two least_conn; - zone default_coffee_80 512k; - - server 10.244.0.13:8080; -} -``` - -Key information to note is: - -1. A new `server` block is created with the hostname of the HTTPRoute. When a request is sent to this hostname, it will be handled by this `server` block. -2. Within the `server` block, three new `location` blocks are added for _coffee_, each with distinct prefix and exact paths. Requests directed to the _coffee_ application with a path prefix `/coffee/hello` will be managed by the first location block, while those with an exact path `/coffee` will be handled by the second location block. Any other requests not recognized by the server block for this hostname will default to the third location block, returning a 404 Not Found status. -3. Each `location` block has headers and directives that configure the NGINX proxy to forward requests to the `/coffee` path correctly, preserving important client information and ensuring compatibility with the upstream server. -4. The `upstream` block in the given NGINX configuration defines a group of backend servers and configures how NGINX should load balance requests among them. - -Review the behaviour when a curl request is sent to the `coffee` application: - -Matches location /coffee/ block - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee/hello -Handling connection for 8080 -Server address: 10.244.0.13:8080 -Server name: coffee-56b44d4c55-hwpkp -Date: 13/Jun/2024:22:51:52 +0000 -URI: /coffee/hello -Request ID: 21fc2baad77337065e7cf2cd57e04383 -``` - -Matches location = /coffee block - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -Handling connection for 8080 -Server address: 10.244.0.13:8080 -Server name: coffee-56b44d4c55-hwpkp -Date: 13/Jun/2024:22:51:40 +0000 -URI: /coffee -Request ID: 4d8d719e95063303e290ad74ecd7339f -``` - -Matches location / block - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/ -Handling connection for 8080 - -404 Not Found - -

404 Not Found

-
nginx/1.25.4
- -``` - -{{< warning >}} -The configuration may change in future releases. This configuration is valid for version 1.3. -{{< /warning >}} - -#### Metrics for troubleshooting - -Metrics can be useful to identify performance bottlenecks and pinpoint areas of high resource consumption within NGINX Gateway Fabric. To set up metrics collection, refer to the [Prometheus Metrics guide]({{< relref "prometheus.md" >}}). The metrics dashboard will help you understand problems with the way NGINX Gateway Fabric is set up or potential issues that could show up with time. - -For example, metrics `nginx_reloads_total` and `nginx_reload_errors_total` offer valuable insights into the system's stability and reliability. A high `nginx_reloads_total` value indicates frequent updates or configuration changes, while a high `nginx_reload_errors_total` value suggests issues with the configuration or other problems preventing successful reloads. Monitoring these metrics helps identify and resolve configuration errors, ensuring consistent service reliability. - -In such situations, it's advisable to review the logs of both NGINX and NGINX Gateway containers for any potential error messages. Additionally, verify the configured resources to ensure they are in a valid state. - -#### Access the NGINX Plus Dashboard - -If you have NGINX Gateway Fabric installed with NGINX Plus, you can access the NGINX Plus dashboard at `http://localhost:8080/dashboard.html`. -Verify that the port number (for example, `8080`) matches the port number you have port-forwarded to your NGINX Gateway Fabric Pod. For further details, see the [dashboard guide]({{< relref "dashboard.md" >}}) - -### Common errors - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Problem Area | Symptom | Troubleshooting Method | Common Cause | -|------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| Startup | NGINX Gateway Fabric fails to start. | Check logs for _nginx_ and _nginx-gateway_ containers. | Readiness probe failed. | -| Resources not configured | Status missing on resources. | Check referenced resources. | Referenced resources do not belong to NGINX Gateway Fabric. | -| NGINX errors | Reload failures on NGINX | Fix permissions for control plane. | Security context not configured. | -| NGINX Plus errors | Failure to start; traffic interruptions | Set up the [NGINX Plus JWT]({{< relref "installation/nginx-plus-jwt.md" >}}) | License is not configured or has expired. | -| Client Settings | Request entity too large error | Adjust client settings. Refer to [Client Settings Policy]({{< relref "../traffic-management/client-settings.md" >}}) | Payload is greater than the [`client_max_body_size`](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) value.| - -{{< /bootstrap-table >}} - -##### NGINX fails to reload - -NGINX reload errors can occur for various reasons, including syntax errors in configuration files, permission issues, and more. To determine if NGINX has failed to reload, check logs for your _nginx-gateway_ and _nginx_ containers. -You will see the following error in the _nginx-gateway_ logs: `failed to reload NGINX:`, followed by the reason for the failure. Similarly, error logs in _nginx_ container start with `emerg`. For example, `2024/06/12 14:25:11 [emerg] 12345#0: open() "/var/run/nginx.pid" failed (13: Permission denied)` shows a critical error, such as a permission problem preventing NGINX from accessing necessary files. - -To debug why your reload has failed, start with verifying the syntax of your configuration files by opening a shell in the NGINX container following these [steps](#get-shell-access-to-nginx-container) and running `nginx -T`. If there are errors in your configuration file, the reload will fail and specify the reason for it. - -##### NGINX Gateway Fabric Pod is not running or ready - -To understand why the NGINX Gateway Fabric Pod has not started running or is not ready, check the state of the Pod to get detailed information about the current status and events happening in the Pod. To do this, use `kubectl describe`: - -```shell -kubectl describe pod -n nginx-gateway -``` - -The Pod description includes details about the image name, tags, current status, and environment variables. Verify that these details match your setup and cross-check with the events to ensure everything is functioning as expected. For example, the Pod below has two containers that are running and the events reflect the same. - -```text -Containers: - nginx-gateway: - Container ID: containerd://06c97a9de938b35049b7c63e251418395aef65dd1ff996119362212708b79cab - Image: nginx-gateway-fabric - Image ID: docker.io/library/import-2024-06-13@sha256:1460d63bd8a352a6e455884d7ebf51ce9c92c512cb43b13e44a1c3e3e6a08918 - Ports: 9113/TCP, 8081/TCP - Host Ports: 0/TCP, 0/TCP - State: Running - Started: Thu, 13 Jun 2024 11:47:46 -0600 - Ready: True - Restart Count: 0 - Readiness: http-get http://:health/readyz delay=3s timeout=1s period=1s #success=1 #failure=3 - Environment: - POD_IP: (v1:status.podIP) - POD_NAMESPACE: nginx-gateway (v1:metadata.namespace) - POD_NAME: ngf-nginx-gateway-fabric-66dd665756-zh7d7 (v1:metadata.name) - nginx: - Container ID: containerd://c2f3684fd8922e4fac7d5707ab4eb5f49b1f76a48893852c9a812cd6dbaa2f55 - Image: nginx-gateway-fabric/nginx - Image ID: docker.io/library/import-2024-06-13@sha256:c9a02cb5665c6218373f8f65fc2c730f018d0ca652ae827cc913a7c6e9db6f45 - Ports: 80/TCP, 443/TCP - Host Ports: 0/TCP, 0/TCP - State: Running - Started: Thu, 13 Jun 2024 11:47:46 -0600 - Ready: True - Restart Count: 0 - Environment: -Events: - Type Reason Age From Message - ---- ------ ---- ---- ------- - Normal Scheduled 40s default-scheduler Successfully assigned nginx-gateway/ngf-nginx-gateway-fabric-66dd665756-zh7d7 to kind-control-plane - Normal Pulled 40s kubelet Container image "nginx-gateway-fabric" already present on machine - Normal Created 40s kubelet Created container nginx-gateway - Normal Started 39s kubelet Started container nginx-gateway - Normal Pulled 39s kubelet Container image "nginx-gateway-fabric/nginx" already present on machine - Normal Created 39s kubelet Created container nginx - Normal Started 39s kubelet Started container nginx -``` - -##### Insufficient Privileges errors - -Depending on your environment's configuration, the control plane may not have the proper permissions to reload NGINX. The NGINX configuration will not be applied and you will see the following error in the _nginx-gateway_ logs: - -`failed to reload NGINX: failed to send the HUP signal to NGINX main: operation not permitted` - -To **resolve** this issue you will need to set `allowPrivilegeEscalation` to `true`. - -- If using Helm, you can set the `nginxGateway.securityContext.allowPrivilegeEscalation` value. -- If using the manifests directly, you can update this field under the `nginx-gateway` container's `securityContext`. - -##### NGINX Plus failure to start or traffic interruptions - -Beginning with NGINX Gateway Fabric 1.5.0, NGINX Plus requires a valid JSON Web Token (JWT) to run. If this is not set up properly, or your JWT token has expired, you may see errors in the NGINX logs that look like the following: - -```text -nginx: [error] invalid license token -``` - -```text -nginx: [emerg] License file is required. Download JWT license from MyF5 and configure its location... -``` - -```text -nginx: [emerg] license expired -``` - -These errors could prevent NGINX Plus from starting or prevent traffic from flowing. To fix these issues, see the [NGINX Plus JWT]({{< relref "installation/nginx-plus-jwt.md" >}}) guide. - -##### 413 Request Entity Too Large - -If you receive the following error: - -```text - -413 Request Entity Too Large - -

413 Request Entity Too Large

-
nginx/1.25.5
- - -``` - -Or view the following error message in the NGINX logs: - -```text -2024/05/30 21:48:22 [error] 138#138: *43 client intended to send too large body: 112 bytes, client: 127.0.0.1, server: cafe.example.com, request: "POST /coffee HTTP/1.1", host: "cafe.example.com:8080" -``` - -The request body exceeds the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size). -To **resolve** this, you can configure the `client_max_body_size` using the `ClientSettingsPolicy` API. Read the [Client Settings Policy]({{< relref "how-to/traffic-management/client-settings.md" >}}) documentation for more information. - -##### IP Family Mismatch Errors - -If you `describe` your HTTPRoute and see the following error: - -```text - Conditions: - Last Transition Time: 2024-07-14T23:36:37Z - Message: The route is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-07-14T23:36:37Z - Message: Service configured with IPv4 family but NginxProxy is configured with IPv6 - Observed Generation: 1 - Reason: InvalidServiceIPFamily - Status: False - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller -``` - -The Service associated with your HTTPRoute is configured with a IP Family different than the one specified in the NginxProxy configuration. -To **resolve** this, you can do one of the following: - -- Update the NginxProxy configuration with the proper [`ipFamily`]({{< relref "reference/api.md" >}}) field. You can edit the NginxProxy configuration using `kubectl edit`. For example: - - ```shell - kubectl edit -n nginx-gateway nginxproxies.gateway.nginx.org ngf-proxy-config - ``` - -- When installing NGINX Gateway Fabric, change the IPFamily by modifying the field `nginx.config.ipFamily` in the `values.yaml` or add the `--set nginx.config.ipFamily=` flag to the `helm install` command. The supported IPFamilies are `ipv4`, `ipv6` and `dual` (default). - -- Adjust the IPFamily of your Service to match that of the NginxProxy configuration. - -##### Policy cannot be applied to target - -If you `describe` your Policy and see the following error: - -```text - Conditions: - Last Transition Time: 2024-08-20T14:48:53Z - Message: Policy cannot be applied to target "default/route1" since another Route "default/route2" shares a hostname:port/path combination with this target - Observed Generation: 3 - Reason: TargetConflict - Status: False - Type: Accepted -``` - -This means you are attempting to attach a Policy to a Route that has an overlapping hostname:port/path combination with another Route. To work around this, you can do one of the following: - -- Combine the Route rules for the overlapping path into a single Route. -- If the Policy allows it, specify both Routes in the `targetRefs` list. - -##### Broken Header error - -If you check your _nginx_ container logs and see the following error: - -```text - 2024/07/25 00:50:45 [error] 211#211: *22 broken header: "GET /coffee HTTP/1.1" while reading PROXY protocol, client: 127.0.0.1, server: 0.0.0.0:80 -``` - -It indicates that `proxy_protocol` is enabled for the gateway listeners, but the request sent to the application endpoint does not contain proxy information. To **resolve** this, you can do one of the following: - -- Unassign the field [`rewriteClientIP.mode`]({{< relref "reference/api.md" >}}) in the NginxProxy configuration. - -- Send valid proxy information with requests being handled by your application. - -### Further reading - -You can view the [Kubernetes Troubleshooting Guide](https://kubernetes.io/docs/tasks/debug/debug-application/) for more debugging guidance. diff --git a/site/content/how-to/traffic-management/_index.md b/site/content/how-to/traffic-management/_index.md deleted file mode 100644 index eb4895183f..0000000000 --- a/site/content/how-to/traffic-management/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Traffic management" -weight: 100 ---- diff --git a/site/content/how-to/traffic-management/advanced-routing.md b/site/content/how-to/traffic-management/advanced-routing.md deleted file mode 100644 index cdac87aa6b..0000000000 --- a/site/content/how-to/traffic-management/advanced-routing.md +++ /dev/null @@ -1,367 +0,0 @@ ---- -title: "Application routes using HTTP matching conditions" -toc: true -weight: 200 -type: how-to -product: NGF -docs: DOCS-1422 ---- - -Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters - ---- - -## 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]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. - -The following image shows the traffic flow that we will be creating with these rules. - -{{}} - -The goal is to create a set of rules that will result in client requests being sent to specific backends based on the request attributes. In this diagram, we have two versions of the `coffee` service. Traffic for v1 needs to be directed to the old application, while traffic for v2 needs to be directed towards the new application. We also have two `tea` services, one that handles GET operations and one that handles POST operations. Both the `tea` and `coffee` applications share the same Gateway. - - ---- - -## Before you begin - -- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. {{< /note >}} - ---- - -## Coffee applications - -### Deploy the Coffee applications - -Begin by deploying the `coffee-v1` and `coffee-v2` applications: - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/advanced-routing/coffee.yaml -``` - ---- - -### Deploy the Gateway API Resources for the Coffee applications - -The [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the gateway: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -``` - -This request should receive a response from the `coffee-v1` Pod. - -```text -Server address: 10.244.0.9:8080 -Server name: coffee-v1-76c7c85bbd-cf8nz -``` - -If we want our request to be routed to `coffee-v2`, then we need to meet the defined conditions. We can include a header: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -H "version:v2" -``` - -or include a query parameter: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee?TEST=v2 -``` - -Either request should result in a response from the `coffee-v2` Pod. - -```text -Server address: 10.244.0.9:8080 -Server name: coffee-v2-68bd55f798-s9z5q -``` - ---- - -## Tea applications - -Let's deploy a different set of applications now called `tea` and `tea-post`. These applications will have their own set of rules, but will still attach to the same gateway listener as the `coffee` apps. - ---- - -### Deploy the Tea applications - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/advanced-routing/tea.yaml -``` - ---- - -### Deploy the HTTPRoute for the Tea services - -We are reusing the previous gateway for these applications, so all we need to create is the HTTPRoute. - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea -``` - -This GET request should receive a response from the `tea` Pod. - -```text -Server address: 10.244.0.10:8080 -Server name: tea-df5655878-5fmfg -``` - -If we want our request to be routed to `tea-post`, then we need to send a POST request: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea -X POST -``` - -```text -Server address: 10.244.0.7:8080 -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. - ---- - -## Troubleshooting - -If you have any issues while sending traffic, try the following to debug your configuration and setup: - -- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX Gateway Fabric service. Refer to the [Installation]({{< relref "/installation/" >}}) guides for more information. - -- Check the status of the Gateway: - - ```shell - kubectl describe gateway cafe - ``` - - The Gateway status should look like this: - - ```text - Status: - Addresses: - Type: IPAddress - Value: 10.244.0.85 - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: Gateway is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: Gateway is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Listeners: - Attached Routes: 2 - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: Listener is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: Listener is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Last Transition Time: 2023-08-15T20:57:21Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Last Transition Time: 2023-08-15T20:57:21Z - Message: No conflicts - Observed Generation: 1 - Reason: NoConflicts - Status: False - Type: Conflicted - Name: http - ``` - - Check that the conditions match and that the attached routes for the `http` listener equals 2. If it is less than 2, there may be an issue with the routes. - -- Check the status of the HTTPRoutes: - - ```shell - kubectl describe httproute coffee - ``` - - ```shell - kubectl describe httproute tea - ``` - - Each HTTPRoute status should look like this: - - ```text - Status: - Parents: - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: The route is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: cafe - Namespace: default - ``` - - Check for any error messages in the conditions. - ---- - -## See also - -To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources: - -- [Gateway API Overview](https://gateway-api.sigs.k8s.io/concepts/api-overview/) -- [Deploying a simple Gateway](https://gateway-api.sigs.k8s.io/guides/simple-gateway/) -- [HTTP Routing](https://gateway-api.sigs.k8s.io/guides/http-routing/) diff --git a/site/content/how-to/traffic-management/client-settings.md b/site/content/how-to/traffic-management/client-settings.md deleted file mode 100644 index ea644a827e..0000000000 --- a/site/content/how-to/traffic-management/client-settings.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: "Client Settings Policy API" -weight: 800 -toc: true -docs: "DOCS-000" ---- - -Learn how to use the `ClientSettingsPolicy` API. - -## Overview - -The `ClientSettingsPolicy` API allows Cluster Operators and Application Developers to configure the connection behavior between the client and NGINX. - -The settings in `ClientSettingsPolicy` correspond to the following NGINX directives: - -- [`client_max_body_size`]() -- [`client_body_timeout`]() -- [`keepalive_requests`]() -- [`keepalive_time`]() -- [`keepalive_timeout`]() - -`ClientSettingsPolicy` is an [Inherited Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) that can be applied to a Gateway, HTTPRoute, or GRPCRoute in the same namespace as the `ClientSettingsPolicy`. - -When applied to a Gateway, the settings specified in the `ClientSettingsPolicy` affect all HTTPRoutes and GRPCRoutes attached to the Gateway. This allows Cluster Operators to set defaults for all applications using the Gateway. - -When applied to an HTTPRoute or GRPCRoute, the settings in the `ClientSettingsPolicy` affect only the route they are applied to. This allows Application Developers to set values for their applications based on their application's behavior or requirements. -Settings applied to an HTTPRoute or GRPCRoute take precedence over settings applied to a Gateway. See the [custom policies]({{< relref "overview/custom-policies.md" >}}) document for more information on policies. - -This guide will show you how to use the `ClientSettingsPolicy` API to configure the client max body size for your applications. - -For all the possible configuration options for `ClientSettingsPolicy`, see the [API reference]({{< relref "reference/api.md" >}}). - -## Setup - -- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - - {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} - -- Create the coffee and tea example applications: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/client-settings-policy/app.yaml - ``` - -- Create a Gateway: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/client-settings-policy/gateway.yaml - ``` - -- Create HTTPRoutes for the coffee and tea applications: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/client-settings-policy/httproutes.yaml - ``` - -- Test the configuration: - - You can send traffic to the coffee and tea applications using the external IP address and port for NGINX Gateway Fabric. - - Send a request to coffee: - - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee - ``` - - This request should receive a response from the coffee Pod: - - ```text - Server address: 10.244.0.9:8080 - Server name: coffee-76c7c85bbd-cf8nz - ``` - - Send a request to tea: - - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - ``` - - This request should receive a response from the tea Pod: - - ```text - Server address: 10.244.0.9:8080 - Server name: tea-76c7c85bbd-cf8nz - ``` - -## Configure client max body size - -### Set a default client max body size for the Gateway - -To set a default client max body size for the Gateway created during setup, add the following `ClientSettingsPolicy`: - -```yaml -kubectl apply -f - < -``` - -Next, test that the policy is configured by sending a POST request to the coffee and tea applications exceeding the client's max body size of 50 bytes. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -X POST --data "this payload is greater than fifty bytes by four bytes" -``` - -You should receive the following error: - -```text - -413 Request Entity Too Large - -

413 Request Entity Too Large

-
nginx/1.25.5
- - -``` - -Try again with a payload that's less than the 50 byte limit: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -X POST --data "this payload is under fifty bytes" -``` - -This time, you should receive a response from coffee: - -```text -Server address: 10.244.0.6:8080 -Server name: coffee-56b44d4c55-7ldjc -``` - -You can repeat this test with the tea application to confirm that the policy affects both HTTPRoutes. - -### Set a different client max body size for a route - -To set a different client max body size for a particular route, you can create another `ClientSettingsPolicy` that targets the route: - -```yaml -kubectl apply -f - < -``` - -Notice that the Ancestor Ref in the status is the tea HTTPRoute instead of the Gateway. - -Next, test that the policy is configured by sending a POST request to the tea application with a request body size greater than 50 bytes. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea -X POST --data "this payload is greater than fifty bytes but less than seventy five" -``` - -You should receive a response from tea: - -```text -Server address: 10.244.0.7:8080 -Server name: tea-596697966f-bf6tw -``` - -However, since the coffee app is still affected by the `ClientSettingsPolicy` attached to the Gateway, the same request to coffee should fail: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -X POST --data "this payload is greater than fifty bytes but less than seventy five" -``` - -```text - -413 Request Entity Too Large - -

413 Request Entity Too Large

-
nginx/1.25.5
- - -``` - -To configure a `ClientSettingsPolicy` for a GRPCRoute, you can specify the GRPCRoute in the `spec.targetRef`: - -```yaml -kubectl apply -f - <}}): learn about how NGINX Gateway Fabric custom policies work. -- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the `ClientSettingsPolicy` API. diff --git a/site/content/how-to/traffic-management/https-termination.md b/site/content/how-to/traffic-management/https-termination.md deleted file mode 100644 index ad8ae6ba79..0000000000 --- a/site/content/how-to/traffic-management/https-termination.md +++ /dev/null @@ -1,262 +0,0 @@ ---- -title: "HTTPS termination" -toc: true -weight: 500 -type: how-to -product: NGF -docs: DOCS-1421 ---- - -Learn how to terminate HTTPS traffic using NGINX Gateway Fabric. - ---- - -## Overview - -In this guide, we will show how to configure HTTPS termination for your application, using an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) redirect filter, secret, and [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/). - ---- - -## Before you begin - -- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - - Save the ports of NGINX Gateway Fabric: - - ```text - GW_HTTP_PORT= - GW_HTTPS_PORT= - ``` - -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} - ---- - -## Set up - -Create the **coffee** application in Kubernetes by copying and pasting the following block into your terminal: - -```yaml -kubectl apply -f - < 80/TCP 40s -``` - ---- - -## Configure HTTPS termination and routing - -For the HTTPS, we need a certificate and key that are stored in a secret. This secret will live in a separate namespace, so we will need a ReferenceGrant in order to access it. - -To create the **certificate** namespace and secret, copy and paste the following into your terminal: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -To test that NGINX sends an HTTPS redirect, we will send requests to the `coffee` service on the HTTP port. We -will use curl's `--include` option to print the response headers (we are interested in the `Location` header). - -```shell -curl --resolve cafe.example.com:$GW_HTTP_PORT:$GW_IP http://cafe.example.com:$GW_HTTP_PORT/coffee --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -... -Location: https://cafe.example.com/coffee -... -``` - -Now we will access the application over HTTPS. Since our certificate is self-signed, we will use curl's `--insecure` -option to turn off certificate verification. - -```shell -curl --resolve cafe.example.com:$GW_HTTPS_PORT:$GW_IP https://cafe.example.com:$GW_HTTPS_PORT/coffee --insecure -``` - -```text -Server address: 10.244.0.6:80 -Server name: coffee-6b8b6d6486-7fc78 -``` - ---- - -## See also - -To learn more about redirects using the Gateway API, see the following resource: - -- [Gateway API Redirects](https://gateway-api.sigs.k8s.io/guides/http-redirect-rewrite/) diff --git a/site/content/how-to/traffic-management/redirects-and-rewrites.md b/site/content/how-to/traffic-management/redirects-and-rewrites.md deleted file mode 100644 index f8eb293130..0000000000 --- a/site/content/how-to/traffic-management/redirects-and-rewrites.md +++ /dev/null @@ -1,516 +0,0 @@ ---- -title: "HTTP redirects and rewrites" -weight: 400 -toc: true -docs: "DOCS-1424" ---- - -Learn how to redirect or rewrite your HTTP traffic using NGINX Gateway Fabric. - -## Overview - -[HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) filters can be used to configure HTTP redirects or rewrites. Redirects return HTTP 3XX responses to a client, instructing it to retrieve a different resource. Rewrites modify components of a client request (such as hostname and/or path) before proxying it upstream. - -In this guide, we will set up the coffee application to demonstrate path URL rewriting, and the tea and soda applications to showcase path-based request redirection. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. - -To see an example of a redirect using scheme and port, see the [HTTPS Termination]({{< relref "/how-to/traffic-management/https-termination.md" >}}) guide. - ---- - -## Before you begin - -- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} - ---- - -## HTTP rewrites and redirects examples - -We will configure a common gateway for the `URLRewrite` and `RequestRedirect` filter examples mentioned below. - ---- - -### Deploy the Gateway resource for the applications - -The [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [Cluster Operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: - -```yaml -kubectl apply -f - < 80/TCP 40s -``` - ---- - -### Configure a path rewrite - -The following HTTPRoute defines two filters that will rewrite requests such as the following: - -- `http://cafe.example.com/coffee` to `http://cafe.example.com/beans` -- `http://cafe.example.com/coffee/flavors` to `http://cafe.example.com/beans` -- `http://cafe.example.com/latte/prices` to `http://cafe.example.com/prices` - -To create the httproute resource, copy and paste the following into your terminal: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -This example demonstrates a rewrite from `http://cafe.example.com/coffee/flavors` to `http://cafe.example.com/beans`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee/flavors -``` - -Notice in the output that the URI has been rewritten: - -```text -Server address: 10.244.0.6:8080 -Server name: coffee-6b8b6d6486-7fc78 -... -URI: /beans -``` - -Other examples: - -This example demonstrates a rewrite from `http://cafe.example.com/coffee` to `http://cafe.example.com/beans`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -``` - -```text -Server address: 10.244.0.6:8080 -Server name: coffee-6b8b6d6486-7fc78 -... -URI: /beans -``` - -This example demonstrates a rewrite from `http://cafe.example.com/coffee/mocha` to `http://cafe.example.com/beans` and specifies query parameters `test=v1&test=v2`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee/mocha\?test\=v1\&test\=v2 -``` - -```text -Server address: 10.244.0.235:8080 -Server name: coffee-6db967495b-twn6x -... -URI: /beans?test=v1&test=v2 -``` - -This example demonstrates a rewrite from `http://cafe.example.com/latte/prices` to `http://cafe.example.com/prices`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/latte/prices -``` - -```text -Server address: 10.244.0.6:8080 -Server name: coffee-6b8b6d6486-7fc78 -... -URI: /prices -``` - -This example demonstrates a rewrite from `http://cafe.example.com/coffee/latte/prices` to `http://cafe.example.com/prices` and specifies query parameters `test=v1&test=v2`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/latte/prices\?test\=v1\&test\=v2 -``` - -```text -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/latte/prices\?test\=v1\&test\=v2 -Server address: 10.244.0.235:8080 -Server name: coffee-6db967495b-twn6x -... -URI: /prices?test=v1&test=v2 -``` - ---- - -## RequestRedirect example - -This example demonstrates how to redirect the traffic to a new location for the tea and soda applications, using `RequestRedirect` filters. - ---- - -### Setup - -Create the **tea** and **soda** application in Kubernetes by copying and pasting the following block into your terminal: - -```yaml -kubectl apply -f - < 80/TCP 89m -service/tea ClusterIP 10.96.151.194 80/TCP 120m -``` - ---- - -### Configure a path redirect - -In this section, we'll define two HTTPRoutes for the tea and soda applications to demonstrate different types of request redirection using the `RequestRedirect` filter. - -1. The `tea-redirect` route uses the `ReplacePrefixMatch` type for path modification. This configuration matches the prefix of the original path and updates it to a new path, preserving the rest of the original URL structure. It will redirect request as follows: - - - `http://cafe.example.com/tea` to `http://cafe.example.com/organic` - - `http://cafe.example.com/tea/origin` to `http://cafe.example.com/organic/origin` - -2. The `soda-redirect` route uses the `ReplaceFullPath` type for path modification. This configuration updates the entire original path to the new location, effectively overwriting it. It will redirect request as follows: - - - `http://cafe.example.com/soda` to `http://cafe.example.com/flavors` - - `http://cafe.example.com/soda/pepsi` to `http://cafe.example.com/flavors` - -To create the httproute resource, copy and paste the following into your terminal: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `cafe.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -This example demonstrates a redirect from `http://cafe.example.com/tea` to `http://cafe.example.com/organic`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea --include -``` - -Notice in the output that the URI has been redirected to the new location: - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/organic -``` - -Other examples: - -This example demonstrates a redirect from `http://cafe.example.com/tea/type` to `http://cafe.example.com/organic/type`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea/type --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/organic/type -``` - -This example demonstrates a redirect from `http://cafe.example.com/tea/type` to `http://cafe.example.com/organic/type` and specifies query params `test=v1`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea/type\?test\=v1 --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/organic/type?test=v1 -``` - -This example demonstrates a redirect from `http://cafe.example.com/soda` to `http://cafe.example.com/flavors`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/soda --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/flavors -``` - -This example demonstrates a redirect from `http://cafe.example.com/soda/pepsi` to `http://cafe.example.com/flavors/pepsi`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/soda/pepsi --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/flavors -``` - -This example demonstrates a redirect from `http://cafe.example.com/soda/pepsi` to `http://cafe.example.com/flavors/pepsi` and specifies query params `test=v1`. - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/soda/pepsi\?test\=v1 --include -``` - -```text -HTTP/1.1 302 Moved Temporarily -.. -Location: http://cafe.example.com:8080/flavors?test=v1 -``` - ---- - -## Further reading - -To learn more about redirects and rewrites using the Gateway API, see the following resource: - -- [Gateway API Redirects and Rewrites](https://gateway-api.sigs.k8s.io/guides/http-redirect-rewrite/) diff --git a/site/content/how-to/traffic-management/request-response-headers.md b/site/content/how-to/traffic-management/request-response-headers.md deleted file mode 100644 index f782f30967..0000000000 --- a/site/content/how-to/traffic-management/request-response-headers.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -title: "Modify HTTP request and response headers" -toc: true -weight: 600 -type: how-to -product: NGF -docs: DOCS-000 ---- - -Learn how to modify the request and response headers of your application using NGINX Gateway Fabric. - -## Overview - -[HTTP Header Modifiers](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/?h=request#http-header-modifiers) can be used to add, modify or remove headers during the request-response lifecycle. The [RequestHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-request-header-modifier) is used to alter headers in a request sent by client and [ResponseHeaderModifier](https://gateway-api.sigs.k8s.io/guides/http-header-modifier/#http-response-header-modifier) is used to alter headers in a response to the client. - -This guide describes how to configure the headers application to modify the headers in the request. Another version of the headers application is then used to modify response headers when client requests are made. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first. - ---- - -## Before you begin - -- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for .{{< /note >}} - ---- - -## HTTP Header Modifiers examples - -We will configure a common gateway for the `RequestHeaderModifier` and `ResponseHeaderModifier` examples mentioned below. - ---- - -### Deploy the Gateway API resources for the Header application - -The [Gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [Cluster Operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). This Gateway defines a single listener on port 80. Since no hostname is specified, this listener matches on all hostnames. To deploy the Gateway: - -```yaml -kubectl apply -f - < 80/TCP 23s -``` - ---- - -### Configure the HTTPRoute with RequestHeaderModifier filter - -Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. Use the following command: - -```yaml -kubectl apply -f - < 80/TCP 95s -``` - -### Configure the basic HTTPRoute - -Create a HTTPRoute that exposes the header application outside the cluster using the listener created in the previous section. You can do this with the following command: - -```yaml -kubectl apply -f - <}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - ---- - -## Example application - -The application we are going to use in this guide is a simple **coffee** application comprised of one service and two pods: - -{{This image shows a single 'coffee' Service connecting to two 'coffee' Pods.}} - -Using this architecture, the **coffee** application is not accessible outside the cluster. We want to expose this application on the hostname "cafe.example.com" so that clients outside the cluster can access it. - -Install NGINX Gateway Fabric and create two Gateway API resources: a [gateway](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Gateway) and an [HTTPRoute](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.HTTPRoute). - -Using these resources we will configure a simple routing rule to match all HTTP traffic with the hostname "cafe.example.com" and route it to the **coffee** service. - ---- - -## Set up - -Create the **coffee** application in Kubernetes by copying and pasting the following block into your terminal: - -```yaml -kubectl apply -f - < 80/TCP 77s -``` - ---- - -## Application architecture with NGINX Gateway Fabric - -To route traffic to the **coffee** application, we will create a gateway and HTTPRoute. The following diagram shows the configuration we are creating in the next step: - -{{}} - -We need a gateway to create an entry point for HTTP traffic coming into the cluster. The **cafe** gateway we are going to create will open an entry point to the cluster on port 80 for HTTP traffic. - -To route HTTP traffic from the gateway to the **coffee** service, we need to create an HTTPRoute named **coffee** and attach it to the gateway. This HTTPRoute will have a single routing rule that routes all traffic to the hostname "cafe.example.com" from the gateway to the **coffee** service. - -Once NGINX Gateway Fabric processes the **cafe** gateway and **coffee** HTTPRoute, it will configure its data plane (NGINX) to route all HTTP requests sent to "cafe.example.com" to the pods that the **coffee** service targets: - -{{Traffic Flow}} - -The **coffee** service is omitted from the diagram above because the NGINX Gateway Fabric routes directly to the pods that the **coffee** service targets. - -{{< note >}}In the diagrams above, all resources that are the responsibility of the cluster operator are shown in blue. The orange resources are the responsibility of the application developers. - -See the [roles and personas](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1) Gateway API document for more information on these roles.{{< /note >}} - ---- - -## Create the Gateway API resources - -To create the **cafe** gateway, copy and paste the following into your terminal: - -```yaml -kubectl apply -f - <}}). - -We specify a [listener](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Listener) on the gateway to open an entry point on the cluster. In this case, since the coffee application accepts HTTP requests, we create an HTTP listener, named **http**, that listens on port 80. - -By default, gateways only allow routes (such as HTTPRoutes) to attach if they are in the same namespace as the gateway. If you want to change this behavior, you can set -the [**allowedRoutes**](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.AllowedRoutes) field. - -Next you will create the HTTPRoute by copying and pasting the following into your terminal: - -```yaml -kubectl apply -f - <}}Your clients should be able to resolve the domain name "cafe.example.com" to the public IP of the NGINX Gateway Fabric. In this guide we will simulate that using curl's `--resolve` option. {{< /note >}} - - -First, let's send a request to the path "/": - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/ -``` - -We should get a response from one of the **coffee** pods: - -```text -Server address: 10.12.0.18:8080 -Server name: coffee-7dd75bc79b-cqvb7 -``` - -Since the **cafe** HTTPRoute routes all traffic on any path to the **coffee** application, the following requests should also be handled by the **coffee** pods: - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/some-path -``` - -```text -Server address: 10.12.0.18:8080 -Server name: coffee-7dd75bc79b-cqvb7 -``` - -```shell -curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/some/path -``` - -```text -Server address: 10.12.0.19:8080 -Server name: coffee-7dd75bc79b-dett3 -``` - -Requests to hostnames other than "cafe.example.com" should _not_ be routed to the coffee application, since the **cafe** HTTPRoute only matches requests with the "cafe.example.com"need hostname. To verify this, send a request to the hostname "pub.example.com": - -```shell -curl --resolve pub.example.com:$GW_PORT:$GW_IP http://pub.example.com:$GW_PORT/ -``` - -You should receive a 404 Not Found error: - -```text - -404 Not Found - -

404 Not Found

-
nginx/1.25.2
- - -``` - ---- - -## Troubleshooting - -If you have any issues while testing the configuration, try the following to debug your configuration and setup: - -- Make sure you set the shell variables $GW_IP and $GW_PORT to the public IP and port of the NGINX Gateway Fabric Service. Refer to the [Installation]({{< relref "/installation/" >}}) guides for more information. - -- Check the status of the gateway: - - ```shell - kubectl describe gateway cafe - ``` - - The gateway status should look similar to this: - - ```text - Status: - Addresses: - Type: IPAddress - Value: 10.244.0.85 - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: Gateway is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: Gateway is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Listeners: - Attached Routes: 1 - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: Listener is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: Listener is programmed - Observed Generation: 1 - Reason: Programmed - Status: True - Type: Programmed - Last Transition Time: 2023-08-15T20:57:21Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Last Transition Time: 2023-08-15T20:57:21Z - Message: No conflicts - Observed Generation: 1 - Reason: NoConflicts - Status: False - Type: Conflicted - Name: http - ``` - - Check that the conditions match and that the attached routes for the **http** listener equals 1. If it is 0, there may be an issue with the HTTPRoute. - -- Check the status of the HTTPRoute: - - ```shell - kubectl describe httproute coffee - ``` - - The HTTPRoute status should look similar to this: - - ```text - Status: - Parents: - Conditions: - Last Transition Time: 2023-08-15T20:57:21Z - Message: The route is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2023-08-15T20:57:21Z - Message: All references are resolved - Observed Generation: 1 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: cafe - Namespace: default - ``` - - Check for any error messages in the conditions. - -- Check the generated nginx config: - - ```shell - kubectl exec -it -n nginx-gateway -c nginx -- nginx -T - ``` - - The config should contain a server block with the server name "cafe.example.com" that listens on port 80. This server block should have a single location `/` that proxy passes to the coffee upstream: - - ```nginx configuration - server { - listen 80; - - server_name cafe.example.com; - - location / { - ... - proxy_pass http://default_coffee_80$request_uri; # the upstream is named default_coffee_80 - ... - } - } - ``` - - There should also be an upstream block with a name that matches the upstream in the **proxy_pass** directive. This upstream block should contain the pod IPs of the **coffee** pods: - - ```nginx configuration - upstream default_coffee_80 { - ... - server 10.12.0.18:8080; # these should be the pod IPs of the coffee pods - server 10.12.0.19:8080; - ... - } - ``` - -{{< note >}} The entire configuration is not shown because it is subject to change. Ellipses indicate that there's configuration not shown. {{< /note >}} - -If your issue persists, [contact us](https://github.com/nginx/nginx-gateway-fabric#contacts). - ---- - -## See also - -To learn more about the Gateway API and the resources we created in this guide, check out the following resources: - -- [Gateway API Overview](https://gateway-api.sigs.k8s.io/concepts/api-overview/) -- [Deploying a simple Gateway](https://gateway-api.sigs.k8s.io/guides/simple-gateway/) -- [HTTP Routing](https://gateway-api.sigs.k8s.io/guides/http-routing/) diff --git a/site/content/how-to/traffic-management/snippets.md b/site/content/how-to/traffic-management/snippets.md deleted file mode 100644 index 631efc6038..0000000000 --- a/site/content/how-to/traffic-management/snippets.md +++ /dev/null @@ -1,473 +0,0 @@ ---- -title: "Use the SnippetsFilter API" -weight: 800 -toc: true -docs: "DOCS-000" ---- - -This topic introduces Snippets, how to implement them using the `SnippetsFilter` API, and provides an example of how to use `SnippetsFilter` for rate limiting. - ---- - -## Overview - -Snippets allow users to insert NGINX configuration into different contexts of the -NGINX configurations that NGINX Gateway Fabric generates. - -Snippets should only be used by advanced NGINX users who need more control over the generated NGINX configuration, -and only in cases where Gateway API resources or NGINX extension policies don't apply. - -Users can configure Snippets through the `SnippetsFilter` API. `SnippetsFilter` can be an [HTTPRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteFilter) or [GRPCRouteFilter](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GRPCRouteFilter), -that can be defined in an HTTPRoute/GRPCRoute rule and is intended to modify NGINX configuration specifically for that Route rule. `SnippetsFilter` is an `extensionRef` type filter. - ---- - -## Disadvantages of Snippets - -{{< warning >}} We recommend managing NGINX configuration through Gateway API resources, [first-class policies]({{< relref "overview/custom-policies.md" >}}), and other existing [NGINX extensions]({{< relref "data-plane-configuration.md" >}}) -before using Snippets. {{< /warning >}} - -Snippets are configured using the `SnippetsFilter` API, but are disabled by default due to their complexity and security implications. - -Snippets have the following disadvantages: - -- _Complexity_. Snippets require you to: - - Understand NGINX configuration primitives to implement correct NGINX configuration. - - Understand how NGINX Gateway Fabric generates NGINX configuration so that a Snippet doesn’t interfere with the other features in the configuration. -- _Decreased robustness_. An incorrect Snippet can invalidate NGINX configuration, causing reload failures. Until the snippet is fixed, it will prevent any new configuration updates, including updates for the other Gateway resources. -- _Security implications_. Snippets give access to NGINX configuration primitives, which are not validated by NGINX Gateway Fabric. For example, a Snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Gateway resources. - -{{< note >}} If the NGINX configuration includes an invalid Snippet, NGINX will continue to operate with the last valid configuration. No new configuration will be applied until the invalid Snippet is fixed. {{< /note >}} - ---- - -## Best Practices when using SnippetsFilters - -There are endless ways to use `SnippetsFilters` to modify NGINX configuration, and thus there are many ways to generate invalid or undesired NGINX configuration. -We have outlined a few best practices to keep in mind when using `SnippetsFilters` to keep NGINX Gateway Fabric functioning correctly: - -1. Using the [Roles and Personas](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/) defined in the Gateway API, `SnippetsFilter` access - should be limited to Cluster operators. Application developers should not be able to create, modify, or delete `SnippetsFilters` as they affect other applications. - `SnippetsFilter` creates a natural split of responsibilities between the Cluster operator and the Application developer: the Cluster operator creates a `SnippetsFilter`; the Application developer references the `SnippetsFilter` in an HTTPRoute/GRPCRoute to enable it. -2. In a `SnippetsFilter`, only one Snippet per NGINX context is allowed, however multiple `SnippetsFilters` can be referenced in the same routing rule. As such, `SnippetsFilters` should not conflict with each other. If `SnippetsFilters` do conflict, they should not be referenced on the same routing rule. -3. `SnippetsFilters` that define Snippets targeting NGINX contexts `main`, `http`, or `http.server`, can potentially affect more than the routing rule they are referenced by. Proceed with caution and verify the behavior of the NGINX configuration before creating those `SnippetsFilters` in a production scenario. - ---- - -## Setup - -- To enable Snippets, [install]({{< relref "/installation/" >}}) NGINX Gateway Fabric with these modifications: - - Using Helm: set the `nginxGateway.snippetsFilters.enable=true` Helm value. - - Using Kubernetes manifests: set the `--snippets-filters` flag in the nginx-gateway container argument, add `snippetsfilters` to the RBAC - rules with verbs `list` and `watch`, and add `snippetsfilters/status` to the RBAC rules with verb `update`. See this [example manifest](https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/snippets-filters/deploy.yaml) for clarification. - -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP= - GW_PORT= - ``` - - {{< note >}} In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for. {{< /note >}} - -- Create the coffee and tea example applications: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/snippets-filter/app.yaml - ``` - -- Create a Gateway: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/snippets-filter/gateway.yaml - ``` - -- Create HTTPRoutes for the coffee and tea applications: - - ```yaml - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/examples/snippets-filter/httproutes.yaml - ``` - -- Test the configuration: - - You can send traffic to the coffee and tea applications using the external IP address and port for NGINX Gateway Fabric. - - Send a request to coffee: - - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee - ``` - - This request should receive a response from the coffee Pod: - - ```text - Server address: 10.244.0.7:8080 - Server name: coffee-76c7c85bbd-cf8nz - ``` - - Send a request to tea: - - ```shell - curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/tea - ``` - - This request should receive a response from the tea Pod: - - ```text - Server address: 10.244.0.6:8080 - Server name: tea-76c7c85bbd-cf8nz - ``` - - Before we enable rate limiting, try sending multiple requests to coffee: - - ```shell - for i in `seq 1 10`; do curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee; done - ``` - - You should see all successful responses in quick succession as we have not configured any rate limiting rules yet. - ---- - -## Create Rate Limiting SnippetsFilters - -Configure a rate limiting `SnippetsFilter` named `rate-limiting-sf` by adding the following `SnippetsFilter`: - -```yaml -kubectl apply -f - < -``` - -Configure another rate limiting `SnippetsFilter` named `no-delay-rate-limiting-sf` by adding the following `SnippetsFilter`: - -```yaml -kubectl apply -f - < -``` - -## Configure coffee to reference rate-limiting-sf SnippetsFilter - -To use the `rate-limiting-sf` `SnippetsFilter`, update the coffee HTTPRoute to reference it: - -```yaml -kubectl apply -f - < -503 Service Temporarily Unavailable - -

503 Service Temporarily Unavailable

-
nginx
- - -``` - -This is the default error response given by NGINX when the rate limit burst is exceeded, meaning our `SnippetsFilter` -correctly applied our rate limiting NGINX configuration changes. - ---- - -## Conclusion - -You've successfully used Snippets with the `SnippetsFilter` resource to configure two distinct rate limiting rules to different backend applications. - -In this example guide, the Cluster Operator would have played the role in creating and applying the `SnippetsFilter` resources shown in [Create Rate Limiting SnippetsFilters](#create-rate-limiting-snippetsfilters) -while the Application Developers for coffee and tea would have played the role in modifying their application to reference whichever `SnippetsFilter` they want shown in -[Configure coffee to reference rate-limiting-sf SnippetsFilter](#configure-coffee-to-reference-rate-limiting-sf-snippetsfilter) and [Configure tea to reference no-delay-rate-limiting-sf SnippetsFilter](#configure-tea-to-reference-no-delay-rate-limiting-sf-snippetsfilter). -This follows our recommended Role and Persona separation described in the [Best Practices when using SnippetsFilters](#best-practices-when-using-snippetsfilters). - -For an alternative method of modifying the NGINX configuration NGINX Gateway Fabric generates through Gateway API resources, check out -our supported [first-class policies]({{< relref "overview/custom-policies.md" >}}) which don't carry many of the aforementioned disadvantages of Snippets. - ---- - -## Troubleshooting - -If a `SnippetsFilter` is defined in a Route and contains a Snippet which includes an invalid NGINX configuration, NGINX will continue to operate -with the last valid configuration and an event with the error will be outputted. No new configuration will be applied until the invalid Snippet is fixed. - -An example of an error from the NGINX Gateway Fabric `nginx-gateway` container logs: - -```text -{"level":"error","ts":"2024-10-29T22:19:41Z","logger":"eventLoop.eventHandler","msg":"Failed to update NGINX configuration","batchID":156,"error":"failed to reload NGINX: reload unsuccessful: no new NGINX worker processes started for config version 141. Please check the NGINX container logs for possible configuration issues: context deadline exceeded","stacktrace":"github.com/nginx/nginx-gateway-fabric/internal/mode/static.(*eventHandlerImpl).HandleEventBatch\n\tgithub.com/nginx/nginx-gateway-fabric/internal/mode/static/handler.go:219\ngithub.com/nginx/nginx-gateway-fabric/internal/framework/events.(*EventLoop).Start.func1.1\n\tgithub.com/nginx/nginx-gateway-fabric/internal/framework/events/loop.go:74"} -``` - -An example of an error from the NGINX Gateway Fabric `nginx` container logs: - -```text -2024/10/29 22:18:41 [emerg] 40#40: invalid number of arguments in "limit_req_zone" directive in /etc/nginx/includes/SnippetsFilter_http_default_rate-limiting-sf.conf:1 -``` - -The Route which references the `SnippetsFilter` may also contain information in its conditions describing the error: - -```text - Conditions: - Last Transition Time: 2024-10-29T22:19:41Z - Message: All references are resolved - Observed Generation: 2 - Reason: ResolvedRefs - Status: True - Type: ResolvedRefs - Last Transition Time: 2024-10-29T22:19:41Z - Message: The Gateway is not programmed due to a failure to reload nginx with the configuration. Please see the nginx container logs for any possible configuration issues. NGINX may still be configured for this Route. However, future updates to this resource will not be configured until the Gateway is programmed again - Observed Generation: 2 - Reason: GatewayNotProgrammed - Status: False - Type: Accepted -``` - -If a Route references a `SnippetsFilter` which cannot be resolved, the route will return a 500 HTTP error response on all requests. -The Route conditions will contain information describing the error: - -```text -Conditions: - Last Transition Time: 2024-10-29T22:26:01Z - Message: The route is accepted - Observed Generation: 2 - Reason: Accepted - Status: True - Type: Accepted - Last Transition Time: 2024-10-29T22:26:01Z - Message: spec.rules[0].filters[0].extensionRef: Not found: v1.LocalObjectReference{Group:"gateway.nginx.org", Kind:"SnippetsFilter", Name:"rate-limiting-sf"} - Observed Generation: 2 - Reason: InvalidFilter - Status: False - Type: ResolvedRefs -``` - -{{< note >}} If you run into situations where an NGINX directive fails to be applied and the troubleshooting information here isn't sufficient, please create an issue in the -[NGINX Gateway Fabric Github repository](https://github.com/nginx/nginx-gateway-fabric). {{< /note >}} - ---- - -## See also - -- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the `SnippetsFilter` API. diff --git a/site/content/how-to/traffic-management/tls-passthrough.md b/site/content/how-to/traffic-management/tls-passthrough.md deleted file mode 100644 index 8ade7ff8bb..0000000000 --- a/site/content/how-to/traffic-management/tls-passthrough.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: "TLS Passthrough" -weight: 800 -toc: true -docs: "DOCS-000" ---- - -Learn how to use TLSRoutes to configure TLS Passthrough load-balancing with NGINX Gateway Fabric. - -## Overview - -In this guide, we will show how to configure TLS passthrough for your application, using a [TLSRoute](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.TLSRoute). - -## Note on Gateway API Experimental Features - -{{< important >}} TLSRoute is a Gateway API resource from the experimental release channel. {{< /important >}} - -{{}} - -## Before you begin - -- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric with experimental features enabled. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_TLS_PORT= - ``` - -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the Gateway will forward for.{{< /note >}} - -## Set up - -Create the `secure-app` application by copying and pasting the following block into your terminal: - -```yaml -kubectl apply -f - < 8443/TCP 12s -``` - -Create a Gateway. This will create a TLS listener with the hostname `*.example.com` and passthrough TLS mode. Copy and paste this into your terminal. - -```yaml -kubectl apply -f - <}}It is possible to add an HTTPS listener on the same port that terminates TLS connections so long as the hostname does not overlap with the TLS listener hostname.{{< /note >}} - -Create a TLSRoute that attaches to the Gateway and routes requests to `app.example.com` to the `secure-app` Service: - -```yaml -kubectl apply -f - <}}To route to a Service in a Namespace different from the TLSRoute Namespace, create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1beta1.ReferenceGrant) to permit the cross-namespace reference. {{< /note >}} - -## Send traffic - -Using the external IP address and port for NGINX Gateway Fabric, send traffic to the `secure-app` application. - -{{< note >}}If you have a DNS record allocated for `app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -Send a request to the `secure-app` Service on the TLS port with the `--insecure` flag. The `--insecure` flag is required because the `secure-app` is using self-signed certificates. - -```shell -curl --resolve app.example.com:$GW_TLS_PORT:$GW_IP https://app.example.com:$GW_TLS_PORT --insecure -v -``` - -```text -Added app.example.com:8443:127.0.0.1 to DNS cache -* Hostname app.example.com was found in DNS cache -* Trying 127.0.0.1:8443... -* Connected to app.example.com (127.0.0.1) port 8443 -* ALPN: curl offers h2,http/1.1 -* (304) (OUT), TLS handshake, Client hello (1): -* (304) (IN), TLS handshake, Server hello (2): -* (304) (IN), TLS handshake, Unknown (8): -* (304) (IN), TLS handshake, Certificate (11): -* (304) (IN), TLS handshake, CERT verify (15): -* (304) (IN), TLS handshake, Finished (20): -* (304) (OUT), TLS handshake, Finished (20): -* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF -* ALPN: server accepted http/1.1 -* Server certificate: -* subject: C=US; ST=CA; L=San Francisco; CN=app.example.com -* start date: Mar 23 23:20:43 2020 GMT -* expire date: Mar 23 23:20:43 2023 GMT -* issuer: C=US; ST=CA; L=San Francisco; CN=app.example.com -* SSL certificate verify result: self signed certificate (18), continuing anyway. -* using HTTP/1.x -> GET / HTTP/1.1 -> Host: app.example.com:8443 -> User-Agent: curl/8.6.0 -> Accept: */* -> -< HTTP/1.1 200 OK -< Server: nginx/1.27.0 -< Date: Wed, 14 Aug 2024 20:41:21 GMT -< Content-Type: text/plain -< Content-Length: 43 -< Connection: keep-alive -< -hello from pod secure-app-575785644-kzqf6 -``` - -Note that the server certificate used to terminate the TLS connection has the subject common name of `app.example.com`. This is the server certificate that the `secure-app` is configured with and shows that the TLS connection was terminated by the `secure-app`, not NGINX Gateway Fabric. diff --git a/site/content/how-to/traffic-management/upgrade-apps-without-downtime.md b/site/content/how-to/traffic-management/upgrade-apps-without-downtime.md deleted file mode 100644 index 7d802ceb3d..0000000000 --- a/site/content/how-to/traffic-management/upgrade-apps-without-downtime.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: "Upgrade applications without downtime" -toc: true -weight: 300 -type: how-to -product: NGF -docs: "DOCS-1420" ---- - -Learn how to use NGINX Gateway Fabric to upgrade applications without downtime. - ---- - -## Overview - -{{< note >}} See the [Architecture document]({{< relref "/overview/gateway-architecture.md" >}}) to learn more about NGINX Gateway Fabric architecture.{{< /note >}} - -NGINX Gateway Fabric allows upgrading applications without downtime. To understand the upgrade methods, you need to be familiar with the NGINX features that help prevent application downtime: Graceful configuration reloads and upstream server updates. - ---- - -### Graceful configuration reloads - -If a relevant gateway API or built-in Kubernetes resource is changed, NGINX Gateway Fabric will update NGINX by regenerating the NGINX configuration. NGINX Gateway Fabric then sends a reload signal to the master NGINX process to apply the new configuration. - -We call such an operation a "reload", during which client requests are not dropped - which defines it as a graceful reload. - -This process is further explained in the [NGINX configuration documentation](https://nginx.org/en/docs/control.html?#reconfiguration). - ---- - -### Upstream server updates - -Endpoints frequently change during application upgrades: Kubernetes creates pods for the new version of an application and removes the old ones, creating and removing the respective endpoints as well. - -NGINX Gateway Fabric detects changes to endpoints by watching their corresponding [EndpointSlices](https://kubernetes.io/docs/concepts/services-networking/endpoint-slices/). - -In an NGINX configuration, a service is represented as an [upstream](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream), and an endpoint as an [upstream server](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#server). - -Adding and removing endpoints are two of the most common cases: - -- If an endpoint is added, NGINX Gateway Fabric adds an upstream server to NGINX that corresponds to the endpoint, then reloads NGINX. Next, NGINX will start proxying traffic to that endpoint. -- If an endpoint is removed, NGINX Gateway Fabric removes the corresponding upstream server from NGINX. After a reload, NGINX will stop proxying traffic to that server. However, it will finish proxying any pending requests to that server before switching to another endpoint. - -As long as you have more than one endpoint ready, clients won't experience downtime during upgrades. - -{{< note >}}It is good practice to configure a [Readiness probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/) in the deployment so that a pod can report when it is ready to receive traffic. Note that NGINX Gateway Fabric will not add any endpoint to NGINX that is not ready.{{< /note >}} - ---- - -## Prerequisites - -- You have deployed your application as a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) -- The pods of the deployment belong to a [service](https://kubernetes.io/docs/concepts/services-networking/service/) so that Kubernetes creates an [endpoint](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/endpoints-v1/) for each pod. -- You have exposed the application to the clients via an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) resource that references that service. - -For example, an application can be exposed using a routing rule like below: - -```yaml -- matches: - - path: - type: PathPrefix - value: / - backendRefs: - - name: my-app - port: 80 -``` - -{{< note >}}See the [Cafe example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.0/examples/cafe-example) for a basic example.{{< /note >}} - -The upgrade methods in the next sections cover: - -- Rolling deployment upgrades -- Blue-green deployments -- Canary releases - ---- - -## Rolling deployment upgrade - -To start a [rolling deployment upgrade](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment), you update the deployment to use the new version tag of the application. As a result, Kubernetes terminates the pods with the old version and create new ones. By default, Kubernetes also ensures that some number of pods always stay available during the upgrade. - -This upgrade will add new upstream servers to NGINX and remove the old ones. As long as the number of pods (ready endpoints) during an upgrade does not reach zero, NGINX will be able to proxy traffic, and therefore prevent any downtime. - -This method does not require you to update the **HTTPRoute**. - ---- - -## Blue-green deployments - -With this method, you deploy a new version of the application (blue version) as a separate deployment, while the old version (green) keeps running and handling client traffic. Next, you switch the traffic from the green version to the blue. If the blue works as expected, you terminate the green. Otherwise, you switch the traffic back to the green. - -There are two ways to switch the traffic: - -- Update the service selector to select the pods of the blue version instead of the green. As a result, NGINX Gateway Fabric removes the green upstream servers from NGINX and adds the blue ones. With this approach, it is not necessary to update the **HTTPRoute**. -- Create a separate service for the blue version and update the backend reference in the **HTTPRoute** to reference this service, which leads to the same result as with the previous option. - ---- - -## Canary releases - -Canary releases involve gradually introducing a new version of your application to a subset of nodes in a controlled manner, splitting the traffic between the old are new (canary) release. This allows for monitoring and testing the new release's performance and reliability before full deployment, helping to identify and address issues without impacting the entire user base. - -To support canary releases, you can implement an approach with two deployments behind the same service (see [Canary deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#canary-deployment) in the Kubernetes documentation). However, this approach lacks precision for defining the traffic split between the old and the canary version. You can greatly influence it by controlling the number of pods (for example, four pods of the old version and one pod of the canary). However, note that NGINX Gateway Fabric uses [`random two least_conn`](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#random) load balancing method, which doesn't guarantee an exact split based on the number of pods (80/20 in the given example). - -A more flexible and precise way to implement canary releases is to configure a traffic split in an **HTTPRoute**. In this case, you create a separate deployment for the new version with a separate service. For example, for the rule below, NGINX will proxy 95% of the traffic to the old version endpoints and only 5% to the new ones. - -```yaml -- matches: - - path: - type: PathPrefix - value: / - backendRefs: - - name: my-app-old - port: 80 - weight: 95 - - name: my-app-new - port: 80 - weight: 5 -``` - -{{< note >}}Every request coming from the same client won't necessarily be sent to the same backend. NGINX will independently split each request among the backend references.{{< /note >}} - -By updating the rule you can further increase the share of traffic the new version gets and finally completely switch to the new version: - -```yaml -- matches: - - path: - type: PathPrefix - value: / - backendRefs: - - name: my-app-old - port: 80 - weight: 0 - - name: my-app-new - port: 80 - weight: 1 -``` - -See the [Traffic splitting example](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.0/examples/traffic-splitting) from our repository. diff --git a/site/content/how-to/traffic-management/upstream-settings.md b/site/content/how-to/traffic-management/upstream-settings.md deleted file mode 100644 index 55ae6b4d36..0000000000 --- a/site/content/how-to/traffic-management/upstream-settings.md +++ /dev/null @@ -1,395 +0,0 @@ ---- -title: "Upstream Settings Policy API" -weight: 900 -toc: true -docs: "DOCS-000" ---- - -Learn how to use the `UpstreamSettingsPolicy` API. - -## Overview - -The `UpstreamSettingsPolicy` API allows Application Developers to configure the behavior of a connection between NGINX and the upstream applications. - -The settings in `UpstreamSettingsPolicy` correspond to the following NGINX directives: - -- [`zone`]() -- [`keepalive`]() -- [`keepalive_requests`]() -- [`keepalive_time`]() -- [`keepalive_timeout`]() - -`UpstreamSettingsPolicy` is a [Direct Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) that can be applied to one or more services in the same namespace as the policy. -`UpstreamSettingsPolicies` can only be applied to HTTP or gRPC services, in other words, services that are referenced by an HTTPRoute or GRPCRoute. - -See the [custom policies]({{< relref "overview/custom-policies.md" >}}) document for more information on policies. - -This guide will show you how to use the `UpstreamSettingsPolicy` API to configure the upstream zone size and keepalives for your applications. - -For all the possible configuration options for `UpstreamSettingsPolicy`, see the [API reference]({{< relref "reference/api.md" >}}). - ---- - -## Before you begin - -- [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -- Lookup the name of the NGINX Gateway Fabric pod and save into shell variable: - - ```text - NGF_POD_NAME= - ``` - - {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} - ---- - -## Setup - -Create the `coffee` and `tea` example applications: - -```yaml -kubectl apply -f - < 80/TCP 23h -service/tea ClusterIP 10.244.0.15 80/TCP 23h - -NAME READY STATUS RESTARTS AGE -pod/coffee-676c9f8944-n9g6n 1/1 Running 0 23h -pod/tea-6fbfdcb95d-cf84d 1/1 Running 0 23h -``` - -Create a Gateway: - -```yaml -kubectl apply -f - < -``` - -Next, verify that the policy has been applied to the `coffee` and `tea` upstreams by inspecting the NGINX configuration: - -```shell -kubectl exec -it -n nginx-gateway $NGF_POD_NAME -c nginx -- nginx -T -``` - -You should see the `zone` directive in the `coffee` and `tea` upstreams both specify the size `1m`: - -```text -upstream default_coffee_80 { - random two least_conn; - zone default_coffee_80 1m; - - server 10.244.0.14:8080; -} - -upstream default_tea_80 { - random two least_conn; - zone default_tea_80 1m; - - server 10.244.0.15:8080; -} -``` - -## Enable keepalive connections - -To enable keepalive connections for the `coffee` service, create the following `UpstreamSettingsPolicy`: - -```yaml -kubectl apply -f - < -``` - -Next, verify that the policy has been applied to the `coffee` upstreams, by inspecting the NGINX configuration: - -```shell -kubectl exec -it -n nginx-gateway $NGF_POD_NAME -c nginx -- nginx -T -``` - -You should see that the `coffee` upstream has the `keepalive` directive set to 32: - -```text -upstream default_coffee_80 { - random two least_conn; - zone default_coffee_80 1m; - - server 10.244.0.14:8080; - keepalive 32; -} -``` - -Notice, that the `tea` upstream does not contain the `keepalive` directive, since the `upstream-keepalives` policy does not target the `tea` service: - -```text -upstream default_tea_80 { - random two least_conn; - zone default_tea_80 1m; - - server 10.244.0.15:8080; -} -``` - ---- - -## Further reading - -- [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work. -- [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the `UpstreamSettingsPolicy` API. diff --git a/site/content/how-to/traffic-security/_index.md b/site/content/how-to/traffic-security/_index.md deleted file mode 100644 index 0a6ddcf151..0000000000 --- a/site/content/how-to/traffic-security/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Traffic security" -weight: 200 ---- diff --git a/site/content/how-to/traffic-security/integrating-cert-manager.md b/site/content/how-to/traffic-security/integrating-cert-manager.md deleted file mode 100644 index d374bb577f..0000000000 --- a/site/content/how-to/traffic-security/integrating-cert-manager.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -title: "Secure traffic using Let's Encrypt and cert-manager" -weight: 100 -toc: true -type: how-to -product: NGF -docs: "DOCS-1425" ---- - -Learn how to issue and mange certificates using Let's Encrypt and cert-manager. - -## Overview - -Securing client server communication is a crucial part of modern application architectures. One of the most important steps in this process is implementing HTTPS (HTTP over TLS/SSL) for all communications. This encrypts the data transmitted between the client and server, preventing eavesdropping and tampering. To do this, you need an SSL/TLS certificate from a trusted Certificate Authority (CA). However, issuing and managing certificates can be a complicated manual process. Luckily, there are many services and tools available to simplify and automate certificate issuance and management. - -Follow the steps in this guide to: - -- Configure HTTPS for your application using a [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/). -- Use [Let’s Encrypt](https://letsencrypt.org) as the Certificate Authority (CA) issuing the TLS certificate. -- Use [cert-manager](https://cert-manager.io) to automate the provisioning and management of the certificate. - ---- - -## Before you begin - -- Administrator access to a Kubernetes cluster. -- [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally. -- [NGINX Gateway Fabric deployed]({{< relref "/installation/" >}}) in the Kubernetes cluster. -- A DNS-resolvable domain name is required. It must resolve to the public endpoint of the NGINX Gateway Fabric deployment, and this public endpoint must be an external IP address or alias accessible over the internet. The process here will depend on your DNS provider. This DNS name will need to be resolvable from the Let’s Encrypt servers, which may require that you wait for the record to propagate before it will work. - ---- - -## Secure traffic using Let's Encrypt and cert-manager - -{{cert-manager ACME challenge and certificate management with Gateway API}} - -The diagram above shows a simplified representation of the cert-manager ACME challenge and certificate issuance process using Gateway API. Please note that not all of the kubernetes objects created in this process are represented in this diagram. - -At a high level, the process looks like this: - -1. We deploy cert-manager and create a ClusterIssuer which specifies Let’s Encrypt as our CA and gateway as our ACME HTTP01 challenge solver. -1. We create a gateway resource for our domain (cafe.example.com) and configure cert-manager integration using an annotation. -1. This starts the certificate issuance process – cert-manager contacts Let’s Encrypt to obtain a certificate, and Let’s Encrypt starts the ACME challenge. As part of this challenge, cert-manager creates a temporary HTTPRoute resource which directs the traffic through NGINX Gateway Fabric to verify we control the domain name in the certificate request. -1. Once the domain has been verified, the certificate is issued. Cert-manager stores the keypair in a Kubernetes secret that is referenced by the gateway resource. As a result, NGINX is configured to terminate HTTPS traffic from clients using this signed keypair. -1. We deploy our application and our HTTPRoute which defines our routing rules. The routing rules defined configure NGINX to direct requests to `https://cafe.example.com/coffee` to our coffee-app application, and to use the HTTPS listener defined in our gateway resource. -1. When the client connects to `https://cafe.example.com/coffee`, the request is routed to the coffee-app application and the communication is secured using the signed keypair contained in the cafe-secret secret. -1. The certificate will be automatically renewed when it is close to expiry, the secret will be updated using the new certificate, and NGINX Gateway Fabric will dynamically update the keypair on the filesystem used by NGINX for HTTPS termination once the secret is updated. - ---- - -## Securing traffic - -### Deploy cert-manager - -The first step is to deploy cert-manager onto the cluster. - -- Add the Helm repository. - - ```shell - helm repo add jetstack https://charts.jetstack.io - helm repo update - ``` - -- Install cert-manager, and enable the GatewayAPI feature gate: - - ```shell - helm install \ - cert-manager jetstack/cert-manager \ - --namespace cert-manager \ - --create-namespace \ - --version v1.12.0 \ - --set installCRDs=true \ - --set "extraArgs={--feature-gates=ExperimentalGatewayAPISupport=true}" - ``` - ---- - -### Create a ClusterIssuer - -Next we need to create a [ClusterIssuer](https://cert-manager.io/docs/concepts/issuer/), a Kubernetes resource that represents the certificate authority (CA) that will generate the signed certificates by honouring certificate signing requests. - -We are using the ACME Issuer type, and Let's Encrypt as the CA server. In order for Let's Encypt to verify that we own the domain a certificate is being requested for, we must complete "challenges". This is to ensure clients are unable to request certificates for domains they do not own. We will configure the issuer to use a HTTP01 challenge, and our gateway resource that we will create in the next step as the solver. To read more about HTTP01 challenges, see the [cert-manager documentation](https://cert-manager.io/docs/configuration/acme/http01/). Use the following YAML definition to create the resource, but please note the `email` field must be updated to your own email address. - -```yaml -apiVersion: cert-manager.io/v1 -kind: ClusterIssuer -metadata: - name: letsencrypt-prod -spec: - acme: - # You must replace this email address with your own. - # Let's Encrypt will use this to contact you about expiring - # certificates, and issues related to your account. - email: my-name@example.com - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - # Secret resource that will be used to store the account's private key. - name: issuer-account-key - # Add a single challenge solver, HTTP01 using NGINX Gateway Fabric - solvers: - - http01: - gatewayHTTPRoute: - parentRefs: # This is the name of the Gateway that will be created in the next step - - name: gateway - namespace: default - kind: Gateway -``` - ---- - -### Deploy our Gateway with the cert-manager annotation - -Next we need to deploy our gateway. You can use the YAML manifest below, updating the `spec.listeners[1].hostname` field to the required value for your environment. - -```yaml -apiVersion: gateway.networking.k8s.io/v1 -kind: Gateway -metadata: - name: gateway - annotations: # This is the name of the ClusterIssuer created in the previous step - cert-manager.io/cluster-issuer: letsencrypt-prod -spec: - gatewayClassName: nginx - listeners: - - name: http - port: 80 - protocol: HTTP - - name: https - # Important: The hostname needs to be set to your domain - hostname: "cafe.example.com" - port: 443 - protocol: HTTPS - tls: - mode: Terminate - certificateRefs: - - kind: Secret - name: cafe-secret -``` - -It's worth noting a couple of key details in this manifest: - -- The cert-manager annotation is present in the metadata – this enables the cert-manager integration, and tells cert-manager which ClusterIssuer configuration it should use for the certificates. -- There are two listeners configured, an HTTP listener on port 80, and an HTTPS listener on port 443. - - The HTTP listener on port 80 is required for the HTTP01 ACME challenge to work. This is because as part of the HTTP01 challenge, a temporary HTTPRoute will be created by cert-manager to solve the ACME challenge, and this HTTPRoute requires a listener on port 80. See the [HTTP01 Gateway API solver documentation](https://cert-manager.io/docs/configuration/acme/http01/#configuring-the-http-01-gateway-api-solver) for more information. - - The HTTPS listener on port 443 is the listener we will use in our HTTPRoute in the next step. Cert-manager will create a certificate for this listener block. -- The hostname needs to set to the required value. A new certificate will be issued from the `letsencrypt-prod` ClusterIssuer for the domain, e.g. "cafe.example.com", once the ACME challenge is successful. - -Once the certificate has been issued, cert-manager will create a certificate resource on the cluster and the `cafe-secret` Secret containing the signed keypair in the same Namespace as the gateway. We can verify the secret has been created successfully using `kubectl`. Note it will take a little bit of time for the challenge to complete and the secret to be created: - -```shell -kubectl get secret cafe-secret -``` - -```text -NAME TYPE DATA AGE -cafe-secret kubernetes.io/tls 2 20s -``` - ---- - -### Deploy our application and HTTPRoute - -Now we can create our coffee deployment and service, and configure the routing rules. You can use the following manifest to create the deployment and service: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: coffee -spec: - replicas: 1 - selector: - matchLabels: - app: coffee - template: - metadata: - labels: - app: coffee - spec: - containers: - - name: coffee - image: nginxdemos/nginx-hello:plain-text - ports: - - containerPort: 8080 ---- -apiVersion: v1 -kind: Service -metadata: - name: coffee -spec: - ports: - - port: 80 - targetPort: 8080 - protocol: TCP - name: http - selector: - app: coffee -``` - -Deploy our HTTPRoute to configure our routing rules for the coffee application. Note the `parentRefs` section in the spec refers to the listener configured in the previous step. - -```yaml -apiVersion: gateway.networking.k8s.io/v1 -kind: HTTPRoute -metadata: - name: coffee -spec: - parentRefs: - - name: gateway - sectionName: https - hostnames: # Update the hostname to match what is configured in the Gateway resource - - "cafe.example.com" - rules: - - matches: - - path: - type: PathPrefix - value: /coffee - backendRefs: - - name: coffee - port: 80 -``` - ---- - -## Testing - -To test everything has worked correctly, we can use curl to the navigate to our endpoint, for example, `https://cafe.example.com/coffee`. To verify using curl, we can use the `-v` option to increase verbosity and inspect the presented certificate. - -```shell -curl https://cafe.example.com/coffee -v -``` - -The output will look similar to this: - -```text -* Trying 54.195.47.105:443... -* Connected to cafe.example.com (54.195.47.105) port 443 (#0) -* ALPN: offers h2,http/1.1 -* (304) (OUT), TLS handshake, Client hello (1): -* CAfile: /etc/ssl/cert.pem -* CApath: none -* (304) (IN), TLS handshake, Server hello (2): -* (304) (IN), TLS handshake, Unknown (8): -* (304) (IN), TLS handshake, Certificate (11): -* (304) (IN), TLS handshake, CERT verify (15): -* (304) (IN), TLS handshake, Finished (20): -* (304) (OUT), TLS handshake, Finished (20): -* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 -* ALPN: server accepted http/1.1 -* Server certificate: -* subject: CN=cafe.example.com -* start date: Aug 11 08:22:11 2023 GMT -* expire date: Nov 9 08:22:10 2023 GMT -* subjectAltName: host "cafe.example.com" matched cert's "cafe.example.com" -* issuer: C=US; O=Let's Encrypt; CN=R3 -* SSL certificate verify ok. -* using HTTP/1.1 -> GET /coffee HTTP/1.1 -> Host: cafe.example.com -> User-Agent: curl/7.88.1 -> Accept: */* -> -< HTTP/1.1 200 OK -< Server: nginx/1.25.1 -< Date: Fri, 11 Aug 2023 10:03:21 GMT -< Content-Type: text/plain -< Content-Length: 163 -< Connection: keep-alive -< Expires: Fri, 11 Aug 2023 10:03:20 GMT -< Cache-Control: no-cache -< -Server address: 192.168.78.136:8080 -Server name: coffee-9bf875848-xvkqv -Date: 11/Aug/2023:10:03:21 +0000 -URI: /coffee -Request ID: e64c54a2ac253375ac085d48980f000a -* Connection #0 to host cafe.example.com left intact -``` - ---- - -## Troubleshooting - -- To troubleshoot any issues related to the cert-manager installation or issuer setup, see [the cert-manager troubleshooting guide](https://cert-manager.io/docs/troubleshooting/). -- To troubleshoot the HTTP01 ACME challenge, please see the cert-manager [ACME troubleshooting guide](https://cert-manager.io/docs/troubleshooting/acme/). - - Note that for the HTTP01 challenge to work using the gateway resource, HTTPS redirect must not be configured. - - The temporary HTTPRoute created by cert-manager routes the traffic between cert-manager and the Let's Encrypt server through NGINX Gateway Fabric. If the challenge is not successful, it may be useful to inspect the NGINX logs to see the ACME challenge requests. You should see something like the following: - - ```shell - kubectl logs -n nginx-gateway -c nginx - <...> - 52.208.162.19 - - [15/Aug/2023:13:18:12 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" - 52.208.162.19 - - [15/Aug/2023:13:18:14 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" - 52.208.162.19 - - [15/Aug/2023:13:18:16 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" - 52.208.162.19 - - [15/Aug/2023:13:18:18 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" - 52.208.162.19 - - [15/Aug/2023:13:18:20 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "cert-manager-challenges/v1.12.0 (linux/amd64) cert-manager/bd192c4f76dd883f9ee908035b894ffb49002384" - 3.128.204.81 - - [15/Aug/2023:13:18:22 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)" - 23.178.112.204 - - [15/Aug/2023:13:18:22 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)" - 35.166.192.222 - - [15/Aug/2023:13:18:22 +0000] "GET /.well-known/acme-challenge/bXQn27Lenax2AJKmOOS523T-MWOKeFhL0bvrouNkUc4 HTTP/1.1" 200 87 "-" "Mozilla/5.0 (compatible; Let's Encrypt validation server; +https://www.letsencrypt.org)" - <...> - ``` - ---- - -## See also - -- [Gateway docs](https://gateway-api.sigs.k8s.io) -- [Cert-manager gateway usage](https://cert-manager.io/docs/usage/gateway/) -- [Cert-manager ACME](https://cert-manager.io/docs/configuration/acme/) -- [Let’s Encrypt](https://letsencrypt.org) -- [NGINX HTTPS docs](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) diff --git a/site/content/how-to/traffic-security/securing-backend-traffic.md b/site/content/how-to/traffic-security/securing-backend-traffic.md deleted file mode 100644 index 8265b0a8f2..0000000000 --- a/site/content/how-to/traffic-security/securing-backend-traffic.md +++ /dev/null @@ -1,342 +0,0 @@ ---- -title: "Securing backend traffic" -weight: 200 -toc: true -type: how-to -product: NGF -docs: "DOCS-1423" ---- - -Learn how to encrypt HTTP traffic between NGINX Gateway Fabric and your backend pods. - ---- - -## Overview - -In this guide, we will show how to specify the TLS configuration of the connection from the Gateway to a backend pod/s via the Service API object using a [BackendTLSPolicy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/). This covers the use-case where the service or backend owner is doing their own TLS and NGINX Gateway Fabric needs to know how to connect to this backend pod that has its own certificate over HTTPS. - ---- - -## Note on Gateway API Experimental Features - -{{< important >}} BackendTLSPolicy is a Gateway API resource from the experimental release channel. {{< /important >}} - -{{}} - ---- - -## Before you begin - -- [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric with experimental features enabled. -- Save the public IP address and port of NGINX Gateway Fabric into shell variables: - - ```text - GW_IP=XXX.YYY.ZZZ.III - GW_PORT= - ``` - -{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}} - ---- - -## Set up - -Create the **secure-app** application in Kubernetes by copying and pasting the following block into your terminal: - -```yaml -kubectl apply -f - < 8443/TCP 9s -``` - ---- - -## Configure routing rules - -First, we will create the Gateway resource with an HTTP listener: - -```yaml -kubectl apply -f - <}}If you have a DNS record allocated for `secure-app.example.com`, you can send the request directly to that hostname, without needing to resolve.{{< /note >}} - -```shell -curl --resolve secure-app.example.com:$GW_PORT:$GW_IP http://secure-app.example.com:$GW_PORT/ -``` - -```text - -400 The plain HTTP request was sent to HTTPS port - -

400 Bad Request

-
The plain HTTP request was sent to HTTPS port
-
nginx/1.25.3
- - -``` - -We can see we a status 400 Bad Request message from NGINX. - ---- - -## Create the backend TLS configuration - -To configure the backend TLS terminationm, first we will create the ConfigMap that holds the `ca.crt` entry for verifying our self-signed certificates: - -```yaml -kubectl apply -f - < -Annotations: -API Version: gateway.networking.k8s.io/v1alpha3 -Kind: BackendTLSPolicy -Metadata: - Creation Timestamp: 2024-05-15T12:02:38Z - Generation: 1 - Resource Version: 19380 - UID: b3983a6e-92f1-4a98-b2af-64b317d74528 -Spec: - Target Refs: - Group: - Kind: Service - Name: secure-app - Validation: - Ca Certificate Refs: - Group: - Kind: ConfigMap - Name: backend-cert - Hostname: secure-app.example.com -Status: - Ancestors: - Ancestor Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Namespace: default - Conditions: - Last Transition Time: 2024-05-15T12:02:38Z - Message: BackendTLSPolicy is accepted by the Gateway - Reason: Accepted - Status: True - Type: Accepted - Controller Name: gateway.nginx.org/nginx-gateway-controller -Events: -``` - ---- - -## Send traffic with backend TLS configuration - -Now let's try sending traffic again: - -```shell -curl --resolve secure-app.example.com:$GW_PORT:$GW_IP http://secure-app.example.com:$GW_PORT/ -``` - -```text -hello from pod secure-app -``` - ---- - -## See also - -To learn more about configuring backend TLS termination using the Gateway API, see the following resources: - -- [Backend TLS Policy](https://gateway-api.sigs.k8s.io/api-types/backendtlspolicy/) -- [Backend TLS Policy GEP](https://gateway-api.sigs.k8s.io/geps/gep-1897/) diff --git a/site/content/includes/index.md b/site/content/includes/index.md deleted file mode 100644 index ca03031f1e..0000000000 --- a/site/content/includes/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -headless: true ---- diff --git a/site/content/includes/installation/delay-pod-termination/delay-pod-termination-overview.md b/site/content/includes/installation/delay-pod-termination/delay-pod-termination-overview.md deleted file mode 100644 index b22a143424..0000000000 --- a/site/content/includes/installation/delay-pod-termination/delay-pod-termination-overview.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -docs: "DOCS-1441" ---- - -To avoid client service interruptions when upgrading NGINX Gateway Fabric, you can configure [`PreStop` hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/) to delay terminating the NGINX Gateway Fabric pod, allowing the pod to complete certain actions before shutting down. This ensures a smooth upgrade without any downtime, also known as a zero downtime upgrade. - -For an in-depth explanation of how Kubernetes handles pod termination, see the [Termination of Pods](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination) topic on their official website. - -{{}}Keep in mind that NGINX won't shut down while WebSocket or other long-lived connections are open. NGINX will only stop when these connections are closed by the client or the backend. If these connections stay open during an upgrade, Kubernetes might need to shut down NGINX forcefully. This sudden shutdown could interrupt service for clients.{{}} diff --git a/site/content/includes/installation/delay-pod-termination/termination-grace-period.md b/site/content/includes/installation/delay-pod-termination/termination-grace-period.md deleted file mode 100644 index 8b2b3f473b..0000000000 --- a/site/content/includes/installation/delay-pod-termination/termination-grace-period.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -docs: "DOCS-1440" ---- - -Set `terminationGracePeriodSeconds` to a value that is equal to or greater than the `sleep` duration specified in the `preStop` hook (default is `30`). This setting prevents Kubernetes from terminating the pod before before the `preStop` hook has completed running. - - ```yaml - terminationGracePeriodSeconds: 50 - ``` diff --git a/site/content/includes/installation/expose-nginx-gateway-fabric.md b/site/content/includes/installation/expose-nginx-gateway-fabric.md deleted file mode 100644 index bfa704c3ef..0000000000 --- a/site/content/includes/installation/expose-nginx-gateway-fabric.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: "Expose NGINX Gateway Fabric" -weight: 300 -docs: "DOCS-1427" ---- - -There are two options for accessing NGINX Gateway Fabric depending on the type of LoadBalancer service you chose during installation: - -- If the LoadBalancer type is `NodePort`, Kubernetes will randomly allocate two ports on every node of the cluster. - To access the NGINX Gateway Fabric, use an IP address of any node of the cluster along with the two allocated ports. - - {{}} Read more about the type NodePort in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport). {{}} - -- If the LoadBalancer type is `LoadBalancer`: - - - For GCP or Azure, Kubernetes will allocate a cloud load balancer for load balancing the NGINX Gateway Fabric pods. - Use the public IP of the load balancer to access NGINX Gateway Fabric. - - For AWS, Kubernetes will allocate a Network Load Balancer (NLB) in TCP mode with the PROXY protocol enabled to pass - the client's information (the IP address and the port). - - Use the public IP of the load balancer to access NGINX Gateway Fabric. To get the public IP which is reported in the `EXTERNAL-IP` column: - - - For GCP or Azure, run: - - ```shell - kubectl get svc nginx-gateway -n nginx-gateway - ``` - - - In AWS, the NLB (Network Load Balancer) DNS (directory name system) name will be reported by Kubernetes instead of a public IP. To get the DNS name, run: - - ```shell - kubectl get svc nginx-gateway -n nginx-gateway - ``` - - {{< note >}} We recommend using the NLB DNS whenever possible, but for testing purposes, you can resolve the DNS name to get the IP address of the load balancer: - - ```shell - nslookup - ``` - - {{< /note >}} - - {{}} Learn more about type LoadBalancer in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer). - - For AWS, additional options regarding an allocated load balancer are available, such as its type and SSL - termination. Read the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/#type-loadbalancer) to learn more. - {{}} - -{{}}By default Helm and manifests configure NGINX Gateway Fabric on ports `80` and `443`, affecting any gateway [listeners](https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.Listener) on these ports. To use different ports, update the configuration. NGINX Gateway Fabric requires a configured [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/#gateway) resource with a valid listener to listen on any ports.{{}} - -NGINX Gateway Fabric uses the created service to update the **Addresses** field in the **Gateway Status** resource. Using a **LoadBalancer** service sets this field to the IP address and/or hostname of that service. Without a service, the pod IP address is used. - -This gateway is associated with the NGINX Gateway Fabric through the **gatewayClassName** field. The default installation of NGINX Gateway Fabric creates a **GatewayClass** with the name **nginx**. NGINX Gateway Fabric will only configure gateways with a **gatewayClassName** of **nginx** unless you change the name via the `--gatewayclass` [command-line flag]({{< relref "reference/cli-help.md#static-mode">}}). diff --git a/site/content/includes/installation/helm/pulling-the-chart.md b/site/content/includes/installation/helm/pulling-the-chart.md deleted file mode 100644 index 0d0a5071ab..0000000000 --- a/site/content/includes/installation/helm/pulling-the-chart.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -docs: "DOCS-1439" ---- - -Pull the latest stable release of the NGINX Gateway Fabric chart: - - ```shell - helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar - cd nginx-gateway-fabric - ``` - - If you want the latest version from the **main** branch, add `--version 0.0.0-edge` to your pull command. diff --git a/site/content/includes/installation/install-gateway-api-experimental-features.md b/site/content/includes/installation/install-gateway-api-experimental-features.md deleted file mode 100644 index 6d40ecb564..0000000000 --- a/site/content/includes/installation/install-gateway-api-experimental-features.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: "Install NGINX Gateway Fabric with experimental features" -docs: "DOCS-000" ---- - -To use Gateway API experimental resources, the Gateway API resources from the experimental channel must be installed before deploying NGINX Gateway Fabric. Additionally, NGINX Gateway Fabric must have experimental features enabled. - -{{< caution >}}As noted in the [Gateway API documentation](https://gateway-api.sigs.k8s.io/guides/#install-experimental-channel), future releases of the Gateway API can include breaking changes to experimental resources and fields. {{}} - -To install the Gateway API resources from the experimental channel, run the following: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl apply -f - -``` - -{{< note >}}If you plan to use the `edge` version of NGINX Gateway Fabric, you can replace the version in `ref` with `main`, for example `ref=main`. {{}} - -To enable experimental features on NGINX Gateway Fabric: - -Using Helm: Set `nginxGateway.gwAPIExperimentalFeatures.enable` to true. An example can be found -in the [Installation with Helm]({{< relref "installation/installing-ngf/helm.md#custom-installation-options" >}}) guide. - -Using Kubernetes manifests: Add the `--gateway-api-experimental-features` command-line flag to the deployment manifest args. -An example can be found in the [Installation with Kubernetes manifests]({{< relref "installation/installing-ngf/manifests.md#3-deploy-nginx-gateway-fabric" >}}) guide. diff --git a/site/content/includes/installation/install-gateway-api-resources.md b/site/content/includes/installation/install-gateway-api-resources.md deleted file mode 100644 index 0673fabd68..0000000000 --- a/site/content/includes/installation/install-gateway-api-resources.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -docs: "DOCS-1438" ---- - -{{< note >}} The [Gateway API resources](https://github.com/kubernetes-sigs/gateway-api) from the standard channel must be installed before deploying NGINX Gateway Fabric. If they are already installed in your cluster, please ensure they are the correct version as supported by the NGINX Gateway Fabric - [see the Technical Specifications](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.0/README.md#technical-specifications). {{}} - -To install the Gateway API resources, run the following: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.0" | kubectl apply -f - -``` - -{{< note >}}If you plan to use the `edge` version of NGINX Gateway Fabric, you can replace the version in `ref` with `main`, for example `ref=main`.{{}} - -Alternatively, you can install the Gateway API resources from the experimental channel. -Installing Gateway API resources from the experimental channel includes everything in the standard release channel plus additional experimental resources and fields. -NGINX Gateway Fabric currently supports a subset of the additional features provided by the experimental channel. -To install from the experimental channel, run the following: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl apply -f - -``` - -{{< note >}} To learn more about what Gateway API resources NGINX Gateway Fabric currently supports, visit our [Gateway API Compatibility]({{< relref "overview/gateway-api-compatibility.md" >}}) document. {{}} diff --git a/site/content/includes/installation/jwt-password-note.md b/site/content/includes/installation/jwt-password-note.md deleted file mode 100644 index 4cfeec8b92..0000000000 --- a/site/content/includes/installation/jwt-password-note.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -docs: "DOCS-000" ---- - -{{< note >}} For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history: - -1. **JWTs:** JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access. - -1. **Shell history:** Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your `~/.bash_history` file. Alternatively, you can run the `history -c` command to erase your shell history. - -Follow these practices to help ensure the security of your system and data. {{< /note >}} diff --git a/site/content/includes/installation/nginx-plus/docker-registry-secret.md b/site/content/includes/installation/nginx-plus/docker-registry-secret.md deleted file mode 100644 index b909f8f22e..0000000000 --- a/site/content/includes/installation/nginx-plus/docker-registry-secret.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -docs: "DOCS-000" ---- - -{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{}}). {{< /note >}} - -If the `nginx-gateway` namespace does not yet exist, create it: - -```shell -kubectl create namespace nginx-gateway -``` - -Create a Kubernetes `docker-registry` secret type using the contents of the JWT as the username and `none` for password (as the password is not used). The name of the docker server is `private-registry.nginx.com`. - -```shell -kubectl create secret docker-registry nginx-plus-registry-secret --docker-server=private-registry.nginx.com --docker-username= --docker-password=none -n nginx-gateway -``` - -It is important that the `--docker-username=` contains the contents of the token and is not pointing to the token itself. When you copy the contents of the JWT, ensure there are no additional characters such as extra whitespaces. This can invalidate the token, causing 401 errors when trying to authenticate to the registry. diff --git a/site/content/includes/installation/nginx-plus/download-jwt.md b/site/content/includes/installation/nginx-plus/download-jwt.md deleted file mode 100644 index d89c65a43b..0000000000 --- a/site/content/includes/installation/nginx-plus/download-jwt.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -docs: "DOCS-000" ---- - -1. Log in to [MyF5](https://my.f5.com/manage/s/). -2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions. -3. Find your NGINX products or services subscription, and select the **Subscription ID** for details. -4. Download the **JSON Web Token (JWT)** from the subscription page. - -{{< note >}} The Connectivity Stack for Kubernetes JWT does not work with NGINX Plus reporting. A regular NGINX Plus instance JWT must be used. {{< /note >}} diff --git a/site/content/includes/installation/nginx-plus/nginx-plus-secret.md b/site/content/includes/installation/nginx-plus/nginx-plus-secret.md deleted file mode 100644 index 1a5beb4746..0000000000 --- a/site/content/includes/installation/nginx-plus/nginx-plus-secret.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -docs: "DOCS-000" ---- - -Place the JWT in a file called `license.jwt`. Create a Kubernetes Secret using the contents of the JWT file. - -```shell -kubectl create secret generic nplus-license --from-file license.jwt -n nginx-gateway -``` - -You can now delete the `license.jwt` file. - -If you need to update the JWT at any time, update the `license.jwt` field in the Secret using `kubectl edit` and apply the changes. diff --git a/site/content/includes/installation/uninstall-gateway-api-resources.md b/site/content/includes/installation/uninstall-gateway-api-resources.md deleted file mode 100644 index 180b3601fb..0000000000 --- a/site/content/includes/installation/uninstall-gateway-api-resources.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -docs: "DOCS-1436" ---- - -{{}}This will remove all corresponding custom resources in your entire cluster, across all namespaces. Double-check to make sure you don't have any custom resources you need to keep, and confirm that there are no other Gateway API implementations active in your cluster.{{}} - -To uninstall the Gateway API resources, run the following: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.0" | kubectl delete -f - -``` - -Alternatively, if you installed the Gateway APIs from the experimental channel, run the following: - -```shell -kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl delete -f - -``` diff --git a/site/content/installation/_index.md b/site/content/installation/_index.md deleted file mode 100644 index 0761ac2cd2..0000000000 --- a/site/content/installation/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Installation" -weight: 300 ---- diff --git a/site/content/installation/building-the-images.md b/site/content/installation/building-the-images.md deleted file mode 100644 index 070cb12391..0000000000 --- a/site/content/installation/building-the-images.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "Build NGINX Gateway Fabric and NGINX images" -weight: 500 -toc: true -docs: "DOCS-1431" ---- - -## Overview - -While most users will install NGINX Gateway Fabric [with Helm]({{< relref "/installation/installing-ngf/helm.md" >}}) or [Kubernetes manifests]({{< relref "/installation/installing-ngf/manifests.md" >}}), manually building the [NGINX Gateway Fabric and NGINX images]({{< relref "/overview/gateway-architecture.md#the-nginx-gateway-fabric-pod" >}}) can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images. - -## Prerequisites - -Before you can build the NGINX Gateway Fabric and NGINX images, make sure you have the following software -installed on your machine: - -- [git](https://git-scm.com/) -- [GNU Make](https://www.gnu.org/software/software.html) -- [Docker](https://www.docker.com/) v18.09+ -- [Go](https://go.dev/doc/install) v1.20 - -If building the NGINX Plus image, you will also need a valid NGINX Plus license certificate (`nginx-repo.crt`) and key (`nginx-repo.key`) in the root of the repo. - -## Steps - -1. Clone the repo and change into the `nginx-gateway-fabric` directory: - - ```shell - git clone https://github.com/nginx/nginx-gateway-fabric.git --branch v1.6.0 - cd nginx-gateway-fabric - ``` - -1. Build the images: - - To build both the NGINX Gateway Fabric and NGINX images: - - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images - ``` - - - To build both the NGINX Gateway Fabric and NGINX Plus images: - - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-images-with-plus - ``` - - - To build just the NGINX Gateway Fabric image: - - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-ngf-image - ``` - - - To build just the NGINX image: - - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric build-prod-nginx-image - ``` - - - To build just the NGINX Plus image: - - ```makefile - make PREFIX=myregistry.example.com/nginx-gateway-fabric/nginx-plus build-prod-nginx-plus-image - ``` - - Set the `PREFIX` variable to the name of the registry you'd like to push the image to. By default, the images will be - named `nginx-gateway-fabric:1.6.0` and `nginx-gateway-fabric/nginx:1.6.0` or `nginx-gateway-fabric/nginx-plus:1.6.0`. - -1. Push the images to your container registry: - - ```shell - docker push myregistry.example.com/nginx-gateway-fabric:1.6.0 - docker push myregistry.example.com/nginx-gateway-fabric/nginx:1.6.0 - ``` - - or - - ```shell - docker push myregistry.example.com/nginx-gateway-fabric:1.6.0 - docker push myregistry.example.com/nginx-gateway-fabric/nginx-plus:1.6.0 - ``` - - Make sure to substitute `myregistry.example.com/nginx-gateway-fabric` with your registry. diff --git a/site/content/installation/installing-ngf/_index.md b/site/content/installation/installing-ngf/_index.md deleted file mode 100644 index 401f982246..0000000000 --- a/site/content/installation/installing-ngf/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Install NGINX Gateway Fabric" -description: -weight: 100 -linkTitle: "Install NGINX Gateway Fabric" -menu: - docs: - parent: Installation ---- diff --git a/site/content/installation/installing-ngf/helm.md b/site/content/installation/installing-ngf/helm.md deleted file mode 100644 index a9a39f8ab2..0000000000 --- a/site/content/installation/installing-ngf/helm.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: "Installation with Helm" -weight: 100 -toc: true -docs: "DOCS-1430" ---- - -## Overview - -Learn how to install, upgrade, and uninstall NGINX Gateway Fabric in a Kubernetes cluster using Helm. - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=` when running `helm upgrade`. {{< /important >}} - -## Before you begin - -To complete this guide, you'll need to install: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line tool for managing Kubernetes clusters. -- [Helm 3.0 or later](https://helm.sh/docs/intro/install/), for deploying and managing applications on Kubernetes. - -{{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} -
-NGINX Plus JWT setup - -{{}} - -### 1. Download the JWT from MyF5 - -{{}} - -### 2. Create the Docker Registry Secret - -{{}} - -### 3. Create the NGINX Plus Secret - -{{}} - -{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< relref "installation/nginx-plus-jwt.md" >}}) document. {{< /note >}} - -
- -## Deploy NGINX Gateway Fabric - -### Installing the Gateway API resources - -{{}} - -### Install from the OCI registry - -The following steps install NGINX Gateway Fabric directly from the OCI helm registry. If you prefer, you can [install from sources](#install-from-sources) instead. - -{{}} - -{{%tab name="NGINX"%}} - -To install the latest stable release of NGINX Gateway Fabric in the **nginx-gateway** namespace, run the following command: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway -``` - -{{% /tab %}} - -{{%tab name="NGINX Plus"%}} - -{{< note >}} If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry for your NGINX Plus image, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default `nplus-license`, then define that name using the `nginx.usage.secretName` flag. {{< /note >}} - -To install the latest stable release of NGINX Gateway Fabric in the **nginx-gateway** namespace, run the following command: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set serviceAccount.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway -``` - -{{% /tab %}} - -{{}} - -`ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. - -If you want the latest version from the **main** branch, add `--version 0.0.0-edge` to your install command. - -To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run the following after installing: - -```shell -kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available -``` - -### Install from sources {#install-from-sources} - -If you prefer to install directly from sources, instead of through the OCI helm registry, use the following steps. - -{{}} - -{{}} - -{{%tab name="NGINX"%}} - -To install the chart into the **nginx-gateway** namespace, run the following command: - -```shell -helm install ngf . --create-namespace -n nginx-gateway -``` - -{{% /tab %}} - -{{%tab name="NGINX Plus"%}} - -{{< note >}} If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry for your NGINX Plus image, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials. If your NGINX Plus JWT Secret has a different name than the default `nplus-license`, then define that name using the `nginx.usage.secretName` flag. {{< /note >}} - -To install the chart into the **nginx-gateway** namespace, run the following command: - -```shell -helm install ngf . --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set serviceAccount.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway -``` - -{{% /tab %}} - -{{}} - - `ngf` is the name of the release, and can be changed to any name you want. This name is added as a prefix to the Deployment name. - - To wait for the Deployment to be ready, you can either add the `--wait` flag to the `helm install` command, or run the following after installing: - - ```shell - kubectl wait --timeout=5m -n nginx-gateway deployment/ngf-nginx-gateway-fabric --for=condition=Available - ``` - -### Custom installation options - -#### Service type - -By default, the NGINX Gateway Fabric helm chart deploys a LoadBalancer Service. - -To use a NodePort Service instead: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.type=NodePort -``` - -To disable the creation of a Service: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set service.create=false -``` - -#### Experimental features - -We support a subset of the additional features provided by the Gateway API experimental channel. To enable the -experimental features of Gateway API which are supported by NGINX Gateway Fabric: - -```shell -helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --create-namespace -n nginx-gateway --set nginxGateway.gwAPIExperimentalFeatures.enable=true -``` - -{{}}Requires the Gateway APIs installed from the experimental channel.{{}} - -#### Examples - -You can find several examples of configuration options of the `values.yaml` file in the [helm examples](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.0/examples/helm) directory. - -### Access NGINX Gateway Fabric - -{{}} - -## Upgrade NGINX Gateway Fabric - -{{}}For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below.{{}} - -To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps: - -### Upgrade Gateway resources - -To upgrade your Gateway API resources, take the following steps: - -- Verify the Gateway API resources are compatible with your NGINX Gateway Fabric version. Refer to the [Technical Specifications]({{< relref "reference/technical-specifications.md" >}}) for details. -- Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information. -- To upgrade the Gateway API resources, run: - - ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.0" | kubectl apply -f - - ``` - - or, if you installed the from the experimental channel: - - ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl apply -f - - ``` - -### Upgrade NGINX Gateway Fabric CRDs - -Helm's upgrade process does not automatically upgrade the NGINX Gateway Fabric CRDs (Custom Resource Definitions). - -To upgrade the CRDs, take the following steps: - -1. {{}} - -2. Upgrade the CRDs: - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/crds.yaml - ``` - - {{}}Ignore the following warning, as it is expected.{{}} - - ```text - Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply. - ``` - -### Upgrade NGINX Gateway Fabric release - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret. If you use a different name than the default `nplus-license` name, specify the Secret name by setting `--set nginx.usage.secretName=` when running `helm upgrade`. {{}} - -There are two possible ways to upgrade NGINX Gateway Fabric. You can either upgrade from the OCI registry, or download the chart and upgrade from the source. - -#### Upgrade from the OCI registry - -- To upgrade to the latest stable release of NGINX Gateway Fabric, run: - - ```shell - helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric -n nginx-gateway - ``` - - If needed, replace `ngf` with your chosen release name. - -#### Upgrade from sources - -1. {{}} - -1. To upgrade, run: the following command: - - ```shell - helm upgrade ngf . -n nginx-gateway - ``` - - If needed, replace `ngf` with your chosen release name. - -## How to upgrade from NGINX OSS to NGINX Plus - -- To upgrade from NGINX OSS to NGINX Plus, update the Helm command to include the necessary values for Plus: - - {{< note >}}If applicable, replace the F5 Container registry `private-registry.nginx.com` with your internal registry for your NGINX Plus image, and replace `nginx-plus-registry-secret` with your Secret name containing the registry credentials.{{< /note >}} - - {{< important >}}Ensure that you [Create the required JWT Secrets]({{< relref "installation/nginx-plus-jwt.md" >}}) before installing.{{< /important >}} - - ```shell - helm upgrade ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus --set nginx.plus=true --set serviceAccount.imagePullSecret=nginx-plus-registry-secret -n nginx-gateway - ``` - - If needed, replace `ngf` with your chosen release name. - -## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} - -{{< include "installation/delay-pod-termination/delay-pod-termination-overview.md" >}} - -Follow these steps to configure delayed pod termination: - -1. Open the `values.yaml` for editing. - -1. **Add delayed shutdown hooks**: - - - In the `values.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment. - - ```yaml - nginxGateway: - <...> - lifecycle: - preStop: - exec: - command: - - /usr/bin/gateway - - sleep - - --duration=40s # This flag is optional, the default is 30s - - nginx: - <...> - lifecycle: - preStop: - exec: - command: - - /bin/sleep - - "40" - ``` - -1. **Set the termination grace period**: - - - {{}} - -1. Save the changes. - -{{}} -For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation: - -- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) -- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination) - -{{}} - -## Uninstall NGINX Gateway Fabric - -Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster: - -1. **Uninstall NGINX Gateway Fabric:** - - - To uninstall NGINX Gateway Fabric, run: - - ```shell - helm uninstall ngf -n nginx-gateway - ``` - - If needed, replace `ngf` with your chosen release name. - -2. **Remove namespace and CRDs:** - - - To remove the **nginx-gateway** namespace and its custom resource definitions (CRDs), run: - - ```shell - kubectl delete ns nginx-gateway - kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/crds.yaml - ``` - -3. **Remove the Gateway API resources:** - - - {{}} - -## Additional configuration - -For a full list of the Helm Chart configuration parameters, read [the NGINX Gateway Fabric Helm Chart](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.0/charts/nginx-gateway-fabric/README.md#configuration). diff --git a/site/content/installation/installing-ngf/manifests.md b/site/content/installation/installing-ngf/manifests.md deleted file mode 100644 index f1af32f8ab..0000000000 --- a/site/content/installation/installing-ngf/manifests.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: "Installation with Kubernetes manifests" -weight: 200 -toc: true -docs: "DOCS-1429" ---- - -## Overview - -Learn how to install, upgrade, and uninstall NGINX Gateway Fabric using Kubernetes manifests. - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret, which is referenced in the updated deployment manifest for the newest version. {{< /important >}} - -## Before you begin - -To complete this guide, you'll need to install: - -- [kubectl](https://kubernetes.io/docs/tasks/tools/), a command-line interface for managing Kubernetes clusters. - -{{< important >}} If you’d like to use NGINX Plus, some additional setup is also required: {{}} -
-NGINX Plus JWT setup - -{{}} - -### 1. Download the JWT from MyF5 - -{{}} - -### 2. Create the Docker Registry Secret - -{{}} - -### 3. Create the NGINX Plus Secret - -{{}} - -{{< note >}} For more information on why this is needed and additional configuration options, including how to report to NGINX Instance Manager instead, see the [NGINX Plus Image and JWT Requirement]({{< relref "installation/nginx-plus-jwt.md" >}}) document. {{< /note >}} - -
- -## Deploy NGINX Gateway Fabric - -Deploying NGINX Gateway Fabric with Kubernetes manifests takes only a few steps. With manifests, you can configure your deployment exactly how you want. Manifests also make it easy to replicate deployments across environments or clusters, ensuring consistency. - -### 1. Install the Gateway API resources - -{{}} - -### 2. Deploy the NGINX Gateway Fabric CRDs - -#### Stable release - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/crds.yaml -``` - -#### Edge version - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/main/deploy/crds.yaml -``` - -### 3. Deploy NGINX Gateway Fabric - -{{< note >}} By default, NGINX Gateway Fabric is installed in the **nginx-gateway** namespace. You can deploy in another namespace by modifying the manifest files. {{< /note >}} - -{{}} - -{{%tab name="Default"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/default/deploy.yaml -``` - -{{% /tab %}} - -{{%tab name="AWS NLB"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS and an AWS Network Load Balancer service. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/aws-nlb/deploy.yaml -``` - -{{% /tab %}} - -{{%tab name="Azure"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS and `nodeSelector` to deploy on Linux nodes. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/azure/deploy.yaml -``` - -{{% /tab %}} - -{{%tab name="NGINX Plus"%}} - -Deploys NGINX Gateway Fabric with NGINX Plus. The image is pulled from the -NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Secret to use to pull the image. -The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/nginx-plus/deploy.yaml -``` - -{{% /tab %}} - -{{%tab name="Experimental"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS and experimental features. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/experimental/deploy.yaml -``` - -{{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}} - -{{% /tab %}} - -{{%tab name="NGINX Plus Experimental"%}} - -Deploys NGINX Gateway Fabric with NGINX Plus and experimental features. The image is pulled from the -NGINX Plus Docker registry, and the `imagePullSecretName` is the name of the Secret to use to pull the image. -The NGINX Plus JWT Secret used to run NGINX Plus is also specified in a volume mount and the `--usage-report-secret` parameter. These Secrets are created as part of the [Before you begin](#before-you-begin) section. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/nginx-plus-experimental/deploy.yaml -``` - -{{< note >}} Requires the Gateway APIs installed from the experimental channel. {{< /note >}} - -{{% /tab %}} - -{{%tab name="NodePort"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS using a Service type of `NodePort`. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/nodeport/deploy.yaml -``` - -{{% /tab %}} - -{{%tab name="OpenShift"%}} - -Deploys NGINX Gateway Fabric with NGINX OSS on OpenShift. - -```shell -kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/openshift/deploy.yaml -``` - -{{% /tab %}} - -{{}} - -### 4. Verify the Deployment - -To confirm that NGINX Gateway Fabric is running, check the pods in the `nginx-gateway` namespace: - -```shell -kubectl get pods -n nginx-gateway -``` - -The output should look similar to this (note that the pod name will include a unique string): - -```text -NAME READY STATUS RESTARTS AGE -nginx-gateway-5d4f4c7db7-xk2kq 2/2 Running 0 112s -``` - -### 5. Access NGINX Gateway Fabric - -{{}} - -## Upgrade NGINX Gateway Fabric - -{{< important >}} NGINX Plus users that are upgrading from version 1.4.0 to 1.5.x need to install an NGINX Plus JWT -Secret before upgrading. Follow the steps in the [Before you begin](#before-you-begin) section to create the Secret, which is referenced in the updated deployment manifest for the newest version. {{< /important >}} - -{{}}For guidance on zero downtime upgrades, see the [Delay Pod Termination](#configure-delayed-pod-termination-for-zero-downtime-upgrades) section below.{{}} - -To upgrade NGINX Gateway Fabric and get the latest features and improvements, take the following steps: - -1. **Upgrade Gateway API resources:** - - - Verify that your NGINX Gateway Fabric version is compatible with the Gateway API resources. Refer to the [Technical Specifications]({{< relref "reference/technical-specifications.md" >}}) for details. - - Review the [release notes](https://github.com/kubernetes-sigs/gateway-api/releases) for any important upgrade-specific information. - - To upgrade the Gateway API resources, run: - - ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v1.6.0" | kubectl apply -f - - ``` - - or, if you installed the from the experimental channel: - - ```shell - kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/experimental?ref=v1.6.0" | kubectl apply -f - - ``` - -1. **Upgrade NGINX Gateway Fabric CRDs:** - - - To upgrade the Custom Resource Definitions (CRDs), run: - - ```shell - kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/crds.yaml - ``` - -1. **Upgrade NGINX Gateway Fabric deployment:** - - Select the deployment manifest that matches your current deployment from the table above in the [Deploy NGINX Gateway Fabric](#3-deploy-nginx-gateway-fabric) section and apply it. - -## Delay pod termination for zero downtime upgrades {#configure-delayed-pod-termination-for-zero-downtime-upgrades} - -{{< include "installation/delay-pod-termination/delay-pod-termination-overview.md" >}} - -Follow these steps to configure delayed pod termination: - -1. Open the `deploy.yaml` for editing. - -1. **Add delayed shutdown hooks**: - - - In the `deploy.yaml` file, add `lifecycle: preStop` hooks to both the `nginx` and `nginx-gateway` container definitions. These hooks instruct the containers to delay their shutdown process, allowing time for connections to close gracefully. Update the `sleep` value to what works for your environment. - - ```yaml - <...> - name: nginx-gateway - <...> - lifecycle: - preStop: - exec: - command: - - /usr/bin/gateway - - sleep - - --duration=40s # This flag is optional, the default is 30s - <...> - name: nginx - <...> - lifecycle: - preStop: - exec: - command: - - /bin/sleep - - "40" - <...> - ``` - -1. **Set the termination grace period**: - - - {{}} - -1. Save the changes. - -{{}} -For additional information on configuring and understanding the behavior of containers and pods during their lifecycle, refer to the following Kubernetes documentation: - -- [Container Lifecycle Hooks](https://kubernetes.io/docs/concepts/containers/container-lifecycle-hooks/#container-hooks) -- [Pod Lifecycle](https://kubernetes.io/docs/concepts/workloads/Pods/Pod-lifecycle/#Pod-termination) - -{{}} - -## Uninstall NGINX Gateway Fabric - -Follow these steps to uninstall NGINX Gateway Fabric and Gateway API from your Kubernetes cluster: - -1. **Uninstall NGINX Gateway Fabric:** - - - To remove NGINX Gateway Fabric and its custom resource definitions (CRDs), run: - - ```shell - kubectl delete namespace nginx-gateway - kubectl delete cluterrole nginx-gateway - kubectl delete clusterrolebinding nginx-gateway - ``` - - ```shell - kubectl delete -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v1.6.0/deploy/crds.yaml - ``` - -1. **Remove the Gateway API resources:** - - - {{}} diff --git a/site/content/installation/nginx-plus-jwt.md b/site/content/installation/nginx-plus-jwt.md deleted file mode 100644 index e516e7098b..0000000000 --- a/site/content/installation/nginx-plus-jwt.md +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: "NGINX Plus Image and JWT Requirement" -weight: 300 -toc: true -docs: "DOCS-000" ---- - -## Overview - -NGINX Gateway Fabric with NGINX Plus requires a valid JSON Web Token (JWT) to download the container image from the F5 registry. From version 1.5.0, this JWT token is also required to run NGINX Plus. - -This requirement is part of F5’s broader licensing program and aligns with industry best practices. The JWT will streamline subscription renewals and usage reporting, helping you manage your NGINX Plus subscription more efficiently. The [telemetry](#telemetry) data we collect helps us improve our products and services to better meet your needs. - -The JWT is required for validating your subscription and reporting telemetry data. For environments connected to the internet, telemetry is automatically sent to F5’s licensing endpoint. In offline environments, telemetry is routed through [NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/). Usage is reported every hour and on startup whenever NGINX is reloaded. - -## Set up the JWT - -The JWT needs to be configured before deploying NGINX Gateway Fabric. The JWT will be stored in two Kubernetes Secrets: one for downloading the NGINX Plus container image, and the other for running NGINX Plus. - -{{< include "installation/jwt-password-note.md" >}} - -### Download the JWT from MyF5 - -{{< include "installation/nginx-plus/download-jwt.md" >}} - -### Docker Registry Secret - -{{< include "installation/nginx-plus/docker-registry-secret.md" >}} - -Provide the name of this Secret when installing NGINX Gateway Fabric: - -{{}} - -{{%tab name="Helm"%}} - -Specify the Secret name using the `serviceAccount.imagePullSecret` or `serviceAccount.imagePullSecrets` helm value. - -{{% /tab %}} - -{{%tab name="Manifests"%}} - -Specify the Secret name in the `imagePullSecrets` field of the `nginx-gateway` ServiceAccount. - -{{% /tab %}} - -{{}} - -### NGINX Plus Secret - -{{< include "installation/nginx-plus/nginx-plus-secret.md" >}} - -If using a name other than the default `nplus-license`, provide the name of this Secret when installing NGINX Gateway Fabric: - -{{}} - -{{%tab name="Helm"%}} - -Specify the Secret name using the `nginx.usage.secretName` helm value. - -{{% /tab %}} - -{{%tab name="Manifests"%}} - -Specify the Secret name in the `--usage-report-secret` command-line flag on the `nginx-gateway` container. - -You also need to define the proper volume mount to mount the Secret to the nginx container. If it doesn't already exist, add the following volume to the Deployment: - -```yaml -- name: nginx-plus-license - secret: - secretName: nplus-license -``` - -and the following volume mount to the `nginx` container: - -```yaml -- mountPath: /etc/nginx/license.jwt - name: nginx-plus-license - subPath: license.jwt -``` - -{{% /tab %}} - -{{}} - -**If you are reporting to the default licensing endpoint, then you can now proceed with [installing NGINX Gateway Fabric]({{< relref "installation/installing-ngf" >}}). Otherwise, follow the steps below to configure reporting to NGINX Instance Manager.** - -### Reporting to NGINX Instance Manager {#nim} - -If you are deploying NGINX Gateway Fabric in an environment where you need to report to NGINX Instance Manager instead of the default licensing endpoint, a few extra steps may be required. - -First, you must specify the endpoint of your NGINX Instance Manager: - -{{}} - -{{%tab name="Helm"%}} - -Specify the endpoint using the `nginx.usage.endpoint` helm value. - -{{% /tab %}} - -{{%tab name="Manifests"%}} - -Specify the endpoint in the `--usage-report-endpoint` command-line flag on the `nginx-gateway` container. You also need to add the following line to the `mgmt` block of the `nginx-includes-bootstrap` ConfigMap: - -```text -usage_report endpoint=; -``` - -{{% /tab %}} - -{{}} - -#### CA and Client certificate/key {#nim-cert} - -To configure a CA cert and/or client certificate and key, a few extra steps are needed. - -First, you need to create two Secrets in the `nginx-gateway` namespace. The CA must live under the key `ca.crt`: - -```shell -kubectl -n nginx-gateway create secret generic nim-ca --from-file ca.crt -``` - -The client cert and key must be added to a TLS Secret: - -```shell -kubectl -n nginx-gateway create secret tls nim-client --cert /path/to/cert --key /path/to/key -``` - -{{}} - -{{%tab name="Helm"%}} - -Specify the CA Secret name using the `nginx.usage.caSecretName` helm value. Specify the client Secret name using the `nginx.usage.clientSSLSecretName` helm value. - -{{% /tab %}} - -{{%tab name="Manifests"%}} - -Specify the CA Secret name in the `--usage-report-ca-secret` command-line flag on the `nginx-gateway` container. Specify the client Secret name in the `--usage-report-client-ssl-secret` command-line flag on the `nginx-gateway` container. - -You also need to define the proper volume mount to mount the Secrets to the nginx container. Add the following volume to the Deployment: - -```yaml -- name: nginx-plus-usage-certs - projected: - sources: - - secret: - name: nim-ca - - secret: - name: nim-client -``` - -and the following volume mounts to the `nginx` container: - -```yaml -- mountPath: /etc/nginx/certs-bootstrap/ - name: nginx-plus-usage-certs -``` - -Finally, in the `nginx-includes-bootstrap` ConfigMap, add the following lines to the `mgmt` block: - -```text -ssl_trusted_certificate /etc/nginx/certs-bootstrap/ca.crt; -ssl_certificate /etc/nginx/certs-bootstrap/tls.crt; -ssl_certificate_key /etc/nginx/certs-bootstrap/tls.key; -``` - -{{% /tab %}} - -{{}} - -
- -**Once these Secrets are created and configuration options are set, you can now [install NGINX Gateway Fabric]({{< relref "installation/installing-ngf" >}}).** - -## Installation flags to configure usage reporting {#flags} - -When installing NGINX Gateway Fabric, the following flags can be specified to configure usage reporting to fit your needs: - -If using Helm, the `nginx.usage` values should be set as necessary: - -- `secretName` should be the name of the JWT Secret you created. By default this field is set to `nplus-license`. This field is required. -- `endpoint` is the endpoint to send the telemetry data to. This is optional, and by default is `product.connect.nginx.com`. -- `resolver` is the nameserver used to resolve the NGINX Plus usage reporting endpoint. This is optional and used with NGINX Instance Manager. -- `skipVerify` disables client verification of the NGINX Plus usage reporting server certificate. -- `caSecretName` is 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). -- `clientSSLSecretName` is 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). - -If using manifests, the following command-line options should be set as necessary on the `nginx-gateway` container: - -- `--usage-report-secret` should be the name of the JWT Secret you created. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). By default this field is set to `nplus-license`. A [volume mount](#nginx-plus-secret) for this Secret is required for installation. -- `--usage-report-endpoint` is the endpoint to send the telemetry data to. This is optional, and by default is `product.connect.nginx.com`. Requires [extra configuration](#nim) if specified. -- `--usage-report-resolver` is the nameserver used to resolve the NGINX Plus usage reporting endpoint. This is optional and used with NGINX Instance Manager. -- `--usage-report-skip-verify` disables client verification of the NGINX Plus usage reporting server certificate. -- `--usage-report-ca-secret` is 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). Requires [extra configuration](#nim-cert) if specified. -- `--usage-report-client-ssl-secret` is 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). Requires [extra configuration](#nim-cert) if specified. - -## What’s reported and how it’s protected {#telemetry} - -NGINX Plus reports the following data every hour by default: - -- **NGINX version and status**: The version of NGINX Plus running on the instance. -- **Instance UUID**: A unique identifier for each NGINX Plus instance. -- **Traffic data**: - - **Bytes received from and sent to clients**: HTTP and stream traffic volume between clients and NGINX Plus. - - **Bytes received from and sent to upstreams**: HTTP and stream traffic volume between NGINX Plus and upstream servers. - - **Client connections**: The number of accepted client connections (HTTP and stream traffic). - - **Requests handled**: The total number of HTTP requests processed. -- **NGINX uptime**: The number of reloads and worker connections during uptime. -- **Usage report timestamps**: Start and end times for each usage report. -- **Kubernetes node details**: Information about Kubernetes nodes. - -### Security and privacy of reported data - -All communication between your NGINX Plus instances, NGINX Instance Manager, and F5’s licensing endpoint (`product.connect.nginx.com`) is protected using **SSL/TLS** encryption. - -Only **operational metrics** are reported — no **personally identifiable information (PII)** or **sensitive customer data** is transmitted. - -## Pull an image for local use - -To pull an image for local use, use this command: - -```shell -docker login private-registry.nginx.com --username= --password=none -``` - -Replace the contents of `` with the contents of the JWT token itself. - -You can then pull the image: - -```shell -docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:1.6.0 -``` - -Once you have successfully pulled the image, you can tag it as needed, then push it to a different container registry. - -## Alternative installation options - -There are alternative ways to get an NGINX Plus image for NGINX Gateway Fabric: - -- [Build the Gateway Fabric image]({{}}) describes how to use the source code with an NGINX Plus subscription certificate and key to build an image. diff --git a/site/content/overview/_index.md b/site/content/overview/_index.md deleted file mode 100644 index fb6a7d7d89..0000000000 --- a/site/content/overview/_index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Overview" -description: -weight: 100 -linkTitle: "Overview" -menu: - docs: - parent: NGINX Gateway Fabric ---- diff --git a/site/content/overview/custom-policies.md b/site/content/overview/custom-policies.md deleted file mode 100644 index 29c552f4a0..0000000000 --- a/site/content/overview/custom-policies.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "Custom policies" -weight: 300 -toc: true -docs: "DOCS-000" ---- - -## Overview - -Custom policies are NGINX Gateway Fabric CRDs (Custom Resource Definitions) that allow users to configure NGINX data plane features that are unavailable in the Gateway API. -These custom policies follow the Gateway API [Policy Attachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) pattern, which allows users to extend the Gateway API functionality by creating implementation-specific policies and attaching them to Kubernetes objects such as HTTPRoutes, Gateways, and Services. - -Policies are a Kubernetes object that augments the behavior of an object in a standard way. Policies can be attached to one object ([Direct Policy Attachment](#direct-policy-attachment)) or objects in a hierarchy ([Inherited Policy Attachment](#inherited-policy-attachment)). -The following table summarizes NGINX Gateway Fabric custom policies: - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Policy | Description | Attachment Type | Supported Target Object(s) | Supports Multiple Target Refs | Mergeable | API Version | -|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|-----------------|-------------------------------|-------------------------------|-----------|-------------| -| [ClientSettingsPolicy]({{}}) | Configure connection behavior between client and NGINX | Inherited | Gateway, HTTPRoute, GRPCRoute | No | Yes | v1alpha1 | -| [ObservabilityPolicy]({{}}) | Define settings related to tracing, metrics, or logging | Direct | HTTPRoute, GRPCRoute | Yes | No | v1alpha2 | -| [UpstreamSettingsPolicy]({{}}) | Configure connection behavior between NGINX and upstream applications | Direct | Service | Yes | Yes | v1alpha1 | - -{{}} - -{{< important >}} -If attaching a Policy to a Route, that Route must not share a hostname:port/path combination with any other Route that is not referenced by the same Policy. If it does, the Policy will be rejected. This is because the Policy would end up affecting other Routes that it is not attached to. -{{< /important >}} - -## Terminology - -- _Attachment Type_. How the policy attaches to an object. Attachment type can be "direct" or "inherited". -- _Supported Target Object(s)_. API objects the policy can be applied to. -- _Supports Multiple Target Refs_. Whether a single policy can target multiple objects. -- _Mergeable_. Whether policies that target the same object can be merged. - -## Direct Policy Attachment - -A Direct Policy Attachment is a policy that references a single object, such as a Gateway or HTTPRoute. It is tightly bound to one instance of a particular Kind within a single Namespace or an instance of a single Kind at the cluster-scope. It affects _only_ the object specified in its TargetRef. - -This diagram uses a fictional retry policy to show how Direct Policy Attachment works: - -{{}} - -The policy targets the HTTPRoute `baz` and sets `retries` to `3` and `timeout` to `60s`. Since this policy is a Direct Policy Attachment, its settings are only applied to the `baz` HTTPRoute. - -## Inherited Policy Attachment - -Inherited Policy Attachment allows settings to cascade down a hierarchy. The hierarchy for Gateway API resources looks like this: - -{{}} - -Settings defined in a policy attached to an object in this hierarchy may be inherited by the resources below it. For example, the settings defined in a policy attached to a Gateway may be inherited by all the HTTPRoutes attached to that Gateway. - -Settings in an Inherited Policy can be Defaults or Overrides. Defaults set the default value for something and can be overridden by policies on a lower object. Overrides cannot be overridden by lower objects. -All settings in NGINX Gateway Fabric Inherited Policies are Defaults. - -Default values are given precedence from the bottom up. Therefore, a policy setting attached to a Backend will have the highest precedence over the one attached to higher objects. - -The following diagram shows how Inherited Policies work in NGINX Gateway Fabric using a fictional retry policy: - -{{}} - -There are three policies defined: - -- `dev-policy` that targets the `dev` Gateway -- `baz-policy` that targets the `baz` HTTPRoute -- `foo-policy` that targets the `foo` HTTPRoute - -The settings in `dev-policy` affect the `dev` Gateway and are inherited by all the HTTPRoutes attached to `dev`. -The `baz-policy` and `foo-policy` are attached to the `baz` and `foo` HTTPRoutes. Since HTTPRoutes are lower than Gateways in the hierarchy, the settings defined in them override those in the `dev` policy. -Since the `foo-policy` only defines the `retries` setting, it still inherits the `timeout` setting from `dev-policy`. -The `bar` HTTPRoute has no policy attached to it and inherits all the settings from `dev-policy`. - -## Merging Policies - -With some NGINX Gateway Fabric Policies, it is possible to create multiple policies that target the same resource as long as the fields in those policies do not conflict. - -For example, consider the following fictional policies: - -```yaml -apiVersion: gateway.nginx.org/v1alpha1 -kind: ExamplePolicy -metadata: - name: retries -spec: - targetRef: - group: gateway.networking.k8s.io - kind: HTTPRoute - name: foo - retries: 10 -``` - - -```yaml -apiVersion: gateway.nginx.org/v1alpha1 -kind: ExamplePolicy -metadata: - name: timeout -spec: - targetRef: - kind: HTTPRoute - name: foo - timeout: 60s -``` - -The `retries` ExamplePolicy defines the number of retries for the `foo` HTTPRoute, and the `timeout` ExamplePolicy defines the timeout for the `foo` HTTPRoute. -NGINX Gateway Fabric will merge the fields defined in the policies and apply the following settings to the `foo` HTTPRoute: - -```yaml -retries: 10 -timeout: 60s -``` - -However, if both policies had the `retries` field set, then the policies cannot be merged. In this case, NGINX Gateway Fabric will choose which policy to configure based on the following criteria (continuing on ties): - -1. The oldest policy by creation timestamp -1. The policy appearing first in alphabetical order by "{namespace}/{name}" - -If a policy conflicts with a configured policy, NGINX Gateway Fabric will set the policy `Accepted` status to false with a reason of `Conflicted`. See [Policy Status](#policy-status) for more details. - -## Policy Status - -NGINX Gateway Fabric sets the [PolicyStatus](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1alpha2.PolicyStatus) on all policies. - -`PolicyStatus` fields: - -- `ancestors`: describes the status of a route with respect to the ancestor. - - `ancestorRef`: the object that the policy targets in `spec.targetRef`. - - `controllerName`: the controller name of NGINX Gateway Fabric. - - `conditions`: (Condition/Status/Reason): - - `Accepted/True/Accepted`: the policy is accepted by the ancestor. - - `Accepted/False/Invalid`: the policy is not accepted because it is semantically or syntactically invalid. - - `Accepted/False/Conflicted`: the policy is not accepted because it conflicts with another policy. - - `Accepted/False/TargetNotFound`: the policy is not accepted because it targets a resource that is invalid or does not exist. - - `Accepted/False/NginxProxyNotSet`: the policy is not accepted because it relies on the NginxProxy configuration which is missing or invalid. - -To check the status of a policy, use `kubectl describe`. This example checks the status of the `foo` ObservabilityPolicy, which is accepted: - -```shell -kubectl describe observabilitypolicies.gateway.nginx.org foo -n default -``` - -```text -Status: - Ancestors: - Ancestor Ref: - Group: gateway.networking.k8s.io - Kind: HTTPRoute - Name: foo - Namespace: default - Conditions: - Last Transition Time: 2024-05-23T18:13:03Z - Message: Policy is accepted - Observed Generation: 1 - Reason: Accepted - Status: True - Type: Accepted - Controller Name: gateway.nginx.org/nginx-gateway-controller -``` diff --git a/site/content/overview/gateway-api-compatibility.md b/site/content/overview/gateway-api-compatibility.md deleted file mode 100644 index 7573597983..0000000000 --- a/site/content/overview/gateway-api-compatibility.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -title: "Gateway API Compatibility" -weight: 200 -toc: true -docs: "DOCS-1412" ---- - -Learn which Gateway API resources NGINX Gateway Fabric supports and to which level. - -## Summary - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|---------------------------------------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| [GatewayClass](#gatewayclass) | Supported | Not supported | Supported | v1 | Standard | -| [Gateway](#gateway) | Supported | Partially supported | Not supported | v1 | Standard | -| [HTTPRoute](#httproute) | Supported | Partially supported | Not supported | v1 | Standard | -| [GRPCRoute](#grpcroute) | Supported | Partially supported | Not supported | v1 | Standard | -| [ReferenceGrant](#referencegrant) | Supported | N/A | Not supported | v1beta1 | Standard | -| [TLSRoute](#tlsroute) | Supported | Not supported | Not supported | v1alpha2 | Experimental | -| [TCPRoute](#tcproute) | Not supported | Not supported | Not supported | v1alpha2 | Experimental | -| [UDPRoute](#udproute) | Not supported | Not supported | Not supported | v1alpha2 | Experimental | -| [BackendTLSPolicy](#backendtlspolicy) | Supported | Supported | Not supported | v1alpha3 | Experimental | -| [Custom policies](#custom-policies) | N/A | N/A | Supported | N/A | N/A | - -{{< /bootstrap-table >}} - ---- - -## Terminology - -Gateway API features has three [support levels](https://gateway-api.sigs.k8s.io/concepts/conformance/#2-support-levels): Core, Extended and Implementation-specific. We use the following terms to describe the support status for each level and resource field: - -- _Supported_. The resource or field is fully supported. -- _Partially supported_. The resource or field is supported partially, with limitations. It will become fully - supported in future releases. -- _Not supported_. The resource or field is not yet supported. It will become partially or fully supported in future - releases. - -{{< 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. {{< /note >}} - ---- - -## Resources - -Each resource below includes the support status of their corresponding fields. - -For a description of each field, visit the [Gateway API documentation](https://gateway-api.sigs.k8s.io/references/spec/). - -### GatewayClass - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|--------------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| GatewayClass | Supported | Not supported | Supported | v1 | Standard | - -{{< /bootstrap-table >}} - -NGINX Gateway Fabric supports a single GatewayClass resource configured with the `--gatewayclass` flag of the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) command. - -**Fields**: - -- `spec` - - `controllerName` - supported. - - `parametersRef` - NginxProxy resource supported. - - `description` - supported. -- `status` - - `conditions` - supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/False/InvalidParameters` - - `Accepted/False/UnsupportedVersion` - - `Accepted/False/GatewayClassConflict`: Custom reason for when the GatewayClass references this controller, but - a different GatewayClass name is provided to the controller via the command-line argument. - - `SupportedVersion/True/SupportedVersion` - - `SupportedVersion/False/UnsupportedVersion` - ---- - -### Gateway - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| Gateway | Supported | Partially supported | Not supported | v1 | Standard | - -{{< /bootstrap-table >}} - -NGINX Gateway Fabric supports a single Gateway resource. The Gateway resource must reference NGINX Gateway Fabric's corresponding GatewayClass. - -See the [static-mode]({{< relref "/reference/cli-help.md#static-mode">}}) command for more information. - -**Fields**: - -- `spec` - - `gatewayClassName`: Supported. - - `listeners` - - `name`: Supported. - - `hostname`: Supported. - - `port`: Supported. - - `protocol`: Partially supported. Allowed values: `HTTP`, `HTTPS`. - - `tls` - - `mode`: Partially supported. Allowed value: `Terminate`. - - `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. -- `status` - - `addresses`: Partially supported (LoadBalancer and Pod IP). - - `conditions`: Supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/True/ListenersNotValid` - - `Accepted/False/ListenersNotValid` - - `Accepted/False/Invalid` - - `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Gateway is invalid or not supported. - - `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. - NGINX Gateway Fabric only supports a single Gateway. - - `Programmed/True/Programmed` - - `Programmed/False/Invalid` - - `Programmed/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NGINX Gateway Fabric only supports a single Gateway. - - `listeners` - - `name`: Supported. - - `supportedKinds`: Supported. - - `attachedRoutes`: Supported. - - `conditions`: Supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/False/UnsupportedProtocol` - - `Accepted/False/InvalidCertificateRef` - - `Accepted/False/ProtocolConflict` - - `Accpeted/False/HostnameConflict` - - `Accepted/False/UnsupportedValue`: Custom reason for when a value of a field in a Listener is invalid or not supported. - - `Accepted/False/GatewayConflict`: Custom reason for when the Gateway is ignored due to a conflicting Gateway. NGINX Gateway Fabric only supports a single Gateway. - - `Programmed/True/Programmed` - - `Programmed/False/Invalid` - - `ResolvedRefs/True/ResolvedRefs` - - `ResolvedRefs/False/InvalidCertificateRef` - - `ResolvedRefs/False/InvalidRouteKinds` - - `Conflicted/True/ProtocolConflict` - - `Conflicted/True/HostnameConflict` - - `Conflicted/False/NoConflicts` - ---- - -### HTTPRoute - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|-----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| HTTPRoute | Supported | Partially supported | Not supported | v1 | Standard | - -{{< /bootstrap-table >}} - -**Fields**: - -- `spec` - - `parentRefs`: Partially supported. Port not supported. - - `hostnames`: Supported. - - `rules` - - `matches` - - `path`: Partially supported. Only `PathPrefix` and `Exact` types. - - `headers`: Partially supported. Only `Exact` type. - - `queryParams`: Partially supported. Only `Exact` type. - - `method`: Supported. - - `filters` - - `type`: Supported. - - `requestRedirect`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. Incompatible with `urlRewrite`. - - `requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. - - `urlRewrite`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. Incompatible with `requestRedirect`. - - `responseHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. - - `requestMirror`, `extensionRef`: Not supported. - - `backendRefs`: Partially supported. Backend ref `filters` are not supported. -- `status` - - `parents` - - `parentRef`: Supported. - - `controllerName`: Supported. - - `conditions`: Partially supported. Supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/False/NoMatchingListenerHostname` - - `Accepted/False/NoMatchingParent` - - `Accepted/False/NotAllowedByListeners` - - `Accepted/False/UnsupportedValue`: Custom reason for when the HTTPRoute includes an invalid or unsupported value. - - `Accepted/False/InvalidListener`: Custom reason for when the HTTPRoute references an invalid listener. - - `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. HTTPRoute can be valid and configured, but will maintain this status as long as the Gateway is not Programmed. - - `Accepted/False/GatewayIgnored`: Custom reason for when the Gateway is ignored by NGINX Gateway Fabric. NGINX Gateway Fabric only supports one Gateway. - - `ResolvedRefs/True/ResolvedRefs` - - `ResolvedRefs/False/InvalidKind` - - `ResolvedRefs/False/RefNotPermitted` - - `ResolvedRefs/False/BackendNotFound` - - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the HTTPRoute rules has a backendRef with an unsupported value. - - `ResolvedRefs/False/InvalidIPFamily`: Custom reason for when one of the HTTPRoute rules has a backendRef that has an invalid IPFamily. - - `PartiallyInvalid/True/UnsupportedValue` - ---- - -### GRPCRoute - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|-----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| GRPCRoute | Supported | Partially supported | Not supported | v1 | Standard | - -{{< /bootstrap-table >}} - -**Fields**: - -- `spec` - - `parentRefs`: Partially supported. Port not supported. - - `hostnames`: Supported. - - `rules` - - `matches` - - `method`: Partially supported. Only `Exact` type with both `method.service` and `method.method` specified. - - `headers`: Partially supported. Only `Exact` type. - - `filters` - - `type`: Supported. - - `requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. - - `responseHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. - - `requestMirror`, `extensionRef`: Not supported. - - `backendRefs`: Partially supported. Backend ref `filters` are not supported. -- `status` - - `parents` - - `parentRef`: Supported. - - `controllerName`: Supported. - - `conditions`: Partially supported. Supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/False/NoMatchingListenerHostname` - - `Accepted/False/NoMatchingParent` - - `Accepted/False/NotAllowedByListeners` - - `Accepted/False/UnsupportedValue`: Custom reason for when the GRPCRoute includes an invalid or unsupported value. - - `Accepted/False/InvalidListener`: Custom reason for when the GRPCRoute references an invalid listener. - - `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. GRPCRoute can be valid and configured, but will maintain this status as long as the Gateway is not Programmed. - - `ResolvedRefs/True/ResolvedRefs` - - `ResolvedRefs/False/InvalidKind` - - `ResolvedRefs/False/RefNotPermitted` - - `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` - ---- - -### ReferenceGrant - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|----------------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| ReferenceGrant | Supported | N/A | Not supported | v1beta1 | Standard | - -{{< /bootstrap-table >}} - -Fields: - -- `spec` - - `to` - - `group` - supported. - - `kind` - supports `Secret` and `Service`. - - `name`- supported. - - `from` - - `group` - supported. - - `kind` - supports `Gateway` and `HTTPRoute`. - - `namespace`- supported. - ---- - -### TLSRoute - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| TLSRoute | Supported | Not supported | Not supported | v1alpha2 | Experimental | - -{{< /bootstrap-table >}} - -**Fields**: - -- `spec` - - `parentRefs`: Partially supported. Port not supported. - - `hostnames`: Supported. - - `rules` - - `backendRefs`: Partially supported. Only one backend ref allowed. - - `weight`: Not supported. -- `status` - - `parents` - - `parentRef`: Supported. - - `controllerName`: Supported. - - `conditions`: Supported (Condition/Status/Reason): - - `Accepted/True/Accepted` - - `Accepted/False/NoMatchingListenerHostname` - - `Accepted/False/NoMatchingParent` - - `Accepted/False/NotAllowedByListeners` - - `Accepted/False/UnsupportedValue`: Custom reason for when the TLSRoute includes an invalid or unsupported value. - - `Accepted/False/InvalidListener`: Custom reason for when the TLSRoute references an invalid listener. - - `Accepted/False/GatewayNotProgrammed`: Custom reason for when the Gateway is not Programmed. TLSRoute can be valid and configured, but will maintain this status as long as the Gateway is not Programmed. - - `Accepted/False/HostnameConflict`: Custom reason for when the TLSRoute has a hostname that conflicts with another TLSRoute on the same port. - - `ResolvedRefs/True/ResolvedRefs` - - `ResolvedRefs/False/InvalidKind` - - `ResolvedRefs/False/RefNotPermitted` - - `ResolvedRefs/False/BackendNotFound` - - `ResolvedRefs/False/UnsupportedValue`: Custom reason for when one of the TLSRoute rules has a backendRef with an unsupported value. - - `PartiallyInvalid/True/UnsupportedValue` - ---- - -### TCPRoute - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| TCPRoute | Not supported | Not supported | Not supported | v1alpha2 | Experimental | - -{{< /bootstrap-table >}} - ---- - -### UDPRoute - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|----------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| UDPRoute | Not supported | Not supported | Not supported | v1alpha2 | Experimental | - -{{< /bootstrap-table >}} - ---- - -### BackendTLSPolicy - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|------------------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| BackendTLSPolicy | Supported | Supported | Not supported | v1alpha3 | Experimental | - -{{< /bootstrap-table >}} - -Fields: - -- `spec` - - `targetRefs` - - `group` - supported. - - `kind` - supports `Service`. - - `name` - supported. - - `validation` - - `caCertificateRefs` - supports single reference to a `ConfigMap`, with the CA certificate in a key named `ca.crt`. - - `name`- supported. - - `group` - supported. - - `kind` - supports `ConfigMap`. - - `hostname` - supported. - - `wellKnownCertificates` - supports `System`. This will set the CA certificate to the Alpine system root CA path `/etc/ssl/cert.pem`. NB: This option will only work if the NGINX image used is Alpine based. The NGF NGINX images are Alpine based by default. -- `status` - - `ancestors` - - `ancestorRef` - supported. - - `controllerName`: supported. - - `conditions`: Partially supported. Supported (Condition/Status/Reason): - - `Accepted/True/PolicyReasonAccepted` - - `Accepted/False/PolicyReasonInvalid` - -{{}}If multiple `backendRefs` are defined for a HTTPRoute rule, all the referenced Services *must* have matching BackendTLSPolicy configuration. BackendTLSPolicy configuration is considered to be matching if 1. CACertRefs reference the same ConfigMap, or 2. WellKnownCACerts are the same, and 3. Hostname is the same.{{}} - -### Custom Policies - -{{< bootstrap-table "table table-striped table-bordered" >}} - -| Resource | Core Support Level | Extended Support Level | Implementation-Specific Support Level | API Version | API Release Channel | -|-----------------|--------------------|------------------------|---------------------------------------|-------------|---------------------| -| Custom policies | N/A | N/A | Supported | N/A | N/A | - -{{< /bootstrap-table >}} - -Custom policies are NGINX Gateway Fabric-specific CRDs (Custom Resource Definitions) that support features such as tracing, and client connection settings. These important data-plane features are not part of the Gateway API specifications. -While these CRDs are not part of the Gateway API, the mechanism to attach them to Gateway API resources is part of the Gateway API. See the [Policy Attachment documentation](https://gateway-api.sigs.k8s.io/references/policy-attachment/). - -See the [custom policies]({{< relref "overview/custom-policies.md" >}}) document for more information. diff --git a/site/content/overview/gateway-architecture.md b/site/content/overview/gateway-architecture.md deleted file mode 100644 index 2f270fe947..0000000000 --- a/site/content/overview/gateway-architecture.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Gateway architecture" -weight: 100 -toc: true -docs: "DOCS-1413" ---- - -Learn about the architecture and design principles of NGINX Gateway Fabric. - -The intended audience for this information is primarily the two following groups: - - -- _Cluster Operators_ who would like to know how the software works and understand how it can fail. -- _Developers_ who would like to [contribute](https://github.com/nginx/nginx-gateway-fabric/blob/main/CONTRIBUTING.md) to the project. - -The reader needs to be familiar with core Kubernetes concepts, such as pods, deployments, services, and endpoints. For an understanding of how NGINX itself works, you can read the ["Inside NGINX: How We Designed for Performance & Scale"](https://www.nginx.com/blog/inside-nginx-how-we-designed-for-performance-scale/) blog post. - -## Overview - -NGINX Gateway Fabric is an open source project that provides an implementation of the [Gateway API](https://gateway-api.sigs.k8s.io/) using [NGINX](https://nginx.org/) as the data plane. The goal of this project is to implement the core Gateway APIs -- _Gateway_, _GatewayClass_, _HTTPRoute_, _GRPCRoute_, _TCPRoute_, _TLSRoute_, and _UDPRoute_ -- to configure an HTTP or TCP/UDP load balancer, reverse proxy, or API gateway for applications running on Kubernetes. NGINX Gateway Fabric supports a subset of the Gateway API. - -For a list of supported Gateway API resources and features, see the [Gateway API Compatibility]({{< relref "/overview/gateway-api-compatibility.md" >}}) documentation. - -We have more information regarding our [design principles](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.0/docs/developer/design-principles.md) in the project's GitHub repository. - -## NGINX Gateway Fabric at a high level - -This figure depicts an example of NGINX Gateway Fabric exposing two web applications within a Kubernetes cluster to clients on the internet: - -{{}} - -{{< note >}} The figure does not show many of the necessary Kubernetes resources the Cluster Operators and Application Developers need to create, like deployment and services. {{< /note >}} - -The figure shows: - -- A _Kubernetes cluster_. -- Users _Cluster Operator_, _Application Developer A_ and _Application Developer B_. These users interact with the cluster through the Kubernetes API by creating Kubernetes objects. -- _Clients A_ and _Clients B_ connect to _Applications A_ and _B_, respectively, which they have deployed. -- The _NGF Pod_, [deployed by _Cluster Operator_]({{< relref "installation">}}) in the namespace _nginx-gateway_. For scalability and availability, you can have multiple replicas. This pod consists of two containers: `NGINX` and `NGF`. The _NGF_ container interacts with the Kubernetes API to retrieve the most up-to-date Gateway API resources created within the cluster. It then dynamically configures the _NGINX_ container based on these resources, ensuring proper alignment between the cluster state and the NGINX configuration. -- _Gateway AB_, created by _Cluster Operator_, requests a point where traffic can be translated to Services within the cluster. This Gateway includes a listener with a hostname `*.example.com`. Application Developers have the ability to attach their application's routes to this Gateway if their application's hostname matches `*.example.com`. -- _Application A_ with two pods deployed in the _applications_ namespace by _Application Developer A_. To expose the application to its clients (_Clients A_) via the host `a.example.com`, _Application Developer A_ creates _HTTPRoute A_ and attaches it to `Gateway AB`. -- _Application B_ with one pod deployed in the _applications_ namespace by _Application Developer B_. To expose the application to its clients (_Clients B_) via the host `b.example.com`, _Application Developer B_ creates _HTTPRoute B_ and attaches it to `Gateway AB`. -- _Public Endpoint_, which fronts the _NGF_ pod. This is typically a TCP load balancer (cloud, software, or hardware) or a combination of such load balancer with a NodePort service. _Clients A_ and _B_ connect to their applications via the _Public Endpoint_. - -The yellow and purple arrows represent connections related to the client traffic, and the black arrows represent access to the Kubernetes API. The resources within the cluster are color-coded based on the user responsible for their creation. - -For example, the Cluster Operator is denoted by the color green, indicating they create and manage all the green resources. - -## The NGINX Gateway Fabric pod - -NGINX Gateway Fabric consists of two containers: - -1. `nginx`: the data plane. Consists of an NGINX master process and NGINX worker processes. The master process controls the worker processes. The worker processes handle the client traffic and load balance traffic to the backend applications. -1. `nginx-gateway`: the control plane. Watches Kubernetes objects and configures NGINX. - -These containers are deployed in a single pod as a Kubernetes Deployment. - -The `nginx-gateway`, or the control plane, is a [Kubernetes controller](https://kubernetes.io/docs/concepts/architecture/controller/), written with the [controller-runtime](https://github.com/kubernetes-sigs/controller-runtime) library. It watches Kubernetes objects (services, endpoints, secrets, and Gateway API CRDs), translates them to NGINX configuration, and configures NGINX. - -This configuration happens in two stages: - -1. NGINX configuration files are written to the NGINX configuration volume shared by the `nginx-gateway` and `nginx` containers. -1. The control plane reloads the NGINX process. - -This is possible because the two containers [share a process namespace](https://kubernetes.io/docs/tasks/configure-pod-container/share-process-namespace/), allowing the NGINX Gateway Fabric process to send signals to the NGINX main process. - -The following diagram represents the connections, relationships and interactions between process with the `nginx` and `nginx-gateway` containers, as well as external processes/entities. - -{{}} - -The following list describes the connections, preceeded by their types in parentheses. For brevity, the suffix "process" has been omitted from the process descriptions. - -1. (HTTPS) - - Read: _NGF_ reads the _Kubernetes API_ to get the latest versions of the resources in the cluster. - - Write: _NGF_ writes to the _Kubernetes API_ to update the handled resources' statuses and emit events. If there's more than one replica of _NGF_ and [leader election](https://github.com/nginx/nginx-gateway-fabric/tree/v1.6.0/charts/nginx-gateway-fabric#configuration) is enabled, only the _NGF_ pod that is leading will write statuses to the _Kubernetes API_. -1. (HTTP, HTTPS) _Prometheus_ fetches the `controller-runtime` and NGINX metrics via an HTTP endpoint that _NGF_ exposes (`:9113/metrics` by default). Prometheus is **not** required by NGINX Gateway Fabric, and its endpoint can be turned off. -1. (File I/O) - - Write: _NGF_ generates NGINX _configuration_ based on the cluster resources and writes them as `.conf` files to the mounted `nginx-conf` volume, located at `/etc/nginx/conf.d`. It also writes _TLS certificates_ and _keys_ from [TLS secrets](https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) referenced in the accepted Gateway resource to the `nginx-secrets` volume at the path `/etc/nginx/secrets`. - - Read: _NGF_ reads the PID file `nginx.pid` from the `nginx-run` volume, located at `/var/run/nginx`. _NGF_ extracts the PID of the nginx process from this file in order to send reload signals to _NGINX master_. -1. (File I/O) _NGF_ writes logs to its _stdout_ and _stderr_, which are collected by the container runtime. -1. (HTTP) _NGF_ fetches the NGINX metrics via the unix:/var/run/nginx/nginx-status.sock UNIX socket and converts it to _Prometheus_ format used in #2. -1. (Signal) To reload NGINX, _NGF_ sends the [reload signal](https://nginx.org/en/docs/control.html) to the **NGINX master**. -1. (File I/O) - - Write: The _NGINX master_ writes its PID to the `nginx.pid` file stored in the `nginx-run` volume. - - Read: The _NGINX master_ reads _configuration files_ and the _TLS cert and keys_ referenced in the configuration when it starts or during a reload. These files, certificates, and keys are stored in the `nginx-conf` and `nginx-secrets` volumes that are mounted to both the `nginx-gateway` and `nginx` containers. -1. (File I/O) - - Write: The _NGINX master_ writes to the auxiliary Unix sockets folder, which is located in the `/var/run/nginx` - directory. - - Read: The _NGINX master_ reads the `nginx.conf` file from the `/etc/nginx` directory. This [file](https://github.com/nginx/nginx-gateway-fabric/blob/v1.6.0/internal/mode/static/nginx/conf/nginx.conf) contains the global and http configuration settings for NGINX. In addition, _NGINX master_ reads the NJS modules referenced in the configuration when it starts or during a reload. NJS modules are stored in the `/usr/lib/nginx/modules` directory. -1. (File I/O) The _NGINX master_ sends logs to its _stdout_ and _stderr_, which are collected by the container runtime. -1. (File I/O) An _NGINX worker_ writes logs to its _stdout_ and _stderr_, which are collected by the container runtime. -1. (Signal) The _NGINX master_ controls the [lifecycle of _NGINX workers_](https://nginx.org/en/docs/control.html#reconfiguration) it creates workers with the new configuration and shutdowns workers with the old configuration. -1. (HTTP) To consider a configuration reload a success, _NGF_ ensures that at least one NGINX worker has the new configuration. To do that, _NGF_ checks a particular endpoint via the unix:/var/run/nginx/nginx-config-version.sock UNIX socket. -1. (HTTP, HTTPS) A _client_ sends traffic to and receives traffic from any of the _NGINX workers_ on ports 80 and 443. -1. (HTTP, HTTPS) An _NGINX worker_ sends traffic to and receives traffic from the _backends_. - -Below are additional connections not depcited on the diagram: - -- (HTTPS) NGF sends [product telemetry data]({{< relref "/overview/product-telemetry.md" >}}) to the F5 telemetry service. - -### Differences with NGINX Plus - -The previous diagram depicts NGINX Gateway Fabric using NGINX Open Source. NGINX Gateway Fabric with NGINX Plus has the following difference: - -- An _admin_ can connect to the NGINX Plus API using port 8765. NGINX only allows connections from localhost. - -## Updating upstream servers - -The normal process to update any changes to NGINX is to write the configuration files and reload NGINX. However, when using NGINX Plus, we can take advantage of the [NGINX Plus API](http://nginx.org/en/docs/http/ngx_http_api_module.html) to limit the amount of reloads triggered when making changes to NGINX. Specifically, when the endpoints of an application in Kubernetes change (Such as scaling up or down), the NGINX Plus API is used to update the upstream servers in NGINX with the new endpoints without a reload. This reduces the potential for a disruption that could occur when reloading. - -## Pod readiness - -The `nginx-gateway` container includes a readiness endpoint available through the path `/readyz`. A [readiness probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes) periodically checks the endpoint on startup, returning a `200 OK` response when the pod can accept traffic for the data plane. Once the control plane successfully starts, the pod becomes ready. - -If there are relevant Gateway API resources in the cluster, the control plane will generate the first NGINX configuration and successfully reload NGINX before the pod is considered ready. diff --git a/site/content/overview/nginx-plus.md b/site/content/overview/nginx-plus.md deleted file mode 100644 index bc67839bf0..0000000000 --- a/site/content/overview/nginx-plus.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Advanced features with NGINX Plus" -weight: 400 -toc: true -docs: "DOCS-1415" ---- - -NGINX Gateway Fabric can use NGINX Open Source or NGINX Plus as its data plane. [NGINX Plus](https://www.nginx.com/products/nginx/) is the closed source, commercial version of NGINX. Using NGINX Plus as the data plane offers additional benefits compared to the open source version. - -## Benefits of NGINX Plus - -- **Robust metrics**: A plethora of [additional Prometheus metrics](https://github.com/nginx/nginx-prometheus-exporter#metrics-for-nginx-plus) are available. -- **Live activity monitoring**: The [NGINX Plus dashboard]({{< relref "/how-to/monitoring/dashboard.md" >}}) shows real-time metrics and information about your server infrastructure. -- **Dynamic upstream configuration**: NGINX Plus can dynamically reconfigure upstream servers when applications in Kubernetes scale up and down, preventing the need for an NGINX reload. -- **Support**: With an NGINX Plus license, you can take advantage of full [support](https://my.f5.com/manage/s/article/K000140156/) from NGINX, Inc. diff --git a/site/content/overview/product-telemetry.md b/site/content/overview/product-telemetry.md deleted file mode 100644 index eb69961c92..0000000000 --- a/site/content/overview/product-telemetry.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Product telemetry" -weight: 500 -toc: true ---- - -Learn why, what and how NGINX Gateway Fabric collects telemetry. - -## Overview - -NGINX Gateway Fabric collects telemetry by default, which allows its developers to understand what features are most popular with its user base. This data is used to triage development work, prioritizing features and functionality that will positively impact the most people. - -Telemetry data is collected once every 24 hours and sent to a service managed by F5 over HTTPS. Personally identifiable information (PII) is **not** collected. The list of data points that are collected can be seen below. - -**If you would prefer to not have data collected, you can [opt-out](#opt-out) when installing NGINX Gateway Fabric.** - -## Collected data - -- **Kubernetes:** - - **Platform:** the Kubernetes platform that NGINX Gateway Fabric is running on - - **Version:** the Kubernetes version that NGINX Gateway Fabric is running on. - - **Architecture:** the architecture that the Kubernetes environment is running on. -- **Cluster UID:** the UID of the `kube-system` Namespace in the cluster that NGINX Gateway Fabric is running in. -- **Cluster Node Count:** the number of Nodes in the cluster. -- **Version:** the version of the NGINX Gateway Fabric Deployment. -- **Deployment UID:** the UID of the NGINX Gateway Fabric Deployment. -- **Deployment Replica Count:** the count of NGINX Gateway Fabric Pods. -- **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. -- **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. -- **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. -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. -- The scale of NGINX Gateway Fabric Deployments. -- The scale of Gateway API resources. -- The used features of NGINX Gateway Fabric. - -Our goal is to publicly discuss data trends to drive roadmap discussions in our [Community Meeting](https://github.com/nginx/nginx-gateway-fabric/discussions/1472). - -## Opt out - -You can disable product telemetry when installing NGINX Gateway Fabric using an option dependent on your installation method: - -### Helm - -Set the `nginxGateway.productTelemetry.enable=false` flag either in the `values.yaml` file or when installing: - -```shell -helm install ... --set nginxGateway.productTelemetry.enable=false -``` - -### Manifests - -Add the `--product-telemetry-disable` flag to the `nginx-gateway` container in your Deployment manifest. diff --git a/site/content/overview/resource-validation.md b/site/content/overview/resource-validation.md deleted file mode 100644 index fba7b42a7d..0000000000 --- a/site/content/overview/resource-validation.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: "Resource validation" -weight: 600 -toc: true -docs: "DOCS-1414" ---- - -## Overview - -This document describes how NGINX Gateway Fabric validates Gateway API and NGINX Gateway Fabric Kubernetes resources. - -## Gateway API resource validation - -NGINX Gateway Fabric validates Gateway API resources for several reasons: - -- _Robustness_: to gracefully handle invalid resources. -- _Security_: to prevent malicious input from propagating to the NGINX configuration. -- _Correctness_: to conform to the Gateway API specification for handling invalid resources. - -The process involves four different steps, explained in detail in this document, with the goal of making sure that NGINX continues to handle traffic even if invalid Gateway API resources were created. - -### Step 1 - OpenAPI Scheme validation by Kubernetes API Server - -The Kubernetes API server validates Gateway API resources against the OpenAPI schema embedded in the Gateway API CRDs. For example, if you create an HTTPRoute with an invalid hostname "cafe.!@#$%example.com", the API server will reject it with the following error: - -```shell -kubectl apply -f coffee-route.yaml -``` - -```text -The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$%example.com": spec.hostnames[0] in body should match '^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$' -``` - -{{< note >}}While unlikely, bypassing this validation step is possible if the Gateway API CRDs are modified to remove the validation. If this happens, Step 4 will reject any invalid values (from NGINX perspective).{{< /note >}} - -### Step 2 - CEL validation by Kubernetes API Server - -The Kubernetes API server validates Gateway API resources using CEL validation embedded in the Gateway API CRDs. It validates Gateway API resources using advanced rules unavailable in the OpenAPI schema validation. For example, if you create a Gateway resource with a TCP listener that configures a hostname, the CEL validation will reject it with the following error: - -```shell -kubectl apply -f some-gateway.yaml -``` - -```text -The Gateway "some-gateway" is invalid: spec.listeners: Invalid value: "array": hostname must not be specified for protocols ['TCP', 'UDP'] -``` - -More information on CEL in Kubernetes can be found [here](https://kubernetes.io/docs/reference/using-api/cel/). - - -### Step 3 - Validation by NGINX Gateway Fabric - -This step catches the following cases of invalid values: - -- Valid values from the Gateway API perspective but not supported by NGINX Gateway Fabric yet. For example, a feature in an HTTPRoute routing rule. For the list of supported features see [Gateway API Compatibility]({{< relref "gateway-api-compatibility.md" >}}) doc. -- Valid values from the Gateway API perspective, but invalid for NGINX, because NGINX has stricter validation requirements for certain fields. These values will cause NGINX to fail to reload or operate erroneously. -- Invalid values (both from the Gateway API and NGINX perspectives) that were not rejected because Step 1 was bypassed. Similar to the previous case, these values will cause NGINX to fail to reload or operate erroneously. -- Malicious values that inject unrestricted NGINX config into the NGINX configuration (similar to an SQL injection attack). - -Below is an example of how NGINX Gateway Fabric rejects an invalid resource. The validation error is reported via the status: - -```shell -kubectl describe httproutes.gateway.networking.k8s.io coffee -``` - -```text -. . . -Status: - Parents: - Conditions: - Last Transition Time: 2023-03-30T22:37:53Z - Message: All rules are invalid: spec.rules[0].matches[0].method: Unsupported value: "CONNECT": supported values: "DELETE", "GET", "HEAD", "OPTIONS", "PATCH", "POST", "PUT" - Observed Generation: 1 - Reason: UnsupportedValue - Status: False - Type: Accepted - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: prod-gateway - Namespace: default - Section Name: http -``` - -{{< note >}}This validation step always runs and cannot be bypassed.{{< /note >}} - -### Confirm validation - -To confirm that a resource is valid and accepted by NGINX Gateway Fabric, check that the **Accepted** condition in the resource status has the Status field set to **True**. For example, in a status of a valid HTTPRoute, if NGINX Gateway Fabric accepts a parentRef, the status of that parentRef will look like this: - -```text -Status: - Parents: - Conditions: - Last Transition Time: 2023-03-30T23:18:00Z - Message: The route is accepted - Observed Generation: 2 - Reason: Accepted - Status: True - Type: Accepted - Controller Name: gateway.nginx.org/nginx-gateway-controller - Parent Ref: - Group: gateway.networking.k8s.io - Kind: Gateway - Name: gateway - Namespace: default - Section Name: http -``` - -{{< note>}}Make sure the reported observed generation is the same as the resource generation.{{< /note >}} - -## NGINX Gateway Fabric Resource validation - -### Step 1 - OpenAPI Scheme validation by Kubernetes API Server - -The Kubernetes API server validates NGINX Gateway Fabric resources against the OpenAPI schema embedded in the NGINX Gateway Fabric CRDs. For example, if you create an NginxGateway with an invalid logging level, "some-level", the API server will reject it with the following error: - -```shell -kubectl apply -f nginx-gateway-config.yaml -``` - -```text -The NginxGateway "nginx-gateway-config" is invalid: spec.logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error" -``` - -{{< note >}}While unlikely, bypassing this validation step is possible if the NGINX Gateway Fabric CRDs are modified to remove the validation. If this happens, Step 2 will report an error in the resource's status.{{< /note >}} - -### Step 2 - Validation by NGINX Gateway Fabric - -This step validates the settings in the NGINX Gateway Fabric CRDs and rejects invalid resources. The validation error is reported via the status and as an Event. For example: - -```shell -kubectl describe nginxgateways.gateway.nginx.org nginx-gateway-config -``` - -Status: - -```text -... -Status: - Conditions: - Last Transition Time: 2023-12-15T21:02:30Z - Message: Failed to update control plane configuration: logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error" - Observed Generation: 1 - Reason: Invalid - Status: False - Type: Valid -``` - -Event: - -```text -Warning UpdateFailed 1s (x2 over 1s) nginx-gateway-fabric-nginx Failed to update control plane configuration: logging.level: Unsupported value: "some-level": supported values: "info", "debug", "error" -``` - -### Confirm validation - -To confirm that a resource is valid and accepted by NGINX Gateway Fabric, check that the **Valid** condition in the resource status has the Status field set to **True**. For example, the status of a valid NginxGateway will look like this: - -```text -Status: - Conditions: - Last Transition Time: 2023-12-15T21:04:49Z - Message: NginxGateway is valid - Observed Generation: 1 - Reason: Valid - Status: True - Type: Valid -``` diff --git a/site/content/reference/_index.md b/site/content/reference/_index.md deleted file mode 100644 index 2dff1597cd..0000000000 --- a/site/content/reference/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Reference" -weight: 500 ---- diff --git a/site/content/reference/api.md b/site/content/reference/api.md deleted file mode 100644 index 0f829e7ac7..0000000000 --- a/site/content/reference/api.md +++ /dev/null @@ -1,2754 +0,0 @@ ---- -title: "API reference" -weight: 100 -toc: false ---- -## Overview -NGINX Gateway API Reference -

Packages:

- -

gateway.nginx.org/v1alpha1

-

-

Package v1alpha1 contains API Schema definitions for the -gateway.nginx.org API group.

-

-Resource Types: - -

ClientSettingsPolicy - -

-

-

ClientSettingsPolicy is an Inherited Attached Policy. It provides a way to configure the behavior of the connection -between the client and NGINX Gateway Fabric.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		ClientSettingsPolicy
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -ClientSettingsPolicySpec - - -		 -

Spec defines the desired state of the ClientSettingsPolicy.

-
-
- - - - - - - - - - - - - -
-body
- - -ClientBody - - -		 -(Optional) -

Body defines the client request body settings.

-
-keepAlive
- - -ClientKeepAlive - - -		 -(Optional) -

KeepAlive defines the keep-alive settings.

-
-targetRef
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRef identifies an API object to apply the policy to. -Object must be in the same namespace as the policy. -Support: Gateway, HTTPRoute, GRPCRoute.

-
-
-status
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus - - -		 -

Status defines the state of the ClientSettingsPolicy.

-
-

NginxGateway - -

-

-

NginxGateway represents the dynamic configuration for an NGINX Gateway Fabric control plane.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		NginxGateway
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -NginxGatewaySpec - - -		 -

NginxGatewaySpec defines the desired state of the NginxGateway.

-
-
- - - - - -
-logging
- - -Logging - - -		 -(Optional) -

Logging defines logging related settings for the control plane.

-
-
-status
- - -NginxGatewayStatus - - -		 -

NginxGatewayStatus defines the state of the NginxGateway.

-
-

NginxProxy - -

-

-

NginxProxy is a configuration object that is attached to a GatewayClass parametersRef. It provides a way -to configure global settings for all Gateways defined from the GatewayClass.

-

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		NginxProxy
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -NginxProxySpec - - -		 -

Spec defines the desired state of the NginxProxy.

-
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
-ipFamily
- - -IPFamilyType - - -		 -(Optional) -

IPFamily specifies the IP family to be used by the NGINX. -Default is “dual”, meaning the server will use both IPv4 and IPv6.

-
-telemetry
- - -Telemetry - - -		 -(Optional) -

Telemetry specifies the OpenTelemetry configuration.

-
-rewriteClientIP
- - -RewriteClientIP - - -		 -(Optional) -

RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP.

-
-logging
- - -NginxLogging - - -		 -(Optional) -

Logging defines logging related settings for NGINX.

-
-nginxPlus
- - -NginxPlus - - -		 -(Optional) -

NginxPlus specifies NGINX Plus additional settings.

-
-disableHTTP2
- -bool - -		 -

DisableHTTP2 defines if http2 should be disabled for all servers. -Default is false, meaning http2 will be enabled for all servers.

-
-
-

ObservabilityPolicy - -

-

-

ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for -the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the -GatewayClass parametersRef.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		ObservabilityPolicy
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -ObservabilityPolicySpec - - -		 -

Spec defines the desired state of the ObservabilityPolicy.

-
-
- - - - - - - - - -
-tracing
- - -Tracing - - -		 -(Optional) -

Tracing allows for enabling and configuring tracing.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies the API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: HTTPRoute, GRPCRoute.

-
-
-status
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus - - -		 -

Status defines the state of the ObservabilityPolicy.

-
-

SnippetsFilter - -

-

-

SnippetsFilter is a filter that allows inserting NGINX configuration into the -generated NGINX config for HTTPRoute and GRPCRoute resources.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		SnippetsFilter
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -SnippetsFilterSpec - - -		 -

Spec defines the desired state of the SnippetsFilter.

-
-
- - - - - -
-snippets
- - -[]Snippet - - -		 -

Snippets is a list of NGINX configuration snippets. -There can only be one snippet per context. -Allowed contexts: main, http, http.server, http.server.location.

-
-
-status
- - -SnippetsFilterStatus - - -		 -

Status defines the state of the SnippetsFilter.

-
-

UpstreamSettingsPolicy - -

-

-

UpstreamSettingsPolicy is a Direct Attached Policy. It provides a way to configure the behavior of -the connection between NGINX and the upstream applications.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha1 - -
-kind
-string -		UpstreamSettingsPolicy
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -UpstreamSettingsPolicySpec - - -		 -

Spec defines the desired state of the UpstreamSettingsPolicy.

-
-
- - - - - - - - - - - - - -
-zoneSize
- - -Size - - -		 -(Optional) -

ZoneSize is the size of the shared memory zone used by the upstream. This memory zone is used to share -the upstream configuration between nginx worker processes. The more servers that an upstream has, -the larger memory zone is required. -Default: OSS: 512k, Plus: 1m. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone

-
-keepAlive
- - -UpstreamKeepAlive - - -		 -(Optional) -

KeepAlive defines the keep-alive settings.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: Service

-

TargetRefs must be distinct. The name field must be unique for all targetRef entries in the UpstreamSettingsPolicy.

-
-
-status
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus - - -		 -

Status defines the state of the UpstreamSettingsPolicy.

-
-

ClientBody - -

-

-(Appears on: -ClientSettingsPolicySpec) -

-

-

ClientBody contains the settings for the client request body.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-maxSize
- - -Size - - -		 -(Optional) -

MaxSize sets the maximum allowed size of the client request body. -If the size in a request exceeds the configured value, -the 413 (Request Entity Too Large) error is returned to the client. -Setting size to 0 disables checking of client request body size. -Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size.

-
-timeout
- - -Duration - - -		 -(Optional) -

Timeout defines a timeout for reading client request body. The timeout is set only for a period between -two successive read operations, not for the transmission of the whole request body. -If a client does not transmit anything within this time, the request is terminated with the -408 (Request Time-out) error. -Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_timeout.

-
-

ClientKeepAlive - -

-

-(Appears on: -ClientSettingsPolicySpec) -

-

-

ClientKeepAlive defines the keep-alive settings for clients.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-requests
- -int32 - -		 -(Optional) -

Requests sets the maximum number of requests that can be served through one keep-alive connection. -After the maximum number of requests are made, the connection is closed. Closing connections periodically -is necessary to free per-connection memory allocations. Therefore, using too high maximum number of requests -is not recommended as it can lead to excessive memory usage. -Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests.

-
-time
- - -Duration - - -		 -(Optional) -

Time defines the maximum time during which requests can be processed through one keep-alive connection. -After this time is reached, the connection is closed following the subsequent request processing. -Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_time.

-
-timeout
- - -ClientKeepAliveTimeout - - -		 -(Optional) -

Timeout defines the keep-alive timeouts for clients.

-
-

ClientKeepAliveTimeout - -

-

-(Appears on: -ClientKeepAlive) -

-

-

ClientKeepAliveTimeout defines the timeouts related to keep-alive client connections. -Default: https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-server
- - -Duration - - -		 -(Optional) -

Server sets the timeout during which a keep-alive client connection will stay open on the server side. -Setting this value to 0 disables keep-alive client connections.

-
-header
- - -Duration - - -		 -(Optional) -

Header sets the timeout in the “Keep-Alive: timeout=time” response header field.

-
-

ClientSettingsPolicySpec - -

-

-(Appears on: -ClientSettingsPolicy) -

-

-

ClientSettingsPolicySpec defines the desired state of ClientSettingsPolicy.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-body
- - -ClientBody - - -		 -(Optional) -

Body defines the client request body settings.

-
-keepAlive
- - -ClientKeepAlive - - -		 -(Optional) -

KeepAlive defines the keep-alive settings.

-
-targetRef
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRef identifies an API object to apply the policy to. -Object must be in the same namespace as the policy. -Support: Gateway, HTTPRoute, GRPCRoute.

-
-

ControllerLogLevel -(string alias)

-

-

-(Appears on: -Logging) -

-

-

ControllerLogLevel type defines the logging level for the control plane.

-

- - - - - - - - - - - - - - -
ValueDescription

"debug"

ControllerLogLevelDebug is the debug level for control plane logging.

-

"error"

ControllerLogLevelError is the error level for control plane logging.

-

"info"

ControllerLogLevelInfo is the info level for control plane logging.

-
-

ControllerStatus - -

-

-(Appears on: -SnippetsFilterStatus) -

-

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-controllerName
- - -sigs.k8s.io/gateway-api/apis/v1.GatewayController - - -		 -

ControllerName is a domain/path string that indicates the name of the -controller that wrote this status. This corresponds with the -controllerName field on GatewayClass.

-

Example: “example.net/gateway-controller”.

-

The format of this field is DOMAIN “/” PATH, where DOMAIN and PATH are -valid Kubernetes names -(https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).

-

Controllers MUST populate this field when writing status. Controllers should ensure that -entries to status populated with their ControllerName are cleaned up when they are no -longer necessary.

-
-conditions
- - -[]Kubernetes meta/v1.Condition - - -		 -(Optional) -

Conditions describe the status of the SnippetsFilter.

-
-

Duration -(string alias)

-

-

-(Appears on: -ClientBody, -ClientKeepAlive, -ClientKeepAliveTimeout, -TelemetryExporter, -UpstreamKeepAlive) -

-

-

Duration is a string value representing a duration in time. -Duration can be specified in milliseconds (ms), seconds (s), minutes (m), hours (h). -A value without a suffix is seconds. -Examples: 120s, 50ms, 5m, 1h.

-

-

IPFamilyType -(string alias)

-

-

-(Appears on: -NginxProxySpec) -

-

-

IPFamilyType specifies the IP family to be used by NGINX.

-

- - - - - - - - - - - - - - -
ValueDescription

"dual"

Dual specifies that NGINX will use both IPv4 and IPv6.

-

"ipv4"

IPv4 specifies that NGINX will use only IPv4.

-

"ipv6"

IPv6 specifies that NGINX will use only IPv6.

-
-

Logging - -

-

-(Appears on: -NginxGatewaySpec) -

-

-

Logging defines logging related settings for the control plane.

-

- - - - - - - - - - - - - -
FieldDescription
-level
- - -ControllerLogLevel - - -		 -(Optional) -

Level defines the logging level.

-
-

NginxContext -(string alias)

-

-

-(Appears on: -Snippet) -

-

-

NginxContext represents the NGINX configuration context.

-

- - - - - - - - - - - - - - - - -
ValueDescription

"http"

NginxContextHTTP is the http context of the NGINX configuration. -https://nginx.org/en/docs/http/ngx_http_core_module.html#http

-

"http.server"

NginxContextHTTPServer is the server context of the NGINX configuration. -https://nginx.org/en/docs/http/ngx_http_core_module.html#server

-

"http.server.location"

NginxContextHTTPServerLocation is the location context of the NGINX configuration. -https://nginx.org/en/docs/http/ngx_http_core_module.html#location

-

"main"

NginxContextMain is the main context of the NGINX configuration.

-
-

NginxErrorLogLevel -(string alias)

-

-

-(Appears on: -NginxLogging) -

-

-

NginxErrorLogLevel type defines the log level of error logs for NGINX.

-

- - - - - - - - - - - - - - - - - - - - - - - - -
ValueDescription

"alert"

NginxLogLevelAlert is the alert level for NGINX error logs.

-

"crit"

NginxLogLevelCrit is the crit level for NGINX error logs.

-

"debug"

NginxLogLevelDebug is the debug level for NGINX error logs.

-

"emerg"

NginxLogLevelEmerg is the emerg level for NGINX error logs.

-

"error"

NginxLogLevelError is the error level for NGINX error logs.

-

"info"

NginxLogLevelInfo is the info level for NGINX error logs.

-

"notice"

NginxLogLevelNotice is the notice level for NGINX error logs.

-

"warn"

NginxLogLevelWarn is the warn level for NGINX error logs.

-
-

NginxGatewayConditionReason -(string alias)

-

-

-

NginxGatewayConditionReason defines the set of reasons that explain why a -particular NginxGateway condition type has been raised.

-

- - - - - - - - - - - - -
ValueDescription

"Invalid"

NginxGatewayReasonInvalid is a reason that is used with the “Valid” condition when the condition is False.

-

"Valid"

NginxGatewayReasonValid is a reason that is used with the “Valid” condition when the condition is True.

-
-

NginxGatewayConditionType -(string alias)

-

-

-

NginxGatewayConditionType is a type of condition associated with an -NginxGateway. This type should be used with the NginxGatewayStatus.Conditions field.

-

- - - - - - - - - - -
ValueDescription

"Valid"

NginxGatewayConditionValid is a condition that is true when the NginxGateway -configuration is syntactically and semantically valid.

-
-

NginxGatewaySpec - -

-

-(Appears on: -NginxGateway) -

-

-

NginxGatewaySpec defines the desired state of the NginxGateway.

-

- - - - - - - - - - - - - -
FieldDescription
-logging
- - -Logging - - -		 -(Optional) -

Logging defines logging related settings for the control plane.

-
-

NginxGatewayStatus - -

-

-(Appears on: -NginxGateway) -

-

-

NginxGatewayStatus defines the state of the NginxGateway.

-

- - - - - - - - - - - - - -
FieldDescription
-conditions
- - -[]Kubernetes meta/v1.Condition - - -		 -(Optional) -
-

NginxLogging - -

-

-(Appears on: -NginxProxySpec) -

-

-

NginxLogging defines logging related settings for NGINX.

-

- - - - - - - - - - - - - -
FieldDescription
-errorLevel
- - -NginxErrorLogLevel - - -		 -(Optional) -

ErrorLevel defines the error log level. Possible log levels listed in order of increasing severity are -debug, info, notice, warn, error, crit, alert, and emerg. Setting a certain log level will cause all messages -of the specified and more severe log levels to be logged. For example, the log level ‘error’ will cause error, -crit, alert, and emerg messages to be logged. https://nginx.org/en/docs/ngx_core_module.html#error_log

-
-

NginxPlus - -

-

-(Appears on: -NginxProxySpec) -

-

-

NginxPlus specifies NGINX Plus additional settings. These will only be applied if NGINX Plus is being used.

-

- - - - - - - - - - - - - -
FieldDescription
-allowedAddresses
- - -[]NginxPlusAllowAddress - - -		 -(Optional) -

AllowedAddresses specifies IPAddresses or CIDR blocks to the allow list for accessing the NGINX Plus API.

-
-

NginxPlusAllowAddress - -

-

-(Appears on: -NginxPlus) -

-

-

NginxPlusAllowAddress specifies the address type and value for an NginxPlus allow address.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-type
- - -NginxPlusAllowAddressType - - -		 -

Type specifies the type of address.

-
-value
- -string - -		 -

Value specifies the address value.

-
-

NginxPlusAllowAddressType -(string alias)

-

-

-(Appears on: -NginxPlusAllowAddress) -

-

-

NginxPlusAllowAddressType specifies the type of address.

-

- - - - - - - - - - - - -
ValueDescription

"CIDR"

NginxPlusAllowCIDRAddressType specifies that the address is a CIDR block.

-

"IPAddress"

NginxPlusAllowIPAddressType specifies that the address is an IP address.

-
-

NginxProxySpec - -

-

-(Appears on: -NginxProxy) -

-

-

NginxProxySpec defines the desired state of the NginxProxy.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-ipFamily
- - -IPFamilyType - - -		 -(Optional) -

IPFamily specifies the IP family to be used by the NGINX. -Default is “dual”, meaning the server will use both IPv4 and IPv6.

-
-telemetry
- - -Telemetry - - -		 -(Optional) -

Telemetry specifies the OpenTelemetry configuration.

-
-rewriteClientIP
- - -RewriteClientIP - - -		 -(Optional) -

RewriteClientIP defines configuration for rewriting the client IP to the original client’s IP.

-
-logging
- - -NginxLogging - - -		 -(Optional) -

Logging defines logging related settings for NGINX.

-
-nginxPlus
- - -NginxPlus - - -		 -(Optional) -

NginxPlus specifies NGINX Plus additional settings.

-
-disableHTTP2
- -bool - -		 -

DisableHTTP2 defines if http2 should be disabled for all servers. -Default is false, meaning http2 will be enabled for all servers.

-
-

ObservabilityPolicySpec - -

-

-(Appears on: -ObservabilityPolicy) -

-

-

ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-tracing
- - -Tracing - - -		 -(Optional) -

Tracing allows for enabling and configuring tracing.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies the API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: HTTPRoute, GRPCRoute.

-
-

RewriteClientIP - -

-

-(Appears on: -NginxProxySpec) -

-

-

RewriteClientIP specifies the configuration for rewriting the client’s IP address.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-mode
- - -RewriteClientIPModeType - - -		 -(Optional) -

Mode defines how NGINX will rewrite the client’s IP address. -There are two possible modes: -- ProxyProtocol: NGINX will rewrite the client’s IP using the PROXY protocol header. -- XForwardedFor: NGINX will rewrite the client’s IP using the X-Forwarded-For header. -Sets NGINX directive real_ip_header: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header

-
-setIPRecursively
- -bool - -		 -(Optional) -

SetIPRecursively configures whether recursive search is used when selecting the client’s address from -the X-Forwarded-For header. It is used in conjunction with TrustedAddresses. -If enabled, NGINX will recurse on the values in X-Forwarded-Header from the end of array -to start of array and select the first untrusted IP. -For example, if X-Forwarded-For is [11.11.11.11, 22.22.22.22, 55.55.55.1], -and TrustedAddresses is set to 55.55.55.1⁄32, NGINX will rewrite the client IP to 22.22.22.22. -If disabled, NGINX will select the IP at the end of the array. -In the previous example, 55.55.55.1 would be selected. -Sets NGINX directive real_ip_recursive: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_recursive

-
-trustedAddresses
- - -[]RewriteClientIPAddress - - -		 -(Optional) -

TrustedAddresses specifies the addresses that are trusted to send correct client IP information. -If a request comes from a trusted address, NGINX will rewrite the client IP information, -and forward it to the backend in the X-Forwarded-For* and X-Real-IP headers. -If the request does not come from a trusted address, NGINX will not rewrite the client IP information. -TrustedAddresses only supports CIDR blocks: 192.33.21.1⁄24, fe80::1⁄64. -To trust all addresses (not recommended for production), set to 0.0.0.0/0. -If no addresses are provided, NGINX will not rewrite the client IP information. -Sets NGINX directive set_real_ip_from: https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from -This field is required if mode is set.

-
-

RewriteClientIPAddress - -

-

-(Appears on: -RewriteClientIP) -

-

-

RewriteClientIPAddress specifies the address type and value for a RewriteClientIP address.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-type
- - -RewriteClientIPAddressType - - -		 -

Type specifies the type of address.

-
-value
- -string - -		 -

Value specifies the address value.

-
-

RewriteClientIPAddressType -(string alias)

-

-

-(Appears on: -RewriteClientIPAddress) -

-

-

RewriteClientIPAddressType specifies the type of address.

-

- - - - - - - - - - - - - - -
ValueDescription

"CIDR"

RewriteClientIPCIDRAddressType specifies that the address is a CIDR block.

-

"Hostname"

RewriteClientIPHostnameAddressType specifies that the address is a Hostname.

-

"IPAddress"

RewriteClientIPIPAddressType specifies that the address is an IP address.

-
-

RewriteClientIPModeType -(string alias)

-

-

-(Appears on: -RewriteClientIP) -

-

-

RewriteClientIPModeType defines how NGINX Gateway Fabric will determine the client’s original IP address.

-

- - - - - - - - - - - - -
ValueDescription

"ProxyProtocol"

RewriteClientIPModeProxyProtocol configures NGINX to accept PROXY protocol and -set the client’s IP address to the IP address in the PROXY protocol header. -Sets the proxy_protocol parameter on the listen directive of all servers and sets real_ip_header -to proxy_protocol: https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header.

-

"XForwardedFor"

RewriteClientIPModeXForwardedFor configures NGINX to set the client’s IP address to the -IP address in the X-Forwarded-For HTTP header. -https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header.

-
-

Size -(string alias)

-

-

-(Appears on: -ClientBody, -UpstreamSettingsPolicySpec) -

-

-

Size is a string value representing a size. Size can be specified in bytes, kilobytes (k), megabytes (m), -or gigabytes (g). -Examples: 1024, 8k, 1m.

-

-

Snippet - -

-

-(Appears on: -SnippetsFilterSpec) -

-

-

Snippet represents an NGINX configuration snippet.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-context
- - -NginxContext - - -		 -

Context is the NGINX context to insert the snippet into.

-
-value
- -string - -		 -

Value is the NGINX configuration snippet.

-
-

SnippetsFilterConditionReason -(string alias)

-

-

-

SnippetsFilterConditionReason is a reason for a SnippetsFilter condition type.

-

- - - - - - - - - - - - -
ValueDescription

"Accepted"

SnippetsFilterConditionReasonAccepted is used with the Accepted condition type when -the condition is true.

-

"Invalid"

SnippetsFilterConditionReasonInvalid is used with the Accepted condition type when -SnippetsFilter is invalid.

-
-

SnippetsFilterConditionType -(string alias)

-

-

-

SnippetsFilterConditionType is a type of condition associated with SnippetsFilter.

-

- - - - - - - - - - -
ValueDescription

"Accepted"

SnippetsFilterConditionTypeAccepted indicates that the SnippetsFilter is accepted.

-

Possible reasons for this condition to be True:

-
    -
  • Accepted
    • -
-

Possible reasons for this condition to be False:

-
    -
  • Invalid.
    • -
-
-

SnippetsFilterSpec - -

-

-(Appears on: -SnippetsFilter) -

-

-

SnippetsFilterSpec defines the desired state of the SnippetsFilter.

-

- - - - - - - - - - - - - -
FieldDescription
-snippets
- - -[]Snippet - - -		 -

Snippets is a list of NGINX configuration snippets. -There can only be one snippet per context. -Allowed contexts: main, http, http.server, http.server.location.

-
-

SnippetsFilterStatus - -

-

-(Appears on: -SnippetsFilter) -

-

-

SnippetsFilterStatus defines the state of SnippetsFilter.

-

- - - - - - - - - - - - - -
FieldDescription
-controllers
- - -[]ControllerStatus - - -		 -

Controllers is a list of Gateway API controllers that processed the SnippetsFilter -and the status of the SnippetsFilter with respect to each controller.

-
-

SpanAttribute - -

-

-(Appears on: -Telemetry, -Tracing, -Tracing) -

-

-

SpanAttribute is a key value pair to be added to a tracing span.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-key
- -string - -		 -

Key is the key for a span attribute. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’

-
-value
- -string - -		 -

Value is the value for a span attribute. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’

-
-

Telemetry - -

-

-(Appears on: -NginxProxySpec) -

-

-

Telemetry specifies the OpenTelemetry configuration.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-exporter
- - -TelemetryExporter - - -		 -(Optional) -

Exporter specifies OpenTelemetry export parameters.

-
-serviceName
- -string - -		 -(Optional) -

ServiceName is the “service.name” attribute of the OpenTelemetry resource. -Default is ‘ngf::’. If a value is provided by the user, -then the default becomes a prefix to that value.

-
-spanAttributes
- - -[]SpanAttribute - - -		 -(Optional) -

SpanAttributes are custom key/value attributes that are added to each span.

-
-

TelemetryExporter - -

-

-(Appears on: -Telemetry) -

-

-

TelemetryExporter specifies OpenTelemetry export parameters.

-

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-interval
- - -Duration - - -		 -(Optional) -

Interval is the maximum interval between two exports. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter

-
-batchSize
- -int32 - -		 -(Optional) -

BatchSize is the maximum number of spans to be sent in one batch per worker. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter

-
-batchCount
- -int32 - -		 -(Optional) -

BatchCount is the number of pending batches per worker, spans exceeding the limit are dropped. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_exporter

-
-endpoint
- -string - -		 -

Endpoint is the address of OTLP/gRPC endpoint that will accept telemetry data. -Format: alphanumeric hostname with optional http scheme and optional port.

-
-

TraceContext -(string alias)

-

-

-(Appears on: -Tracing) -

-

-

TraceContext specifies how to propagate traceparent/tracestate headers.

-

- - - - - - - - - - - - - - - - -
ValueDescription

"extract"

TraceContextExtract uses an existing trace context from the request, so that the identifiers -of a trace and the parent span are inherited from the incoming request.

-

"ignore"

TraceContextIgnore skips context headers processing.

-

"inject"

TraceContextInject adds a new context to the request, overwriting existing headers, if any.

-

"propagate"

TraceContextPropagate updates the existing context (combines extract and inject).

-
-

TraceStrategy -(string alias)

-

-

-(Appears on: -Tracing) -

-

-

TraceStrategy defines the tracing strategy.

-

- - - - - - - - - - - - -
ValueDescription

"parent"

TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

-

"ratio"

TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

-
-

Tracing - -

-

-(Appears on: -ObservabilityPolicySpec) -

-

-

Tracing allows for enabling and configuring OpenTelemetry tracing.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-strategy
- - -TraceStrategy - - -		 -

Strategy defines if tracing is ratio-based or parent-based.

-
-ratio
- -int32 - -		 -(Optional) -

Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. -By default, 100% of http requests are traced. Not applicable for parent-based tracing. -If ratio is set to 0, tracing is disabled.

-
-context
- - -TraceContext - - -		 -(Optional) -

Context specifies how to propagate traceparent/tracestate headers. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context

-
-spanName
- -string - -		 -(Optional) -

SpanName defines the name of the Otel span. By default is the name of the location for a request. -If specified, applies to all locations that are created for a route. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ -Examples of invalid names: some-$value, quoted-“value”-name, unescaped

-
-spanAttributes
- - -[]SpanAttribute - - -		 -(Optional) -

SpanAttributes are custom key/value attributes that are added to each span.

-
-

UpstreamKeepAlive - -

-

-(Appears on: -UpstreamSettingsPolicySpec) -

-

-

UpstreamKeepAlive defines the keep-alive settings for upstreams.

-

- - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-connections
- -int32 - -		 -(Optional) -

Connections sets the maximum number of idle keep-alive connections to upstream servers that are preserved -in the cache of each nginx worker process. When this number is exceeded, the least recently used -connections are closed. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive

-
-requests
- -int32 - -		 -(Optional) -

Requests sets the maximum number of requests that can be served through one keep-alive connection. -After the maximum number of requests are made, the connection is closed. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_requests

-
-time
- - -Duration - - -		 -(Optional) -

Time defines the maximum time during which requests can be processed through one keep-alive connection. -After this time is reached, the connection is closed following the subsequent request processing. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_time

-
-timeout
- - -Duration - - -		 -(Optional) -

Timeout defines the keep-alive timeout for upstreams. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#keepalive_timeout

-
-

UpstreamSettingsPolicySpec - -

-

-(Appears on: -UpstreamSettingsPolicy) -

-

-

UpstreamSettingsPolicySpec defines the desired state of the UpstreamSettingsPolicy.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-zoneSize
- - -Size - - -		 -(Optional) -

ZoneSize is the size of the shared memory zone used by the upstream. This memory zone is used to share -the upstream configuration between nginx worker processes. The more servers that an upstream has, -the larger memory zone is required. -Default: OSS: 512k, Plus: 1m. -Directive: https://nginx.org/en/docs/http/ngx_http_upstream_module.html#zone

-
-keepAlive
- - -UpstreamKeepAlive - - -		 -(Optional) -

KeepAlive defines the keep-alive settings.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: Service

-

TargetRefs must be distinct. The name field must be unique for all targetRef entries in the UpstreamSettingsPolicy.

-
-
-

gateway.nginx.org/v1alpha2

-

-

Package v1alpha2 contains API Schema definitions for the -gateway.nginx.org API group.

-

-Resource Types: - -

ObservabilityPolicy - -

-

-

ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for -the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the -GatewayClass parametersRef.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-apiVersion
-string		 - -gateway.nginx.org/v1alpha2 - -
-kind
-string -		ObservabilityPolicy
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -ObservabilityPolicySpec - - -		 -

Spec defines the desired state of the ObservabilityPolicy.

-
-
- - - - - - - - - -
-tracing
- - -Tracing - - -		 -(Optional) -

Tracing allows for enabling and configuring tracing.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies the API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: HTTPRoute, GRPCRoute.

-

TargetRefs must be distinct. This means that the multi-part key defined by kind and name must -be unique across all targetRef entries in the ObservabilityPolicy.

-
-
-status
- - -sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus - - -		 -

Status defines the state of the ObservabilityPolicy.

-
-

ObservabilityPolicySpec - -

-

-(Appears on: -ObservabilityPolicy) -

-

-

ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

-

- - - - - - - - - - - - - - - - - -
FieldDescription
-tracing
- - -Tracing - - -		 -(Optional) -

Tracing allows for enabling and configuring tracing.

-
-targetRefs
- - -[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference - - -		 -

TargetRefs identifies the API object(s) to apply the policy to. -Objects must be in the same namespace as the policy. -Support: HTTPRoute, GRPCRoute.

-

TargetRefs must be distinct. This means that the multi-part key defined by kind and name must -be unique across all targetRef entries in the ObservabilityPolicy.

-
-

TraceContext -(string alias)

-

-

-(Appears on: -Tracing) -

-

-

TraceContext specifies how to propagate traceparent/tracestate headers.

-

- - - - - - - - - - - - - - - - -
ValueDescription

"extract"

TraceContextExtract uses an existing trace context from the request, so that the identifiers -of a trace and the parent span are inherited from the incoming request.

-

"ignore"

TraceContextIgnore skips context headers processing.

-

"inject"

TraceContextInject adds a new context to the request, overwriting existing headers, if any.

-

"propagate"

TraceContextPropagate updates the existing context (combines extract and inject).

-
-

TraceStrategy -(string alias)

-

-

-(Appears on: -Tracing) -

-

-

TraceStrategy defines the tracing strategy.

-

- - - - - - - - - - - - -
ValueDescription

"parent"

TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

-

"ratio"

TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

-
-

Tracing - -

-

-(Appears on: -ObservabilityPolicySpec) -

-

-

Tracing allows for enabling and configuring OpenTelemetry tracing.

-

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-strategy
- - -TraceStrategy - - -		 -

Strategy defines if tracing is ratio-based or parent-based.

-
-ratio
- -int32 - -		 -(Optional) -

Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. -By default, 100% of http requests are traced. Not applicable for parent-based tracing. -If ratio is set to 0, tracing is disabled.

-
-context
- - -TraceContext - - -		 -(Optional) -

Context specifies how to propagate traceparent/tracestate headers. -Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context

-
-spanName
- -string - -		 -(Optional) -

SpanName defines the name of the Otel span. By default is the name of the location for a request. -If specified, applies to all locations that are created for a route. -Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ -Examples of invalid names: some-$value, quoted-“value”-name, unescaped

-
-spanAttributes
- - -[]SpanAttribute - - -		 -(Optional) -

SpanAttributes are custom key/value attributes that are added to each span.

-
-
-

-Generated with gen-crd-api-reference-docs -

diff --git a/site/content/reference/cli-help.md b/site/content/reference/cli-help.md deleted file mode 100644 index aedcc0e74c..0000000000 --- a/site/content/reference/cli-help.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Command-line reference guide" -weight: 100 -toc: true -docs: "DOCS-1435" ---- - -## Overview - -Learn about the commands available for the executable file of the NGINX Gateway Fabric container. - -## Static mode - -This command configures NGINX for a single NGINX Gateway Fabric resource. - -*Usage*: - -```shell - gateway static-mode [flags] -``` - -### Flags - -{{< bootstrap-table "table table-bordered table-striped table-responsive" >}} - -| Name | Type | Description | -|-------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| _gateway-ctlr-name_ | _string_ | The name of the Gateway controller. The controller name must be in the form: `DOMAIN/PATH`. The controller's domain is `gateway.nginx.org`. | -| _gatewayclass_ | _string_ | The name of the GatewayClass resource. Every NGINX Gateway Fabric must have a unique corresponding GatewayClass resource. | -| _gateway_ | _string_ | The namespaced name of the Gateway resource to use. Must be of the form: `NAMESPACE/NAME`. If not specified, the control plane will process all Gateways for the configured GatewayClass. Among them, it will choose the oldest resource by creation timestamp. If the timestamps are equal, it will choose the resource that appears first in alphabetical order by {namespace}/{name}. | -| _nginx-plus_ | _bool_ | Enable support for NGINX Plus. | -| _gateway-api-experimental-features_ | _bool_ | Enable the experimental features of Gateway API which are supported by NGINX Gateway Fabric. Requires the Gateway APIs installed from the experimental channel. | -| _config_ | _string_ | The name of the NginxGateway resource to be used for this controller's dynamic configuration. Lives in the same namespace as the controller. | -| _service_ | _string_ | The name of the service that fronts this NGINX Gateway Fabric pod. Lives in the same namespace as the controller. | -| _metrics-disable_ | _bool_ | Disable exposing metrics in the Prometheus format (Default: `false`). | -| _metrics-listen-port_ | _int_ | Sets the port where the Prometheus metrics are exposed. An integer between 1024 - 65535 (Default: `9113`) | -| _metrics-secure-serving_ | _bool_ | Configures if the metrics endpoint should be secured using https. Note that this endpoint will be secured with a self-signed certificate (Default `false`). | -| _update-gatewayclass-status_ | _bool_ | Update the status of the GatewayClass resource (Default: `true`). | -| _health-disable_ | _bool_ | Disable running the health probe server (Default: `false`). | -| _health-port_ | _int_ | Set the port where the health probe server is exposed. An integer between 1024 - 65535 (Default: `8081`). | -| _leader-election-disable_ | _bool_ | Disable leader election, which is used to avoid multiple replicas of the NGINX Gateway Fabric reporting the status of the Gateway API resources. If disabled, all replicas of NGINX Gateway Fabric will update the statuses of the Gateway API resources (Default: `false`). | -| _leader-election-lock-name_ | _string_ | The name of the leader election lock. A lease object with this name will be created in the same namespace as the controller (Default: `"nginx-gateway-leader-election-lock"`). | -| _product-telemetry-disable_ | _bool_ | Disable the collection of product telemetry (Default: `false`). | -| _usage-report-secret_ | _string_ | The name of the Secret containing the JWT for NGINX Plus usage reporting. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway) | -| _usage-report-endpoint_ | _string_ | The endpoint of the NGINX Plus usage reporting server. | -| _usage-report-resolver_ | _string_ | The nameserver used to resolve the NGINX Plus usage reporting endpoint. Used with NGINX Instance Manager. | -| _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_ | TThe 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) | -| _snippets-filters_ | _bool_ | Enable SnippetsFilters feature. SnippetsFilters allow inserting NGINX configuration into the generated NGINX config for HTTPRoute and GRPCRoute resources. | - -{{% /bootstrap-table %}} - -## Sleep - -This command sleeps for specified duration, then exits. - -_Usage_: - -```shell - gateway sleep [flags] -``` - -{{< bootstrap-table "table table-bordered table-striped table-responsive" >}} - -| Name | Type | Description | -| -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| duration | `time.Duration` | Set the duration of sleep. Must be parsable by [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration). (default `30s`) | - -{{% /bootstrap-table %}} diff --git a/site/content/reference/technical-specifications.md b/site/content/reference/technical-specifications.md deleted file mode 100644 index 97bb523ba5..0000000000 --- a/site/content/reference/technical-specifications.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Technical specifications" -draft: false -description: "NGINX Gateway Fabric technical specifications." -weight: 200 -toc: true -tags: [ "docs" ] -docs: "DOCS-1434" ---- - -See the NGINX Gateway Fabric technical specifications page: - - diff --git a/site/content/releases.md b/site/content/releases.md deleted file mode 100644 index fb2991857a..0000000000 --- a/site/content/releases.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: "Releases" -description: "NGINX Gateway Fabric releases." -toc: true -weight: 700 -docs: "DOCS-1359" ---- - -See the NGINX Gateway Fabric changelog page: - - diff --git a/site/content/support.md b/site/content/support.md deleted file mode 100644 index c62d4f723d..0000000000 --- a/site/content/support.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: "Support" -toc: true -weight: 600 -docs: "DOCS-1411" ---- - -F5 NGINX Gateway Fabric adheres to the support policy detailed in the following knowledge base article: [K000140156](https://my.f5.com/manage/s/article/K000140156). - -After opening a support ticket, F5 staff will request additional information to better understand the problem. - -The [nginx-supportpkg-for-k8s](https://github.com/nginxinc/nginx-supportpkg-for-k8s) plugin collects the information needed by F5 Technical Support to assist with troubleshooting your issue. - -The plugin uses [krew](https://krew.sigs.k8s.io), the plugin manager for the Kubernetes [kubectl](https://kubernetes.io/docs/reference/kubectl/) command-line tool. - -The plugin may collect some or all of the following global and namespace-specific information: - -- Kubernetes version and information about Nodes and Custom Resources -- Kubernetes metrics -- Helm deployments -- List of Pods, Events, ConfigMaps, Services, Deployments, Daemonsets, StatefulSets, ReplicaSets, and Leases -- Pod log output -- `nginx -T` output from NGINX-related Pods - -This plugin **does not** collect secrets or coredumps. - -Visit the [project’s GitHub repository](https://github.com/nginxinc/nginx-supportpkg-for-k8s) for further details. - - -**Support Channels:** - -- If you experience issues with NGINX Gateway Fabric, please [open an issue](https://github.com/nginx/nginx-gateway-fabric/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=) in GitHub. - -- If you have any suggestions or enhancement requests, please [open an idea](https://github.com/nginx/nginx-gateway-fabric/discussions/categories/ideas) on GitHub discussions. - -- You can contact us directly, by sending an email to [kubernetes@nginx.com](mailto:kubernetes@nginx.com) or on the [NGINX Community Slack](https://nginxcommunity.slack.com/channels/nginx-gateway-fabric), in the #nginx-gateway-fabric channel. - -- If you need dedicated support for NGINX Gateway Fabric, or you would like to leverage our [advanced NGINX Plus features](https://docs.nginx.com/nginx-gateway-fabric/overview/nginx-plus/), you can contact [F5 Sales](https://www.f5.com/content/f5-com/en_us/products/get-f5). diff --git a/site/go.mod b/site/go.mod deleted file mode 100644 index 942de55c3a..0000000000 --- a/site/go.mod +++ /dev/null @@ -1,5 +0,0 @@ -module github.com/nginx/nginx-gateway-fabric/site - -go 1.21.0 - -require github.com/nginxinc/nginx-hugo-theme v0.41.23 // indirect diff --git a/site/go.sum b/site/go.sum deleted file mode 100644 index 6bf2752ad6..0000000000 --- a/site/go.sum +++ /dev/null @@ -1,2 +0,0 @@ -github.com/nginxinc/nginx-hugo-theme v0.41.23 h1:ddIfLF7BFd78qyIn3z5aReeC4BO/m9FH81d5S+al/6s= -github.com/nginxinc/nginx-hugo-theme v0.41.23/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M= diff --git a/site/hugo-entrypoint.sh b/site/hugo-entrypoint.sh deleted file mode 100755 index 7462155cdf..0000000000 --- a/site/hugo-entrypoint.sh +++ /dev/null @@ -1,4 +0,0 @@ -#!/bin/sh - -hugo mod get -u github.com/nginxinc/nginx-hugo-theme -hugo --environment docker $* diff --git a/site/layouts/shortcodes/call-out.html b/site/layouts/shortcodes/call-out.html deleted file mode 100644 index d8e591d832..0000000000 --- a/site/layouts/shortcodes/call-out.html +++ /dev/null @@ -1,3 +0,0 @@ -
-
{{ .Get 1 }}
{{ .Inner | markdownify }}
-
diff --git a/site/layouts/shortcodes/custom-styles.html b/site/layouts/shortcodes/custom-styles.html deleted file mode 100644 index 8ec2a0bbf4..0000000000 --- a/site/layouts/shortcodes/custom-styles.html +++ /dev/null @@ -1,43 +0,0 @@ - diff --git a/site/md-linkcheck-config.json b/site/md-linkcheck-config.json deleted file mode 100644 index aff3727179..0000000000 --- a/site/md-linkcheck-config.json +++ /dev/null @@ -1,13 +0,0 @@ -{ - "replacementPatterns": [ - { - "pattern": "^/", - "replacement": "/" - } - ], - "ignorePatterns": [ - { - "pattern": "^.+localhost.+$|/.+yaml" - } - ] -} diff --git a/site/static/grafana-dashboard.json b/site/static/grafana-dashboard.json deleted file mode 100644 index 0c3c40392d..0000000000 --- a/site/static/grafana-dashboard.json +++ /dev/null @@ -1,815 +0,0 @@ -{ - "annotations": { - "list": [ - { - "builtIn": 1, - "datasource": { - "type": "grafana", - "uid": "-- Grafana --" - }, - "enable": true, - "hide": true, - "iconColor": "rgba(0, 211, 255, 1)", - "name": "Annotations & Alerts", - "type": "dashboard" - } - ] - }, - "description": "Sample dashboard for NGINX Gateway Fabric", - "editable": true, - "fiscalYearStartMonth": 0, - "graphTooltip": 0, - "id": 1, - "links": [], - "liveNow": false, - "panels": [ - { - "collapsed": false, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 0 - }, - "id": 5, - "panels": [], - "title": "Status", - "type": "row" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "fieldConfig": { - "defaults": { - "color": { - "mode": "thresholds" - }, - "mappings": [ - { - "options": { - "0": { - "index": 0, - "text": "Down" - }, - "1": { - "index": 1, - "text": "Up" - } - }, - "type": "value" - } - ], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "semi-dark-red", - "value": null - }, - { - "color": "#EAB839", - "value": 1 - }, - { - "color": "semi-dark-green", - "value": 1 - } - ] - }, - "unit": "none", - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 4, - "w": 6, - "x": 0, - "y": 1 - }, - "id": 3, - "options": { - "colorMode": "background", - "graphMode": "none", - "justifyMode": "auto", - "orientation": "horizontal", - "reduceOptions": { - "calcs": [ - "lastNotNull" - ], - "fields": "", - "values": false - }, - "showPercentChange": false, - "textMode": "auto", - "wideLayout": true - }, - "pluginVersion": "10.3.3", - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "builder", - "expr": "nginx_gateway_fabric_up{instance=~\"$instance\"}", - "fullMetaSearch": false, - "includeNullMetadata": true, - "instant": false, - "legendFormat": "", - "range": true, - "refId": "A", - "useBackend": false - } - ], - "title": "NGINX Status for $instance", - "type": "stat" - }, - { - "collapsed": false, - "gridPos": { - "h": 1, - "w": 24, - "x": 0, - "y": 5 - }, - "id": 6, - "panels": [], - "title": "Metrics", - "type": "row" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "description": "", - "fieldConfig": { - "defaults": { - "color": { - "mode": "palette-classic" - }, - "custom": { - "axisBorderShow": false, - "axisCenteredZero": false, - "axisColorMode": "text", - "axisLabel": "Connections (rate)", - "axisPlacement": "auto", - "barAlignment": 0, - "drawStyle": "line", - "fillOpacity": 10, - "gradientMode": "none", - "hideFrom": { - "legend": false, - "tooltip": false, - "viz": false - }, - "insertNulls": false, - "lineInterpolation": "linear", - "lineWidth": 1, - "pointSize": 1, - "scaleDistribution": { - "type": "linear" - }, - "showPoints": "auto", - "spanNulls": false, - "stacking": { - "group": "A", - "mode": "none" - }, - "thresholdsStyle": { - "mode": "off" - } - }, - "mappings": [], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - } - ] - }, - "unit": "reqps", - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 10, - "w": 12, - "x": 0, - "y": 6 - }, - "id": 1, - "options": { - "legend": { - "calcs": [], - "displayMode": "list", - "placement": "bottom", - "showLegend": true - }, - "tooltip": { - "mode": "single", - "sort": "none" - } - }, - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "code", - "expr": "irate(nginx_gateway_fabric_connections_accepted{instance=~\"$instance\"}[1m])", - "fullMetaSearch": false, - "includeNullMetadata": false, - "instant": false, - "interval": "", - "legendFormat": "{{instance}} accepted", - "range": true, - "refId": "A", - "useBackend": false - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "editorMode": "code", - "expr": "irate(nginx_gateway_fabric_connections_handled{instance=~\"$instance\"}[1m])", - "hide": false, - "instant": false, - "legendFormat": "{{instance}} handled", - "range": true, - "refId": "B" - } - ], - "title": "Processed Connections", - "type": "timeseries" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "description": "", - "fieldConfig": { - "defaults": { - "color": { - "mode": "palette-classic" - }, - "custom": { - "axisBorderShow": false, - "axisCenteredZero": false, - "axisColorMode": "text", - "axisLabel": "Connections", - "axisPlacement": "auto", - "barAlignment": 0, - "drawStyle": "line", - "fillOpacity": 10, - "gradientMode": "none", - "hideFrom": { - "legend": false, - "tooltip": false, - "viz": false - }, - "insertNulls": false, - "lineInterpolation": "linear", - "lineWidth": 1, - "pointSize": 1, - "scaleDistribution": { - "type": "linear" - }, - "showPoints": "auto", - "spanNulls": false, - "stacking": { - "group": "A", - "mode": "none" - }, - "thresholdsStyle": { - "mode": "off" - } - }, - "mappings": [], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - } - ] - }, - "unit": "short", - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 10, - "w": 12, - "x": 12, - "y": 6 - }, - "id": 4, - "options": { - "legend": { - "calcs": [], - "displayMode": "list", - "placement": "bottom", - "showLegend": true - }, - "tooltip": { - "mode": "single", - "sort": "none" - } - }, - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "editorMode": "code", - "expr": "nginx_gateway_fabric_connections_active{instance=~\"$instance\"}", - "instant": false, - "legendFormat": "{{instance}} active", - "range": true, - "refId": "A" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "editorMode": "code", - "expr": "nginx_gateway_fabric_connections_reading{instance=~\"$instance\"}", - "hide": false, - "instant": false, - "legendFormat": "{{instance}} reading", - "range": true, - "refId": "B" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "editorMode": "code", - "expr": "nginx_gateway_fabric_connections_waiting{instance=~\"$instance\"}", - "hide": false, - "instant": false, - "legendFormat": "{{instance}} waiting", - "range": true, - "refId": "C" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "editorMode": "code", - "expr": "nginx_gateway_fabric_connections_writing{instance=~\"$instance\"}", - "hide": false, - "instant": false, - "legendFormat": "{{instance}} writing", - "range": true, - "refId": "D" - } - ], - "title": "Active Connections", - "type": "timeseries" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "fieldConfig": { - "defaults": { - "color": { - "mode": "palette-classic" - }, - "custom": { - "axisBorderShow": false, - "axisCenteredZero": false, - "axisColorMode": "text", - "axisLabel": "", - "axisPlacement": "auto", - "barAlignment": 0, - "drawStyle": "line", - "fillOpacity": 10, - "gradientMode": "none", - "hideFrom": { - "legend": false, - "tooltip": false, - "viz": false - }, - "insertNulls": false, - "lineInterpolation": "linear", - "lineWidth": 1, - "pointSize": 1, - "scaleDistribution": { - "type": "linear" - }, - "showPoints": "auto", - "spanNulls": false, - "stacking": { - "group": "A", - "mode": "none" - }, - "thresholdsStyle": { - "mode": "off" - } - }, - "mappings": [], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - } - ] - }, - "unit": "reqps", - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 8, - "w": 24, - "x": 0, - "y": 16 - }, - "id": 2, - "options": { - "legend": { - "calcs": [], - "displayMode": "list", - "placement": "bottom", - "showLegend": true - }, - "tooltip": { - "mode": "single", - "sort": "none" - } - }, - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "code", - "expr": "irate(nginx_gateway_fabric_http_requests_total{instance=~\"$instance\"}[1m])", - "fullMetaSearch": false, - "includeNullMetadata": false, - "instant": false, - "legendFormat": "{{instance}} total requests", - "range": true, - "refId": "A", - "useBackend": false - } - ], - "title": "Total Requests", - "type": "timeseries" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "fieldConfig": { - "defaults": { - "color": { - "mode": "palette-classic" - }, - "custom": { - "axisBorderShow": false, - "axisCenteredZero": false, - "axisColorMode": "text", - "axisLabel": "", - "axisPlacement": "auto", - "barAlignment": 0, - "drawStyle": "line", - "fillOpacity": 10, - "gradientMode": "none", - "hideFrom": { - "legend": false, - "tooltip": false, - "viz": false - }, - "insertNulls": false, - "lineInterpolation": "linear", - "lineWidth": 1, - "pointSize": 1, - "scaleDistribution": { - "type": "linear" - }, - "showPoints": "auto", - "spanNulls": false, - "stacking": { - "group": "A", - "mode": "none" - }, - "thresholdsStyle": { - "mode": "off" - } - }, - "mappings": [], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - } - ] - }, - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 8, - "w": 12, - "x": 0, - "y": 24 - }, - "id": 8, - "options": { - "legend": { - "calcs": [], - "displayMode": "list", - "placement": "bottom", - "showLegend": true - }, - "tooltip": { - "mode": "single", - "sort": "none" - } - }, - "pluginVersion": "10.3.3", - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "code", - "expr": "irate(nginx_gateway_fabric_nginx_reloads_total{instance=~\"$instance\"}[1m])", - "fullMetaSearch": false, - "includeNullMetadata": false, - "instant": false, - "legendFormat": "{{instance}}", - "range": true, - "refId": "A", - "useBackend": false - } - ], - "title": "Total NGINX Reloads Rate", - "type": "timeseries" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "fieldConfig": { - "defaults": { - "color": { - "mode": "thresholds" - }, - "mappings": [], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - }, - { - "color": "red", - "value": 1 - } - ] - }, - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 12, - "y": 24 - }, - "id": 9, - "options": { - "colorMode": "value", - "graphMode": "area", - "justifyMode": "auto", - "orientation": "auto", - "reduceOptions": { - "calcs": [ - "lastNotNull" - ], - "fields": "", - "values": false - }, - "showPercentChange": false, - "textMode": "auto", - "wideLayout": true - }, - "pluginVersion": "10.3.3", - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "builder", - "expr": "nginx_gateway_fabric_nginx_reload_errors_total{instance=~\"$instance\"}", - "fullMetaSearch": false, - "includeNullMetadata": true, - "instant": false, - "legendFormat": "{{instance}}", - "range": true, - "refId": "A", - "useBackend": false - } - ], - "title": "Total NGINX Reload Errors", - "type": "stat" - }, - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "fieldConfig": { - "defaults": { - "color": { - "mode": "thresholds" - }, - "mappings": [ - { - "options": { - "0": { - "color": "semi-dark-green", - "index": 0, - "text": "Up to date" - }, - "1": { - "color": "semi-dark-red", - "index": 1, - "text": "Stale" - } - }, - "type": "value" - } - ], - "thresholds": { - "mode": "absolute", - "steps": [ - { - "color": "green", - "value": null - }, - { - "color": "semi-dark-red", - "value": 1 - } - ] - }, - "unitScale": true - }, - "overrides": [] - }, - "gridPos": { - "h": 8, - "w": 6, - "x": 18, - "y": 24 - }, - "id": 10, - "options": { - "colorMode": "value", - "graphMode": "area", - "justifyMode": "auto", - "orientation": "auto", - "reduceOptions": { - "calcs": [ - "lastNotNull" - ], - "fields": "", - "values": false - }, - "showPercentChange": false, - "textMode": "auto", - "wideLayout": true - }, - "pluginVersion": "10.3.3", - "targets": [ - { - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "disableTextWrap": false, - "editorMode": "builder", - "expr": "nginx_gateway_fabric_nginx_stale_config{instance=~\"$instance\"}", - "fullMetaSearch": false, - "includeNullMetadata": true, - "instant": false, - "legendFormat": "__auto", - "range": true, - "refId": "A", - "useBackend": false - } - ], - "title": "NGINX Config State", - "type": "stat" - } - ], - "refresh": "5s", - "schemaVersion": 39, - "tags": [ - "nginx-gateway-fabric" - ], - "templating": { - "list": [ - { - "current": { - "selected": false, - "text": "default", - "value": "default" - }, - "hide": 0, - "includeAll": false, - "label": "datasource", - "multi": false, - "name": "DS_PROMETHEUS", - "options": [], - "query": "prometheus", - "queryValue": "", - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "type": "datasource" - }, - { - "current": { - "selected": true, - "text": [ - "All" - ], - "value": [ - "$__all" - ] - }, - "datasource": { - "type": "prometheus", - "uid": "${DS_PROMETHEUS}" - }, - "definition": "label_values(nginx_gateway_fabric_up,instance)", - "hide": 0, - "includeAll": true, - "multi": true, - "name": "instance", - "options": [], - "query": { - "qryType": 1, - "query": "label_values(nginx_gateway_fabric_up,instance)", - "refId": "PrometheusVariableQueryEditor-VariableQuery" - }, - "refresh": 1, - "regex": "", - "skipUrlSync": false, - "sort": 0, - "type": "query" - } - ] - }, - "time": { - "from": "now-15m", - "to": "now" - }, - "timepicker": {}, - "timezone": "", - "title": "NGINX Gateway Fabric", - "uid": "cdb1c6f6-7c77-4cee-a177-593f41364dbe", - "version": 1, - "weekStart": "" -} diff --git a/site/static/img/advanced-routing.png b/site/static/img/advanced-routing.png deleted file mode 100644 index 9be8d7c509..0000000000 Binary files a/site/static/img/advanced-routing.png and /dev/null differ diff --git a/site/static/img/cert-manager-gateway-workflow.png b/site/static/img/cert-manager-gateway-workflow.png deleted file mode 100644 index c4de785951..0000000000 Binary files a/site/static/img/cert-manager-gateway-workflow.png and /dev/null differ diff --git a/site/static/img/direct-policy-attachment.png b/site/static/img/direct-policy-attachment.png deleted file mode 100644 index 618dc1cded..0000000000 Binary files a/site/static/img/direct-policy-attachment.png and /dev/null differ diff --git a/site/static/img/hierarchy.png b/site/static/img/hierarchy.png deleted file mode 100644 index 2bdc19936c..0000000000 Binary files a/site/static/img/hierarchy.png and /dev/null differ diff --git a/site/static/img/inherited-policy-attachment.png b/site/static/img/inherited-policy-attachment.png deleted file mode 100644 index 6c368cc756..0000000000 Binary files a/site/static/img/inherited-policy-attachment.png and /dev/null differ diff --git a/site/static/img/jaeger-trace-attributes.png b/site/static/img/jaeger-trace-attributes.png deleted file mode 100644 index ea8d383b11..0000000000 Binary files a/site/static/img/jaeger-trace-attributes.png and /dev/null differ diff --git a/site/static/img/jaeger-trace-overview.png b/site/static/img/jaeger-trace-overview.png deleted file mode 100644 index 309c826917..0000000000 Binary files a/site/static/img/jaeger-trace-overview.png and /dev/null differ diff --git a/site/static/img/ngf-high-level.png b/site/static/img/ngf-high-level.png deleted file mode 100644 index 6f2bef6f05..0000000000 Binary files a/site/static/img/ngf-high-level.png and /dev/null differ diff --git a/site/static/img/ngf-pod.png b/site/static/img/ngf-pod.png deleted file mode 100644 index d7b67e5b04..0000000000 Binary files a/site/static/img/ngf-pod.png and /dev/null differ diff --git a/site/static/img/nginx-plus-dashboard.png b/site/static/img/nginx-plus-dashboard.png deleted file mode 100644 index 26f8726c22..0000000000 Binary files a/site/static/img/nginx-plus-dashboard.png and /dev/null differ diff --git a/site/static/img/route-all-traffic-app.png b/site/static/img/route-all-traffic-app.png deleted file mode 100644 index 6de84f7b09..0000000000 Binary files a/site/static/img/route-all-traffic-app.png and /dev/null differ diff --git a/site/static/img/route-all-traffic-config.png b/site/static/img/route-all-traffic-config.png deleted file mode 100644 index 01ae221030..0000000000 Binary files a/site/static/img/route-all-traffic-config.png and /dev/null differ diff --git a/site/static/img/route-all-traffic-flow.png b/site/static/img/route-all-traffic-flow.png deleted file mode 100644 index 04a09c94cc..0000000000 Binary files a/site/static/img/route-all-traffic-flow.png and /dev/null differ diff --git a/site/static/img/src/README.md b/site/static/img/src/README.md deleted file mode 100644 index 02c93c4d41..0000000000 --- a/site/static/img/src/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Diagram Source Files - -This directory contains the source files for the diagrams used in the docs. Source files are named after the image name. diff --git a/site/static/img/src/advanced-routing.mermaid b/site/static/img/src/advanced-routing.mermaid deleted file mode 100644 index dda2c78883..0000000000 --- a/site/static/img/src/advanced-routing.mermaid +++ /dev/null @@ -1,38 +0,0 @@ -%% mermaid source for advanced-routing.png diagram -graph LR - users[Users] - ngfSvc["Public Endpoint\nfor\ncafe.example.com"] - subgraph cluster [Kubernetes Cluster] - subgraph clusterPadding [" "] - subgraph clusterPadding2 [" "] - subgraph gwNS [Namespace\nnginx-gateway] - ngfPod[Pod\nnginx-gateway] - end - end - end - subgraph appNs [Namespace\ndefault] - subgraph nsPadding [" "] - coffeeV1Pod[Pod\ncoffee v1] - coffeeV2Pod[Pod\ncoffee v2] - teaPod[Pod\ntea] - teaPostPod[Pod\ntea-post] - end - end - end - ngfSvc --> ngfPod - ngfPod --/coffee--> coffeeV1Pod - ngfPod --/coffee\nheader: version=v2\nOR\n/coffee?TEST=v2--> coffeeV2Pod - ngfPod --GET /tea--> teaPod - ngfPod --POST /tea--> teaPostPod - users --> ngfSvc - class clusterPadding,nsPadding,clusterPadding2 noBorder - class gwNS,appNs namespace - class ngfSvc,ngfPod nginxNode - class coffeeV1Pod,coffeeV2Pod coffeeNode - class teaPod,teaPostPod teaNode - classDef noBorder stroke:none,fill:none - classDef default fill:#FFFFFF,stroke:#000000 - classDef namespace fill:#FFFFFF,stroke:#036ffc,stroke-dasharray: 5 5,text-align:center - classDef nginxNode fill:#b4e0ad,stroke:#2AA317 - classDef coffeeNode fill:#edbd8c,stroke:#D9822B - classDef teaNode fill:#ff8f6a,stroke:#e5805f diff --git a/site/static/img/src/route-all-traffic-app.mermaid b/site/static/img/src/route-all-traffic-app.mermaid deleted file mode 100644 index bc2d4d7063..0000000000 --- a/site/static/img/src/route-all-traffic-app.mermaid +++ /dev/null @@ -1,13 +0,0 @@ -%% mermaid source for route-all-traffic-app.png diagram -graph TB - subgraph cluster [Kubernetes Cluster] - style cluster fill:#FFFFFF,stroke:#000000 - svc[Service\ncoffee] - pod1[Pod\ncoffee] - pod2[Pod\ncoffee] - end - - svc --> pod1 & pod2 - - class pod1,pod2,svc appNode - classDef appNode fill:#edbd8c,stroke:#D9822B diff --git a/site/static/img/src/route-all-traffic-config.mermaid b/site/static/img/src/route-all-traffic-config.mermaid deleted file mode 100644 index d2e0a4ffc9..0000000000 --- a/site/static/img/src/route-all-traffic-config.mermaid +++ /dev/null @@ -1,42 +0,0 @@ -%% mermaid source for route-all-traffic-config.png diagram -graph LR - subgraph config [Namespace default] - subgraph padding [" "] - direction LR - style config fill:#FFFFFF,stroke:#000000 - subgraph gw[Gateway cafe] - subgraph gwPadding [" "] - gwContents[HTTP/80] - end - end - subgraph hr[HTTPRoute coffee] - subgraph hrPadding [" "] - hrContents[cafe.example.com] - subgraph describeMatchAll [Match all\ntraffic] - subgraph describeMatchPadding [" "] - matchAll[Host: *\nPath: *] - end - end - subgraph describeService [Group matching\npods within a Service] - subgraph describePadding [" "] - coffeeSvc[Service\ncoffee] - end - end - end - end - end - end - - gwContents --> hrContents --> matchAll --> coffeeSvc - class padding,gwPadding,hrPadding,describeMatchAll,describeService,describePadding,describeMatchPadding noBorder - class gw gateway - class hr httpRoute - class matchAll,hrContents,coffeeSvc appDevNode - class gwContents clusterOppNode - - classDef noBorder stroke:none,fill:none,text-align:center - classDef default fill:#FFFFFF,stroke:#000000 - classDef gateway fill:#FFFFFF,stroke:#2AA317,stroke-dasharray: 3 3,text-align:center - classDef httpRoute fill:#FFFFFF,stroke:#D9822B,stroke-dasharray: 3 3,text-align:center - classDef appDevNode fill:#edbd8c,stroke:#D9822B - classDef clusterOppNode fill:#b4e0ad,stroke:#2AA317 diff --git a/site/static/img/src/route-all-traffic-flow.mermaid b/site/static/img/src/route-all-traffic-flow.mermaid deleted file mode 100644 index f53d35ae54..0000000000 --- a/site/static/img/src/route-all-traffic-flow.mermaid +++ /dev/null @@ -1,42 +0,0 @@ -%% mermaid source for route-all-traffic-flow.png diagram -graph LR - clients[Clients] - ngfSvc["Public IP Address\nfor\ncafe.example.com"] - - subgraph cluster [Kubernetes Cluster] - style cluster fill:#FFFFFF,stroke:#000000 - subgraph clusterPadding [" "] - subgraph clusterPadding2 [" "] - subgraph gwNS [Namespace\nnginx-gateway] - ngfPod[Pod\nnginx-gateway] - end - end - end - - subgraph appNs [Namespace\ndefault] - subgraph nsPadding [" "] - coffeePod1[Pod\ncoffee] - coffeePod2[Pod\ncoffee] - end - end - end - - - - ngfSvc --> ngfPod - ngfPod --> coffeePod1 & coffeePod2 - clients --> ngfSvc - - class clusterPadding,nsPadding,clusterPadding2 noBorder - class gwNS,appNs namespace - class ngfPod,ngfSvc nginxNode - class coffeePod1,coffeePod2 coffeeNode - class clients clientNode - - - classDef noBorder stroke:none,fill:none - classDef default fill:#FFFFFF,stroke:#000000 - classDef namespace fill:#FFFFFF,stroke:#036ffc,stroke-dasharray: 5 5,text-align:center - classDef nginxNode fill:#b4e0ad,stroke:#2AA317 - classDef coffeeNode fill:#edbd8c,stroke:#D9822B - classDef clientNode fill:#D3D3D3 diff --git a/site/static/jaeger.yaml b/site/static/jaeger.yaml deleted file mode 100644 index 9f1a11c275..0000000000 --- a/site/static/jaeger.yaml +++ /dev/null @@ -1,37 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: jaeger - labels: - app.kubernetes.io/name: jaeger -spec: - replicas: 1 - selector: - matchLabels: - app.kubernetes.io/name: jaeger - template: - metadata: - labels: - app.kubernetes.io/name: jaeger - spec: - containers: - - name: jaeger - image: jaegertracing/all-in-one:latest - ports: - - containerPort: 16686 - - containerPort: 4317 ---- -apiVersion: v1 -kind: Service -metadata: - name: jaeger - labels: - app.kubernetes.io/name: jaeger -spec: - selector: - app.kubernetes.io/name: jaeger - ports: - - name: frontend - port: 16686 - - name: collector - port: 4317 diff --git a/site/static/otel-collector.yaml b/site/static/otel-collector.yaml deleted file mode 100644 index ff2fe807fb..0000000000 --- a/site/static/otel-collector.yaml +++ /dev/null @@ -1,72 +0,0 @@ -apiVersion: v1 -kind: ConfigMap -metadata: - name: otel-collector-config -data: - otel-collector-config: | - receivers: - otlp: - protocols: - grpc: - endpoint: 0.0.0.0:4317 - processors: - extensions: - exporters: - otlp/jaeger: - endpoint: "jaeger.tracing.svc:4317" - tls: - insecure: true - service: - pipelines: - traces: - receivers: [otlp] - processors: [] - exporters: [otlp/jaeger] ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: otel-collector - labels: - app.kubernetes.io/name: otel-collector -spec: - selector: - matchLabels: - app.kubernetes.io/name: otel-collector - replicas: 1 - template: - metadata: - labels: - app.kubernetes.io/name: otel-collector - spec: - containers: - - name: otel-collector - image: otel/opentelemetry-collector:latest - command: - - /otelcol - - --config=/conf/otel-collector-config.yaml - ports: - - containerPort: 4317 - volumeMounts: - - name: otel-collector-config - mountPath: /conf - volumes: - - name: otel-collector-config - configMap: - name: otel-collector-config - items: - - key: otel-collector-config - path: otel-collector-config.yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: otel-collector - labels: - app.kubernetes.io/name: otel-collector -spec: - selector: - app.kubernetes.io/name: otel-collector - ports: - - name: otlp-grpc - port: 4317