From 71ee032625ccb7c8bf557877f6120e78e83a39cf Mon Sep 17 00:00:00 2001 From: Erik Godding Boye Date: Sat, 5 Oct 2024 16:10:38 +0200 Subject: [PATCH] Update trust-manager API docs Signed-off-by: Erik Godding Boye --- .spelling | 10 + .../docs/trust/trust-manager/api-reference.md | 469 +++++++++--------- scripts/gendocs/generate-trust-manager | 4 +- .../templates-trust-manager/markdown.tmpl | 2 +- 4 files changed, 255 insertions(+), 230 deletions(-) diff --git a/.spelling b/.spelling index dac3c06a191..7686f74d626 100644 --- a/.spelling +++ b/.spelling @@ -87,6 +87,7 @@ APIServices APIs AWS Akamai +ANDed Anthos AppRole approvers @@ -106,6 +107,7 @@ BundleSource BundleTarget BundleCondition NamespaceSelector +CamelCase CAs CNAME CNAMEs @@ -160,6 +162,7 @@ Dean-Coakley DigitalOcean OVHCloud Distroless +DoesNotExist DuckDuckGo etcd EC2 @@ -234,6 +237,7 @@ NameCheap NGINX NLB NLBs +NotIn Ocado OmairK OpenAPI @@ -343,6 +347,7 @@ coderanger config containerd customizable +defaultCAPackageVersion distroless e.g. e2e @@ -426,8 +431,10 @@ multivalue macOS makefile manual-rotation-private-key +matchExpressions mechanism metadata +metadata.generation middleware migrate-api-version misconfiguration @@ -444,6 +451,7 @@ namespaces ndegory oauth2 OAuth +observedGeneration onwards openshift-supported-versions plaintext @@ -472,6 +480,7 @@ runtime runtimes signoff sigstore +status.condition stdout subchart subcommand @@ -501,6 +510,7 @@ unredacted unschedule untrusted upstream +useDefaultCAs userinfo util vhosakot diff --git a/content/docs/trust/trust-manager/api-reference.md b/content/docs/trust/trust-manager/api-reference.md index 8134a417a1b..c4a841c893a 100644 --- a/content/docs/trust/trust-manager/api-reference.md +++ b/content/docs/trust/trust-manager/api-reference.md @@ -47,7 +47,7 @@ Resource Types: true - metadata + metadata object Refer to the Kubernetes API documentation for the fields of the `metadata` field. true @@ -104,7 +104,8 @@ Desired state of the Bundle resource. ### `Bundle.spec.sources[index]` -BundleSource is the set of sources whose data will be appended and synced to the BundleTarget in all Namespaces. +BundleSource is the set of sources whose data will be appended and synced to +the BundleTarget in all Namespaces. @@ -119,7 +120,8 @@ BundleSource is the set of sources whose data will be appended and synced to the @@ -133,14 +135,22 @@ BundleSource is the set of sources whose data will be appended and synced to the @@ -150,7 +160,8 @@ BundleSource is the set of sources whose data will be appended and synced to the ### `Bundle.spec.sources[index].configMap` -ConfigMap is a reference to a ConfigMap's `data` key, in the trust Namespace. +ConfigMap is a reference (by name) to a ConfigMap's `data` key, or to a +list of ConfigMap's `data` key using label selector, in the trust Namespace.
configMap object - ConfigMap is a reference to a ConfigMap's `data` key, in the trust Namespace.
+ ConfigMap is a reference (by name) to a ConfigMap's `data` key, or to a +list of ConfigMap's `data` key using label selector, in the trust Namespace.
 false
secret object - Secret is a reference to a Secrets's `data` key, in the trust Namespace.
+ Secret is a reference (by name) to a Secret's `data` key, or to a +list of Secret's `data` key using label selector, in the trust Namespace.
 false
useDefaultCAs boolean - UseDefaultCAs, when true, requests the default CA bundle to be used as a source. Default CAs are available if trust-manager was installed via Helm or was otherwise set up to include a package-injecting init container by using the "--default-package-location" flag when starting the trust-manager controller. If default CAs were not configured at start-up, any request to use the default CAs will fail. The version of the default CA package which is used for a Bundle is stored in the defaultCAPackageVersion field of the Bundle's status field.
+ UseDefaultCAs, when true, requests the default CA bundle to be used as a source. +Default CAs are available if trust-manager was installed via Helm +or was otherwise set up to include a package-injecting init container by using the +"--default-package-location" flag when starting the trust-manager controller. +If default CAs were not configured at start-up, any request to use the default +CAs will fail. +The version of the default CA package which is used for a Bundle is stored in the +defaultCAPackageVersion field of the Bundle's status field.
 false
@@ -172,24 +183,27 @@ ConfigMap is a reference to a ConfigMap's `data` key, in the trust Namespace. - - + +
name string - Name is the name of the source object in the trust Namespace. If not set, `selector` must be set.
+ Name is the name of the source object in the trust Namespace. +This field must be left empty when `selector` is set
 false
selectorLabelSelectorselectorobject - A LabelSelector object to reference, by labels, a list of source objects in the trust Namespace. If not set, `name` must be set.
+ Selector is the label selector to use to fetch a list of objects. Must not be set +when `Name` is set.
 false
-### `Bundle.spec.sources[index].secret` +### `Bundle.spec.sources[index].configMap.selector` -Secret is a reference to a Secrets's `data` key, in the trust Namespace. +Selector is the label selector to use to fetch a list of objects. Must not be set +when `Name` is set. @@ -201,34 +215,30 @@ Secret is a reference to a Secrets's `data` key, in the trust Namespace. - - - - - - - + + - - + +
keystring - Key is the key of the entry in the object's `data` field to be used.
- 		true
namestringmatchExpressions[]object - Name is the name of the source object in the trust Namespace. If not set, `selector` must be set.
+ matchExpressions is a list of label selector requirements. The requirements are ANDed.
 false
selectorLabelSelectormatchLabelsmap[string]string - A LabelSelector object to reference, by labels, a list of source objects in the trust Namespace. If not set, `name` must be set.
+ matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed.
 false
-### `Bundle.spec.target` +### `Bundle.spec.sources[index].configMap.selector.matchExpressions[index]` -Target is the target location in all namespaces to sync source data to. +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. @@ -240,41 +250,39 @@ Target is the target location in all namespaces to sync source data to. - - - - - - - + + - + - - + + - + - - + +
additionalFormatsobject - AdditionalFormats specifies any additional formats to write to the target
- 		false
configMapobjectkeystring - ConfigMap is the target ConfigMap in Namespaces that all Bundle source data will be synced to.
+ key is the label key that the selector applies to.
falsetrue
namespaceSelectorobjectoperatorstring - NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector.
+ operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist.
falsetrue
secretobjectvalues[]string - Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace.
+ values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch.
 false
-### `Bundle.spec.target.additionalFormats` +### `Bundle.spec.sources[index].secret` -AdditionalFormats specifies any additional formats to write to the target +Secret is a reference (by name) to a Secret's `data` key, or to a +list of Secret's `data` key using label selector, in the trust Namespace. @@ -286,27 +294,37 @@ AdditionalFormats specifies any additional formats to write to the target - - + + + + + + + - +
jksobjectkeystring + Key is the key of the entry in the object's `data` field to be used.
+ 		true
namestring - JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit".
+ Name is the name of the source object in the trust Namespace. +This field must be left empty when `selector` is set
 false
pkcs12selector object - PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.
+ Selector is the label selector to use to fetch a list of objects. Must not be set +when `Name` is set.
 false
-### `Bundle.spec.target.additionalFormats.jks` +### `Bundle.spec.sources[index].secret.selector` -JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit". +Selector is the label selector to use to fetch a list of objects. Must not be set +when `Name` is set. @@ -318,20 +336,30 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th - - + + - + + + + + +
keystringmatchExpressions[]object - Key is the key of the entry in the object's `data` field to be used.
+ matchExpressions is a list of label selector requirements. The requirements are ANDed.
truefalse
matchLabelsmap[string]string + matchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels +map is equivalent to an element of matchExpressions, whose key field is "key", the +operator is "In", and the values array contains only "value". The requirements are ANDed.
+ 		false
-### `Bundle.spec.target.additionalFormats.pkcs12` +### `Bundle.spec.sources[index].secret.selector.matchExpressions[index]` -PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password. +A label selector requirement is a selector that contains values, a key, and an operator that +relates the key and values. @@ -346,67 +374,35 @@ PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the targ - -
key string - Key is the key of the entry in the object's `data` field to be used.
+ key is the label key that the selector applies to.
 true
- - -### `Bundle.spec.target.configMap` - - -ConfigMap is the target ConfigMap in Namespaces that all Bundle source data will be synced to. - - - - - - - - - - - - + + - -
NameTypeDescriptionRequired
key
operator string - Key is the key of the entry in the object's `data` field to be used.
+ operator represents a key's relationship to a set of values. +Valid operators are In, NotIn, Exists and DoesNotExist.
 true
- - -### `Bundle.spec.target.namespaceSelector` - - -NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector. - - - - - - - - - - - - - + + +
NameTypeDescriptionRequired
matchLabelsmap[string]string
values[]string - MatchLabels matches on the set of labels that must be present on a Namespace for the Bundle target to be synced there.
+ values is an array of string values. If the operator is In or NotIn, +the values array must be non-empty. If the operator is Exists or DoesNotExist, +the values array must be empty. This array is replaced during a strategic +merge patch.
 false
-### `Bundle.spec.target.secret` +### `Bundle.spec.target` -Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace. +Target is the target location in all namespaces to sync source data to. @@ -418,59 +414,45 @@ Secret is the target Secret that all Bundle source data will be synced to. Using - - + + - - -
keystringadditionalFormatsobject - Key is the key of the entry in the object's `data` field to be used.
+ AdditionalFormats specifies any additional formats to write to the target
true
- - -### `Bundle.status` - - -Status of the Bundle. This is set and managed automatically. - - - - - - - - - - - - - + + + + - - + + - +
NameTypeDescriptionRequired
conditions[]objectfalse
configMapobject - List of status conditions to indicate the status of the Bundle. Known condition types are `Bundle`.
+ ConfigMap is the target ConfigMap in Namespaces that all Bundle source +data will be synced to.
 false
defaultCAVersionstringnamespaceSelectorobject - DefaultCAPackageVersion, if set and non-empty, indicates the version information which was retrieved when the set of default CAs was requested in the bundle source. This should only be set if useDefaultCAs was set to "true" on a source, and will be the same for the same version of a bundle with identical certificates.
+ NamespaceSelector will, if set, only sync the target resource in +Namespaces which match the selector.
 false
targetsecret object - Target is the current Target that the Bundle is attempting or has completed syncing the source data to.
+ Secret is the target Secret that all Bundle source data will be synced to. +Using Secrets as targets is only supported if enabled at trust-manager startup. +By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace.
 false
-### `Bundle.status.conditions[index]` +### `Bundle.spec.target.additionalFormats` -BundleCondition contains condition information for a Bundle. +AdditionalFormats specifies any additional formats to write to the target @@ -482,59 +464,32 @@ BundleCondition contains condition information for a Bundle. - - - - - - - - - - - - - - - - - - - - - - + + - - + +
statusstring - Status of the condition, one of ('True', 'False', 'Unknown').
- 		true
typestring - Type of the condition, known values are (`Synced`).
- 		true
lastTransitionTimestring - LastTransitionTime is the timestamp corresponding to the last status change of this condition.
-
- Format: date-time
- 		false
messagestring - Message is a human readable description of the details of the last transition, complementing reason.
- 		false
observedGenerationintegerjksobject - If set, this represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.condition[x].observedGeneration is 9, the condition is out of date with respect to the current state of the Bundle.
-
- Format: int64
+ JKS requests a JKS-formatted binary trust bundle to be written to the target. +The bundle has "changeit" as the default password. +For more information refer to this link https://cert-manager.io/docs/faq/#keystore-passwords
 false
reasonstringpkcs12object - Reason is a brief machine readable explanation for the condition's last transition.
+ PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. +The bundle is by default created without a password.
 false
-### `Bundle.status.target` +### `Bundle.spec.target.additionalFormats.jks` -Target is the current Target that the Bundle is attempting or has completed syncing the source data to. +JKS requests a JKS-formatted binary trust bundle to be written to the target. +The bundle has "changeit" as the default password. +For more information refer to this link https://cert-manager.io/docs/faq/#keystore-passwords @@ -546,41 +501,30 @@ Target is the current Target that the Bundle is attempting or has completed sync - - - - - - - - - - - - + + - + - - + +
additionalFormatsobject - AdditionalFormats specifies any additional formats to write to the target
- 		false
configMapobject - ConfigMap is the target ConfigMap in Namespaces that all Bundle source data will be synced to.
- 		false
namespaceSelectorobjectkeystring - NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector.
+ Key is the key of the entry in the object's `data` field to be used.
falsetrue
secretobjectpasswordstring - Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace.
+ Password for JKS trust store
+
+ Default: changeit
 false
-### `Bundle.status.target.additionalFormats` +### `Bundle.spec.target.additionalFormats.pkcs12` -AdditionalFormats specifies any additional formats to write to the target +PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. +The bundle is by default created without a password. @@ -592,27 +536,30 @@ AdditionalFormats specifies any additional formats to write to the target - - + + - + - - + +
jksobjectkeystring - JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit".
+ Key is the key of the entry in the object's `data` field to be used.
falsetrue
pkcs12objectpasswordstring - PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password.
+ Password for PKCS12 trust store
+
+ Default:
false
-### `Bundle.status.target.additionalFormats.jks` +### `Bundle.spec.target.configMap` -JKS requests a JKS-formatted binary trust bundle to be written to the target. The bundle is created with the hardcoded password "changeit". +ConfigMap is the target ConfigMap in Namespaces that all Bundle source +data will be synced to. @@ -634,10 +581,11 @@ JKS requests a JKS-formatted binary trust bundle to be written to the target. Th
-### `Bundle.status.target.additionalFormats.pkcs12` +### `Bundle.spec.target.namespaceSelector` -PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. The bundle is created without a password. +NamespaceSelector will, if set, only sync the target resource in +Namespaces which match the selector. @@ -649,20 +597,23 @@ PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the targ - - + + - +
keystringmatchLabelsmap[string]string - Key is the key of the entry in the object's `data` field to be used.
+ MatchLabels matches on the set of labels that must be present on a +Namespace for the Bundle target to be synced there.
truefalse
-### `Bundle.status.target.configMap` +### `Bundle.spec.target.secret` -ConfigMap is the target ConfigMap in Namespaces that all Bundle source data will be synced to. +Secret is the target Secret that all Bundle source data will be synced to. +Using Secrets as targets is only supported if enabled at trust-manager startup. +By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace. @@ -684,10 +635,10 @@ ConfigMap is the target ConfigMap in Namespaces that all Bundle source data will
-### `Bundle.status.target.namespaceSelector` +### `Bundle.status` -NamespaceSelector will, if set, only sync the target resource in Namespaces which match the selector. +Status of the Bundle. This is set and managed automatically. @@ -699,20 +650,31 @@ NamespaceSelector will, if set, only sync the target resource in Namespaces whic - - + + + + + + +
matchLabelsmap[string]stringconditions[]object - MatchLabels matches on the set of labels that must be present on a Namespace for the Bundle target to be synced there.
+ List of status conditions to indicate the status of the Bundle. +Known condition types are `Bundle`.
+ 		false
defaultCAVersionstring + DefaultCAPackageVersion, if set and non-empty, indicates the version information +which was retrieved when the set of default CAs was requested in the bundle +source. This should only be set if useDefaultCAs was set to "true" on a source, +and will be the same for the same version of a bundle with identical certificates.
 false
-### `Bundle.status.target.secret` +### `Bundle.status.conditions[index]` -Secret is the target Secret that all Bundle source data will be synced to. Using Secrets as targets is only supported if enabled at trust-manager startup. By default, trust-manager has no permissions for writing to secrets and can only read secrets in the trust namespace. +BundleCondition contains condition information for a Bundle. @@ -724,11 +686,62 @@ Secret is the target Secret that all Bundle source data will be synced to. Using - + + + + + + + + + + + + + + + + + + + + + + + + + +
keylastTransitionTime string - Key is the key of the entry in the object's `data` field to be used.
+ LastTransitionTime is the timestamp corresponding to the last status +change of this condition.
+
+ Format: date-time
+ 		true
reasonstring + Reason is a brief machine-readable explanation for the condition's last +transition. +The value should be a CamelCase string. +This field may not be empty.
+ 		true
statusenum + Status of the condition, one of True, False, Unknown.
+
+ Enum: True, False, Unknown
 true
typestring + Type of the condition, known values are (`Synced`).
+ 		true
messagestring + Message is a human-readable description of the details of the last +transition, complementing reason.
+ 		false
observedGenerationinteger + If set, this represents the .metadata.generation that the condition was +set based upon. +For instance, if .metadata.generation is currently 12, but the +.status.condition[x].observedGeneration is 9, the condition is out of date +with respect to the current state of the Bundle.
+
+ Format: int64
+ Minimum: 0
+ 		false
diff --git a/scripts/gendocs/generate-trust-manager b/scripts/gendocs/generate-trust-manager index d4102a8d416..ffc2c1bd640 100755 --- a/scripts/gendocs/generate-trust-manager +++ b/scripts/gendocs/generate-trust-manager @@ -46,8 +46,10 @@ gendocs() { echo "+++ Generating trust-manager reference docs..." + (cd $tmpdir && make generate-crds) + $CRDOC \ - --resources "$tmpdir/deploy/crds/trust.cert-manager.io_bundles.yaml" \ + --resources "$tmpdir/_bin/scratch/crds/trust.cert-manager.io_bundles.yaml" \ --template $REPO_ROOT/scripts/gendocs/templates-trust-manager/markdown.tmpl \ --output $outputdir } diff --git a/scripts/gendocs/templates-trust-manager/markdown.tmpl b/scripts/gendocs/templates-trust-manager/markdown.tmpl index aac77c9c57c..591c670b48e 100644 --- a/scripts/gendocs/templates-trust-manager/markdown.tmpl +++ b/scripts/gendocs/templates-trust-manager/markdown.tmpl @@ -55,7 +55,7 @@ Resource Types: true - metadata + metadata object Refer to the Kubernetes API documentation for the fields of the `metadata` field. true