diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..1075d04 --- /dev/null +++ b/Makefile @@ -0,0 +1,25 @@ +API_DOCS ?= $(CURDIR)/bin/gen-crd-api-reference-docs +BRANCH ?= $(shell git tag --sort=-version:refname | grep -v '^manager/' | grep -v '^helm/' | head -1) + +.PHONY: gen-api-docs +gen-api-docs: $(API_DOCS) + @TEMPDIR=$$(mktemp -d) && \ + trap 'rm -rf "$$TEMPDIR"' EXIT && \ + echo "Extracting Go types from $(BRANCH)..." && \ + git archive $(BRANCH) -- api/ go.mod go.sum | tar -x -C "$$TEMPDIR" && \ + if [ ! -f "$$TEMPDIR/api/v1alpha1/doc.go" ]; then \ + git show main:api/v1alpha1/doc.go > "$$TEMPDIR/api/v1alpha1/doc.go"; \ + fi && \ + echo "Downloading dependencies..." && \ + cd "$$TEMPDIR" && \ + go mod download && \ + echo "Generating API reference..." && \ + $(API_DOCS) \ + -config $(CURDIR)/hack/api-reference/config.json \ + -template-dir $(CURDIR)/hack/api-reference/template \ + -api-dir ./api/v1alpha1 \ + -out-file $(CURDIR)/includes/api-reference.html && \ + echo "Done: $(CURDIR)/includes/api-reference.html" + +$(API_DOCS): + GOBIN=$(CURDIR)/bin go install github.com/ahmetb/gen-crd-api-reference-docs@latest diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md new file mode 100644 index 0000000..ea2b46e --- /dev/null +++ b/content/en/docs/reference/_index.md @@ -0,0 +1,10 @@ +--- +title: "Reference" +linkTitle: "Reference" +weight: 99 +type: "docs" +description: > + API reference +--- + +{{% include "includes/api-reference.html" %}} diff --git a/hack/api-reference/config.json b/hack/api-reference/config.json new file mode 100644 index 0000000..9b853bd --- /dev/null +++ b/hack/api-reference/config.json @@ -0,0 +1,20 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", + "docsURLTemplate": "https://pkg.go.dev/{{.PackagePath}}#{{.TypeIdentifier}}" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/api-reference/template/members.tpl b/hack/api-reference/template/members.tpl new file mode 100644 index 0000000..a529c67 --- /dev/null +++ b/hack/api-reference/template/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/hack/api-reference/template/pkg.tpl b/hack/api-reference/template/pkg.tpl new file mode 100644 index 0000000..842ec93 --- /dev/null +++ b/hack/api-reference/template/pkg.tpl @@ -0,0 +1,49 @@ +{{ define "packages" }} + +{{ 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 + {{ with .gitCommit }} on git commit {{ . }}{{end}}. +

+ +{{ end }} diff --git a/hack/api-reference/template/type.tpl b/hack/api-reference/template/type.tpl new file mode 100644 index 0000000..976e224 --- /dev/null +++ b/hack/api-reference/template/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/includes/api-reference.html b/includes/api-reference.html new file mode 100644 index 0000000..8fc69df --- /dev/null +++ b/includes/api-reference.html @@ -0,0 +1,963 @@ +

Packages:

+ +

operator.sme.sap.com/v1alpha1

+
+

Package v1alpha1 contains API Schema definitions for the operator v1alpha1 API group

+
+Resource Types: + +

CAPOperator +

+
+

CAPOperator is the Schema for the CAPOperators API

+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +CAPOperatorSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+subscriptionServer
+ + +SubscriptionServer + + +		 +

SubscriptionServer specification

+
+dnsTarget
+ +string + +		 +

Public ingress URL for the cluster Load Balancer

+
+ingressGatewayLabels
+ + +[]NameValue + + +		 +

Labels used to identify the istio ingress-gateway component and its corresponding namespace. Usually {“app”:“istio-ingressgateway”,“istio”:“ingressgateway”}

+
+controller
+ + +Controller + + +		 +

Controller specification

+
+monitoring
+ + +Monitoring + + +		 +

Monitoring specification

+
+webhook
+ + +Webhook + + +		 +

Webhook specification

+
+
+status
+ + +CAPOperatorStatus + + +		 +
+

CAPOperatorSpec +

+

+(Appears on: CAPOperator) +

+
+

CAPOperatorSpec defines the desired state of CAPOperator

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+subscriptionServer
+ + +SubscriptionServer + + +		 +

SubscriptionServer specification

+
+dnsTarget
+ +string + +		 +

Public ingress URL for the cluster Load Balancer

+
+ingressGatewayLabels
+ + +[]NameValue + + +		 +

Labels used to identify the istio ingress-gateway component and its corresponding namespace. Usually {“app”:“istio-ingressgateway”,“istio”:“ingressgateway”}

+
+controller
+ + +Controller + + +		 +

Controller specification

+
+monitoring
+ + +Monitoring + + +		 +

Monitoring specification

+
+webhook
+ + +Webhook + + +		 +

Webhook specification

+
+

CAPOperatorStatus +

+

+(Appears on: CAPOperator) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+Status
+ +github.com/sap/component-operator-runtime/pkg/component.Status + +		 +

+(Members of Status are embedded into this type.) +

+

add other fields to status subresource here

+
+

CertManager +

+

+(Appears on: CertificateConfig) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+issuerName
+ +string + +		 +

Issuer name

+
+issuerKind
+ +string + +		 +

Issuer kind

+
+issuerGroup
+ +string + +		 +

Issuer group

+
+

CertificateConfig +

+

+(Appears on: SubscriptionServer, Webhook) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+gardener
+ + +Gardener + + +		 +

Gardener configuration

+
+certManager
+ + +CertManager + + +		 +

CertManager configuration

+
+

CertificateManager +(string alias)

+

+(Appears on: SubscriptionServer, Webhook) +

+
+

Supported values are Gardener, CertManager, or Default +For the subscription server, it can be either Gardener or CertManager, while for the webhook, it can be either Default or CertManager

+
+

CommonConfig +

+

+(Appears on: Controller, SubscriptionServer, Webhook) +

+
+

Common aspects for Controller, SubscriptionServer and Webhook

+
+ + + + + + + + + + + + + +
FieldDescription
+resources
+ + +Kubernetes core/v1.ResourceRequirements + + +		 +

Resource Requirements configuration

+
+

Controller +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+detailedOperationalMetrics
+ +bool + +		 +

Optionally enable detailed opertational metrics for the controller by setting this to true

+
+maxConcurrentReconciles
+ + +MaxConcurrentReconciles + + +		 +

Configuration of maximum number of concurrent reconciles for the resources managed by the controller

+
+versionMonitoring
+ + +VersionMonitoring + + +		 +

Version monitoring configuration

+
+volumes
+ + +[]Kubernetes core/v1.Volume + + +		 +

Optionally specify list of additional volumes for the controller pod(s)

+
+volumeMounts
+ + +[]Kubernetes core/v1.VolumeMount + + +		 +

Optionally specify list of additional volumeMounts for the controller container(s)

+
+

Duration +(string alias)

+

+(Appears on: VersionMonitoring) +

+
+

Duration is a valid time duration that can be parsed by Prometheus +Supported units: y, w, d, h, m, s, ms +Examples: 30s, 1m, 1h20m15s, 15d

+
+

Gardener +

+

+(Appears on: CertificateConfig) +

+
+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+issuerName
+ +string + +		 +

Issuer name

+
+issuerNamespace
+ +string + +		 +

Issuer namespace

+
+

Grafana +

+

+(Appears on: Monitoring) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+dashboard
+ + +GrafanaDashboard + + +		 +

Dashboard configuration

+
+

GrafanaDashboard +

+

+(Appears on: Grafana) +

+
+
+ + + + + + + + + + + + + +
FieldDescription
+configMapLabels
+ +map[string]string + +		 +

Labels for selecting ConfigMaps with dashboards in Grafana

+
+

MaxConcurrentReconciles +

+

+(Appears on: Controller) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+capApplication
+ +string + +		 +

Maximum number of concurrent reconciles for the cap application

+
+capApplicationVersion
+ +string + +		 +

Maximum number of concurrent reconciles for the cap application version

+
+capTenant
+ +string + +		 +

Maximum number of concurrent reconciles for the cap tenant

+
+capTenantOperation
+ +string + +		 +

Maximum number of concurrent reconciles for the cap tenant operation

+
+domain
+ +string + +		 +

Maximum number of concurrent reconciles for the domain

+
+clusterDomain
+ +string + +		 +

Maximum number of concurrent reconciles for the cluster domain

+
+

Monitoring +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+enabled
+ +bool + +		 +

Optionally enable Prometheus monitoring for all components

+
+serviceMonitorSelectorLabels
+ +map[string]string + +		 +

Prometheus service monitor selector labels

+
+grafana
+ + +Grafana + + +		 +

Grafana configuration

+
+

NameValue +

+

+(Appears on: CAPOperatorSpec) +

+
+

Generic Name/Value configuration

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+name
+ +string + +		 +
+value
+ +string + +		 +
+

SubscriptionServer +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+subDomain
+ +string + +		 +
+certificateManager
+ + +CertificateManager + + +		 +

Certificate manager which can be either Gardener or CertManager

+
+certificateConfig
+ + +CertificateConfig + + +		 +

Certificate configuration

+
+

VersionMonitoring +

+

+(Appears on: Controller) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+prometheusAddress
+ +string + +		 +

URL of the Prometheus server from which metrics related to managed application versions can be queried

+
+metricsEvaluationInterval
+ + +Duration + + +		 +

The duration (example 2h) after which versions are evaluated for deletion; based on specified workload metrics

+
+promClientAcquireRetryDelay
+ + +Duration + + +		 +

The duration (example 10m) to wait before retrying to acquire Prometheus client and verify connection, after a failed attempt

+
+

Webhook +

+

+(Appears on: CAPOperatorSpec) +

+
+
+ + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+CommonConfig
+ + +CommonConfig + + +		 +

+(Members of CommonConfig are embedded into this type.) +

+
+certificateManager
+ + +CertificateManager + + +		 +

Certificate manager which can be either Default or CertManager

+
+certificateConfig
+ + +CertificateConfig + + +		 +

Certificate configuration

+
+
+

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