Auto-generate annotation docs (#11820)

.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

internal/ingress/annotations/annotations.go

@@ -19,19 +19,10 @@ package annotations
 import (
 	"dario.cat/mergo"
 
-	"k8s.io/ingress-nginx/internal/ingress/annotations/canary"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/customheaders"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/disableproxyintercepterrors"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/modsecurity"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/opentelemetry"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/proxyssl"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/sslcipher"
-	"k8s.io/ingress-nginx/internal/ingress/annotations/streamsnippet"
-	"k8s.io/klog/v2"
-
 	apiv1 "k8s.io/api/core/v1"
 	networking "k8s.io/api/networking/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/klog/v2"
 
 	"k8s.io/ingress-nginx/internal/ingress/annotations/alias"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/auth"
@@ -39,11 +30,14 @@ import (
 	"k8s.io/ingress-nginx/internal/ingress/annotations/authreqglobal"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/authtls"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/backendprotocol"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/canary"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/clientbodybuffersize"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/connection"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/cors"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/customheaders"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/customhttperrors"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/defaultbackend"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/disableproxyintercepterrors"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/fastcgi"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/globalratelimit"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/http2pushpreload"
@@ -52,9 +46,12 @@ import (
 	"k8s.io/ingress-nginx/internal/ingress/annotations/loadbalancing"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/log"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/mirror"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/modsecurity"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/opentelemetry"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/parser"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/portinredirect"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/proxy"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/proxyssl"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/ratelimit"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/redirect"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/rewrite"
@@ -63,7 +60,9 @@ import (
 	"k8s.io/ingress-nginx/internal/ingress/annotations/serviceupstream"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/sessionaffinity"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/snippet"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/sslcipher"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/sslpassthrough"
+	"k8s.io/ingress-nginx/internal/ingress/annotations/streamsnippet"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/upstreamhashby"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/upstreamvhost"
 	"k8s.io/ingress-nginx/internal/ingress/annotations/xforwardedprefix"
@@ -126,10 +125,8 @@ type Extractor struct {
 	annotations map[string]parser.IngressAnnotation
 }
 
-// NewAnnotationExtractor creates a new annotations extractor
+func NewAnnotationFactory(cfg resolver.Resolver) map[string]parser.IngressAnnotation {
-func NewAnnotationExtractor(cfg resolver.Resolver) Extractor {
+	return map[string]parser.IngressAnnotation{
-	return Extractor{
-		map[string]parser.IngressAnnotation{
 		"Aliases":                     alias.NewParser(cfg),
 		"BasicDigestAuth":             auth.NewParser(auth.AuthDirectory, cfg),
 		"Canary":                      canary.NewParser(cfg),
@@ -171,7 +168,13 @@ func NewAnnotationExtractor(cfg resolver.Resolver) Extractor {
 		"ModSecurity":                 modsecurity.NewParser(cfg),
 		"Mirror":                      mirror.NewParser(cfg),
 		"StreamSnippet":               streamsnippet.NewParser(cfg),
-		},
+	}
+}
+
+// NewAnnotationExtractor creates a new annotations extractor
+func NewAnnotationExtractor(cfg resolver.Resolver) Extractor {
+	return Extractor{
+		NewAnnotationFactory(cfg),
 	}
 }
 

internal/ingress/annotations/parser/main.go

@@ -210,6 +210,21 @@ func StringRiskToRisk(risk string) AnnotationRisk {
 	}
 }
 
+func (a AnnotationRisk) ToString() string {
+	switch a {
+	case AnnotationRiskCritical:
+		return "Critical"
+	case AnnotationRiskHigh:
+		return "High"
+	case AnnotationRiskMedium:
+		return "Medium"
+	case AnnotationRiskLow:
+		return "Low"
+	default:
+		return "Unknown"
+	}
+}
+
 func normalizeString(input string) string {
 	trimmedContent := []string{}
 	for _, line := range strings.Split(input, "\n") {

mkdocs.yml

@@ -83,6 +83,7 @@ nav:
           - Introduction: "user-guide/nginx-configuration/index.md"
           - Basic usage: "user-guide/basic-usage.md"
           - Annotations: "user-guide/nginx-configuration/annotations.md"
+          - Annotations Risks: "user-guide/nginx-configuration/annotations-risk.md"
           - ConfigMap: "user-guide/nginx-configuration/configmap.md"
           - Custom NGINX template: "user-guide/nginx-configuration/custom-template.md"
           - Log format: "user-guide/nginx-configuration/log-format.md"