Auto-generate annotation docs (#11831)

Co-authored-by: Ricardo Katz <ricardo.katz@gmail.com>

.github/workflows/ci.yaml

@@ -69,6 +69,8 @@ jobs:
             baseimage:
               - 'NGINX_BASE'
               - 'images/nginx-1.25/**'
+            docs:
+              - '**/*.md'
 
   test-go:
     runs-on: ubuntu-latest
@@ -92,6 +94,27 @@ jobs:
       - name: Run test
         run: make test
 
+
+  verify-docs:
+    name: Verify Doc generation
+    runs-on: ubuntu-latest
+    needs: changes
+    if: |
+      (needs.changes.outputs.go == 'true') || (needs.changes.outputs.docs == 'true') || ${{ github.event.workflow_dispatch.run_e2e == 'true' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Get go version
+        run: echo "GOLANG_VERSION=$(cat GOLANG_VERSION)" >> $GITHUB_ENV
+      - name: Set up Go
+        id: go
+        uses: actions/setup-go@0a12ed9d6a96ab950c8f026ed9f722fe0da7ef32 # v5.0.2
+        with:
+          go-version: ${{ env.GOLANG_VERSION }}
+          check-latest: true
+      - name: Verify Docs
+        run: make verify-docs
+
   build:
     name: Build
     runs-on: ubuntu-latest

Makefile

@@ -124,6 +124,9 @@ build:  ## Build ingress controller, debug tool and pre-stop hook.
 clean: ## Remove .gocache directory.
 	rm -rf bin/ .gocache/ .cache/
 
+.PHONY: verify-docs
+verify-docs: ## Verify doc generation
+	hack/verify-annotation-docs.sh
 
 .PHONY: static-check
 static-check: ## Run verification script for boilerplate, codegen, gofmt, golint, lualint and chart-lint.

cmd/annotations/annotations.tmpl

@@ -0,0 +1,7 @@
+# Annotations Scope and Risk
+
+|Group   |Annotation        | Risk | Scope |
+|--------|------------------|------|-------|
+{{- range $doc := . }}
+| {{ $doc.Group }} | {{ $doc.Annotation }} | {{ $doc.Risk }} | {{ $doc.Scope }} |
+{{- end }}

cmd/annotations/main.go

@@ -0,0 +1,91 @@
+/*
+Copyright 2024 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"bytes"
+	"embed"
+	"flag"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+	"text/template"
+
+	anns "k8s.io/ingress-nginx/internal/ingress/annotations"
+)
+
+type Documentation struct {
+	Group      string
+	Annotation string
+	Risk       string
+	Scope      string
+}
+
+var output string
+
+//go:embed annotations.tmpl
+var content embed.FS
+
+func main() {
+	flag.StringVar(&output, "output", "", "where to write documentation")
+	flag.Parse()
+	if output == "" {
+		panic(fmt.Errorf("output field is required"))
+	}
+	docEntries := make([]Documentation, 0)
+	annotationFactory := anns.NewAnnotationFactory(nil)
+	for group, val := range annotationFactory {
+		annotations := val.GetDocumentation()
+		intermediateDocs := make([]Documentation, len(annotations))
+		i := 0
+		for annotation, values := range annotations {
+			doc := Documentation{
+				Group:      group,
+				Annotation: annotation,
+				Scope:      string(values.Scope),
+				Risk:       values.Risk.ToString(),
+			}
+			intermediateDocs[i] = doc
+			i++
+		}
+		slices.SortStableFunc(intermediateDocs, func(a, b Documentation) int {
+			return strings.Compare(a.Annotation, b.Annotation)
+		})
+		docEntries = append(docEntries, intermediateDocs...)
+	}
+	slices.SortStableFunc(docEntries, func(a, b Documentation) int {
+		return strings.Compare(a.Group, b.Group)
+	})
+
+	tmpl, err := template.New("annotations.tmpl").ParseFS(content, "annotations.tmpl")
+	if err != nil {
+		panic(fmt.Errorf("error parsing template: %s", err))
+	}
+
+	tplBuffer := new(bytes.Buffer)
+	err = tmpl.Execute(tplBuffer, docEntries)
+	if err != nil {
+		panic(err)
+	}
+	tplBuffer.WriteString("\n")
+
+	//nolint:gosec // no need to check file permission here
+	if err := os.WriteFile(output, tplBuffer.Bytes(), 0o755); err != nil {
+		panic(err)
+	}
+}

docs/user-guide/nginx-configuration/annotations-risk.md

@@ -0,0 +1,142 @@
+# Annotations Scope and Risk
+
+|Group   |Annotation        | Risk | Scope |
+|--------|------------------|------|-------|
+| Aliases | server-alias | High | ingress |
+| Allowlist | allowlist-source-range | Medium | location |
+| BackendProtocol | backend-protocol | Low | location |
+| BasicDigestAuth | auth-realm | Medium | location |
+| BasicDigestAuth | auth-secret | Medium | location |
+| BasicDigestAuth | auth-secret-type | Low | location |
+| BasicDigestAuth | auth-type | Low | location |
+| Canary | canary | Low | ingress |
+| Canary | canary-by-cookie | Medium | ingress |
+| Canary | canary-by-header | Medium | ingress |
+| Canary | canary-by-header-pattern | Medium | ingress |
+| Canary | canary-by-header-value | Medium | ingress |
+| Canary | canary-weight | Low | ingress |
+| Canary | canary-weight-total | Low | ingress |
+| CertificateAuth | auth-tls-error-page | High | location |
+| CertificateAuth | auth-tls-match-cn | High | location |
+| CertificateAuth | auth-tls-pass-certificate-to-upstream | Low | location |
+| CertificateAuth | auth-tls-secret | Medium | location |
+| CertificateAuth | auth-tls-verify-client | Medium | location |
+| CertificateAuth | auth-tls-verify-depth | Low | location |
+| ClientBodyBufferSize | client-body-buffer-size | Low | location |
+| ConfigurationSnippet | configuration-snippet | Critical | location |
+| Connection | connection-proxy-header | Low | location |
+| CorsConfig | cors-allow-credentials | Low | ingress |
+| CorsConfig | cors-allow-headers | Medium | ingress |
+| CorsConfig | cors-allow-methods | Medium | ingress |
+| CorsConfig | cors-allow-origin | Medium | ingress |
+| CorsConfig | cors-expose-headers | Medium | ingress |
+| CorsConfig | cors-max-age | Low | ingress |
+| CorsConfig | enable-cors | Low | ingress |
+| CustomHTTPErrors | custom-http-errors | Low | location |
+| CustomHeaders | custom-headers | Medium | location |
+| DefaultBackend | default-backend | Low | location |
+| Denylist | denylist-source-range | Medium | location |
+| DisableProxyInterceptErrors | disable-proxy-intercept-errors | Low | location |
+| EnableGlobalAuth | enable-global-auth | Low | location |
+| ExternalAuth | auth-always-set-cookie | Low | location |
+| ExternalAuth | auth-cache-duration | Medium | location |
+| ExternalAuth | auth-cache-key | Medium | location |
+| ExternalAuth | auth-keepalive | Low | location |
+| ExternalAuth | auth-keepalive-requests | Low | location |
+| ExternalAuth | auth-keepalive-share-vars | Low | location |
+| ExternalAuth | auth-keepalive-timeout | Low | location |
+| ExternalAuth | auth-method | Low | location |
+| ExternalAuth | auth-proxy-set-headers | Medium | location |
+| ExternalAuth | auth-request-redirect | Medium | location |
+| ExternalAuth | auth-response-headers | Medium | location |
+| ExternalAuth | auth-signin | High | location |
+| ExternalAuth | auth-signin-redirect-param | Medium | location |
+| ExternalAuth | auth-snippet | Critical | location |
+| ExternalAuth | auth-url | High | location |
+| FastCGI | fastcgi-index | Medium | location |
+| FastCGI | fastcgi-params-configmap | Medium | location |
+| GlobalRateLimit | global-rate-limit | Low | ingress |
+| GlobalRateLimit | global-rate-limit-ignored-cidrs | Medium | ingress |
+| GlobalRateLimit | global-rate-limit-key | High | ingress |
+| GlobalRateLimit | global-rate-limit-window | Low | ingress |
+| HTTP2PushPreload | http2-push-preload | Low | location |
+| LoadBalancing | load-balance | Low | location |
+| Logs | enable-access-log | Low | location |
+| Logs | enable-rewrite-log | Low | location |
+| Mirror | mirror-host | High | ingress |
+| Mirror | mirror-request-body | Low | ingress |
+| Mirror | mirror-target | High | ingress |
+| ModSecurity | enable-modsecurity | Low | ingress |
+| ModSecurity | enable-owasp-core-rules | Low | ingress |
+| ModSecurity | modsecurity-snippet | Critical | ingress |
+| ModSecurity | modsecurity-transaction-id | High | ingress |
+| Opentelemetry | enable-opentelemetry | Low | location |
+| Opentelemetry | opentelemetry-operation-name | Medium | location |
+| Opentelemetry | opentelemetry-trust-incoming-span | Low | location |
+| Proxy | proxy-body-size | Medium | location |
+| Proxy | proxy-buffer-size | Low | location |
+| Proxy | proxy-buffering | Low | location |
+| Proxy | proxy-buffers-number | Low | location |
+| Proxy | proxy-connect-timeout | Low | location |
+| Proxy | proxy-cookie-domain | Medium | location |
+| Proxy | proxy-cookie-path | Medium | location |
+| Proxy | proxy-http-version | Low | location |
+| Proxy | proxy-max-temp-file-size | Low | location |
+| Proxy | proxy-next-upstream | Medium | location |
+| Proxy | proxy-next-upstream-timeout | Low | location |
+| Proxy | proxy-next-upstream-tries | Low | location |
+| Proxy | proxy-read-timeout | Low | location |
+| Proxy | proxy-redirect-from | Medium | location |
+| Proxy | proxy-redirect-to | Medium | location |
+| Proxy | proxy-request-buffering | Low | location |
+| Proxy | proxy-send-timeout | Low | location |
+| ProxySSL | proxy-ssl-ciphers | Medium | ingress |
+| ProxySSL | proxy-ssl-name | High | ingress |
+| ProxySSL | proxy-ssl-protocols | Low | ingress |
+| ProxySSL | proxy-ssl-secret | Medium | ingress |
+| ProxySSL | proxy-ssl-server-name | Low | ingress |
+| ProxySSL | proxy-ssl-verify | Low | ingress |
+| ProxySSL | proxy-ssl-verify-depth | Low | ingress |
+| RateLimit | limit-allowlist | Low | location |
+| RateLimit | limit-burst-multiplier | Low | location |
+| RateLimit | limit-connections | Low | location |
+| RateLimit | limit-rate | Low | location |
+| RateLimit | limit-rate-after | Low | location |
+| RateLimit | limit-rpm | Low | location |
+| RateLimit | limit-rps | Low | location |
+| Redirect | from-to-www-redirect | Low | location |
+| Redirect | permanent-redirect | Medium | location |
+| Redirect | permanent-redirect-code | Low | location |
+| Redirect | temporal-redirect | Medium | location |
+| Rewrite | app-root | Medium | location |
+| Rewrite | force-ssl-redirect | Medium | location |
+| Rewrite | preserve-trailing-slash | Medium | location |
+| Rewrite | rewrite-target | Medium | ingress |
+| Rewrite | ssl-redirect | Low | location |
+| Rewrite | use-regex | Low | location |
+| SSLCipher | ssl-ciphers | Low | ingress |
+| SSLCipher | ssl-prefer-server-ciphers | Low | ingress |
+| SSLPassthrough | ssl-passthrough | Low | ingress |
+| Satisfy | satisfy | Low | location |
+| ServerSnippet | server-snippet | Critical | ingress |
+| ServiceUpstream | service-upstream | Low | ingress |
+| SessionAffinity | affinity | Low | ingress |
+| SessionAffinity | affinity-canary-behavior | Low | ingress |
+| SessionAffinity | affinity-mode | Medium | ingress |
+| SessionAffinity | session-cookie-change-on-failure | Low | ingress |
+| SessionAffinity | session-cookie-conditional-samesite-none | Low | ingress |
+| SessionAffinity | session-cookie-domain | Medium | ingress |
+| SessionAffinity | session-cookie-expires | Medium | ingress |
+| SessionAffinity | session-cookie-max-age | Medium | ingress |
+| SessionAffinity | session-cookie-name | Medium | ingress |
+| SessionAffinity | session-cookie-path | Medium | ingress |
+| SessionAffinity | session-cookie-samesite | Low | ingress |
+| SessionAffinity | session-cookie-secure | Low | ingress |
+| StreamSnippet | stream-snippet | Critical | ingress |
+| UpstreamHashBy | upstream-hash-by | High | location |
+| UpstreamHashBy | upstream-hash-by-subset | Low | location |
+| UpstreamHashBy | upstream-hash-by-subset-size | Low | location |
+| UpstreamVhost | upstream-vhost | Low | location |
+| UsePortInRedirects | use-port-in-redirects | Low | location |
+| XForwardedPrefix | x-forwarded-prefix | Medium | location |
+

hack/update-annotation-doc.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# Copyright 2024 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+
+SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..
+ANNOTATIONFILE="${SCRIPT_ROOT}/docs/user-guide/nginx-configuration/annotations-risk.md"
+
+go run "${SCRIPT_ROOT}"/cmd/annotations/main.go -output "${ANNOTATIONFILE}"

hack/verify-annotation-docs.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# Copyright 2024 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+SCRIPT_ROOT=$(dirname "${BASH_SOURCE}")/..
+
+ANNOTATIONFILE="${SCRIPT_ROOT}/docs/user-guide/nginx-configuration/annotations-risk.md"
+TMP_DIFFROOT="${SCRIPT_ROOT}/_tmp"
+TMP_FILE="${TMP_DIFFROOT}/annotations-risk.md"
+
+cleanup() {
+  rm -rf "${TMP_DIFFROOT}"
+}
+trap "cleanup" EXIT SIGINT
+
+cleanup
+
+mkdir -p "${TMP_DIFFROOT}"
+
+go run cmd/annotations/main.go -output "${TMP_FILE}"
+echo "diffing ${ANNOTATIONFILE} against freshly generated annotation doc"
+ret=0
+diff -Naupr --no-dereference "${ANNOTATIONFILE}" "${TMP_FILE}" || ret=1
+
+if [[ $ret -eq 0 ]]; then
+  echo "${ANNOTATIONFILE} up to date."
+else
+  echo "${ANNOTATIONFILE} is out of date. Please run hack/update-annotation-doc.sh"
+  exit 1
+fi