Deprecate the endpointRef field on the BMC resource

Signed-off-by: Andreas Fritzler <andreas.fritzler@sap.com>

Author: afritzler

.golangci.yml

@@ -56,6 +56,12 @@ linters:
       - linters:
           - staticcheck
         text: "SA1019.*metalv1alpha1\\.Endpoint"
+      # BMC.spec.endpointRef references the deprecated Endpoint resource. The operator
+      # still serves existing BMCs that use it, so legacy consumers reference the field
+      # until the Endpoint resource is fully removed.
+      - linters:
+          - staticcheck
+        text: "SA1019.*\\.EndpointRef is deprecated"
     paths:
       - third_party$
       - builtin$

api/v1alpha1/applyconfiguration/api/v1alpha1/bmcspec.go

@@ -30,6 +30,10 @@ type BMCSpec struct {
 	BMCUUID string `json:"bmcUUID,omitempty"`
 
 	// EndpointRef is a reference to the Endpoint object that contains the network access information for the BMC.
+	//
+	// Deprecated: The Endpoint resource is deprecated. Specify the network access inline via
+	// access (an InlineEndpoint carrying the MAC address and IP) instead of referencing an
+	// Endpoint object.
 	// +optional
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="endpointRef is immutable"

api/v1alpha1/bmc_types.go

@@ -649,6 +649,13 @@ func main() { // nolint: gocyclo
 		}
 	}
 	// nolint:goconst
+	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
+		if err := webhookv1alpha1.SetupBMCWebhookWithManager(mgr); err != nil {
+			setupLog.Error(err, "Failed to create webhook", "webhook", "bmc")
+			os.Exit(1)
+		}
+	}
+	// nolint:goconst
 	if os.Getenv("ENABLE_WEBHOOKS") != "false" {
 		if err := webhookv1alpha1.SetupBMCSecretWebhookWithManager(mgr); err != nil {
 			setupLog.Error(err, "Failed to create webhook", "webhook", "bmcsecret")

cmd/main.go

@@ -140,8 +140,12 @@ spec:
                 - port
                 type: object
               endpointRef:
-                description: EndpointRef is a reference to the Endpoint object that
-                  contains the network access information for the BMC.
+                description: |-
+                  EndpointRef is a reference to the Endpoint object that contains the network access information for the BMC.
+
+                  Deprecated: The Endpoint resource is deprecated. Specify the network access inline via
+                  access (an InlineEndpoint carrying the MAC address and IP) instead of referencing an
+                  Endpoint object.
                 properties:
                   name:
                     default: ""

config/crd/bases/metal.ironcore.dev_bmcs.yaml

@@ -46,6 +46,26 @@ webhooks:
     resources:
     - biosversions
   sideEffects: None
+- admissionReviewVersions:
+  - v1
+  clientConfig:
+    service:
+      name: webhook-service
+      namespace: system
+      path: /validate-metal-ironcore-dev-v1alpha1-bmc
+  failurePolicy: Fail
+  name: vbmc-v1alpha1.kb.io
+  rules:
+  - apiGroups:
+    - metal.ironcore.dev
+    apiVersions:
+    - v1alpha1
+    operations:
+    - CREATE
+    - UPDATE
+    resources:
+    - bmcs
+  sideEffects: None
 - admissionReviewVersions:
   - v1
   clientConfig:

config/webhook/manifests.yaml

@@ -146,8 +146,12 @@ spec:
                 - port
                 type: object
               endpointRef:
-                description: EndpointRef is a reference to the Endpoint object that
-                  contains the network access information for the BMC.
+                description: |-
+                  EndpointRef is a reference to the Endpoint object that contains the network access information for the BMC.
+
+                  Deprecated: The Endpoint resource is deprecated. Specify the network access inline via
+                  access (an InlineEndpoint carrying the MAC address and IP) instead of referencing an
+                  Endpoint object.
                 properties:
                   name:
                     default: ""

dist/chart/templates/crd/metal.ironcore.dev_bmcs.yaml

@@ -53,6 +53,26 @@ webhooks:
           - v1alpha1
         resources:
           - biosversions
+  - name: vbmc-v1alpha1.kb.io
+    clientConfig:
+      service:
+        name: metal-operator-webhook-service
+        namespace: {{ .Release.Namespace }}
+        path: /validate-metal-ironcore-dev-v1alpha1-bmc
+    failurePolicy: Fail
+    sideEffects: None
+    admissionReviewVersions:
+      - v1
+    rules:
+      - operations:
+          - CREATE
+          - UPDATE
+        apiGroups:
+          - metal.ironcore.dev
+        apiVersions:
+          - v1alpha1
+        resources:
+          - bmcs
   - name: vbmcsecret-v1alpha1.kb.io
     clientConfig:
       service:

dist/chart/templates/webhook/webhooks.yaml

@@ -635,7 +635,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `bmcUUID` _string_ | BMCUUID is the unique identifier for the BMC as defined in Redfish API. |  | Optional: \{\} <br /> |
-| `endpointRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#localobjectreference-v1-core)_ | EndpointRef is a reference to the Endpoint object that contains the network access information for the BMC. |  | Optional: \{\} <br /> |
+| `endpointRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#localobjectreference-v1-core)_ | EndpointRef is a reference to the Endpoint object that contains the network access information for the BMC.<br />Deprecated: The Endpoint resource is deprecated. Specify the network access inline via<br />access (an InlineEndpoint carrying the MAC address and IP) instead of referencing an<br />Endpoint object. |  | Optional: \{\} <br /> |
 | `access` _[InlineEndpoint](#inlineendpoint)_ | Endpoint specifies inline network access details for the BMC. |  | Optional: \{\} <br /> |
 | `bmcSecretRef` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.36/#localobjectreference-v1-core)_ | BMCSecretRef is a reference to the BMCSecret object that contains the credentials<br />required to access the BMC. |  |  |
 | `protocol` _[Protocol](#protocol)_ | Protocol specifies the protocol to be used for communicating with the BMC. |  |  |

docs/api-reference/api.md

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and IronCore contributors
+// SPDX-License-Identifier: Apache-2.0
+
+package v1alpha1
+
+import (
+	"context"
+
+	"sigs.k8s.io/controller-runtime/pkg/client"
+
+	ctrl "sigs.k8s.io/controller-runtime"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
+	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
+
+	metalv1alpha1 "github.com/ironcore-dev/metal-operator/api/v1alpha1"
+)
+
+// log is for logging in this package.
+var bmclog = logf.Log.WithName("bmc-resource")
+
+// SetupBMCWebhookWithManager registers the webhook for BMC in the manager.
+func SetupBMCWebhookWithManager(mgr ctrl.Manager) error {
+	return ctrl.NewWebhookManagedBy(mgr, &metalv1alpha1.BMC{}).
+		WithValidator(&BMCCustomValidator{Client: mgr.GetClient()}).
+		Complete()
+}
+
+// NOTE: The 'path' attribute must follow a specific pattern and should not be modified directly here.
+// Modifying the path for an invalid path can cause API server errors; failing to locate the webhook.
+// +kubebuilder:webhook:path=/validate-metal-ironcore-dev-v1alpha1-bmc,mutating=false,failurePolicy=fail,sideEffects=None,groups=metal.ironcore.dev,resources=bmcs,verbs=create;update,versions=v1alpha1,name=vbmc-v1alpha1.kb.io,admissionReviewVersions=v1
+
+// BMCCustomValidator struct is responsible for validating the BMC resource
+// when it is created, updated, or deleted.
+//
+// NOTE: The +kubebuilder:object:generate=false marker prevents controller-gen from generating DeepCopy methods,
+// as this struct is used only for temporary operations and does not need to be deeply copied.
+// +kubebuilder:object:generate=false
+type BMCCustomValidator struct {
+	Client client.Client
+}
+
+// bmcEndpointRefDeprecationWarning is the admission warning surfaced on BMC create/update
+// when spec.endpointRef is set, to direct users toward the inlined BMC.spec.access path.
+const bmcEndpointRefDeprecationWarning = "spec.endpointRef is deprecated; specify the network access inline via spec.access (an InlineEndpoint with macAddress and ip) instead"
+
+// ValidateCreate implements webhook.CustomValidator so a webhook will be registered for the type BMC.
+func (v *BMCCustomValidator) ValidateCreate(ctx context.Context, obj *metalv1alpha1.BMC) (admission.Warnings, error) {
+	bmclog.Info("Validating BMC upon creation", "name", obj.GetName())
+
+	return bmcEndpointRefWarnings(obj), nil
+}
+
+// ValidateUpdate implements webhook.CustomValidator so a webhook will be registered for the type BMC.
+func (v *BMCCustomValidator) ValidateUpdate(ctx context.Context, oldObj, newObj *metalv1alpha1.BMC) (admission.Warnings, error) {
+	bmclog.Info("Validating BMC upon update", "name", newObj.GetName())
+
+	return bmcEndpointRefWarnings(newObj), nil
+}
+
+// ValidateDelete implements webhook.CustomValidator so a webhook will be registered for the type BMC.
+func (v *BMCCustomValidator) ValidateDelete(ctx context.Context, obj *metalv1alpha1.BMC) (admission.Warnings, error) {
+	bmclog.Info("Validating BMC upon deletion", "name", obj.GetName())
+
+	return nil, nil
+}
+
+// bmcEndpointRefWarnings returns the deprecation warning when the BMC references an Endpoint
+// via spec.endpointRef. It never rejects the object; the access/endpointRef exactly-one-of and
+// immutability rules are enforced by CEL XValidation markers on the BMCSpec type.
+func bmcEndpointRefWarnings(bmc *metalv1alpha1.BMC) admission.Warnings {
+	if bmc.Spec.EndpointRef != nil {
+		return admission.Warnings{bmcEndpointRefDeprecationWarning}
+	}
+	return nil
+}