From 761798ebef8e73447eb81e2d471eb8dde1f77bb9 Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Fri, 20 Oct 2023 12:19:16 +0200 Subject: [PATCH] Fix external links on API doc, add default values Support for default values was added in https://github.com/elastic/crd-ref-docs/commit/9a3105b6ca763ea03393fa6f396046ad7b5d4e38 but templating support is not complete yet. We will probably revisit this when a new release of crd-ref-docs is out. Change-Id: I24e420808152da563ce01365d5371618747ae61b --- api/v1/softwarefactory_types.go | 116 +++---- ...softwarefactory-project.io_logservers.yaml | 6 +- ...efactory-project.io_softwarefactories.yaml | 169 +++++---- doc/_apidoc/templates/gv_details.tpl | 19 ++ doc/_apidoc/templates/gv_list.tpl | 15 + doc/_apidoc/templates/type.tpl | 33 ++ doc/_apidoc/templates/type_member.tpl | 8 + doc/reference/api/index.md | 320 +++++++++--------- tools/build-api-doc.sh | 3 +- 9 files changed, 398 insertions(+), 291 deletions(-) create mode 100644 doc/_apidoc/templates/gv_details.tpl create mode 100644 doc/_apidoc/templates/gv_list.tpl create mode 100644 doc/_apidoc/templates/type.tpl create mode 100644 doc/_apidoc/templates/type_member.tpl diff --git a/api/v1/softwarefactory_types.go b/api/v1/softwarefactory_types.go index b20a71be..f0e952c3 100644 --- a/api/v1/softwarefactory_types.go +++ b/api/v1/softwarefactory_types.go @@ -28,13 +28,13 @@ const ( type LetsEncryptSpec struct { // Specify the Lets encrypt server. // Valid values are: - // - "staging" - // - "prod" + // "staging", + // "prod" Server LEServer `json:"server"` } type StorageSpec struct { - // Storage space to allocate to the resource, expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/ + // Storage space to allocate to the resource, expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) Size resource.Quantity `json:"size"` // Default storage class to use with Persistent Volume Claims issued by this resource. Consult your cluster's configuration to see what storage classes are available and recommended for your use case. ClassName string `json:"className,omitempty"` @@ -54,87 +54,87 @@ type ConfigLocationSpec struct { ZuulConnectionName string `json:"zuul-connection-name"` } -// Describes a Zuul connection using the `github` driver: https://zuul-ci.org/docs/zuul/latest/drivers/github.html# +// Describes a Zuul connection using the [github driver](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#). type GitHubConnection struct { // How the connection will be named in Zuul's configuration and appear in zuul-web Name string `json:"name"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id + // the [app_id](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id) parameter AppID string `json:"appId"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key + // the [app_key](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key) parameter AppKey string `json:"appKey"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token + // the [api_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token) parameter APIToken string `json:"apiToken"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token + // the [webhook_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token) parameter // +optional WebhookToken string `json:"webHookToken,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server + // the [server](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server) parameter // +optional Server string `json:"server,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname + // the [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname) parameter // +optional Canonicalhostname string `json:"canonicalHostname,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl + // the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl) parameter // +kubebuilder:default:=true // +optional VerifySSL bool `json:"verifySsl,omitempty"` } -// Describes a Zuul connection using the `gerrit` driver: https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration +// Describes a Zuul connection using the [gerrit driver](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration) type GerritConnection struct { // How the connection will be named in Zuul's configuration and appear in zuul-web Name string `json:"name"` - // The gerrit server hostname. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server + // The gerrit server hostname. Equivalent to the [server](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server) parameter. Hostname string `json:"hostname"` - // SSH port number to the Gerrit instance. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port + // SSH port number to the Gerrit instance. Equivalent to the [port](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port) parameter. // +kubebuilder:default:=29418 Port uint16 `json:"port,omitempty"` - // URL to Gerrit's web interface. https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl + // URL to Gerrit's web interface. the [baseurl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl) parameter. // +kubebuilder:validation:Pattern:=`^https?:\/\/.+$` Puburl string `json:"puburl,omitempty"` - // Username that Zuul will use to authenticate on the Gerrit instance. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user + // Username that Zuul will use to authenticate on the Gerrit instance. Equivalent to the [user](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user) parameter. // +kubebuilder:default:=zuul Username string `json:"username,omitempty"` - // The canonical hostname associated with the git repositories on the Gerrit server. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname + // The canonical hostname associated with the git repositories on the Gerrit server. Equivalent to the [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname) parameter. Canonicalhostname string `json:"canonicalhostname,omitempty"` - // The name of a Kubernetes secret holding the Gerrit user's API Password. The secret's data must have a key called "password". Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password + // The name of a Kubernetes secret holding the Gerrit user's API Password. The secret's data must have a key called "password". Equivalent to the [password](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password) parameter. Password string `json:"password,omitempty"` - // Set to true to force git operations over SSH even if the password attribute is set. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh + // Set to true to force git operations over SSH even if the password attribute is set. Equivalent to the [git_over_ssh](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh) parameter. // +kubebuilder:default:=false GitOverSSH bool `json:"git-over-ssh,omitempty"` - // Disable SSL certificate verification with the Gerrit instance when set to false. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl + // Disable SSL certificate verification with the Gerrit instance when set to false. Equivalent to the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl) parameter. // +kubebuilder:default:=true VerifySSL bool `json:"verifyssl,omitempty"` } -// The description of an OpenIDConnect authenticator, see https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication +// The description of an OpenIDConnect authenticator, see [Zuul's authentication documentation](https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication) type ZuulOIDCAuthenticatorSpec struct { - // The name of the authenticator in Zuul's configuration, see https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E + // The [name of the authenticator in Zuul's configuration](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E) Name string `json:"name"` - // Authentication realm, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm + // Authentication realm, equivalent to the [realm](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm) parameter Realm string `json:"realm"` - // The client ID, as exposed in the `aud` claim of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id + // The client ID, as exposed in the `aud` claim of a JWT. Equivalent to the [client_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id) parameter ClientID string `json:"clientID"` - // The issuer ID, as exposed in the `iss` claim of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id + // The issuer ID, as exposed in the `iss` claim of a JWT. Equivalent to the [issuer_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id) parameter IssuerID string `json:"issuerID"` // +kubebuilder:default:=sub - // The JWT claim to use as a unique identifier in audit logs, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id + // The JWT claim to use as a unique identifier in audit logs, equivalent to the [uid_claim](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.uid_claim) parameter UIDClaim string `json:"uidClaim,omitempty"` - // Optionally override the `expires_at` claim in a JWT to enforce a custom expiration time on a token. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time + // Optionally override the `expires_at` claim in a JWT to enforce a custom expiration time on a token. Equivalent to the [max_validity_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time) parameter MaxValidityTime int32 `json:"maxValidityTime,omitempty"` // +kubebuilder:default:=0 - // Optionally compensate for skew between Zuul's and the Identity Provider's clocks, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew + // Optionally compensate for skew between Zuul's and the Identity Provider's clocks, equivalent to the [skew](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew) parameter Skew int32 `json:"skew,omitempty"` - // Optionally provide a URL to fetch the Identity Provider's key set, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url + // Optionally provide a URL to fetch the Identity Provider's key set, equivalent to the [keys_url](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url) parameter KeysURL string `json:"keysURL,omitempty"` // +kubebuilder:default:="openid profile" - // The scope used to fetch a user's details, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope + // The scope used to fetch a user's details, equivalent to the [scope](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope) parameter Scope string `json:"scope,omitempty"` - // Optionally provide the claim where the authority is set if not in `iss`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority + // Optionally provide the claim where the authority is set if not in `iss`, equivalent to the [authority](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority) parameter Authority string `json:"authority,omitempty"` - // Optionally provide the claim where the audience is set if not in `aud`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience + // Optionally provide the claim where the audience is set if not in `aud`, equivalent to the [audience](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience) parameter Audience string `json:"audience,omitempty"` // +kubebuilder:default:=true - // If set to false, zuul-web will skip loading the Identity Provider's `userinfo` endpoint and rely on what's available in the JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info + // If set to false, zuul-web will skip loading the Identity Provider's `userinfo` endpoint and rely on what's available in the JWT. Equivalent to the [load_user_info](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info) parameter LoadUserInfo bool `json:"loadUserInfo,omitempty"` } @@ -146,9 +146,9 @@ type ZuulExecutorSpec struct { Replicas int32 `json:"replicas,omitempty"` // Specify the Log Level of the zuul-executor service. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". // Changing this value will restart the service. // +optional LogLevel LogLevel `json:"logLevel,omitempty"` @@ -157,9 +157,9 @@ type ZuulExecutorSpec struct { type ZuulWebSpec struct { // Specify the Log Level of the zuul-web launcher service. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". // Changing this value will restart the service. // +optional LogLevel LogLevel `json:"logLevel,omitempty"` @@ -173,29 +173,29 @@ type ZuulSchedulerSpec struct { StatsdTarget string `json:"statsdTarget,omitempty"` // Specify the Log Level of the zuul-scheduler service. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". // Changing this value will restart the service. // +optional LogLevel LogLevel `json:"logLevel,omitempty"` } -// Some of the Zuul Merger Configurations can be found at https://zuul-ci.org/docs/zuul/latest/configuration.html#merger +// Zuul Merger Configuration, see [Zuul's documentation](https://zuul-ci.org/docs/zuul/latest/configuration.html#merger) type ZuulMergerSpec struct { - // https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name + // the [git_user_name](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name) parameter // +optional GitUserName string `json:"gitUserName,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email + // the [git_user_email](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email) parameter // +optional GitUserEmail string `json:"gitUserEmail,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit + // the [git_http_low_speed_limit](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit) parameter // +kubebuilder:validation:Minimum:=0 GitHTTPLowSpeedLimit int32 `json:"gitHttpLowSpeedLimit,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time + // the [git_http_low_speed_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time) parameter // +kubebuilder:validation:Minimum:=0 GitHTTPLowSpeedTime int32 `json:"gitHttpLowSpeedTime,omitempty"` - // https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout + // the [git_timeout](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout) parameter // +kubebuilder:validation:Minimum:=1 GitTimeout int32 `json:"gitTimeout,omitempty"` // Storage-related settings @@ -205,9 +205,9 @@ type ZuulMergerSpec struct { MinReplicas int32 `json:"minReplicas,omitempty"` // Specify the Log Level of the nodepool launcher service. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". // Changing this value will restart the service. // +optional LogLevel LogLevel `json:"logLevel,omitempty"` @@ -271,9 +271,9 @@ const ( type NodepoolLauncherSpec struct { // Specify the Log Level of the nodepool launcher service. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". // Changing this value will restart the service. // +optional LogLevel LogLevel `json:"logLevel,omitempty"` @@ -284,9 +284,9 @@ type NodepoolBuilderSpec struct { Storage StorageSpec `json:"storage,omitempty"` // Specify the Log Level of the nodepool launcher process. // Valid values are: - // - "INFO" (default) - // - "WARN" - // - "DEBUG" + // "INFO" (default), + // "WARN", + // "DEBUG". LogLevel LogLevel `json:"logLevel,omitempty"` } @@ -316,7 +316,7 @@ type GitServerSpec struct { type Secret struct { // Name of the referent. - // More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names + // More info on [kubernetes' documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). Name string `json:"name"` // The key of the secret to select from. Must be a valid secret key. Key string `json:"key"` diff --git a/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml b/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml index 56f9b63a..9adddd5e 100644 --- a/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml +++ b/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml @@ -54,7 +54,7 @@ spec: properties: server: description: 'Specify the Lets encrypt server. Valid values are: - - "staging" - "prod"' + "staging", "prod"' enum: - prod - staging @@ -96,8 +96,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: diff --git a/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml b/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml index e1ddd2fe..e89959e0 100644 --- a/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml +++ b/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml @@ -91,8 +91,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -105,7 +105,7 @@ spec: properties: server: description: 'Specify the Lets encrypt server. Valid values are: - - "staging" - "prod"' + "staging", "prod"' enum: - prod - staging @@ -139,8 +139,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -168,8 +168,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -188,8 +188,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -207,8 +207,7 @@ spec: properties: logLevel: description: 'Specify the Log Level of the nodepool launcher - process. Valid values are: - "INFO" (default) - "WARN" - - "DEBUG"' + process. Valid values are: "INFO" (default), "WARN", "DEBUG".' enum: - INFO - WARN @@ -227,8 +226,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, - expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, + expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -240,8 +239,8 @@ spec: properties: logLevel: description: 'Specify the Log Level of the nodepool launcher - service. Valid values are: - "INFO" (default) - "WARN" - - "DEBUG" Changing this value will restart the service.' + service. Valid values are: "INFO" (default), "WARN", "DEBUG". + Changing this value will restart the service.' enum: - INFO - WARN @@ -271,8 +270,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, expressed - as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, expressed + as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -293,8 +292,8 @@ spec: properties: logLevel: description: 'Specify the Log Level of the zuul-executor service. - Valid values are: - "INFO" (default) - "WARN" - "DEBUG" - Changing this value will restart the service.' + Valid values are: "INFO" (default), "WARN", "DEBUG". Changing + this value will restart the service.' enum: - INFO - WARN @@ -317,8 +316,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, - expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, + expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -329,20 +328,25 @@ spec: description: The list of Gerrit-based connections to add to Zuul's configuration items: - description: 'Describes a Zuul connection using the `gerrit` - driver: https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration' + description: Describes a Zuul connection using the [gerrit driver](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration) properties: canonicalhostname: description: The canonical hostname associated with the - git repositories on the Gerrit server. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname + git repositories on the Gerrit server. Equivalent to the + [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname) + parameter. type: string git-over-ssh: default: false description: Set to true to force git operations over SSH - even if the password attribute is set. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh + even if the password attribute is set. Equivalent to the + [git_over_ssh](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh) + parameter. type: boolean hostname: - description: The gerrit server hostname. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server + description: The gerrit server hostname. Equivalent to the + [server](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server) + parameter. type: string name: description: How the connection will be named in Zuul's @@ -351,26 +355,31 @@ spec: password: description: The name of a Kubernetes secret holding the Gerrit user's API Password. The secret's data must have - a key called "password". Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password + a key called "password". Equivalent to the [password](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password) + parameter. type: string port: default: 29418 description: SSH port number to the Gerrit instance. Equivalent - to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port + to the [port](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port) + parameter. type: integer puburl: - description: URL to Gerrit's web interface. https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl + description: URL to Gerrit's web interface. the [baseurl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl) + parameter. pattern: ^https?:\/\/.+$ type: string username: default: zuul description: Username that Zuul will use to authenticate - on the Gerrit instance. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user + on the Gerrit instance. Equivalent to the [user](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user) + parameter. type: string verifyssl: default: true description: Disable SSL certificate verification with the - Gerrit instance when set to false. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl + Gerrit instance when set to false. Equivalent to the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl) + parameter. type: boolean required: - hostname @@ -381,34 +390,40 @@ spec: description: The list of GitHub-based connections to add to Zuul's configuration items: - description: 'Describes a Zuul connection using the `github` - driver: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#' + description: Describes a Zuul connection using the [github driver](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#). properties: apiToken: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token + description: the [api_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token) + parameter type: string appId: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id + description: the [app_id](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id) + parameter type: string appKey: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key + description: the [app_key](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key) + parameter type: string canonicalHostname: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname + description: the [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname) + parameter type: string name: description: How the connection will be named in Zuul's configuration and appear in zuul-web type: string server: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server + description: the [server](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server) + parameter type: string verifySsl: default: true - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl + description: the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl) + parameter type: boolean webHookToken: - description: https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token + description: the [webhook_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token) + parameter type: string required: - apiToken @@ -421,30 +436,35 @@ spec: description: Configuration of the merger microservice properties: gitHttpLowSpeedLimit: - description: https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit + description: the [git_http_low_speed_limit](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit) + parameter format: int32 minimum: 0 type: integer gitHttpLowSpeedTime: - description: https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time + description: the [git_http_low_speed_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time) + parameter format: int32 minimum: 0 type: integer gitTimeout: - description: https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout + description: the [git_timeout](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout) + parameter format: int32 minimum: 1 type: integer gitUserEmail: - description: https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email + description: the [git_user_email](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email) + parameter type: string gitUserName: - description: https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name + description: the [git_user_name](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name) + parameter type: string logLevel: description: 'Specify the Log Level of the nodepool launcher - service. Valid values are: - "INFO" (default) - "WARN" - - "DEBUG" Changing this value will restart the service.' + service. Valid values are: "INFO" (default), "WARN", "DEBUG". + Changing this value will restart the service.' enum: - INFO - WARN @@ -468,8 +488,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, - expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, + expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -481,62 +501,73 @@ spec: enable admin API access on zuul-web items: description: The description of an OpenIDConnect authenticator, - see https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication + see [Zuul's authentication documentation](https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication) properties: audience: description: Optionally provide the claim where the audience - is set if not in `aud`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience + is set if not in `aud`, equivalent to the [audience](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience) + parameter type: string authority: description: Optionally provide the claim where the authority - is set if not in `iss`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority + is set if not in `iss`, equivalent to the [authority](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority) + parameter type: string clientID: description: The client ID, as exposed in the `aud` claim - of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id + of a JWT. Equivalent to the [client_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id) + parameter type: string issuerID: description: The issuer ID, as exposed in the `iss` claim - of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id + of a JWT. Equivalent to the [issuer_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id) + parameter type: string keysURL: description: Optionally provide a URL to fetch the Identity - Provider's key set, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url + Provider's key set, equivalent to the [keys_url](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url) + parameter type: string loadUserInfo: default: true description: If set to false, zuul-web will skip loading the Identity Provider's `userinfo` endpoint and rely on - what's available in the JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info + what's available in the JWT. Equivalent to the [load_user_info](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info) + parameter type: boolean maxValidityTime: description: Optionally override the `expires_at` claim in a JWT to enforce a custom expiration time on a token. - Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time + Equivalent to the [max_validity_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time) + parameter format: int32 type: integer name: - description: The name of the authenticator in Zuul's configuration, - see https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E + description: The [name of the authenticator in Zuul's configuration](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E) type: string realm: - description: Authentication realm, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm + description: Authentication realm, equivalent to the [realm](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm) + parameter type: string scope: default: openid profile description: The scope used to fetch a user's details, equivalent - to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope + to the [scope](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope) + parameter type: string skew: default: 0 description: Optionally compensate for skew between Zuul's - and the Identity Provider's clocks, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew + and the Identity Provider's clocks, equivalent to the + [skew](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew) + parameter format: int32 type: integer uidClaim: default: sub description: The JWT claim to use as a unique identifier - in audit logs, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id + in audit logs, equivalent to the [uid_claim](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.uid_claim) + parameter type: string required: - clientID @@ -550,8 +581,8 @@ spec: properties: logLevel: description: 'Specify the Log Level of the zuul-scheduler - service. Valid values are: - "INFO" (default) - "WARN" - - "DEBUG" Changing this value will restart the service.' + service. Valid values are: "INFO" (default), "WARN", "DEBUG". + Changing this value will restart the service.' enum: - INFO - WARN @@ -574,8 +605,8 @@ spec: anyOf: - type: integer - type: string - description: 'Storage space to allocate to the resource, - expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/' + description: Storage space to allocate to the resource, + expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$ x-kubernetes-int-or-string: true required: @@ -587,8 +618,8 @@ spec: properties: logLevel: description: 'Specify the Log Level of the zuul-web launcher - service. Valid values are: - "INFO" (default) - "WARN" - - "DEBUG" Changing this value will restart the service.' + service. Valid values are: "INFO" (default), "WARN", "DEBUG". + Changing this value will restart the service.' enum: - INFO - WARN diff --git a/doc/_apidoc/templates/gv_details.tpl b/doc/_apidoc/templates/gv_details.tpl new file mode 100644 index 00000000..30ad0d75 --- /dev/null +++ b/doc/_apidoc/templates/gv_details.tpl @@ -0,0 +1,19 @@ +{{- define "gvDetails" -}} +{{- $gv := . -}} + +## {{ $gv.GroupVersionString }} + +{{ $gv.Doc }} + +{{- if $gv.Kinds }} +### Resource Types +{{- range $gv.SortedKinds }} +- {{ $gv.TypeForKind . | markdownRenderTypeLink }} +{{- end }} +{{ end }} + +{{ range $gv.SortedTypes }} +{{ template "type" . }} +{{ end }} + +{{- end -}} diff --git a/doc/_apidoc/templates/gv_list.tpl b/doc/_apidoc/templates/gv_list.tpl new file mode 100644 index 00000000..a4d3dadf --- /dev/null +++ b/doc/_apidoc/templates/gv_list.tpl @@ -0,0 +1,15 @@ +{{- define "gvList" -}} +{{- $groupVersions := . -}} + +# API Reference + +## Packages +{{- range $groupVersions }} +- {{ markdownRenderGVLink . }} +{{- end }} + +{{ range $groupVersions }} +{{ template "gvDetails" . }} +{{ end }} + +{{- end -}} diff --git a/doc/_apidoc/templates/type.tpl b/doc/_apidoc/templates/type.tpl new file mode 100644 index 00000000..6bd202b5 --- /dev/null +++ b/doc/_apidoc/templates/type.tpl @@ -0,0 +1,33 @@ +{{- define "type" -}} +{{- $type := . -}} +{{- if markdownShouldRenderType $type -}} + +#### {{ $type.Name }} + +{{ if $type.IsAlias }}_Underlying type:_ _{{ markdownRenderTypeLink $type.UnderlyingType }}_{{ end }} + +{{ $type.Doc }} + +{{ if $type.References -}} +_Appears in:_ +{{- range $type.SortedReferences }} +- {{ markdownRenderTypeLink . }} +{{- end }} +{{- end }} + +{{ if $type.Members -}} +| Field | Description | Default Value | +| --- | --- | --- | +{{ 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" . }} | {{ if eq .Name "logLevel" -}}INFO{{ else if index .Markers "kubebuilder:default" -}}{{ index .Markers "kubebuilder:default" 0 }}{{- else -}}-{{ end -}} | +{{ end -}} + +{{ end -}} + +{{- end -}} +{{- end -}} diff --git a/doc/_apidoc/templates/type_member.tpl b/doc/_apidoc/templates/type_member.tpl new file mode 100644 index 00000000..041758a8 --- /dev/null +++ b/doc/_apidoc/templates/type_member.tpl @@ -0,0 +1,8 @@ +{{- define "type_members" -}} +{{- $field := . -}} +{{- if eq $field.Name "metadata" -}} +Refer to Kubernetes API documentation for fields of `metadata`. +{{- else -}} +{{ markdownRenderFieldDoc $field.Doc }} +{{- end -}} +{{- end -}} diff --git a/doc/reference/api/index.md b/doc/reference/api/index.md index 5860d2b6..5e296932 100644 --- a/doc/reference/api/index.md +++ b/doc/reference/api/index.md @@ -27,54 +27,54 @@ Package v1 contains API Schema definitions for the sf v1 API group _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `base-url` _string_ | Base URL to use to perform git-related actions on the config repository. For example, if hosted on GitHub, the Base URL would be `https://github.com//` | -| `name` _string_ | The name of the `config` repository. This value is appended to `base-url` to clone the repository | -| `zuul-connection-name` _string_ | Name of the Zuul connection through which Zuul can handle git events on the config repository | +| Field | Description | Default Value | +| --- | --- | --- | +| `base-url` _string_ | Base URL to use to perform git-related actions on the config repository. For example, if hosted on GitHub, the Base URL would be `https://github.com//` | -| +| `name` _string_ | The name of the `config` repository. This value is appended to `base-url` to clone the repository | -| +| `zuul-connection-name` _string_ | Name of the Zuul connection through which Zuul can handle git events on the config repository | -| #### GerritConnection -Describes a Zuul connection using the `gerrit` driver: https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration +Describes a Zuul connection using the [gerrit driver](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#connection-configuration) _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `name` _string_ | How the connection will be named in Zuul's configuration and appear in zuul-web | -| `hostname` _string_ | The gerrit server hostname. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server | -| `port` _integer_ | SSH port number to the Gerrit instance. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port | -| `puburl` _string_ | URL to Gerrit's web interface. https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl | -| `username` _string_ | Username that Zuul will use to authenticate on the Gerrit instance. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user | -| `canonicalhostname` _string_ | The canonical hostname associated with the git repositories on the Gerrit server. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname | -| `password` _string_ | The name of a Kubernetes secret holding the Gerrit user's API Password. The secret's data must have a key called "password". Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password | -| `git-over-ssh` _boolean_ | Set to true to force git operations over SSH even if the password attribute is set. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh | -| `verifyssl` _boolean_ | Disable SSL certificate verification with the Gerrit instance when set to false. Equivalent to https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl | +| Field | Description | Default Value | +| --- | --- | --- | +| `name` _string_ | How the connection will be named in Zuul's configuration and appear in zuul-web | -| +| `hostname` _string_ | The gerrit server hostname. Equivalent to the [server](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.server) parameter. | -| +| `port` _integer_ | SSH port number to the Gerrit instance. Equivalent to the [port](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.port) parameter. | {29418}| +| `puburl` _string_ | URL to Gerrit's web interface. the [baseurl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.baseurl) parameter. | -| +| `username` _string_ | Username that Zuul will use to authenticate on the Gerrit instance. Equivalent to the [user](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.user) parameter. | {zuul}| +| `canonicalhostname` _string_ | The canonical hostname associated with the git repositories on the Gerrit server. Equivalent to the [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20connection%3E.canonical_hostname) parameter. | -| +| `password` _string_ | The name of a Kubernetes secret holding the Gerrit user's API Password. The secret's data must have a key called "password". Equivalent to the [password](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.password) parameter. | -| +| `git-over-ssh` _boolean_ | Set to true to force git operations over SSH even if the password attribute is set. Equivalent to the [git_over_ssh](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.git_over_ssh) parameter. | {false}| +| `verifyssl` _boolean_ | Disable SSL certificate verification with the Gerrit instance when set to false. Equivalent to the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/gerrit.html#attr-%3Cgerrit%20ssh%20connection%3E.verify_ssl) parameter. | {true}| #### GitHubConnection -Describes a Zuul connection using the `github` driver: https://zuul-ci.org/docs/zuul/latest/drivers/github.html# +Describes a Zuul connection using the [github driver](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#). _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `name` _string_ | How the connection will be named in Zuul's configuration and appear in zuul-web | -| `appId` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id | -| `appKey` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key | -| `apiToken` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token | -| `webHookToken` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token | -| `server` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server | -| `canonicalHostname` _string_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname | -| `verifySsl` _boolean_ | https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl | +| Field | Description | Default Value | +| --- | --- | --- | +| `name` _string_ | How the connection will be named in Zuul's configuration and appear in zuul-web | -| +| `appId` _string_ | the [app_id](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_id) parameter | -| +| `appKey` _string_ | the [app_key](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.app_key) parameter | -| +| `apiToken` _string_ | the [api_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.api_token) parameter | -| +| `webHookToken` _string_ | the [webhook_token](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.webhook_token) parameter | -| +| `server` _string_ | the [server](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.server) parameter | -| +| `canonicalHostname` _string_ | the [canonical_hostname](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.canonical_hostname) parameter | -| +| `verifySsl` _boolean_ | the [verify_ssl](https://zuul-ci.org/docs/zuul/latest/drivers/github.html#attr-%3Cgithub%20connection%3E.verify_ssl) parameter | {true}| #### GitServerSpec @@ -86,14 +86,14 @@ _Appears in:_ _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `storage` _[StorageSpec](#storagespec)_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `storage` _[StorageSpec](#storagespec)_ | | -| #### LEServer -_Underlying type:_ `string` +_Underlying type:_ _string_ @@ -112,14 +112,14 @@ _Appears in:_ - [LogServerSpec](#logserverspec) - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `server` _[LEServer](#leserver)_ | Specify the Lets encrypt server. Valid values are: - "staging" - "prod" | +| Field | Description | Default Value | +| --- | --- | --- | +| `server` _[LEServer](#leserver)_ | Specify the Lets encrypt server. Valid values are: "staging", "prod" | -| #### LogLevel -_Underlying type:_ `string` +_Underlying type:_ _string_ @@ -142,12 +142,12 @@ LogServer is the Schema for the LogServers API _Appears in:_ - [LogServerList](#logserverlist) -| Field | Description | -| --- | --- | -| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` -| `kind` _string_ | `LogServer` -| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| `spec` _[LogServerSpec](#logserverspec)_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` | - | +| `kind` _string_ | `LogServer` | - | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| +| `spec` _[LogServerSpec](#logserverspec)_ | | -| #### LogServerList @@ -158,12 +158,12 @@ LogServerList contains a list of LogServer -| Field | Description | -| --- | --- | -| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` -| `kind` _string_ | `LogServerList` -| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| `items` _[LogServer](#logserver) array_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` | - | +| `kind` _string_ | `LogServerList` | - | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| +| `items` _[LogServer](#logserver) array_ | | -| #### LogServerSpec @@ -175,13 +175,13 @@ LogServerSpec defines the desired state of LogServer _Appears in:_ - [LogServer](#logserver) -| Field | Description | -| --- | --- | -| `fqdn` _string_ | The fully qualified domain name to use with the log server. Logs will be served at https://logserver.`FQDN` | -| `LetsEncrypt` _[LetsEncryptSpec](#letsencryptspec)_ | LetsEncrypt settings for enabling using LetsEncrypt for Routes/TLS | -| `storageClassName` _string_ | Default storage class to use with Persistent Volume Claims issued by this resource. Consult your cluster's configuration to see what storage classes are available and recommended for your use case. | -| `authorizedSSHKey` _string_ | The SSH public key, encoded as base64, to use to authorize file transfers on the log server | -| `settings` _[LogServerSpecSettings](#logserverspecsettings)_ | General runtime settings for the log server | +| Field | Description | Default Value | +| --- | --- | --- | +| `fqdn` _string_ | The fully qualified domain name to use with the log server. Logs will be served at https://logserver.`FQDN` | -| +| `LetsEncrypt` _[LetsEncryptSpec](#letsencryptspec)_ | LetsEncrypt settings for enabling using LetsEncrypt for Routes/TLS | -| +| `storageClassName` _string_ | Default storage class to use with Persistent Volume Claims issued by this resource. Consult your cluster's configuration to see what storage classes are available and recommended for your use case. | -| +| `authorizedSSHKey` _string_ | The SSH public key, encoded as base64, to use to authorize file transfers on the log server | -| +| `settings` _[LogServerSpecSettings](#logserverspecsettings)_ | General runtime settings for the log server | -| #### LogServerSpecSettings @@ -194,11 +194,11 @@ _Appears in:_ - [LogServerSpec](#logserverspec) - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `retentionDays` _integer_ | Logs retention time in days. Logs older than this setting in days will be purged by a pruning cronjob. Defaults to 60 days | -| `loopDelay` _integer_ | The frequency, in seconds, at which the log pruning cronjob is running. Defaults to 3600s, i.e. logs are checked for pruning every hour | -| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | +| Field | Description | Default Value | +| --- | --- | --- | +| `retentionDays` _integer_ | Logs retention time in days. Logs older than this setting in days will be purged by a pruning cronjob. Defaults to 60 days | -| +| `loopDelay` _integer_ | The frequency, in seconds, at which the log pruning cronjob is running. Defaults to 3600s, i.e. logs are checked for pruning every hour | -| +| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| @@ -212,10 +212,10 @@ _Appears in:_ _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `dbStorage` _[StorageSpec](#storagespec)_ | Storage parameters related to mariaDB's data | -| `logStorage` _[StorageSpec](#storagespec)_ | Storage parameters related to the database's logging | +| Field | Description | Default Value | +| --- | --- | --- | +| `dbStorage` _[StorageSpec](#storagespec)_ | Storage parameters related to mariaDB's data | -| +| `logStorage` _[StorageSpec](#storagespec)_ | Storage parameters related to the database's logging | -| #### NodepoolBuilderSpec @@ -227,10 +227,10 @@ _Appears in:_ _Appears in:_ - [NodepoolSpec](#nodepoolspec) -| Field | Description | -| --- | --- | -| `storage` _[StorageSpec](#storagespec)_ | Storage related settings | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher process. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" | +| Field | Description | Default Value | +| --- | --- | --- | +| `storage` _[StorageSpec](#storagespec)_ | Storage related settings | -| +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher process. Valid values are: "INFO" (default), "WARN", "DEBUG". | INFO| #### NodepoolLauncherSpec @@ -242,9 +242,9 @@ _Appears in:_ _Appears in:_ - [NodepoolSpec](#nodepoolspec) -| Field | Description | -| --- | --- | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher service. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" Changing this value will restart the service. | +| Field | Description | Default Value | +| --- | --- | --- | +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher service. Valid values are: "INFO" (default), "WARN", "DEBUG". Changing this value will restart the service. | INFO| #### NodepoolSpec @@ -256,11 +256,11 @@ _Appears in:_ _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `launcher` _[NodepoolLauncherSpec](#nodepoollauncherspec)_ | Nodepool-launcher related settings | -| `builder` _[NodepoolBuilderSpec](#nodepoolbuilderspec)_ | Nodepool-builder related settings | -| `statsdTarget` _string_ | The address to forward statsd metrics to (optional), in the form "host:port" | +| Field | Description | Default Value | +| --- | --- | --- | +| `launcher` _[NodepoolLauncherSpec](#nodepoollauncherspec)_ | Nodepool-launcher related settings | -| +| `builder` _[NodepoolBuilderSpec](#nodepoolbuilderspec)_ | Nodepool-builder related settings | -| +| `statsdTarget` _string_ | The address to forward statsd metrics to (optional), in the form "host:port" | -| #### Secret @@ -272,10 +272,10 @@ _Appears in:_ _Appears in:_ - [SecretRef](#secretref) -| Field | Description | -| --- | --- | -| `name` _string_ | Name of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names | -| `key` _string_ | The key of the secret to select from. Must be a valid secret key. | +| Field | Description | Default Value | +| --- | --- | --- | +| `name` _string_ | Name of the referent. More info on [kubernetes' documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). | -| +| `key` _string_ | The key of the secret to select from. Must be a valid secret key. | -| @@ -289,12 +289,12 @@ SoftwareFactory is the Schema for the softwarefactories API _Appears in:_ - [SoftwareFactoryList](#softwarefactorylist) -| Field | Description | -| --- | --- | -| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` -| `kind` _string_ | `SoftwareFactory` -| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| `spec` _[SoftwareFactorySpec](#softwarefactoryspec)_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` | - | +| `kind` _string_ | `SoftwareFactory` | - | +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| +| `spec` _[SoftwareFactorySpec](#softwarefactoryspec)_ | | -| #### SoftwareFactoryList @@ -305,12 +305,12 @@ SoftwareFactoryList contains a list of SoftwareFactory -| Field | Description | -| --- | --- | -| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` -| `kind` _string_ | `SoftwareFactoryList` -| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| `items` _[SoftwareFactory](#softwarefactory) array_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `apiVersion` _string_ | `sf.softwarefactory-project.io/v1` | - | +| `kind` _string_ | `SoftwareFactoryList` | - | +| `metadata` _[ListMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#listmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | -| +| `items` _[SoftwareFactory](#softwarefactory) array_ | | -| #### SoftwareFactorySpec @@ -322,18 +322,18 @@ SoftwareFactorySpec defines the desired state of SoftwareFactory _Appears in:_ - [SoftwareFactory](#softwarefactory) -| Field | Description | -| --- | --- | -| `fqdn` _string_ | The fully qualified domain name to use with the deployment. Relevant services will be served at https://`service`.`FQDN` | -| `letsEncrypt` _[LetsEncryptSpec](#letsencryptspec)_ | LetsEncrypt settings for enabling using LetsEncrypt for Routes/TLS | -| `storageClassName` _string_ | Default storage class to use by Persistent Volume Claims | -| `config-location` _[ConfigLocationSpec](#configlocationspec)_ | Config repository spec | -| `zuul` _[ZuulSpec](#zuulspec)_ | Zuul service spec | -| `nodepool` _[NodepoolSpec](#nodepoolspec)_ | Nodepool services spec | -| `zookeeper` _[ZookeeperSpec](#zookeeperspec)_ | Zookeeper service spec | -| `logserver` _[LogServerSpecSettings](#logserverspecsettings)_ | Logserver service spec | -| `mariadb` _[MariaDBSpec](#mariadbspec)_ | MariaDB service spec | -| `gitserver` _[GitServerSpec](#gitserverspec)_ | Git server spec | +| Field | Description | Default Value | +| --- | --- | --- | +| `fqdn` _string_ | The fully qualified domain name to use with the deployment. Relevant services will be served at https://`service`.`FQDN` | -| +| `letsEncrypt` _[LetsEncryptSpec](#letsencryptspec)_ | LetsEncrypt settings for enabling using LetsEncrypt for Routes/TLS | -| +| `storageClassName` _string_ | Default storage class to use by Persistent Volume Claims | -| +| `config-location` _[ConfigLocationSpec](#configlocationspec)_ | Config repository spec | -| +| `zuul` _[ZuulSpec](#zuulspec)_ | Zuul service spec | -| +| `nodepool` _[NodepoolSpec](#nodepoolspec)_ | Nodepool services spec | -| +| `zookeeper` _[ZookeeperSpec](#zookeeperspec)_ | Zookeeper service spec | -| +| `logserver` _[LogServerSpecSettings](#logserverspecsettings)_ | Logserver service spec | -| +| `mariadb` _[MariaDBSpec](#mariadbspec)_ | MariaDB service spec | -| +| `gitserver` _[GitServerSpec](#gitserverspec)_ | Git server spec | -| @@ -354,10 +354,10 @@ _Appears in:_ - [ZuulMergerSpec](#zuulmergerspec) - [ZuulSchedulerSpec](#zuulschedulerspec) -| Field | Description | -| --- | --- | -| `size` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery@v0.28.2/pkg/api/resource#Quantity)_ | Storage space to allocate to the resource, expressed as a Quantity: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/ | -| `className` _string_ | Default storage class to use with Persistent Volume Claims issued by this resource. Consult your cluster's configuration to see what storage classes are available and recommended for your use case. | +| Field | Description | Default Value | +| --- | --- | --- | +| `size` _[Quantity](https://pkg.go.dev/k8s.io/apimachinery@v0.28.2/pkg/api/resource#Quantity)_ | Storage space to allocate to the resource, expressed as a [Quantity](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/) | -| +| `className` _string_ | Default storage class to use with Persistent Volume Claims issued by this resource. Consult your cluster's configuration to see what storage classes are available and recommended for your use case. | -| #### ZookeeperSpec @@ -369,9 +369,9 @@ _Appears in:_ _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `storage` _[StorageSpec](#storagespec)_ | | +| Field | Description | Default Value | +| --- | --- | --- | +| `storage` _[StorageSpec](#storagespec)_ | | -| #### ZuulExecutorSpec @@ -383,57 +383,57 @@ Spec for the pool of executor microservices _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| `replicas` _integer_ | How many executor pods to run | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-executor service. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" Changing this value will restart the service. | +| Field | Description | Default Value | +| --- | --- | --- | +| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| +| `replicas` _integer_ | How many executor pods to run | -| +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-executor service. Valid values are: "INFO" (default), "WARN", "DEBUG". Changing this value will restart the service. | INFO| #### ZuulMergerSpec -Some of the Zuul Merger Configurations can be found at https://zuul-ci.org/docs/zuul/latest/configuration.html#merger +Zuul Merger Configuration, see [Zuul's documentation](https://zuul-ci.org/docs/zuul/latest/configuration.html#merger) _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `gitUserName` _string_ | https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name | -| `gitUserEmail` _string_ | https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email | -| `gitHttpLowSpeedLimit` _integer_ | https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit | -| `gitHttpLowSpeedTime` _integer_ | https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time | -| `gitTimeout` _integer_ | https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout | -| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| `minReplicas` _integer_ | How many merger pods to run | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher service. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" Changing this value will restart the service. | +| Field | Description | Default Value | +| --- | --- | --- | +| `gitUserName` _string_ | the [git_user_name](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_name) parameter | -| +| `gitUserEmail` _string_ | the [git_user_email](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_user_email) parameter | -| +| `gitHttpLowSpeedLimit` _integer_ | the [git_http_low_speed_limit](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_limit) parameter | -| +| `gitHttpLowSpeedTime` _integer_ | the [git_http_low_speed_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_http_low_speed_time) parameter | -| +| `gitTimeout` _integer_ | the [git_timeout](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-merger.git_timeout) parameter | -| +| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| +| `minReplicas` _integer_ | How many merger pods to run | {1}| +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the nodepool launcher service. Valid values are: "INFO" (default), "WARN", "DEBUG". Changing this value will restart the service. | INFO| #### ZuulOIDCAuthenticatorSpec -The description of an OpenIDConnect authenticator, see https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication +The description of an OpenIDConnect authenticator, see [Zuul's authentication documentation](https://zuul-ci.org/docs/zuul/latest/configuration.html#authentication) _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `name` _string_ | The name of the authenticator in Zuul's configuration, see https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E | -| `realm` _string_ | Authentication realm, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm | -| `clientID` _string_ | The client ID, as exposed in the `aud` claim of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id | -| `issuerID` _string_ | The issuer ID, as exposed in the `iss` claim of a JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id | -| `uidClaim` _string_ | The JWT claim to use as a unique identifier in audit logs, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id | -| `maxValidityTime` _integer_ | Optionally override the `expires_at` claim in a JWT to enforce a custom expiration time on a token. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time | -| `skew` _integer_ | Optionally compensate for skew between Zuul's and the Identity Provider's clocks, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew | -| `keysURL` _string_ | Optionally provide a URL to fetch the Identity Provider's key set, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url | -| `scope` _string_ | The scope used to fetch a user's details, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope | -| `authority` _string_ | Optionally provide the claim where the authority is set if not in `iss`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority | -| `audience` _string_ | Optionally provide the claim where the audience is set if not in `aud`, equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience | -| `loadUserInfo` _boolean_ | If set to false, zuul-web will skip loading the Identity Provider's `userinfo` endpoint and rely on what's available in the JWT. Equivalent to https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info | +| Field | Description | Default Value | +| --- | --- | --- | +| `name` _string_ | The [name of the authenticator in Zuul's configuration](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E) | -| +| `realm` _string_ | Authentication realm, equivalent to the [realm](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.realm) parameter | -| +| `clientID` _string_ | The client ID, as exposed in the `aud` claim of a JWT. Equivalent to the [client_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.client_id) parameter | -| +| `issuerID` _string_ | The issuer ID, as exposed in the `iss` claim of a JWT. Equivalent to the [issuer_id](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.issuer_id) parameter | -| +| `uidClaim` _string_ | The JWT claim to use as a unique identifier in audit logs, equivalent to the [uid_claim](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.uid_claim) parameter | {sub}| +| `maxValidityTime` _integer_ | Optionally override the `expires_at` claim in a JWT to enforce a custom expiration time on a token. Equivalent to the [max_validity_time](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.max_validity_time) parameter | -| +| `skew` _integer_ | Optionally compensate for skew between Zuul's and the Identity Provider's clocks, equivalent to the [skew](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-auth%20%3Cauthenticator%20name%3E.skew) parameter | {0}| +| `keysURL` _string_ | Optionally provide a URL to fetch the Identity Provider's key set, equivalent to the [keys_url](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-keys_url) parameter | -| +| `scope` _string_ | The scope used to fetch a user's details, equivalent to the [scope](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-scope) parameter | {openid profile}| +| `authority` _string_ | Optionally provide the claim where the authority is set if not in `iss`, equivalent to the [authority](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-authority) parameter | -| +| `audience` _string_ | Optionally provide the claim where the audience is set if not in `aud`, equivalent to the [audience](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-audience) parameter | -| +| `loadUserInfo` _boolean_ | If set to false, zuul-web will skip loading the Identity Provider's `userinfo` endpoint and rely on what's available in the JWT. Equivalent to the [load_user_info](https://zuul-ci.org/docs/zuul/latest/configuration.html#attr-load_user_info) parameter | {true}| #### ZuulSchedulerSpec @@ -445,11 +445,11 @@ Spec for the scheduler microservice _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| `statsdTarget` _string_ | The address to forward statsd metrics to (optional), in the form "host:port" | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-scheduler service. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" Changing this value will restart the service. | +| Field | Description | Default Value | +| --- | --- | --- | +| `storage` _[StorageSpec](#storagespec)_ | Storage-related settings | -| +| `statsdTarget` _string_ | The address to forward statsd metrics to (optional), in the form "host:port" | -| +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-scheduler service. Valid values are: "INFO" (default), "WARN", "DEBUG". Changing this value will restart the service. | INFO| #### ZuulSpec @@ -461,16 +461,16 @@ Configuration of the Zuul service _Appears in:_ - [SoftwareFactorySpec](#softwarefactoryspec) -| Field | Description | -| --- | --- | -| `oidcAuthenticators` _[ZuulOIDCAuthenticatorSpec](#zuuloidcauthenticatorspec) array_ | A list of OpenID Connect authenticators that will enable admin API access on zuul-web | -| `defaultAuthenticator` _string_ | The name of the default authenticator to use if no authenticator is bound explicitly to a tenant with zuul-web | -| `gerritconns` _[GerritConnection](#gerritconnection) array_ | The list of Gerrit-based connections to add to Zuul's configuration | -| `githubconns` _[GitHubConnection](#githubconnection) array_ | The list of GitHub-based connections to add to Zuul's configuration | -| `executor` _[ZuulExecutorSpec](#zuulexecutorspec)_ | Configuration of the executor microservices | -| `scheduler` _[ZuulSchedulerSpec](#zuulschedulerspec)_ | Configuration of the scheduler microservice | -| `web` _[ZuulWebSpec](#zuulwebspec)_ | Configuration of the web microservice | -| `merger` _[ZuulMergerSpec](#zuulmergerspec)_ | Configuration of the merger microservice | +| Field | Description | Default Value | +| --- | --- | --- | +| `oidcAuthenticators` _[ZuulOIDCAuthenticatorSpec](#zuuloidcauthenticatorspec) array_ | A list of OpenID Connect authenticators that will enable admin API access on zuul-web | -| +| `defaultAuthenticator` _string_ | The name of the default authenticator to use if no authenticator is bound explicitly to a tenant with zuul-web | -| +| `gerritconns` _[GerritConnection](#gerritconnection) array_ | The list of Gerrit-based connections to add to Zuul's configuration | -| +| `githubconns` _[GitHubConnection](#githubconnection) array_ | The list of GitHub-based connections to add to Zuul's configuration | -| +| `executor` _[ZuulExecutorSpec](#zuulexecutorspec)_ | Configuration of the executor microservices | -| +| `scheduler` _[ZuulSchedulerSpec](#zuulschedulerspec)_ | Configuration of the scheduler microservice | -| +| `web` _[ZuulWebSpec](#zuulwebspec)_ | Configuration of the web microservice | -| +| `merger` _[ZuulMergerSpec](#zuulmergerspec)_ | Configuration of the merger microservice | -| #### ZuulWebSpec @@ -482,8 +482,8 @@ _Appears in:_ _Appears in:_ - [ZuulSpec](#zuulspec) -| Field | Description | -| --- | --- | -| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-web launcher service. Valid values are: - "INFO" (default) - "WARN" - "DEBUG" Changing this value will restart the service. | +| Field | Description | Default Value | +| --- | --- | --- | +| `logLevel` _[LogLevel](#loglevel)_ | Specify the Log Level of the zuul-web launcher service. Valid values are: "INFO" (default), "WARN", "DEBUG". Changing this value will restart the service. | INFO| diff --git a/tools/build-api-doc.sh b/tools/build-api-doc.sh index cc75285a..0696cad7 100755 --- a/tools/build-api-doc.sh +++ b/tools/build-api-doc.sh @@ -31,7 +31,7 @@ git clone --depth=1 "file://${REPO_ROOT}" "$GITDIR" pushd "$GITDIR" # go mod vendor -go get github.com/elastic/crd-ref-docs +go get github.com/elastic/crd-ref-docs@master go install github.com/elastic/crd-ref-docs mkdir -p "${docstmpdir}/apidocs/" @@ -39,6 +39,7 @@ ${GOBIN}/crd-ref-docs \ --config "${DOC_ROOT}/_apidoc/config.yaml" \ --source-path "./api" \ --output-path "${docstmpdir}/apidocs/index.md" \ + --templates-dir "${DOC_ROOT}/_apidoc/templates" \ --renderer=markdown popd