From 63f265c2e50a6aa05f1375169c59018326779713 Mon Sep 17 00:00:00 2001 From: Erik Godding Boye Date: Sun, 17 Nov 2024 11:07:57 +0100 Subject: [PATCH] Improve API specification Signed-off-by: Erik Godding Boye --- .../crd-trust.cert-manager.io_bundles.yaml | 18 ++++++++ docs/api/api.md | 44 ++++++++++++------- pkg/apis/trust/v1alpha1/types_bundle.go | 18 ++++++++ 3 files changed, 63 insertions(+), 17 deletions(-) diff --git a/deploy/charts/trust-manager/templates/crd-trust.cert-manager.io_bundles.yaml b/deploy/charts/trust-manager/templates/crd-trust.cert-manager.io_bundles.yaml index 5211aab6..0058cba3 100644 --- a/deploy/charts/trust-manager/templates/crd-trust.cert-manager.io_bundles.yaml +++ b/deploy/charts/trust-manager/templates/crd-trust.cert-manager.io_bundles.yaml @@ -82,11 +82,13 @@ spec: type: boolean key: description: Key of the entry in the object's `data` field to be used. + minLength: 1 type: string name: description: |- Name is the name of the source object in the trust Namespace. This field must be left empty when `selector` is set + minLength: 1 type: string selector: description: |- @@ -135,6 +137,7 @@ spec: type: object x-kubernetes-map-type: atomic type: object + x-kubernetes-map-type: atomic inLine: description: InLine is a simple string to append as the source data. type: string @@ -150,11 +153,13 @@ spec: type: boolean key: description: Key of the entry in the object's `data` field to be used. + minLength: 1 type: string name: description: |- Name is the name of the source object in the trust Namespace. This field must be left empty when `selector` is set + minLength: 1 type: string selector: description: |- @@ -203,6 +208,7 @@ spec: type: object x-kubernetes-map-type: atomic type: object + x-kubernetes-map-type: atomic useDefaultCAs: description: |- UseDefaultCAs, when true, requests the default CA bundle to be used as a source. @@ -215,7 +221,11 @@ spec: defaultCAPackageVersion field of the Bundle's status field. type: boolean type: object + x-kubernetes-map-type: atomic + maxItems: 100 + minItems: 1 type: array + x-kubernetes-list-type: atomic target: description: Target is the target location in all namespaces to sync source data to. properties: @@ -230,6 +240,7 @@ spec: properties: key: description: Key is the key of the entry in the object's `data` field to be used. + minLength: 1 type: string password: default: changeit @@ -240,6 +251,7 @@ spec: required: - key type: object + x-kubernetes-map-type: atomic pkcs12: description: |- PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. @@ -247,6 +259,7 @@ spec: properties: key: description: Key is the key of the entry in the object's `data` field to be used. + minLength: 1 type: string password: default: "" @@ -256,7 +269,9 @@ spec: required: - key type: object + x-kubernetes-map-type: atomic type: object + x-kubernetes-map-type: atomic configMap: description: |- ConfigMap is the target ConfigMap in Namespaces that all Bundle source @@ -264,6 +279,7 @@ spec: properties: key: description: Key is the key of the entry in the object's `data` field to be used. + minLength: 1 type: string required: - key @@ -289,11 +305,13 @@ spec: properties: key: description: Key is the key of the entry in the object's `data` field to be used. + minLength: 1 type: string required: - key type: object type: object + x-kubernetes-map-type: atomic required: - sources - target diff --git a/docs/api/api.md b/docs/api/api.md index 5b913c14..9e2cac00 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -125,18 +125,20 @@ func Resource(resource string) schema.GroupResource Resource takes an unqualified resource and returns a Group qualified GroupResource -## type [AdditionalFormats]() +## type [AdditionalFormats]() -AdditionalFormats specifies any additional formats to write to the target +AdditionalFormats specifies any additional formats to write to the target \+structType=atomic ```go type AdditionalFormats struct { // 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 + // +optional JKS *JKS `json:"jks,omitempty"` // PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. // The bundle is by default created without a password. + // +optional PKCS12 *PKCS12 `json:"pkcs12,omitempty"` } ``` @@ -206,7 +208,7 @@ func (in *Bundle) DeepCopyObject() runtime.Object DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. -## type [BundleCondition]() +## type [BundleCondition]() BundleCondition contains condition information for a Bundle. @@ -313,9 +315,9 @@ func (in *BundleList) DeepCopyObject() runtime.Object DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. -## type [BundleSource]() +## type [BundleSource]() -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. \+structType=atomic ```go type BundleSource struct { @@ -365,13 +367,16 @@ func (in *BundleSource) DeepCopyInto(out *BundleSource) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [BundleSpec]() +## type [BundleSpec]() BundleSpec defines the desired state of a Bundle. ```go type BundleSpec struct { // Sources is a set of references to data whose data will sync to the target. + // +listType=atomic + // +kubebuilder:validation:MinItems=1 + // +kubebuilder:validation:MaxItems=100 Sources []BundleSource `json:"sources"` // Target is the target location in all namespaces to sync source data to. @@ -398,7 +403,7 @@ func (in *BundleSpec) DeepCopyInto(out *BundleSpec) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [BundleStatus]() +## type [BundleStatus]() BundleStatus defines the observed state of the Bundle. @@ -439,19 +444,21 @@ func (in *BundleStatus) DeepCopyInto(out *BundleStatus) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [BundleTarget]() +## type [BundleTarget]() -BundleTarget is the target resource that the Bundle will sync all source data to. +BundleTarget is the target resource that the Bundle will sync all source data to. \+structType=atomic ```go type BundleTarget struct { // ConfigMap is the target ConfigMap in Namespaces that all Bundle source // data will be synced to. + // +optional ConfigMap *KeySelector `json:"configMap,omitempty"` // 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. + // +optional Secret *KeySelector `json:"secret,omitempty"` // AdditionalFormats specifies any additional formats to write to the target @@ -484,9 +491,9 @@ func (in *BundleTarget) DeepCopyInto(out *BundleTarget) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [JKS]() - +## type [JKS]() +JKS specifies additional target JKS files \+structType=atomic ```go type JKS struct { @@ -520,13 +527,14 @@ func (in *JKS) DeepCopyInto(out *JKS) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [KeySelector]() +## type [KeySelector]() KeySelector is a reference to a key for some map data object. ```go type KeySelector struct { // Key is the key of the entry in the object's `data` field to be used. + // +kubebuilder:validation:MinLength=1 Key string `json:"key"` } ``` @@ -550,7 +558,7 @@ func (in *KeySelector) DeepCopyInto(out *KeySelector) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [NamespaceSelector]() +## type [NamespaceSelector]() NamespaceSelector defines selectors to match on Namespaces. @@ -582,9 +590,9 @@ func (in *NamespaceSelector) DeepCopyInto(out *NamespaceSelector) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [PKCS12]() - +## type [PKCS12]() +PKCS12 specifies additional target PKCS\#12 files \+structType=atomic ```go type PKCS12 struct { @@ -617,15 +625,16 @@ func (in *PKCS12) DeepCopyInto(out *PKCS12) DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non\-nil. -## type [SourceObjectKeySelector]() +## type [SourceObjectKeySelector]() -SourceObjectKeySelector is a reference to a source object and its \`data\` key\(s\) in the trust Namespace. +SourceObjectKeySelector is a reference to a source object and its \`data\` key\(s\) in the trust Namespace. \+structType=atomic ```go type SourceObjectKeySelector struct { // Name is the name of the source object in the trust Namespace. // This field must be left empty when `selector` is set //+optional + // +kubebuilder:validation:MinLength=1 Name string `json:"name,omitempty"` // Selector is the label selector to use to fetch a list of objects. Must not be set @@ -635,6 +644,7 @@ type SourceObjectKeySelector struct { // Key of the entry in the object's `data` field to be used. //+optional + // +kubebuilder:validation:MinLength=1 Key string `json:"key,omitempty"` // IncludeAllKeys is a flag to include all keys in the object's `data` field to be used. False by default. diff --git a/pkg/apis/trust/v1alpha1/types_bundle.go b/pkg/apis/trust/v1alpha1/types_bundle.go index 014839ad..1a6f5aff 100644 --- a/pkg/apis/trust/v1alpha1/types_bundle.go +++ b/pkg/apis/trust/v1alpha1/types_bundle.go @@ -59,6 +59,9 @@ type BundleList struct { // BundleSpec defines the desired state of a Bundle. type BundleSpec struct { // Sources is a set of references to data whose data will sync to the target. + // +listType=atomic + // +kubebuilder:validation:MinItems=1 + // +kubebuilder:validation:MaxItems=100 Sources []BundleSource `json:"sources"` // Target is the target location in all namespaces to sync source data to. @@ -67,6 +70,7 @@ type BundleSpec struct { // BundleSource is the set of sources whose data will be appended and synced to // the BundleTarget in all Namespaces. +// +structType=atomic type BundleSource struct { // ConfigMap is a reference (by name) to a ConfigMap's `data` key(s), or to a // list of ConfigMap's `data` key(s) using label selector, in the trust Namespace. @@ -96,14 +100,17 @@ type BundleSource struct { // BundleTarget is the target resource that the Bundle will sync all source // data to. +// +structType=atomic type BundleTarget struct { // ConfigMap is the target ConfigMap in Namespaces that all Bundle source // data will be synced to. + // +optional ConfigMap *KeySelector `json:"configMap,omitempty"` // 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. + // +optional Secret *KeySelector `json:"secret,omitempty"` // AdditionalFormats specifies any additional formats to write to the target @@ -117,16 +124,21 @@ type BundleTarget struct { } // AdditionalFormats specifies any additional formats to write to the target +// +structType=atomic type AdditionalFormats struct { // 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 + // +optional JKS *JKS `json:"jks,omitempty"` // PKCS12 requests a PKCS12-formatted binary trust bundle to be written to the target. // The bundle is by default created without a password. + // +optional PKCS12 *PKCS12 `json:"pkcs12,omitempty"` } +// JKS specifies additional target JKS files +// +structType=atomic type JKS struct { KeySelector `json:",inline"` @@ -138,6 +150,8 @@ type JKS struct { Password *string `json:"password"` } +// PKCS12 specifies additional target PKCS#12 files +// +structType=atomic type PKCS12 struct { KeySelector `json:",inline"` @@ -158,10 +172,12 @@ type NamespaceSelector struct { // SourceObjectKeySelector is a reference to a source object and its `data` key(s) // in the trust Namespace. +// +structType=atomic type SourceObjectKeySelector struct { // Name is the name of the source object in the trust Namespace. // This field must be left empty when `selector` is set //+optional + // +kubebuilder:validation:MinLength=1 Name string `json:"name,omitempty"` // Selector is the label selector to use to fetch a list of objects. Must not be set @@ -171,6 +187,7 @@ type SourceObjectKeySelector struct { // Key of the entry in the object's `data` field to be used. //+optional + // +kubebuilder:validation:MinLength=1 Key string `json:"key,omitempty"` // IncludeAllKeys is a flag to include all keys in the object's `data` field to be used. False by default. @@ -182,6 +199,7 @@ type SourceObjectKeySelector struct { // KeySelector is a reference to a key for some map data object. type KeySelector struct { // Key is the key of the entry in the object's `data` field to be used. + // +kubebuilder:validation:MinLength=1 Key string `json:"key"` }