From 06d6744500851132666eaeccab4140ee814a7330 Mon Sep 17 00:00:00 2001 From: Luca Comellini Date: Thu, 25 Apr 2024 14:24:03 -0700 Subject: [PATCH] Generate API docs Problem: We want to have our CRDs documented Solution: Use gen-crd-api-reference-docs to automatically generate the docs --- .github/workflows/ci.yml | 3 + Makefile | 3 + go.mod | 4 + go.sum | 19 + site/config/api/config.json | 32 + site/config/api/members.tpl | 48 ++ site/config/api/pkg.tpl | 54 ++ site/config/api/type.tpl | 81 +++ site/content/reference/api.md | 1151 +++++++++++++++++++++++++++++++++ tools.go | 1 + 10 files changed, 1396 insertions(+) create mode 100644 site/config/api/config.json create mode 100644 site/config/api/members.tpl create mode 100644 site/config/api/pkg.tpl create mode 100644 site/config/api/type.tpl create mode 100644 site/content/reference/api.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 576661298..17de31879 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -56,6 +56,9 @@ jobs: - name: Check if generated manifests are up to date run: make generate-manifests && git diff --exit-code + - name: Check if API docs are up to date + run: make generate-api-docs && git diff --exit-code + unit-tests: name: Unit Tests runs-on: ubuntu-22.04 diff --git a/Makefile b/Makefile index 1396373f6..0e65f9d84 100644 --- a/Makefile +++ b/Makefile @@ -113,6 +113,9 @@ generate-manifests: ## Generate manifests using Helm. helm template nginx-gateway $(CHART_DIR) $(HELM_TEMPLATE_COMMON_ARGS) --set service.annotations.'service\.beta\.kubernetes\.io\/aws-load-balancer-type'="nlb" -n nginx-gateway -s templates/service.yaml > $(strip $(MANIFEST_DIR))/service/loadbalancer-aws-nlb.yaml helm template nginx-gateway $(CHART_DIR) $(HELM_TEMPLATE_COMMON_ARGS) --set service.type=NodePort --set service.externalTrafficPolicy="" -n nginx-gateway -s templates/service.yaml > $(strip $(MANIFEST_DIR))/service/nodeport.yaml +generate-api-docs: ## Generate API docs + go run github.com/ahmetb/gen-crd-api-reference-docs -config site/config/api/config.json -template-dir site/config/api -out-file site/content/reference/api.md -api-dir "github.com/nginxinc/nginx-gateway-fabric/apis" + .PHONY: crds-release-file crds-release-file: ## Generate combined crds file for releases scripts/combine-crds.sh diff --git a/go.mod b/go.mod index ae8a0f0c5..f54f4a03c 100644 --- a/go.mod +++ b/go.mod @@ -6,6 +6,7 @@ go 1.22.0 replace github.com/chzyer/logex v1.1.10 => github.com/chzyer/logex v1.2.0 require ( + github.com/ahmetb/gen-crd-api-reference-docs v0.3.0 github.com/go-kit/log v0.2.1 github.com/go-logr/logr v1.4.1 github.com/google/go-cmp v0.6.0 @@ -75,6 +76,7 @@ require ( github.com/pmezard/go-difflib v1.0.0 // indirect github.com/prometheus/client_model v0.6.0 // indirect github.com/prometheus/procfs v0.12.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/stretchr/testify v1.9.0 // indirect go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.26.0 // indirect go.opentelemetry.io/otel/metric v1.26.0 // indirect @@ -101,6 +103,8 @@ require ( gopkg.in/inf.v0 v0.9.1 // indirect gopkg.in/yaml.v2 v2.4.0 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect + k8s.io/gengo v0.0.0-20230829151522-9cce18d56c01 // indirect + k8s.io/klog v0.2.0 // indirect k8s.io/klog/v2 v2.120.1 // indirect k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect diff --git a/go.sum b/go.sum index 984688b85..06f11ced1 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,5 @@ +github.com/ahmetb/gen-crd-api-reference-docs v0.3.0 h1:+XfOU14S4bGuwyvCijJwhhBIjYN+YXS18jrCY2EzJaY= +github.com/ahmetb/gen-crd-api-reference-docs v0.3.0/go.mod h1:TdjdkYhlOifCQWPs1UdTma97kQQMozf5h26hTuG70u8= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs= github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM= @@ -28,6 +30,7 @@ github.com/go-kit/log v0.2.1 h1:MRVx0/zhvdseW+Gza6N9rVzU/IVzaeE1SFI4raAhmBU= github.com/go-kit/log v0.2.1/go.mod h1:NwTd00d/i8cPZ3xOwwiv2PO5MOcx78fFErGNcVmBjv0= github.com/go-logfmt/logfmt v0.5.1 h1:otpy5pqBCBZ1ng9RQ0dPu4PN7ba75Y/aA+UpowDyNVA= github.com/go-logfmt/logfmt v0.5.1/go.mod h1:WYhtIu8zTZfxdn5+rREduYbwxfcBr/Vr6KEVveWlfTs= +github.com/go-logr/logr v0.2.0/go.mod h1:z6/tIYblkpsD+a4lm/fGIIU9mZ+XfAiaFtq7xTgseGU= github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= github.com/go-logr/logr v1.4.1 h1:pKouT5E8xu9zeFC39JXRDukb6JFQPXM5p5I91188VAQ= github.com/go-logr/logr v1.4.1/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= @@ -57,11 +60,13 @@ github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= github.com/google/gnostic-models v0.6.8 h1:yo/ABAfM5IMRsS1VnXjTBvUb61tFIHozhlYvRgGre9I= github.com/google/gnostic-models v0.6.8/go.mod h1:5n7qKqH0f5wFt+aWF8CW6pZLLNOfYuF5OpfBSENuI8U= +github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= +github.com/google/gofuzz v1.1.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= github.com/google/gofuzz v1.2.0 h1:xRy4A+RhZaiKjJ1bPfwQ8sedCA+YS2YcCHW6ec7JMi0= github.com/google/gofuzz v1.2.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= github.com/google/pprof v0.0.0-20210720184732-4bb14d4b1be1 h1:K6RDEckDVWvDI9JAJYCmNdQXq6neHJOYx3V6jnqNEec= @@ -84,6 +89,7 @@ github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnr github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo= github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8= github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck= +github.com/kr/pretty v0.2.0/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= @@ -125,6 +131,7 @@ github.com/onsi/ginkgo/v2 v2.17.1 h1:V++EzdbhI4ZV4ev0UTIj0PzhzOcReJFyJaLjtSF55M8 github.com/onsi/ginkgo/v2 v2.17.1/go.mod h1:llBI3WDLL9Z6taip6f33H76YcWtJv+7R3HigUjbIBOs= github.com/onsi/gomega v1.33.0 h1:snPCflnZrpMsy94p4lXVEkHo12lmPnc3vY5XBbreexE= github.com/onsi/gomega v1.33.0/go.mod h1:+925n5YtiFsLzzafLUHzVMBpvvRAzrydIBiSIxjX3wY= +github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= @@ -139,9 +146,12 @@ github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo= github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ= github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog= +github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/sclevine/spec v1.4.0 h1:z/Q9idDcay5m5irkZ28M7PtQM4aOISzOpj4bUPkDee8= github.com/sclevine/spec v1.4.0/go.mod h1:LvpgJaFyvQzRvc1kaDs0bulYwzC70PbiYjC4QnFHkOM= +github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc= github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0= github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho= github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= @@ -232,6 +242,7 @@ golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4= golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= +golang.org/x/tools v0.0.0-20200505023115-26f46d2f7ef8/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE= golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE= golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= @@ -258,6 +269,7 @@ google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQ google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI= google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc= @@ -278,6 +290,12 @@ k8s.io/apimachinery v0.30.0 h1:qxVPsyDM5XS96NIh9Oj6LavoVFYff/Pon9cZeDIkHHA= k8s.io/apimachinery v0.30.0/go.mod h1:iexa2somDaxdnj7bha06bhb43Zpa6eWH8N8dbqVjTUc= k8s.io/client-go v0.30.0 h1:sB1AGGlhY/o7KCyCEQ0bPWzYDL0pwOZO4vAtTSh/gJQ= k8s.io/client-go v0.30.0/go.mod h1:g7li5O5256qe6TYdAMyX/otJqMhIiGgTapdLchhmOaY= +k8s.io/gengo v0.0.0-20201203183100-97869a43a9d9/go.mod h1:FiNAH4ZV3gBg2Kwh89tzAEV2be7d5xI0vBa/VySYy3E= +k8s.io/gengo v0.0.0-20230829151522-9cce18d56c01 h1:pWEwq4Asjm4vjW7vcsmijwBhOr1/shsbSYiWXmNGlks= +k8s.io/gengo v0.0.0-20230829151522-9cce18d56c01/go.mod h1:FiNAH4ZV3gBg2Kwh89tzAEV2be7d5xI0vBa/VySYy3E= +k8s.io/klog v0.2.0 h1:0ElL0OHzF3N+OhoJTL0uca20SxtYt4X4+bzHeqrB83c= +k8s.io/klog v0.2.0/go.mod h1:Gq+BEi5rUBO/HRz0bTSXDUcqjScdoY3a9IHpCEIOOfk= +k8s.io/klog/v2 v2.2.0/go.mod h1:Od+F08eJP+W3HUb4pSrPpgp9DGU4GzlpG/TmITuYh/Y= k8s.io/klog/v2 v2.120.1 h1:QXU6cPEOIslTGvZaXvFWiP9VKyeet3sawzTOvdXb4Vw= k8s.io/klog/v2 v2.120.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE= k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 h1:BZqlfIlq5YbRMFko6/PM7FjZpUb45WallggurYhKGag= @@ -294,5 +312,6 @@ sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd h1:EDPBXCAspyGV4jQlpZSudPeMm sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd/go.mod h1:B8JuhiUyNFVKdsE8h686QcCxMaH6HrOAZj4vswFpcB0= sigs.k8s.io/structured-merge-diff/v4 v4.4.1 h1:150L+0vs/8DA78h1u02ooW1/fFq/Lwr+sGiqlzvrtq4= sigs.k8s.io/structured-merge-diff/v4 v4.4.1/go.mod h1:N8hJocpFajUSSeSJ9bOZ77VzejKZaXsTtZo4/u7Io08= +sigs.k8s.io/yaml v1.2.0/go.mod h1:yfXDCHCao9+ENCvLSE62v9VSji2MKu5jeNfTrofGhJc= sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E= sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY= diff --git a/site/config/api/config.json b/site/config/api/config.json new file mode 100644 index 000000000..dc143de2a --- /dev/null +++ b/site/config/api/config.json @@ -0,0 +1,32 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + }, + { + "typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/", + "docsURLTemplate": "https://pkg.go.dev/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}" + }, + { + "typeMatchPrefix": "^sigs.k8s.io/gateway-api/apis/", + "docsURLTemplate": "https://pkg.go.dev/sigs.k8s.io/gateway-api/apis/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/site/config/api/members.tpl b/site/config/api/members.tpl new file mode 100644 index 000000000..a529c6716 --- /dev/null +++ b/site/config/api/members.tpl @@ -0,0 +1,48 @@ +{{ define "members" }} + +{{ range .Members }} +{{ if not (hiddenMember .)}} + + + {{ fieldName . }}
+ + {{ if linkForType .Type }} + + {{ typeDisplayName .Type }} + + {{ else }} + {{ typeDisplayName .Type }} + {{ end }} + + + + {{ if fieldEmbedded . }} +

+ (Members of {{ fieldName . }} are embedded into this type.) +

+ {{ end}} + + {{ if isOptionalMember .}} + (Optional) + {{ end }} + + {{ safe (renderComments .CommentLines) }} + + {{ if and (eq (.Type.Name.Name) "ObjectMeta") }} + Refer to the Kubernetes API documentation for the fields of the + metadata field. + {{ end }} + + {{ if or (eq (fieldName .) "spec") }} +
+
+ + {{ template "members" .Type }} +
+ {{ end }} + + +{{ end }} +{{ end }} + +{{ end }} diff --git a/site/config/api/pkg.tpl b/site/config/api/pkg.tpl new file mode 100644 index 000000000..403ff863a --- /dev/null +++ b/site/config/api/pkg.tpl @@ -0,0 +1,54 @@ +{{ define "packages" }} +--- +title: "API Reference" +description: "NGINX Gateway API Reference" +weight: 100 +toc: true +--- + +{{ with .packages}} +

Packages:

+ +{{ end}} + +{{ range .packages }} +

+ {{- packageDisplayName . -}} +

+ + {{ with (index .GoPackages 0 )}} + {{ with .DocComments }} +
+ {{ safe (renderComments .) }} +
+ {{ end }} + {{ end }} + + Resource Types: + + + {{ range (visibleTypes (sortedTypes .Types))}} + {{ template "type" . }} + {{ end }} +
+{{ end }} + +

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

+ +{{ end }} diff --git a/site/config/api/type.tpl b/site/config/api/type.tpl new file mode 100644 index 000000000..8f0d66b8b --- /dev/null +++ b/site/config/api/type.tpl @@ -0,0 +1,81 @@ +{{ define "type" }} + +

+ {{- .Name.Name }} + {{ if eq .Kind "Alias" }}({{.Underlying}} alias){{ end -}} +

+{{ with (typeReferences .) }} +

+ (Appears on: + {{- $prev := "" -}} + {{- range . -}} + {{- if $prev -}}, {{ end -}} + {{- $prev = . -}} + {{ typeDisplayName . }} + {{- end -}} + ) +

+{{ end }} + +
+ {{ safe (renderComments .CommentLines) }} +
+ +{{ with (constantsOfType .) }} + + + + + + + + + {{- range . -}} + + {{- /* + renderComments implicitly creates a

element, so we + add one to the display name as well to make the contents + of the two cells align evenly. + */ -}} +

+ + + {{- end -}} + +
ValueDescription

{{ typeDisplayName . }}

{{ safe (renderComments .CommentLines) }}
+{{ end }} + +{{ if .Members }} + + + + + + + + + {{ if isExportedType . }} + + + + + + + + + {{ end }} + {{ template "members" .}} + +
FieldDescription
+ apiVersion
+ string		 + + {{apiGroup .}} + +
+ kind
+ string + 		{{.Name.Name}}
+{{ end }} + +{{ end }} diff --git a/site/content/reference/api.md b/site/content/reference/api.md new file mode 100644 index 000000000..bc2adf531 --- /dev/null +++ b/site/content/reference/api.md @@ -0,0 +1,1151 @@ +--- +title: "API Reference" +description: "NGINX Gateway API Reference" +weight: 100 +toc: true +--- +

Packages:

+ +

gateway.nginx.org/v1alpha1

+
+

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

+
+Resource Types: + +

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: 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.

+
+

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
+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.

+
+
+ + + + + + + + + + + + + +
+targetRef
+ + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyTargetReference + + +		 +

TargetRef identifies an API object to apply the policy to. +Object must be in the same namespace as the policy.

+

Support: Gateway, HTTPRoute

+
+body
+ + +ClientBody + + +		 +(Optional) +

Body defines the client request body settings.

+
+keepAlive
+ + +ClientKeepAlive + + +		 +(Optional) +

KeepAlive defines the keep-alive settings.

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

Status defines the state of the ClientSettingsPolicy.

+
+

ClientSettingsPolicySpec +

+

+(Appears on:ClientSettingsPolicy) +

+
+

ClientSettingsPolicySpec defines the desired state of ClientSettingsPolicy.

+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+targetRef
+ + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyTargetReference + + +		 +

TargetRef identifies an API object to apply the policy to. +Object must be in the same namespace as the policy.

+

Support: Gateway, HTTPRoute

+
+body
+ + +ClientBody + + +		 +(Optional) +

Body defines the client request body settings.

+
+keepAlive
+ + +ClientKeepAlive + + +		 +(Optional) +

KeepAlive defines the keep-alive settings.

+
+

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.

+
+

Duration +(string alias)

+

+(Appears on:ClientBody, ClientKeepAlive, ClientKeepAliveTimeout, TelemetryExporter) +

+
+

Duration is a string value representing a duration in time. +Duration can be specified in milliseconds (ms) or seconds (s) A value without a suffix is seconds. +Examples: 120s, 50ms.

+
+

Logging +

+

+(Appears on:NginxGatewaySpec) +

+
+

Logging defines logging related settings for the control plane.

+
+ + + + + + + + + + + + + +
FieldDescription
+level
+ + +ControllerLogLevel + + +		 +(Optional) +

Level defines the logging level.

+
+

NginxGateway +

+
+

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

+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

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) +
+

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
+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.

+
+
+ + + + + +
+telemetry
+ + +Telemetry + + +		 +(Optional) +

Telemetry specifies the OpenTelemetry configuration.

+
+
+

NginxProxySpec +

+

+(Appears on:NginxProxy) +

+
+

NginxProxySpec defines the desired state of the NginxProxy.

+
+ + + + + + + + + + + + + +
FieldDescription
+telemetry
+ + +Telemetry + + +		 +(Optional) +

Telemetry specifies the OpenTelemetry configuration.

+
+

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
+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.

+
+
+ + + + + + + + + +
+targetRef
+ + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyTargetReference + + +		 +

TargetRef identifies an API object to apply the policy to. +Object must be in the same namespace as the policy.

+

Support: HTTPRoute

+
+tracing
+ + +Tracing + + +		 +(Optional) +

Tracing allows for enabling and configuring tracing.

+
+
+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
+targetRef
+ + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyTargetReference + + +		 +

TargetRef identifies an API object to apply the policy to. +Object must be in the same namespace as the policy.

+

Support: HTTPRoute

+
+tracing
+ + +Tracing + + +		 +(Optional) +

Tracing allows for enabling and configuring tracing.

+
+

Size +(string alias)

+

+(Appears on:ClientBody) +

+
+

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.

+
+

SpanAttribute +

+

+(Appears on:Telemetry, 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.

+
+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/tools.go b/tools.go index da60ee983..d35978d40 100644 --- a/tools.go +++ b/tools.go @@ -7,6 +7,7 @@ package tools import ( + _ "github.com/ahmetb/gen-crd-api-reference-docs" _ "github.com/maxbrunsfeld/counterfeiter/v6" _ "sigs.k8s.io/controller-tools/cmd/controller-gen" )