Implement dynamic selection of parent prefix from a set of custom fields

ParentPrefixSelectorGuide.md

@@ -0,0 +1,51 @@
+# A guide of `ParentPrefixSelector` in `PrefixClaim`
+
+There are 2 ways to make a Prefix claim:
+- provide a `parentPrefix`
+- provide a `parentPrefixSelector`
+
+In this documentation, we will focus on the `parentPrefixSelector` only.
+
+# CRD format
+
+The following is a sample of utilizing the `parentPrefixSelector`:
+```bash
+apiVersion: netbox.dev/v1
+kind: PrefixClaim
+metadata:
+  labels:
+    app.kubernetes.io/name: netbox-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: prefixclaim-customfields-sample
+spec:
+  tenant: "MY_TENANT"
+  site: "DM-Akron"
+  description: "some description"
+  comments: "your comments"
+  preserveInNetbox: true
+  prefixLength: "/31"
+  parentPrefixSelector: 
+    tenant: "MY_TENANT_2"
+    site: "DM-Bryon"
+    environment: "Production"
+    poolName: "Pool 1"
+```
+
+## `Spec.tenant` and `Spec.site`
+
+Please provide the *name*, not the *slug* value
+
+## `parentPrefixSelector`
+
+The `parentPrefixSelector` is a key-value map, where all the entries are of data type `<string-string>`.
+
+The `parentPrefixSelector` is a set of query conditions for selecting a set of prefixes that can be used as the parent prefix.
+
+The fields that can be used as query conditions in the `parentPrefixSelector` are:
+- `tenant` and `site`
+    - these 2 fields come by design with NetBox, so you do *not* need to create custom fields for them
+    - please provide the *name*, not the *slug* value
+    - if either of the value is missing, it will *not* inherit from the tenant and site from the Spec
+- custom fields
+    - the data types tested and supported so far are `string`, `integer`, and `boolean`
+    - for `boolean` type, please use `true` and `false` as the value

README.md

@@ -58,6 +58,13 @@ Use Cases for this Restoration:
 - Disaster Recovery: In case the cluster is lost, IP Addresses can be restored with the IPAddressClaim only
 - Sticky IPs: Some services do not handle changes to IPs well. This ensures the IP/Prefix assigned to a Custom Resource is always the same.
 
+# `ParentPrefixSelector` in `PrefixClaim`
+
+Please read [ParentPrefixSelector guide] for more information!
+
+[ParentPrefixSelector guide]: ./ParentPrefixSelectorGuide.md
+
+
 # Project Distribution
 
 Following are the steps to build the installer and distribute this project to users.

api/v1/prefixclaim_types.go

@@ -24,24 +24,31 @@ import (
 // NOTE: json tags are required.  Any new fields you add must have json tags for the fields to be serialized.
 
 // PrefixClaimSpec defines the desired state of PrefixClaim
+// TODO: The reason for using a workaround please see https://github.com/netbox-community/netbox-operator/pull/90#issuecomment-2402112475
 // +kubebuilder:validation:XValidation:rule="!has(oldSelf.site) || has(self.site)", message="Site is required once set"
+// +kubebuilder:validation:XValidation:rule="(!has(self.parentPrefix) && has(self.parentPrefixSelector)) || (has(self.parentPrefix) && !has(self.parentPrefixSelector))"
 type PrefixClaimSpec struct {
+
 	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	//+kubebuilder:validation:Required
 	//+kubebuilder:validation:Format=cidr
 	//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'parentPrefix' is immutable"
-	ParentPrefix string `json:"parentPrefix"`
+	ParentPrefix string `json:"parentPrefix,omitempty"`
+
+	//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'parentPrefixSelector' is immutable"
+	ParentPrefixSelector map[string]string `json:"parentPrefixSelector,omitempty"`
 
 	//+kubebuilder:validation:Required
 	//+kubebuilder:validation:Pattern=`^\/[0-9]|[1-9][0-9]|1[01][0-9]|12[0-8]$`
 	//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'prefixLength' is immutable"
 	PrefixLength string `json:"prefixLength"`
 
+	// Use the `name` value instead of the `slug` value
 	//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'site' is immutable"
 	Site string `json:"site,omitempty"`
 
+	// Use the `name` value instead of the `slug` value
 	//+kubebuilder:validation:XValidation:rule="self == oldSelf",message="Field 'tenant' is immutable"
 	Tenant string `json:"tenant,omitempty"`
 
@@ -58,16 +65,19 @@ type PrefixClaimSpec struct {
 type PrefixClaimStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
-	// Prefix status: container, active, reserved , deprecated
-	Prefix     string             `json:"prefix,omitempty"`
-	PrefixName string             `json:"prefixName,omitempty"`
-	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
+	// Prefix status: container, active, reserved, deprecated
+
+	ParentPrefix string             `json:"parentPrefix,omitempty"` // Due to the fact that we can use ParentPrefixSelector to assign parent prefixes, we use this field to store exactly which parent prefix we are using for prefix allocation
+	Prefix       string             `json:"prefix,omitempty"`
+	PrefixName   string             `json:"prefixName,omitempty"`
+	Conditions   []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type" protobuf:"bytes,1,rep,name=conditions"`
 }
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Prefix",type=string,JSONPath=`.status.prefix`
 // +kubebuilder:printcolumn:name="PrefixAssigned",type=string,JSONPath=`.status.conditions[?(@.type=="PrefixAssigned")].status`
+// +kubebuilder:printcolumn:name="ParentPrefix",type=string,JSONPath=`.status.parentPrefix`
 // +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 // +kubebuilder:resource:shortName=pxc
@@ -120,3 +130,17 @@ var ConditionPrefixAssignedFalse = metav1.Condition{
 	Reason:  "PrefixCRNotCreated",
 	Message: "Failed to fetch new Prefix from NetBox",
 }
+
+var ConditionParentPrefixComputedTrue = metav1.Condition{
+	Type:    "ParentPrefixComputed",
+	Status:  "True",
+	Reason:  "ParentPrefixComputed",
+	Message: "The parent prefix was computed successfully",
+}
+
+var ConditionParentPrefixComputedFalse = metav1.Condition{
+	Type:    "ParentPrefixComputed",
+	Status:  "False",
+	Reason:  "ParentPrefixNotComputed",
+	Message: "The parent prefix was not able to be computed",
+}

config/crd/bases/netbox.dev_prefixclaims.yaml

@@ -23,6 +23,9 @@ spec:
     - jsonPath: .status.conditions[?(@.type=="PrefixAssigned")].status
       name: PrefixAssigned
       type: string
+    - jsonPath: .status.parentPrefix
+      name: ParentPrefix
+      type: string
     - jsonPath: .status.conditions[?(@.type=="Ready")].status
       name: Ready
       type: string
@@ -52,7 +55,9 @@ spec:
           metadata:
             type: object
           spec:
-            description: PrefixClaimSpec defines the desired state of PrefixClaim
+            description: |-
+              PrefixClaimSpec defines the desired state of PrefixClaim
+              TODO: The reason for using a workaround please see https://github.com/netbox-community/netbox-operator/pull/90#issuecomment-2402112475
             properties:
               comments:
                 type: string
@@ -68,6 +73,13 @@ spec:
                 x-kubernetes-validations:
                 - message: Field 'parentPrefix' is immutable
                   rule: self == oldSelf
+              parentPrefixSelector:
+                additionalProperties:
+                  type: string
+                type: object
+                x-kubernetes-validations:
+                - message: Field 'parentPrefixSelector' is immutable
+                  rule: self == oldSelf
               prefixLength:
                 pattern: ^\/[0-9]|[1-9][0-9]|1[01][0-9]|12[0-8]$
                 type: string
@@ -77,22 +89,25 @@ spec:
               preserveInNetbox:
                 type: boolean
               site:
+                description: Use the `name` value instead of the `slug` value
                 type: string
                 x-kubernetes-validations:
                 - message: Field 'site' is immutable
                   rule: self == oldSelf
               tenant:
+                description: Use the `name` value instead of the `slug` value
                 type: string
                 x-kubernetes-validations:
                 - message: Field 'tenant' is immutable
                   rule: self == oldSelf
             required:
-            - parentPrefix
             - prefixLength
             type: object
             x-kubernetes-validations:
             - message: Site is required once set
               rule: '!has(oldSelf.site) || has(self.site)'
+            - rule: (!has(self.parentPrefix) && has(self.parentPrefixSelector)) ||
+                (has(self.parentPrefix) && !has(self.parentPrefixSelector))
           status:
             description: PrefixClaimStatus defines the observed state of PrefixClaim
             properties:
@@ -165,11 +180,9 @@ spec:
                   - type
                   type: object
                 type: array
+              parentPrefix:
+                type: string
               prefix:
-                description: |-
-                  INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
-                  Important: Run "make" to regenerate code after modifying this file
-                  Prefix status: container, active, reserved , deprecated
                 type: string
               prefixName:
                 type: string

config/samples/kustomization.yaml

@@ -4,4 +4,5 @@ resources:
 - netbox_v1_ipaddressclaim.yaml
 - netbox_v1_prefix.yaml
 - netbox_v1_prefixclaim.yaml
+- netbox_v1_prefixclaim_customfields.yaml
 #+kubebuilder:scaffold:manifestskustomizesamples

config/samples/netbox_v1_prefixclaim_customfields.yaml

@@ -0,0 +1,19 @@
+apiVersion: netbox.dev/v1
+kind: PrefixClaim
+metadata:
+  labels:
+    app.kubernetes.io/name: netbox-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: prefixclaim-customfields-sample
+spec:
+  tenant: "MY_TENANT" # Use the `name` value instead of the `slug` value
+  site: "DM-Akron" # Use the `name` value instead of the `slug` value
+  description: "some description"
+  comments: "your comments"
+  preserveInNetbox: true
+  prefixLength: "/31"
+  parentPrefixSelector: # The keys and values are case-sensitive
+    environment: "Production"
+    poolName: "Pool 1"
+    # environment: "production"
+    # poolName: "pool 3"

config/samples/netbox_v1_prefixclaim_customfields_bool_int.yaml

@@ -0,0 +1,28 @@
+apiVersion: netbox.dev/v1
+kind: PrefixClaim
+metadata:
+  labels:
+    app.kubernetes.io/name: netbox-operator
+    app.kubernetes.io/managed-by: kustomize
+  name: prefixclaim-customfields-sample-4
+spec:
+  tenant: "MY_TENANT" # Use the `name` value instead of the `slug` value
+  site: "DM-Akron" # Use the `name` value instead of the `slug` value
+  description: "some description"
+  comments: "your comments"
+  preserveInNetbox: true
+  prefixLength: "/31"
+  parentPrefixSelector: # The keys and values are case-sensitive
+    # should return a prefix in 3.0.0.0/24
+    environment: "Production"
+    poolName: "Pool 1"
+    # same condition as above, should return a prefix in 3.0.0.0/24
+    # cfDataTypeBool: "true"
+    # cfDataTypeInteger: "1"
+
+    # should return a prefix in 3.0.2.0/24
+    # environment: "Development"
+    # poolName: "Pool 1"
+    # same condition as above, should return a prefix in 3.0.0.0/24
+    # cfDataTypeBool: "false"
+    # cfDataTypeInteger: "2"

internal/controller/ipaddress_controller.go

@@ -147,9 +147,8 @@ func (r *IpAddressReconciler) Reconcile(ctx context.Context, req ctrl.Request) (
 		// create lock
 		locked := ll.TryLock(lockCtx)
 		if !locked {
-			logger.Info(fmt.Sprintf("failed to lock parent prefix %s", ipAddressClaim.Spec.ParentPrefix))
-			r.Recorder.Eventf(o, corev1.EventTypeWarning, "FailedToLockParentPrefix", "failed to lock parent prefix %s",
-				ipAddressClaim.Spec.ParentPrefix)
+			errorMsg := fmt.Sprintf("failed to lock parent prefix %s", ipAddressClaim.Spec.ParentPrefix)
+			r.Recorder.Eventf(o, corev1.EventTypeWarning, "FailedToLockParentPrefix", errorMsg)
 			return ctrl.Result{
 				RequeueAfter: 2 * time.Second,
 			}, nil

internal/controller/ipaddressclaim_controller.go

@@ -23,7 +23,6 @@ import (
 	"time"
 
 	netboxv1 "github.com/netbox-community/netbox-operator/api/v1"
-	"github.com/netbox-community/netbox-operator/pkg/config"
 	"github.com/netbox-community/netbox-operator/pkg/netbox/api"
 	"github.com/netbox-community/netbox-operator/pkg/netbox/models"
 	"github.com/swisscom/leaselocker"
@@ -111,9 +110,8 @@ func (r *IpAddressClaimReconciler) Reconcile(ctx context.Context, req ctrl.Reque
 		locked := ll.TryLock(lockCtx)
 		if !locked {
 			// lock for parent prefix was not available, rescheduling
-			logger.Info(fmt.Sprintf("failed to lock parent prefix %s", o.Spec.ParentPrefix))
-			r.Recorder.Eventf(o, corev1.EventTypeWarning, "FailedToLockParentPrefix", "failed to lock parent prefix %s",
-				o.Spec.ParentPrefix)
+			errorMsg := fmt.Sprintf("failed to lock parent prefix %s", o.Spec.ParentPrefix)
+			r.Recorder.Eventf(o, corev1.EventTypeWarning, "FailedToLockParentPrefix", errorMsg)
 			return ctrl.Result{
 				RequeueAfter: 2 * time.Second,
 			}, nil
@@ -122,7 +120,7 @@ func (r *IpAddressClaimReconciler) Reconcile(ctx context.Context, req ctrl.Reque
 
 		// 4. try to reclaim ip address
 		h := generateIpAddressRestorationHash(o)
-		ipAddressModel, err := r.NetboxClient.RestoreExistingIpByHash(config.GetOperatorConfig().NetboxRestorationHashFieldName, h)
+		ipAddressModel, err := r.NetboxClient.RestoreExistingIpByHash(h)
 		if err != nil {
 			if setConditionErr := r.SetConditionAndCreateEvent(ctx, o, netboxv1.ConditionIpAssignedFalse, corev1.EventTypeWarning, err.Error()); setConditionErr != nil {
 				return ctrl.Result{}, fmt.Errorf("error updating status: %w, looking up ip by hash failed: %w", setConditionErr, err)

internal/controller/prefix_controller.go

@@ -132,29 +132,42 @@ func (r *PrefixReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctr
 			return ctrl.Result{}, err
 		}
 
-		// get the name of the parent prefix
-		leaseLockerNSN := types.NamespacedName{
-			Name:      convertCIDRToLeaseLockName(prefixClaim.Spec.ParentPrefix),
-			Namespace: r.OperatorNamespace,
-		}
-		ll, err = leaselocker.NewLeaseLocker(r.RestConfig, leaseLockerNSN, req.NamespacedName.String())
-		if err != nil {
-			return ctrl.Result{}, err
+		if prefixClaim.Status.ParentPrefix == "" {
+			// the parent prefix is not computed
+			if err := r.SetConditionAndCreateEvent(ctx, prefix, netboxv1.ConditionPrefixReadyFalse, corev1.EventTypeWarning, "the parent prefix is not computed"); err != nil {
+				return ctrl.Result{}, err
+			}
+			return ctrl.Result{
+				Requeue: true,
+			}, nil
 		}
 
-		lockCtx, cancel := context.WithCancel(ctx)
-		defer cancel()
+		if prefixClaim.Status.ParentPrefix != msgCanNotInferParentPrefix {
+			// we can't restore from the restoration hash
 
-		// create lock
-		if locked := ll.TryLock(lockCtx); !locked {
-			logger.Info(fmt.Sprintf("failed to lock parent prefix %s", prefixClaim.Spec.ParentPrefix))
-			r.Recorder.Eventf(prefix, corev1.EventTypeWarning, "FailedToLockParentPrefix", "failed to lock parent prefix %s",
-				prefixClaim.Spec.ParentPrefix)
-			return ctrl.Result{
-				RequeueAfter: 2 * time.Second,
-			}, nil
+			// get the name of the parent prefix
+			leaseLockerNSN := types.NamespacedName{
+				Name:      convertCIDRToLeaseLockName(prefixClaim.Status.ParentPrefix),
+				Namespace: r.OperatorNamespace,
+			}
+			ll, err = leaselocker.NewLeaseLocker(r.RestConfig, leaseLockerNSN, req.NamespacedName.String())
+			if err != nil {
+				return ctrl.Result{}, err
+			}
+
+			lockCtx, cancel := context.WithCancel(ctx)
+			defer cancel()
+
+			// create lock
+			if locked := ll.TryLock(lockCtx); !locked {
+				errorMsg := fmt.Sprintf("failed to lock parent prefix %s", prefixClaim.Status.ParentPrefix)
+				r.Recorder.Eventf(prefix, corev1.EventTypeWarning, "FailedToLockParentPrefix", errorMsg)
+				return ctrl.Result{
+					RequeueAfter: 2 * time.Second,
+				}, nil
+			}
+			debugLogger.Info("successfully locked parent prefix %s", prefixClaim.Status.ParentPrefix)
 		}
-		debugLogger.Info("successfully locked parent prefix %s", prefixClaim.Spec.ParentPrefix)
 	}
 
 	/* 2. reserve or update Prefix in netbox */
@@ -218,7 +231,6 @@ func (r *PrefixReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctr
 	}
 
 	debugLogger.Info(fmt.Sprintf("reserved prefix in netbox, prefix: %s", prefix.Spec.Prefix))
-
 	if err = r.SetConditionAndCreateEvent(ctx, prefix, netboxv1.ConditionPrefixReadyTrue, corev1.EventTypeNormal, ""); err != nil {
 		return ctrl.Result{}, err
 	}