Make IP/IPRange/Prefix restoration hash configurable

[yypastushenko]

What would you like to be added?

To avoid collisions and make multi-cluster usage safe, it should be possible to include additional user-defined data into the hash generation logic used for IP address allocation.

Instead of relying only on a fixed set of fields, the operator should be able to incorporate tags into the hash. This would allow users to explicitly control allocation behavior across clusters and operator instances.

For example:

• One or more tags configured at the operator or IPAddressClaim level
• Tags representing the operator name, cluster identifier, or any other logical grouping
• Stable values that remain consistent across operator restarts

Depending on the implementation, this could be achieved by:

• Reusing existing NetBox tags on IP addresses or prefixes
• Or introducing a dedicated custom field whose value is included in the hash

The selected tags or metadata would then be included in the hash computation used for IP address allocation.

Such an approach would allow:

• Using different tags to force allocation of different IP addresses from the same parent prefix in different kubernetes clusters, but from the same IpAddressClaim name, namespace and tenant.
• Using identical tags to intentionally allocate the same IP address across multiple clusters
• Safe multi-cluster usage of a shared NetBox instance
• Avoiding the need for globally unique namespaces or IPAddressClaim names

---

Why is this needed?

Problem description

We are using NetBox with the NetBox operator to allocate IP addresses from a shared parent prefix using IPAddressClaims.

Our environment consists of multiple independent Kubernetes clusters that all consume IP addresses from the same NetBox instance and the same large prefix. This prefix represents an anycast network, where the same IP address may be advertised from different locations.

Currently, the uniqueness of an IP allocation is derived from a hash composed of the following fields:

• IPAddressClaim name
• IPAddressClaim namespace
• tenant
• parent prefix

This approach assumes that namespaces and claim names are globally unique across all clusters.
In our environment, this assumption does not hold and is not desirable.
In some cases we need to claim the same address across multiple clusters (when we want to advertise from multiple regions the same adress), but in other cases, we want to advertise different addresses from different clusters (but from same namespaces and IpAddressClaim names).

---

Expected and valid use case

It is a perfectly valid and expected scenario that:

• Different Kubernetes clusters have identical namespaces
• IPAddressClaims inside those namespaces have identical names
• The tenant is the same logical tenant
• The same parent prefix is used for allocation

These IPAddressClaims are not global across clusters and should be treated as independent by default.

However, with the current hash generation logic, two such claims created in different clusters but with identical values for the fields listed above will produce the same hash and therefore receive the same IP address from NetBox.

This leads to unintended IP address collisions across clusters.

---

Why tags or metadata solve this

At the same time, the current behavior unintentionally enables IP migration or cross-cluster reuse by relying on a globally stable hash.

By making additional hash inputs explicit and configurable (for example via tags), this behavior becomes controllable:

• Different tags result in different IP allocations
• Identical tags result in reuse of the same IP address across clusters

This preserves intentional IP reuse or migration scenarios, while preventing accidental collisions in multi-cluster environments.

[yypastushenko]

Workarounds

We currently operate two Kubernetes clusters: cluster-1 and cluster-2.

Because there is no way to explicitly control which fields are used as inputs for hash generation, we are forced to encode the desired allocation behavior directly into the IPAddressClaim name.

Case 1: Allocate unique IP addresses per cluster

Goal

Each cluster should receive a different IP address, even if the claims are created in the same namespace with otherwise identical parameters.

Workaround

Add a cluster-specific identifier to the IPAddressClaim name.

Example

Cluster: cluster-1
Namespace: my-namespace
IPAddressClaim name: cluster-2-my-claim

Cluster: cluster-2
Namespace: my-namespace
IPAddressClaim name: cluster-2-my-claim

Result

Each claim receives a unique IP address.

---

Case 2: Allocate the same IP address across clusters

Goal

Both clusters should receive the same IP address (for example, for anycast use cases).

Workaround

Use an identical, shared identifier in the IPAddressClaim name.

Example

Cluster: cluster-1
Namespace: my-namespace
IPAddressClaim name: anycast-my-claim

Cluster: cluster-2
Namespace: my-namespace
IPAddressClaim name: anycast-my-claim

Result:

Both claims receive the same IP address.

---

These workarounds rely on naming conventions, are error-prone, and leak infrastructure concerns into resource names.
Making hash inputs explicitly configurable (for example via tags) would eliminate the need for such conventions and provide a safer and more flexible solution.