Retire IPClaim and IPAdderess CRDs in favour of CAPI provided IPAddressClaim and IPAdderess

[peppi-lotta]

Cluster-API (CAPI) has introduced IPAddress and IPAddressClaim CRDs, along with support for a new provider type: the IPAMProvider. These CRDs, and the sub-project Cluster-API-ipam-provider-in-cluster, were inspired by Metal3's IP Address Manager. CAPI provides the IPAddress and IPAddressClaim CRD types and expects an IPAMProvider to supply IPPools to handle these resources. This is described in the CAPI IPAMProvider contract.

Since the Cluster-API CRDs differ slightly from their Metal3 counterparts, the original Metal3 IP Address Manager was not directly suitable as a CAPI IPAMProvider. To address this, I worked on adapting Metal3-IPAM into an official provider for CAPI. As of the CAPI v1.11.2 release, Metal3-IPAM is now an official IPAM provider.

CAPI always deploys its own IPAM CRDs. When Metal3 is deployed using clusterctl init --infrastructure metal3, the full Metal3-IPAM stack is also deployed. After the initial changes were merged, no IPAM is deployed unless the --ipam flag is specified. Metal3-IPAM can be deployed explicitly with --ipam metal3. CAPM3 has also added support for the CAPI IPAM contract. Since CAPM3 now supports two types of IPAM, it makes sense that they are deployed and used in the same way.

User Story

As a user when I deploy CAPM3 with Metal3-IPAM, I encounter two types of IP claims: ipclaims.ipam.metal3.io and ipclaims.ipam.cluster.x-k8s.io, and two types of IP addresses: ipaddresses.ipam.metal3.io and ipaddresses.ipam.cluster.x-k8s.io. As a user, I find it confusing that there are two resources with the same name.

As a developer I want the code base I am maintaining to be simple as possible. Currently handling these two slightly different CRDs add un necessary complexity and I want to simplify this.

Detailed Description

I propose a change to the Metal3-IPAM API. I have two suggestions in mind:

1. Delete IPClaim and IPAddress from Metal3-IPAM and rely solely on CAPI’s IPAddressClaim and IPAddress resources.
2. Rename and align IPClaim and IPAddress in Metal3-IPAM with CAPI naming and conditions, reducing code complexity in both Metal3-IPAM and CAPM3.

Suggention 1 will make standalone use of Metal3's IPAM a bit more dificult. Users will have to get the IPAddress and IPAddressClaim CRDs from CAPI project. Suggestion 2 will require maintaining redundant CRDs.

/kind feature

[Rozzii]

/triage accepted
Accepted means that we can start the discussion in the community.
I would like to ask you @peppi-lotta to present the "plan" related to this issue in one of the community meetings too.
There are questions e.g. related to the usability of IPAM without CAPI.

[metal3-io-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues will close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[Rozzii]

/remove-lifecycle stale

[Rozzii]

/lifecycle frozen

[peppi-lotta]

In community meeting on 17.10.2025 we desided that option 1. would be the way to go. IPClaim and IPAddress CRDs will be retired and Metal3-ip-address-manager will not support being a standalone IPAM and it will focus on being a CAPI IPAMProvider. There was no objections to this plan in the community meeting and if there are no objections in the future this is the plan we are going to follow.

As CAPI IPAM contract support is added to CAPM3. It would reduce code complexity in CAPM3 to start using CAPI CRDs. CAPM3 should be able to use the CAPI CRs but next step would be to make sure the CAPI IPAM related CRDs are the ones being used in the e2e tests. I've opened an issue related to that in CAPM3.

After switching the CAPM3 tests we can start deprecating the IPClaim and IPAddress CRDs. This should follow steps:

• Add deprecation notice to IPAM (one release cycle).
• Add functions to handle changing metal3-ipclaims into capi ipaddressclaims in capm3.
• Some conversion logic might be needed in metal3 as well.
• Hide old CRDs behind some feature gate
• Make new API release to fully deprecate the CRDs.