Merge pull request #4303 from JoelSpeed/external-cluster-infra

✨  Add externally managed annotation and predicate

api/v1alpha4/common_types.go

@@ -83,6 +83,14 @@ const (
 
 	// InterruptibleLabel is the label used to mark the nodes that run on interruptible instances.
 	InterruptibleLabel = "cluster.x-k8s.io/interruptible"
+
+	// ManagedByAnnotation is an annotation that can be applied to InfraCluster resources to signify that
+	// some external system is managing the cluster infrastructure.
+	//
+	// Provider InfraCluster controllers will ignore resources with this annotation.
+	// An external controller must fulfill the contract of the InfraCluster resource.
+	// External infrastructure providers should ensure that the annotation, once set, cannot be removed.
+	ManagedByAnnotation = "cluster.x-k8s.io/managed-by"
 )
 
 // MachineAddressType describes a valid MachineAddress type.

docs/book/src/developer/providers/cluster-infrastructure.md

@@ -45,6 +45,8 @@ The following diagram shows the typical logic for a cluster infrastructure provi
 
 ### Normal resource
 
+1. If the resource is externally managed, exit the reconciliation
+    1. The `ResourceIsNotExternallyManaged` predicate can be used to prevent reconciling externally managed resources
 1. If the resource does not have a `Cluster` owner, exit the reconciliation
     1. The Cluster API `Cluster` reconciler populates this based on the value in the `Cluster`'s `spec.infrastructureRef`
        field.

docs/book/src/developer/providers/v1alpha3-to-v1alpha4.md

@@ -3,7 +3,7 @@
 ## Minimum Go version
 
 - The Go version used by Cluster API is now Go 1.16+
-  - In case cloudbuild is used to push images, please upgrade to `gcr.io/k8s-testimages/gcb-docker-gcloud:v20210331-c732583` 
+  - In case cloudbuild is used to push images, please upgrade to `gcr.io/k8s-testimages/gcb-docker-gcloud:v20210331-c732583`
     in the cloudbuild YAML files.  
 
 ## Controller Runtime version
@@ -251,4 +251,21 @@ with `cert-manager.io/v1`
 `MachineDeployment.Spec.Strategy.RollingUpdate.MaxSurge`, `MachineDeployment.Spec.Strategy.RollingUpdate.MaxUnavailable` and `MachineHealthCheck.Spec.MaxUnhealthy` would have previously taken a String value with an integer character in it e.g "3" as a valid input and process it as a percentage value.
 Only String values like "3%" or Int values e.g 3 are valid input values now. A string not matching the percentage format will fail, e.g "3".
 
+## Required change to support externally managed infrastructure.
 
+- A new annotation `cluster.x-k8s.io/managed-by` has been introduced that allows cluster infrastructure to be managed
+externally.
+- When this annotation is added to an `InfraCluster` resource, the controller for these resources should not reconcile
+the resource.
+- The `ResourceIsNotExternallyManaged` predicate is a useful helper to check for the annotation and the filter the resource easily:
+  ```go
+  c, err := ctrl.NewControllerManagedBy(mgr).
+		For(&providerv1.InfraCluster{}).
+		Watches(...).
+		WithOptions(options).
+		WithEventFilter(predicates.ResourceIsNotExternallyManaged(ctrl.LoggerFrom(ctx))).
+		Build(r)
+	if err != nil {
+		return errors.Wrap(err, "failed setting up with a controller manager")
+	}
+  ```

docs/book/src/images/cluster-infra-provider.plantuml

@@ -4,6 +4,10 @@ start
 
 :New/Updated/Deleted resource;
 
+if (Is Externally Managed?) then (yes)
+    stop
+  else (no)
+  endif
 if (Deleted?) then (yes)
     if (Has cluster owner?) then (yes)
         :Reconcile deletion;

util/annotations/helpers.go

@@ -31,6 +31,11 @@ func IsPaused(cluster *clusterv1.Cluster, o metav1.Object) bool {
 	return HasPausedAnnotation(o)
 }
 
+// IsExternallyManaged returns true if the object has the `managed-by` annotation.
+func IsExternallyManaged(o metav1.Object) bool {
+	return hasAnnotation(o, clusterv1.ManagedByAnnotation)
+}
+
 // HasPausedAnnotation returns true if the object has the `paused` annotation.
 func HasPausedAnnotation(o metav1.Object) bool {
 	return hasAnnotation(o, clusterv1.PausedAnnotation)

util/predicates/generic_predicates.go

@@ -209,3 +209,35 @@ func processIfLabelMatch(logger logr.Logger, obj client.Object, labelValue strin
 	log.V(4).Info("Resource does not match label, will not attempt to map resource")
 	return false
 }
+
+// ResourceIsNotExternallyManaged returns a predicate that returns true only if the resource does not contain
+// the externally managed annotation.
+// This implements a requirement for InfraCluster providers to be able to ignore externally managed
+// cluster infrastructure.
+func ResourceIsNotExternallyManaged(logger logr.Logger) predicate.Funcs {
+	return predicate.Funcs{
+		UpdateFunc: func(e event.UpdateEvent) bool {
+			return processIfNotExternallyManaged(logger.WithValues("predicate", "updateEvent"), e.ObjectNew)
+		},
+		CreateFunc: func(e event.CreateEvent) bool {
+			return processIfNotExternallyManaged(logger.WithValues("predicate", "createEvent"), e.Object)
+		},
+		DeleteFunc: func(e event.DeleteEvent) bool {
+			return processIfNotExternallyManaged(logger.WithValues("predicate", "deleteEvent"), e.Object)
+		},
+		GenericFunc: func(e event.GenericEvent) bool {
+			return processIfNotExternallyManaged(logger.WithValues("predicate", "genericEvent"), e.Object)
+		},
+	}
+}
+
+func processIfNotExternallyManaged(logger logr.Logger, obj client.Object) bool {
+	kind := strings.ToLower(obj.GetObjectKind().GroupVersionKind().Kind)
+	log := logger.WithValues("namespace", obj.GetNamespace(), kind, obj.GetName())
+	if annotations.IsExternallyManaged(obj) {
+		log.V(4).Info("Resource is externally managed, will not attempt to map resource")
+		return false
+	}
+	log.V(4).Info("Resource is managed, will attempt to map resource")
+	return true
+}