Merge pull request #477 from erikgb/enrich-api-spec

Improve API specification
cert-manager · Nov 21, 2024 · 2461f5d · 2461f5d
2 parents bbea895 + a25aa22
commit 2461f5d
Show file tree

Hide file tree

Showing 3 changed files with 57 additions and 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
@@ -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,13 +251,15 @@ 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.
                             The bundle is by default created without a password.
                           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
@@ -125,7 +125,7 @@ func Resource(resource string) schema.GroupResource
 Resource takes an unqualified resource and returns a Group qualified GroupResource
 
 <a name="AdditionalFormats"></a>
-## type [AdditionalFormats](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L120-L128>)
+## type [AdditionalFormats](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L126-L136>)
 
 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.
 
 <a name="BundleCondition"></a>
-## type [BundleCondition](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L206-L245>)
+## type [BundleCondition](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L222-L261>)
 
 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.
 
 <a name="BundleSource"></a>
-## type [BundleSource](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L70-L95>)
+## type [BundleSource](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L74-L99>)
 
-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.
 
 <a name="BundleSpec"></a>
-## type [BundleSpec](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L60-L66>)
+## type [BundleSpec](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L60-L69>)
 
 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.
 
 <a name="BundleStatus"></a>
-## type [BundleStatus](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L189-L203>)
+## type [BundleStatus](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L205-L219>)
 
 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.
 
 <a name="BundleTarget"></a>
-## type [BundleTarget](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L99-L117>)
+## type [BundleTarget](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L103-L123>)
 
 BundleTarget is the target resource that the Bundle will sync all source data to.
 
 ```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.
 
 <a name="JKS"></a>
-## type [JKS](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L130-L139>)
-
+## type [JKS](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L140-L149>)
 
+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.
 
 <a name="KeySelector"></a>
-## type [KeySelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L183-L186>)
+## type [KeySelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L198-L202>)
 
 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.
 
 <a name="NamespaceSelector"></a>
-## type [NamespaceSelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L152-L157>)
+## type [NamespaceSelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L164-L169>)
 
 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.
 
 <a name="PKCS12"></a>
-## type [PKCS12](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L141-L149>)
-
+## type [PKCS12](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L153-L161>)
 
+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.
 
 <a name="SourceObjectKeySelector"></a>
-## type [SourceObjectKeySelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L161-L180>)
+## type [SourceObjectKeySelector](<https://github.com/cert-manager/trust-manager/blob/main/pkg/apis/trust/v1alpha1/types_bundle.go#L174-L195>)
 
-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
@@ -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"`
 }