App lifecyle CRD api description updates (#403)

Signed-off-by: Xiangjing Li <[email protected]>
open-cluster-management-io · Jun 18, 2024 · 045f889 · 045f889
1 parent 1ce18af
commit 045f889
Show file tree

Hide file tree

Showing 26 changed files with 2,128 additions and 2,543 deletions.
diff --git a/addon/manifests/chart/templates/apps.open-cluster-management.io_subscriptions_crd_v1.yaml b/addon/manifests/chart/templates/apps.open-cluster-management.io_subscriptions_crd_v1.yaml
diff --git a/...ts/chart/templates/apps.open-cluster-management.io_subscriptionstatuses_crd_v1alpha1.yaml b/...ts/chart/templates/apps.open-cluster-management.io_subscriptionstatuses_crd_v1alpha1.yaml
@@ -81,6 +81,7 @@ apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
   annotations:
+    controller-gen.kubebuilder.io/version: v0.14.0
     helm.sh/resource-policy: keep
     {{ if .Values.onMulticlusterHub }}"addon.open-cluster-management.io/deletion-orphan": ""{{ end }}
   name: subscriptionstatuses.apps.open-cluster-management.io
@@ -98,52 +99,79 @@ spec:
   - name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: SubscriptionStatus defines the status of package deployments
+        description: SubscriptionStatus provides detailed status for all the resources
+          that are deployed by the application in a cluster.
         properties:
           apiVersion:
-            description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
             type: string
           kind:
-            description: 'Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
             type: string
           metadata:
             type: object
           statuses:
-            description: Statuses represents all the resources deployed by the subscription per cluster
+            description: SubscriptionClusterStatusMap contains the status of deployment
+              packages in a cluster.
             properties:
               packages:
                 items:
-                  description: SubscriptionUnitStatus defines status of a package deployment.
+                  description: SubscriptionUnitStatus provides the status of a single
+                    deployment package.
                   properties:
                     apiVersion:
+                      description: API version of the deployment package.
                       type: string
                     kind:
+                      description: Kind of the deployment package.
                       type: string
                     lastUpdateTime:
+                      description: Timestamp of when the deployment package was last
+                        updated.
                       format: date-time
                       type: string
                     message:
+                      description: Informational message or error output from the
+                        deployment of the package.
                       type: string
                     name:
+                      description: Name of the deployment package.
                       type: string
                     namespace:
+                      description: Namespace where the deployment package is deployed.
                       type: string
                     phase:
-                      description: PackagePhase defines the phasing of a Package
+                      description: Phase of the deployment package (unknown/deployed/failed/propagationFailed).
                       type: string
                   required:
                   - lastUpdateTime
                   type: object
                 type: array
               subscription:
+                description: |-
+                  SubscriptionOverallStatus provides the overall status of the subscription. It is computed using the status of
+                  all the deployment packages in the subscription.
                 properties:
                   lastUpdateTime:
+                    description: Timestamp of when the overall subscription status
+                      was last updated.
                     format: date-time
-                    type: string                
+                    type: string
                   message:
+                    description: Informational message or error output from the overall
+                      subscription status.
                     type: string
                   phase:
-                    description: SubscriptionPhase defines the phase of the overall subscription
+                    description: Phase of the overall subscription status (unknown/deployed/failed).
                     type: string
                 type: object
             type: object

diff --git a/deploy/common/apps.open-cluster-management.io_channels_crd.yaml b/deploy/common/apps.open-cluster-management.io_channels_crd.yaml
@@ -1,6 +1,9 @@
+---
 apiVersion: apiextensions.k8s.io/v1
 kind: CustomResourceDefinition
 metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.13.0
   name: channels.apps.open-cluster-management.io
 spec:
   group: apps.open-cluster-management.io
@@ -26,7 +29,10 @@ spec:
     name: v1
     schema:
       openAPIV3Schema:
-        description: Channel is the Schema for the channels API
+        description: 'Channel provides a repository containing application resources
+          which can be deployed to clusters by subscriptions. The following 3 types
+          of channels are supported: Git repository, Helm release registry, and Object
+          storage repository.'
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -82,15 +88,16 @@ spec:
                     description: 'UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids'
                     type: string
                 type: object
+                x-kubernetes-map-type: atomic
               gates:
-                description: Criteria for promoting a Deployable from the sourceNamespaces
-                  to Channel.
+                description: ChannelGate defines a criteria for promoting a Deployable
+                  from the sourceNamespaces to Channel.
                 properties:
                   annotations:
                     additionalProperties:
                       type: string
-                    description: The annotations which must present on a Deployable
-                      for it to be eligible for promotion.
+                    description: The annotations for selecting the Deployables to
+                      be eligible for promotion.
                     type: object
                   labelSelector:
                     description: A label selector for selecting the Deployables.
@@ -136,6 +143,7 @@ spec:
                           "value". The requirements are ANDed.
                         type: object
                     type: object
+                    x-kubernetes-map-type: atomic
                   name:
                     type: string
                 type: object
@@ -144,17 +152,16 @@ spec:
                   channel.
                 type: boolean
               pathname:
-                description: For a `namespace` channel, pathname is the name of the
-                  namespace; For a `helmrepo` or `github` channel, pathname is the
-                  remote URL for the channel contents; For a `objectbucket` channel,
-                  pathname is the URL and name of the bucket.
+                description: For a `helmrepo` or `github` channel, pathname is the
+                  repo URL. For a `objectbucket` channel, pathname is the Object store
+                  URL with the name of the bucket.
                 type: string
               secretRef:
-                description: For a `github` channel or a `helmrepo` channel on github,
-                  this can be used to reference a Secret which contains the credentials
-                  for authentication, i.e. `user` and `accessToken`. For a `objectbucket`
-                  channel, this can be used to reference a Secret which contains the
-                  AWS credentials, i.e. `AccessKeyID` and `SecretAccessKey`.
+                description: 'For a `github` channel or a `helmrepo` channel on github,
+                  use this to reference a secret which contains the credentials for
+                  authentication, for example: `user` and `accessToken`. For a `objectbucket`
+                  channel, use this to reference a secret which contains the AWS credentials,
+                  for example: `AccessKeyID`,`SecretAccessKey` and `Region`.'
                 properties:
                   apiVersion:
                     description: API version of the referent.
@@ -189,14 +196,16 @@ spec:
                     description: 'UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids'
                     type: string
                 type: object
+                x-kubernetes-map-type: atomic
               sourceNamespaces:
                 description: A list of namespace names from which Deployables can
                   be promoted.
                 items:
                   type: string
                 type: array
+                x-kubernetes-list-type: set
               type:
-                description: ChannelType defines types of channel
+                description: ChannelType defines a type of channel
                 enum:
                 - Namespace
                 - HelmRepo
@@ -221,4 +230,4 @@ spec:
         type: object
     served: true
     storage: true
-    subresources: {}
+    subresources: {}