Be more descriptive

Kong · Jul 17, 2024 · cddbd33 · cddbd33
1 parent 7222951
commit cddbd33
Show file tree

Hide file tree

Showing 5 changed files with 17 additions and 13 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,7 +29,8 @@
 
 - Proper `User-Agent` header is now set on outgoing HTTP requests.
   [#387](https://github.com/Kong/gateway-operator/pull/387)
-- Introduce `KongPluginInstallation` CRD
+- Introduce `KongPluginInstallation` CRD to allow installing custom Kong
+  plugins distributed as container images.
   [400](https://github.com/Kong/gateway-operator/pull/400)
 
 ### Fixed

diff --git a/api/v1alpha1/kongplugin_installation_types.go b/api/v1alpha1/kongplugin_installation_types.go
@@ -61,12 +61,12 @@ type KongPluginInstallationSpec struct {
 	//+kubebuilder:validation:Required
 	Image string `json:"image"`
 
-	// SecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image
+	// ImagePullSecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image
 	// in Image. It must follow the format in https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry.
 	// It is optional. If the image is public, omit this field.
 	//
 	//+optional
-	SecretRef *corev1.SecretReference `json:"secretRef,omitempty"`
+	ImagePullSecretRef *corev1.SecretReference `json:"imagePullSecretRef,omitempty"`
 }
 
 // KongPluginInstallationStatus defines the observed state of KongPluginInstallation.
@@ -91,23 +91,23 @@ type KongPluginInstallationConditionReason string
 
 const (
 	// This condition indicates whether the controller has fetched the plugin image
-	// and made it available for use as a specific Custom Kong Plugin.
+	// and made it available for use as a specific custom Kong Plugin.
 	//
 	// It is a positive-polarity summary condition, and so should always be
 	// present on the resource with ObservedGeneration set.
 	//
 	// It should be set to Unknown if the controller performs updates to the
 	// status before it has all the information it needs to be able to determine
-	// if the condition is true.
+	// if the condition is true (e.g. haven't started the download yet).
 	//
 	// Possible reasons for this condition to be "True" are:
 	//
 	// * "Ready"
 	//
 	// Possible reasons for this condition to be "False" are:
 	//
-	// * "Failed"
 	// * "Pending"
+	// * "Failed"
 	//
 	// Possible reasons for this condition to be "Unknown" are:
 	//
@@ -120,11 +120,14 @@ const (
 	KongPluginInstallationReasonReady KongPluginInstallationConditionReason = "Ready"
 
 	// KongPluginInstallationReasonFailed is used with the "Accepted" condition type when
-	// the KongPluginInstallation can't be fetched e.g. image can't be fetched.
+	// the KongPluginInstallation can't be fetched e.g. image can't be fetched due to lack
+	// of permissions or the image doesn't exist. It's a state that can't be recovered without
+	// manual intervention.
 	// More details can be obtained from the condition's message.
 	KongPluginInstallationReasonFailed KongPluginInstallationConditionReason = "Failed"
 
 	// KongPluginInstallationReasonPending is used with the "Accepted" condition type when the requested
-	// controller has started processing the KongPluginInstallation, but it hasn't finished yet.
+	// controller has started processing the KongPluginInstallation, but it hasn't finished yet, e.g.
+	// fetching and unpacking the image is in progress.
 	KongPluginInstallationReasonPending KongPluginInstallationConditionReason = "Pending"
 )
diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/config/crd/bases/gateway-operator.konghq.com_kongplugininstallations.yaml b/config/crd/bases/gateway-operator.konghq.com_kongplugininstallations.yaml
@@ -56,9 +56,9 @@ spec:
                 description: The image is an OCI image URL for a packaged custom Kong
                   plugin.
                 type: string
-              secretRef:
+              imagePullSecretRef:
                 description: |-
-                  SecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image
+                  ImagePullSecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image
                   in Image. It must follow the format in https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry.
                   It is optional. If the image is public, omit this field.
                 properties:

diff --git a/docs/api-reference.md b/docs/api-reference.md
@@ -322,7 +322,7 @@ KongPluginInstallationSpec provides the information necessary to retrieve and in
 | Field | Description |
 | --- | --- |
 | `image` _string_ | The image is an OCI image URL for a packaged custom Kong plugin. |
-| `secretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secretreference-v1-core)_ | SecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image in Image. It must follow the format in https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry. It is optional. If the image is public, omit this field. |
+| `imagePullSecretRef` _[SecretReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#secretreference-v1-core)_ | ImagePullSecretRef is a reference to a Kubernetes Secret containing credentials necessary to pull the OCI image in Image. It must follow the format in https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry. It is optional. If the image is public, omit this field. |
 
 
 _Appears in:_