From a25aa227ef9a2f6f1226ba3243efeeea19cbfdc4 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 | 16 ++++++++ docs/api/api.md | 40 ++++++++++++------- pkg/apis/trust/v1alpha1/types_bundle.go | 16 ++++++++ 3 files changed, 57 insertions(+), 15 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..8d7413d4 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,6 +269,7 @@ spec: required: - key type: object + x-kubernetes-map-type: atomic type: object configMap: description: |- @@ -264,6 +278,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,6 +304,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 diff --git a/docs/api/api.md b/docs/api/api.md index 5b913c14..053e7744 100644 --- a/docs/api/api.md +++ b/docs/api/api.md @@ -125,7 +125,7 @@ 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 @@ -134,9 +134,11 @@ 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,7 +444,7 @@ 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. @@ -447,11 +452,13 @@ BundleTarget is the target resource that the Bundle will sync all source data to 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..9613b7ea 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. @@ -99,11 +103,13 @@ type BundleSource struct { 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 @@ -121,12 +127,16 @@ 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 +148,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 +170,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 +185,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 +197,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"` }