diff --git a/Makefile b/Makefile index e10eec895..e723b8d7c 100644 --- a/Makefile +++ b/Makefile @@ -15,6 +15,12 @@ GATEAY_API_VERSION ?= v1.2.0 DASHBOARD_VERSION ?= dev TEST_TIMEOUT ?= 45m +# CRD Reference Documentation +CRD_REF_DOCS_VERSION ?= v0.1.0 +CRD_REF_DOCS ?= $(LOCALBIN)/crd-ref-docs +CRD_DOCS_CONFIG ?= docs/crd/config.yaml +CRD_DOCS_OUTPUT ?= docs/crd/api.md + export KUBECONFIG = /tmp/$(KIND_NAME).kubeconfig # go @@ -29,7 +35,6 @@ GOBIN=$(shell go env GOPATH)/bin else GOBIN=$(shell go env GOBIN) endif - GOOS ?= linux GOARCH ?= amd64 @@ -346,3 +351,29 @@ helm-build-crds: sort-import: @./scripts/goimports-reviser.sh >/dev/null 2>&1 .PHONY: sort-import + +.PHONY: generate-crd-docs +generate-crd-docs: manifests ## Generate CRD reference documentation in a single file + @mkdir -p $(dir $(CRD_DOCS_OUTPUT)) + @echo "Generating CRD reference documentation" + @$(CRD_REF_DOCS) \ + --source-path=./api \ + --config=$(CRD_DOCS_CONFIG) \ + --renderer=markdown \ + --templates-dir=./docs/template \ + --output-path=$(CRD_DOCS_OUTPUT) \ + --max-depth=100 + @echo "CRD reference documentation generated at $(CRD_DOCS_OUTPUT)" + +.PHONY: generate-crd-docs-grouped +generate-crd-docs-grouped: manifests ## Generate CRD reference documentation grouped by API group + @mkdir -p docs/crd/groups + @echo "Generating CRD reference documentation (grouped by API)" + @$(CRD_REF_DOCS) \ + --source-path=./api \ + --config=$(CRD_DOCS_CONFIG) \ + --renderer=markdown \ + --templates-dir=./docs/template \ + --output-path=docs/crd/groups \ + --output-mode=group + @echo "CRD reference documentation generated in docs/crd/groups directory" diff --git a/docs/crd/api.md b/docs/crd/api.md new file mode 100644 index 000000000..f42684721 --- /dev/null +++ b/docs/crd/api.md @@ -0,0 +1,467 @@ +--- +title: Resource Definitions API Reference +slug: /reference/api7-ingress-controller/crd-reference +description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the API7 Ingress Controller. +--- + +This document provides the API resource description for the API7 Ingress Controller. + +## Packages +- [apisix.apache.org/v1alpha1](#apisixapacheorgv1alpha1) + + +## apisix.apache.org/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the apisix.apache.org v1alpha1 API group + +- [BackendTrafficPolicy](#backendtrafficpolicy) +- [Consumer](#consumer) +- [GatewayProxy](#gatewayproxy) +- [HTTPRoutePolicy](#httproutepolicy) +- [PluginConfig](#pluginconfig) +### BackendTrafficPolicy + + + + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `apisix.apache.org/v1alpha1` +| `kind` _string_ | `BackendTrafficPolicy` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. | +| `spec` _[BackendTrafficPolicySpec](#backendtrafficpolicyspec)_ | | + + + +### Consumer + + + + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `apisix.apache.org/v1alpha1` +| `kind` _string_ | `Consumer` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. | +| `spec` _[ConsumerSpec](#consumerspec)_ | | + + + +### GatewayProxy + + +GatewayProxy is the Schema for the gatewayproxies API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `apisix.apache.org/v1alpha1` +| `kind` _string_ | `GatewayProxy` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. | +| `spec` _[GatewayProxySpec](#gatewayproxyspec)_ | | + + + +### HTTPRoutePolicy + + +HTTPRoutePolicy is the Schema for the httproutepolicies API. + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `apisix.apache.org/v1alpha1` +| `kind` _string_ | `HTTPRoutePolicy` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. | +| `spec` _[HTTPRoutePolicySpec](#httproutepolicyspec)_ | | + + + +### PluginConfig + + +PluginConfig is the Schema for the PluginConfigs API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `apisix.apache.org/v1alpha1` +| `kind` _string_ | `PluginConfig` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#objectmeta-v1-meta)_ | Please refer to the Kubernetes API documentation for details on the `metadata` field. | +| `spec` _[PluginConfigSpec](#pluginconfigspec)_ | | + + + +### Types + +In this section you will find types that the CRDs rely on. +#### AdminKeyAuth + + +AdminKeyAuth defines the admin key authentication configuration + + + +| Field | Description | +| --- | --- | +| `value` _string_ | Value specifies the admin key value directly (not recommended for production) | +| `valueFrom` _[AdminKeyValueFrom](#adminkeyvaluefrom)_ | ValueFrom specifies the source of the admin key | + + +_Appears in:_ +- [ControlPlaneAuth](#controlplaneauth) + +#### AdminKeyValueFrom + + +AdminKeyValueFrom defines the source of the admin key + + + +| Field | Description | +| --- | --- | +| `secretKeyRef` _[SecretKeySelector](#secretkeyselector)_ | SecretKeyRef references a key in a Secret | + + +_Appears in:_ +- [AdminKeyAuth](#adminkeyauth) + +#### AuthType +_Base type:_ `string` + +AuthType defines the type of authentication + + + + + +_Appears in:_ +- [ControlPlaneAuth](#controlplaneauth) + +#### BackendPolicyTargetReferenceWithSectionName +_Base type:_ `LocalPolicyTargetReferenceWithSectionName` + + + + + +| Field | Description | +| --- | --- | +| `group` _[Group](#group)_ | Group is the group of the target resource. | +| `kind` _[Kind](#kind)_ | Kind is kind of the target resource. | +| `name` _[ObjectName](#objectname)_ | Name is the name of the target resource. | +| `sectionName` _[SectionName](#sectionname)_ | SectionName is the name of a section within the target resource. When unspecified, this targetRef targets the entire resource. In the following resources, SectionName is interpreted as the following:

* Gateway: Listener name * HTTPRoute: HTTPRouteRule name * Service: Port name

If a SectionName is specified, but does not exist on the targeted object, the Policy must fail to attach, and the policy implementation should record a `ResolvedRefs` or similar Condition in the Policy's status. | + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +#### BackendTrafficPolicySpec + + + + + + +| Field | Description | +| --- | --- | +| `targetRefs` _[BackendPolicyTargetReferenceWithSectionName](#backendpolicytargetreferencewithsectionname) array_ | TargetRef identifies an API object to apply policy to. Currently, Backends (i.e. Service, ServiceImport, or any implementation-specific backendRef) are the only valid API target references. | +| `loadbalancer` _[LoadBalancer](#loadbalancer)_ | LoadBalancer represents the load balancer configuration for Kubernetes Service. The default strategy is round robin. | +| `scheme` _string_ | The scheme used to talk with the upstream. | +| `retries` _integer_ | How many times that the proxy (Apache APISIX) should do when errors occur (error, timeout or bad http status codes like 500, 502). | +| `timeout` _[Timeout](#timeout)_ | Timeout settings for the read, send and connect to the upstream. | +| `passHost` _string_ | Configures the host when the request is forwarded to the upstream. Can be one of pass, node or rewrite. | +| `upstreamHost` _[Hostname](#hostname)_ | Specifies the host of the Upstream request. This is only valid if the passHost is set to rewrite | + + +_Appears in:_ +- [BackendTrafficPolicy](#backendtrafficpolicy) + +#### ConsumerSpec + + + + + + +| Field | Description | +| --- | --- | +| `gatewayRef` _[GatewayRef](#gatewayref)_ | | +| `credentials` _[Credential](#credential) array_ | | +| `plugins` _[Plugin](#plugin) array_ | | + + +_Appears in:_ +- [Consumer](#consumer) + +#### ControlPlaneAuth + + +ControlPlaneAuth defines the authentication configuration for control plane + + + +| Field | Description | +| --- | --- | +| `type` _[AuthType](#authtype)_ | Type specifies the type of authentication | +| `adminKey` _[AdminKeyAuth](#adminkeyauth)_ | AdminKey specifies the admin key authentication configuration | + + +_Appears in:_ +- [ControlPlaneProvider](#controlplaneprovider) + +#### ControlPlaneProvider + + +ControlPlaneProvider defines the configuration for control plane provider + + + +| Field | Description | +| --- | --- | +| `endpoints` _string array_ | Endpoints specifies the list of control plane endpoints | +| `tlsVerify` _boolean_ | TlsVerify specifies whether to verify the TLS certificate of the control plane | +| `auth` _[ControlPlaneAuth](#controlplaneauth)_ | Auth specifies the authentication configuration | + + +_Appears in:_ +- [GatewayProxyProvider](#gatewayproxyprovider) + +#### Credential + + + + + + +| Field | Description | +| --- | --- | +| `type` _string_ | | +| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | | +| `secretRef` _[SecretReference](#secretreference)_ | | +| `name` _string_ | | + + +_Appears in:_ +- [ConsumerSpec](#consumerspec) + +#### GatewayProxyPlugin + + + + + + +| Field | Description | +| --- | --- | +| `name` _string_ | | +| `enabled` _boolean_ | | +| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | | + + +_Appears in:_ +- [GatewayProxySpec](#gatewayproxyspec) + +#### GatewayProxyProvider + + +GatewayProxyProvider defines the provider configuration for GatewayProxy + + + +| Field | Description | +| --- | --- | +| `type` _[ProviderType](#providertype)_ | Type specifies the type of provider | +| `controlPlane` _[ControlPlaneProvider](#controlplaneprovider)_ | ControlPlane specifies the configuration for control plane provider | + + +_Appears in:_ +- [GatewayProxySpec](#gatewayproxyspec) + +#### GatewayProxySpec + + +GatewayProxySpec defines the desired state of GatewayProxy + + + +| Field | Description | +| --- | --- | +| `publishService` _string_ | | +| `statusAddress` _string array_ | | +| `provider` _[GatewayProxyProvider](#gatewayproxyprovider)_ | | +| `plugins` _[GatewayProxyPlugin](#gatewayproxyplugin) array_ | | +| `pluginMetadata` _object (keys:string, values:[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io))_ | | + + +_Appears in:_ +- [GatewayProxy](#gatewayproxy) + +#### GatewayRef + + + + + + +| Field | Description | +| --- | --- | +| `name` _string_ | | +| `kind` _string_ | | +| `group` _string_ | | +| `namespace` _string_ | | + + +_Appears in:_ +- [ConsumerSpec](#consumerspec) + +#### HTTPRoutePolicySpec + + +HTTPRoutePolicySpec defines the desired state of HTTPRoutePolicy. + + + +| Field | Description | +| --- | --- | +| `targetRefs` _LocalPolicyTargetReferenceWithSectionName array_ | TargetRef identifies an API object (enum: HTTPRoute, Ingress) to apply HTTPRoutePolicy to.

target references. | +| `priority` _integer_ | | +| `vars` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io) array_ | | + + +_Appears in:_ +- [HTTPRoutePolicy](#httproutepolicy) + +#### Hostname +_Base type:_ `string` + + + + + + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +#### LoadBalancer + + +LoadBalancer describes the load balancing parameters. + + + +| Field | Description | +| --- | --- | +| `type` _string_ | | +| `hashOn` _string_ | The HashOn and Key fields are required when Type is "chash". HashOn represents the key fetching scope. | +| `key` _string_ | Key represents the hash key. | + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + +#### Plugin + + + + + + +| Field | Description | +| --- | --- | +| `name` _string_ | The plugin name. | +| `config` _[JSON](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#json-v1-apiextensions-k8s-io)_ | Plugin configuration. | + + +_Appears in:_ +- [ConsumerSpec](#consumerspec) +- [PluginConfigSpec](#pluginconfigspec) + +#### PluginConfigSpec + + +PluginConfigSpec defines the desired state of PluginConfig + + + +| Field | Description | +| --- | --- | +| `plugins` _[Plugin](#plugin) array_ | | + + +_Appears in:_ +- [PluginConfig](#pluginconfig) + + + +#### ProviderType +_Base type:_ `string` + +ProviderType defines the type of provider + + + + + +_Appears in:_ +- [GatewayProxyProvider](#gatewayproxyprovider) + +#### SecretKeySelector + + +SecretKeySelector defines a reference to a specific key within a Secret + + + +| Field | Description | +| --- | --- | +| `name` _string_ | Name is the name of the secret | +| `key` _string_ | Key is the key in the secret | + + +_Appears in:_ +- [AdminKeyValueFrom](#adminkeyvaluefrom) + +#### SecretReference + + + + + + +| Field | Description | +| --- | --- | +| `name` _string_ | | +| `namespace` _string_ | | + + +_Appears in:_ +- [Credential](#credential) + + + +#### Timeout + + + + + + +| Field | Description | +| --- | --- | +| `connect` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | | +| `send` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | | +| `read` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#duration-v1-meta)_ | | + + +_Appears in:_ +- [BackendTrafficPolicySpec](#backendtrafficpolicyspec) + diff --git a/docs/crd/config.yaml b/docs/crd/config.yaml new file mode 100644 index 000000000..e12b9f9cb --- /dev/null +++ b/docs/crd/config.yaml @@ -0,0 +1,13 @@ +processor: + # RE2 regular expressions describing types that should be excluded from the generated documentation. + ignoreTypes: + - "List$" + # RE2 regular expressions describing type fields that should be excluded from the generated documentation. + ignoreFields: + - "status$" + - "TypeMeta$" + +render: + # Version of Kubernetes to use when generating links to Kubernetes API documentation. + # NOTE: Quotes are required, otherwise the value will be intepreted as a number so versions ending with `0` like 1.30 would be covreted to "1.3" in results. + kubernetesVersion: "1.30" diff --git a/docs/template/gv_details.tpl b/docs/template/gv_details.tpl new file mode 100644 index 000000000..0f7e03e24 --- /dev/null +++ b/docs/template/gv_details.tpl @@ -0,0 +1,38 @@ +{{- define "gvDetails" -}} +{{- $gv := . -}} + +## {{ $gv.GroupVersionString }} + +{{ $gv.Doc }} + +{{- if $gv.Kinds }} +{{- range $gv.SortedKinds }} +- {{ $gv.TypeForKind . | markdownRenderTypeLink }} +{{- end }} +{{ end }} + +{{- /* Display exported Kinds first */ -}} +{{- range $gv.SortedKinds -}} +{{- $typ := $gv.TypeForKind . }} +{{- $isKind := true -}} +{{ template "type" (dict "type" $typ "isKind" $isKind) }} +{{ end -}} + +### Types + +In this section you will find types that the CRDs rely on. + +{{- /* Display Types that are not exported Kinds */ -}} +{{- range $typ := $gv.SortedTypes -}} +{{- $isKind := false -}} +{{- range $kind := $gv.SortedKinds -}} +{{- if eq $typ.Name $kind -}} +{{- $isKind = true -}} +{{- end -}} +{{- end -}} +{{- if not $isKind }} +{{ template "type" (dict "type" $typ "isKind" $isKind) }} +{{ end -}} +{{- end }} + +{{- end -}} diff --git a/docs/template/gv_list.tpl b/docs/template/gv_list.tpl new file mode 100644 index 000000000..a10ded3ef --- /dev/null +++ b/docs/template/gv_list.tpl @@ -0,0 +1,21 @@ +{{- define "gvList" -}} +{{- $groupVersions := . -}} + +--- +title: Resource Definitions API Reference +slug: /reference/api7-ingress-controller/crd-reference +description: Explore detailed reference documentation for the custom resource definitions (CRDs) supported by the API7 Ingress Controller. +--- + +This document provides the API resource description for the API7 Ingress Controller. + +## Packages +{{- range $groupVersions }} +- {{ markdownRenderGVLink . }} +{{- end }} + +{{ range $groupVersions }} +{{ template "gvDetails" . }} +{{ end }} + +{{- end -}} diff --git a/docs/template/type.tpl b/docs/template/type.tpl new file mode 100644 index 000000000..c677a2b23 --- /dev/null +++ b/docs/template/type.tpl @@ -0,0 +1,42 @@ +{{- define "type" -}} +{{- $type := $.type -}} +{{- $isKind := $.isKind -}} +{{- if markdownShouldRenderType $type -}} + +{{- if $isKind -}} +### {{ $type.Name }} +{{ else -}} +#### {{ $type.Name }} +{{ end -}} + +{{ if $type.IsAlias }}_Base type:_ `{{ markdownRenderTypeLink $type.UnderlyingType }}`{{ end }} + +{{ $type.Doc | replace "\n\n" "

" }} + +{{ if $type.GVK -}} + +{{- end }} + +{{ if $type.Members -}} +| Field | Description | +| --- | --- | +{{ if $type.GVK -}} +| `apiVersion` _string_ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` +| `kind` _string_ | `{{ $type.GVK.Kind }}` +{{ end -}} + +{{ range $type.Members -}} +| `{{ .Name }}` _{{ markdownRenderType .Type }}_ | {{ template "type_members" . }} | +{{ end -}} + +{{ end }} + +{{ if $type.References -}} +_Appears in:_ +{{- range $type.SortedReferences }} +- {{ markdownRenderTypeLink . }} +{{- end }} +{{- end }} + +{{- end -}} +{{- end -}} diff --git a/docs/template/type_members.tpl b/docs/template/type_members.tpl new file mode 100644 index 000000000..164223a6a --- /dev/null +++ b/docs/template/type_members.tpl @@ -0,0 +1,9 @@ +{{- define "type_members" -}} +{{- $field := . -}} +{{- if eq $field.Name "metadata" -}} +Please refer to the Kubernetes API documentation for details on the `metadata` field. +{{- else -}} +{{- /* First replace makes paragraphs separated, second merges lines in paragraphs. */ -}} +{{ $field.Doc | replace "\n\n" "

" | replace "\n" " " }} +{{- end -}} +{{- end -}}