Add spec.wait usage to the API docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

api/v1beta2/doc.go

@@ -14,7 +14,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package v1beta2 contains API Schema definitions for the kustomize v1beta2 API group
+// Package v1beta2 contains API Schema definitions for the kustomize.toolkit.fluxcd.io v1beta2 API group.
 // +kubebuilder:object:generate=true
 // +groupName=kustomize.toolkit.fluxcd.io
 package v1beta2

api/v1beta2/groupversion_info.go

@@ -22,10 +22,10 @@ import (
 )
 
 var (
-	// GroupVersion is group version used to register these objects
+	// GroupVersion is group version used to register these objects.
 	GroupVersion = schema.GroupVersion{Group: "kustomize.toolkit.fluxcd.io", Version: "v1beta2"}
 
-	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
+	// SchemeBuilder is used to add go types to the GroupVersionKind scheme.
 	SchemeBuilder = &scheme.Builder{GroupVersion: GroupVersion}
 
 	// AddToScheme adds the types in this group-version to the given scheme.

api/v1beta2/inventory_types.go

@@ -16,18 +16,18 @@ limitations under the License.
 
 package v1beta2
 
-// Inventory is a record of objects that have been reconciled.
-type Inventory struct {
-	// Entries of Kubernetes objects IDs.
-	Entries []Entry `json:"entries"`
+// ResourceInventory contains a list of Kubernetes resource object references that have been applied by a Kustomization.
+type ResourceInventory struct {
+	// Entries of Kubernetes resource object references.
+	Entries []ResourceRef `json:"entries"`
 }
 
-// Entry contains the information necessary to locate a resource within a cluster.
-type Entry struct {
-	// ObjectID is the string representation of a Kubernetes object metadata,
+// ResourceRef contains the information necessary to locate a resource within a cluster.
+type ResourceRef struct {
+	// ID is the string representation of the Kubernetes resource object's metadata,
 	// in the format '<namespace>_<name>_<group>_<kind>'.
-	ObjectID string `json:"id"`
+	ID string `json:"id"`
 
-	// ObjectVersion is the API version of this  Kubernetes object kind.
-	ObjectVersion string `json:"v"`
+	// Version is the API version of the Kubernetes resource object's kind.
+	Version string `json:"v"`
 }

api/v1beta2/kustomization_types.go

@@ -36,7 +36,7 @@ const (
 	DisabledValue             = "disabled"
 )
 
-// KustomizationSpec defines the desired state of a kustomization.
+// KustomizationSpec defines the configuration to calculate the desired state from a Source using Kustomize.
 type KustomizationSpec struct {
 	// DependsOn may contain a dependency.CrossNamespaceDependencyReference slice
 	// with references to Kustomization resources that must be ready before this
@@ -224,9 +224,9 @@ type KustomizationStatus struct {
 	// +optional
 	LastAttemptedRevision string `json:"lastAttemptedRevision,omitempty"`
 
-	// The last successfully applied revision metadata.
+	// Inventory contains the list of Kubernetes resource object references that have been successfully applied.
 	// +optional
-	Inventory *Inventory `json:"inventory,omitempty"`
+	Inventory *ResourceInventory `json:"inventory,omitempty"`
 }
 
 // KustomizationProgressing resets the conditions of the given Kustomization to a single
@@ -263,7 +263,7 @@ func KustomizationNotReady(k Kustomization, revision, reason, message string) Ku
 }
 
 // KustomizationNotReadyInventory registers a failed apply attempt of the given Kustomization.
-func KustomizationNotReadyInventory(k Kustomization, inventory *Inventory, revision, reason, message string) Kustomization {
+func KustomizationNotReadyInventory(k Kustomization, inventory *ResourceInventory, revision, reason, message string) Kustomization {
 	SetKustomizationReadiness(&k, metav1.ConditionFalse, reason, trimString(message, MaxConditionMessageLength), revision)
 	SetKustomizationHealthiness(&k, metav1.ConditionFalse, reason, reason)
 	if revision != "" {
@@ -274,7 +274,7 @@ func KustomizationNotReadyInventory(k Kustomization, inventory *Inventory, revis
 }
 
 // KustomizationReadyInventory registers a successful apply attempt of the given Kustomization.
-func KustomizationReadyInventory(k Kustomization, inventory *Inventory, revision, reason, message string) Kustomization {
+func KustomizationReadyInventory(k Kustomization, inventory *ResourceInventory, revision, reason, message string) Kustomization {
 	SetKustomizationReadiness(&k, metav1.ConditionTrue, reason, trimString(message, MaxConditionMessageLength), revision)
 	SetKustomizationHealthiness(&k, metav1.ConditionTrue, reason, reason)
 	k.Status.Inventory = inventory
@@ -315,13 +315,6 @@ func (in *Kustomization) GetStatusConditions() *[]metav1.Condition {
 	return &in.Status.Conditions
 }
 
-const (
-	// GitRepositoryIndexKey is the key used for indexing kustomizations based on their Git sources.
-	GitRepositoryIndexKey string = ".metadata.gitRepository"
-	// BucketIndexKey is the key used for indexing kustomizations based on their S3 sources.
-	BucketIndexKey string = ".metadata.bucket"
-)
-
 // +genclient
 // +genclient:Namespaced
 // +kubebuilder:storageversion

api/v1beta2/reference_types.go

@@ -19,22 +19,22 @@ package v1beta2
 import "fmt"
 
 // CrossNamespaceSourceReference contains enough information to let you locate the
-// typed referenced object at cluster level
+// typed Kubernetes resource object at cluster level.
 type CrossNamespaceSourceReference struct {
-	// API version of the referent
+	// API version of the referent.
 	// +optional
 	APIVersion string `json:"apiVersion,omitempty"`
 
-	// Kind of the referent
+	// Kind of the referent.
 	// +kubebuilder:validation:Enum=GitRepository;Bucket
 	// +required
 	Kind string `json:"kind"`
 
-	// Name of the referent
+	// Name of the referent.
 	// +required
 	Name string `json:"name"`
 
-	// Namespace of the referent, defaults to the Kustomization namespace
+	// Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
 	// +optional
 	Namespace string `json:"namespace,omitempty"`
 }

config/crd/bases/kustomize.toolkit.fluxcd.io_kustomizations.yaml

@@ -447,7 +447,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: KustomizationSpec defines the desired state of a kustomization.
+            description: KustomizationSpec defines the configuration to calculate the desired state from a Source using Kustomize.
             properties:
               decryption:
                 description: Decrypt Kubernetes secrets before applying them on the cluster.
@@ -693,19 +693,19 @@ spec:
                 description: Reference of the source where the kustomization file is.
                 properties:
                   apiVersion:
-                    description: API version of the referent
+                    description: API version of the referent.
                     type: string
                   kind:
-                    description: Kind of the referent
+                    description: Kind of the referent.
                     enum:
                     - GitRepository
                     - Bucket
                     type: string
                   name:
-                    description: Name of the referent
+                    description: Name of the referent.
                     type: string
                   namespace:
-                    description: Namespace of the referent, defaults to the Kustomization namespace
+                    description: Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
                     type: string
                 required:
                 - kind
@@ -782,15 +782,15 @@ spec:
                 description: The last successfully applied revision metadata.
                 properties:
                   entries:
-                    description: Entries of Kubernetes objects IDs.
+                    description: Entries of Kubernetes resource object references.
                     items:
-                      description: Entry contains the information necessary to locate a resource within a cluster.
+                      description: ResourceRef contains the information necessary to locate a resource within a cluster.
                       properties:
                         id:
-                          description: ObjectID is the string representation of a Kubernetes object metadata, in the format '<namespace>_<name>_<group>_<kind>'.
+                          description: ID is the string representation of the Kubernetes resource object's metadata, in the format '<namespace>_<name>_<group>_<kind>'.
                           type: string
                         v:
-                          description: ObjectVersion is the API version of this  Kubernetes object kind.
+                          description: Version is the API version of the Kubernetes resource object's kind.
                           type: string
                       required:
                       - id

controllers/kustomization_controller.go

@@ -90,14 +90,19 @@ type KustomizationReconcilerOptions struct {
 }
 
 func (r *KustomizationReconciler) SetupWithManager(mgr ctrl.Manager, opts KustomizationReconcilerOptions) error {
+	const (
+		gitRepositoryIndexKey string = ".metadata.gitRepository"
+		bucketIndexKey        string = ".metadata.bucket"
+	)
+
 	// Index the Kustomizations by the GitRepository references they (may) point at.
-	if err := mgr.GetCache().IndexField(context.TODO(), &kustomizev1.Kustomization{}, kustomizev1.GitRepositoryIndexKey,
+	if err := mgr.GetCache().IndexField(context.TODO(), &kustomizev1.Kustomization{}, gitRepositoryIndexKey,
 		r.indexBy(sourcev1.GitRepositoryKind)); err != nil {
 		return fmt.Errorf("failed setting index fields: %w", err)
 	}
 
 	// Index the Kustomizations by the Bucket references they (may) point at.
-	if err := mgr.GetCache().IndexField(context.TODO(), &kustomizev1.Kustomization{}, kustomizev1.BucketIndexKey,
+	if err := mgr.GetCache().IndexField(context.TODO(), &kustomizev1.Kustomization{}, bucketIndexKey,
 		r.indexBy(sourcev1.BucketKind)); err != nil {
 		return fmt.Errorf("failed setting index fields: %w", err)
 	}
@@ -119,12 +124,12 @@ func (r *KustomizationReconciler) SetupWithManager(mgr ctrl.Manager, opts Kustom
 		)).
 		Watches(
 			&source.Kind{Type: &sourcev1.GitRepository{}},
-			handler.EnqueueRequestsFromMapFunc(r.requestsForRevisionChangeOf(kustomizev1.GitRepositoryIndexKey)),
+			handler.EnqueueRequestsFromMapFunc(r.requestsForRevisionChangeOf(gitRepositoryIndexKey)),
 			builder.WithPredicates(SourceRevisionChangePredicate{}),
 		).
 		Watches(
 			&source.Kind{Type: &sourcev1.Bucket{}},
-			handler.EnqueueRequestsFromMapFunc(r.requestsForRevisionChangeOf(kustomizev1.BucketIndexKey)),
+			handler.EnqueueRequestsFromMapFunc(r.requestsForRevisionChangeOf(bucketIndexKey)),
 			builder.WithPredicates(SourceRevisionChangePredicate{}),
 		).
 		WithOptions(controller.Options{MaxConcurrentReconciles: opts.MaxConcurrentReconciles}).

controllers/kustomization_inventory.go

@@ -28,14 +28,14 @@ import (
 	"github.com/fluxcd/kustomize-controller/internal/objectutil"
 )
 
-func NewInventory() *kustomizev1.Inventory {
-	return &kustomizev1.Inventory{
-		Entries: []kustomizev1.Entry{},
+func NewInventory() *kustomizev1.ResourceInventory {
+	return &kustomizev1.ResourceInventory{
+		Entries: []kustomizev1.ResourceRef{},
 	}
 }
 
 // AddObjectsToInventory extracts the metadata from the given objects and adds it to the inventory.
-func AddObjectsToInventory(inv *kustomizev1.Inventory, objects []*unstructured.Unstructured) error {
+func AddObjectsToInventory(inv *kustomizev1.ResourceInventory, objects []*unstructured.Unstructured) error {
 	sort.Sort(objectutil.SortableUnstructureds(objects))
 	for _, om := range objects {
 		objMetadata := object.UnstructuredToObjMeta(om)
@@ -44,21 +44,21 @@ func AddObjectsToInventory(inv *kustomizev1.Inventory, objects []*unstructured.U
 			return err
 		}
 
-		inv.Entries = append(inv.Entries, kustomizev1.Entry{
-			ObjectID:      objMetadata.String(),
-			ObjectVersion: gv.Version,
+		inv.Entries = append(inv.Entries, kustomizev1.ResourceRef{
+			ID:      objMetadata.String(),
+			Version: gv.Version,
 		})
 	}
 
 	return nil
 }
 
 // ListObjectsInInventory returns the inventory entries as unstructured.Unstructured objects.
-func ListObjectsInInventory(inv *kustomizev1.Inventory) ([]*unstructured.Unstructured, error) {
+func ListObjectsInInventory(inv *kustomizev1.ResourceInventory) ([]*unstructured.Unstructured, error) {
 	objects := make([]*unstructured.Unstructured, 0)
 
 	for _, entry := range inv.Entries {
-		objMetadata, err := object.ParseObjMetadata(entry.ObjectID)
+		objMetadata, err := object.ParseObjMetadata(entry.ID)
 		if err != nil {
 			return nil, err
 		}
@@ -67,7 +67,7 @@ func ListObjectsInInventory(inv *kustomizev1.Inventory) ([]*unstructured.Unstruc
 		u.SetGroupVersionKind(schema.GroupVersionKind{
 			Group:   objMetadata.GroupKind.Group,
 			Kind:    objMetadata.GroupKind.Kind,
-			Version: entry.ObjectVersion,
+			Version: entry.Version,
 		})
 		u.SetName(objMetadata.Name)
 		u.SetNamespace(objMetadata.Namespace)
@@ -79,10 +79,10 @@ func ListObjectsInInventory(inv *kustomizev1.Inventory) ([]*unstructured.Unstruc
 }
 
 // ListMetaInInventory returns the inventory entries as object.ObjMetadata objects.
-func ListMetaInInventory(inv *kustomizev1.Inventory) ([]object.ObjMetadata, error) {
+func ListMetaInInventory(inv *kustomizev1.ResourceInventory) ([]object.ObjMetadata, error) {
 	var metas []object.ObjMetadata
 	for _, e := range inv.Entries {
-		m, err := object.ParseObjMetadata(e.ObjectID)
+		m, err := object.ParseObjMetadata(e.ID)
 		if err != nil {
 			return metas, err
 		}
@@ -93,11 +93,11 @@ func ListMetaInInventory(inv *kustomizev1.Inventory) ([]object.ObjMetadata, erro
 }
 
 // DiffInventory returns the slice of objects that do not exist in the target inventory.
-func DiffInventory(inv *kustomizev1.Inventory, target *kustomizev1.Inventory) ([]*unstructured.Unstructured, error) {
-	versionOf := func(i *kustomizev1.Inventory, objMetadata object.ObjMetadata) string {
+func DiffInventory(inv *kustomizev1.ResourceInventory, target *kustomizev1.ResourceInventory) ([]*unstructured.Unstructured, error) {
+	versionOf := func(i *kustomizev1.ResourceInventory, objMetadata object.ObjMetadata) string {
 		for _, entry := range i.Entries {
-			if entry.ObjectID == objMetadata.String() {
-				return entry.ObjectVersion
+			if entry.ID == objMetadata.String() {
+				return entry.Version
 			}
 		}
 		return ""