Files
cozystack/packages/core/platform/tests
Aleksei Sviridkin d99e960c00 feat(platform): package address-controller and its MetalLB driver (#3382)
## What this PR does

Adds IP addresses as a first-class resource
([cozystack/community#35](https://github.com/cozystack/community/pull/35))
as two optional system packages, off by default and enabled through
`bundles.enabledPackages`:

- **`cozystack.address-controller`** — the class-agnostic core
([cozystack/address-controller](https://github.com/cozystack/address-controller)):
`IPAddressClass` / `IPAddress` / `IPAddressClaim` in
`local.sdn.cozystack.io`, the PVC/PV-binding analog. It owns
claim–address binding, status and reclaim, and never allocates anything
itself.
- **`cozystack.metallb-iad`** — the per-class driver for addresses
announced by MetalLB
([cozystack/metallb-iad](https://github.com/cozystack/metallb-iad)). A
class names an existing `IPAddressPool` with `autoAssign: false` in
`cozy-metallb`, which the admin provisions together with its
advertisement. The driver holds reservations as placeholder Services in
its own namespace, and attaches an address to a Service that names a
claim with the `local.sdn.cozystack.io/ip-address-claim` annotation.

### Packaging

Both are ordinary wrapper packages under `packages/system/`, sourced
from the `cozystack-packages` artifact like every other package. The
upstream chart is vendored verbatim under `charts/` by `make update` at
a pinned commit, since neither project publishes a chart artifact: the
`v0.2.0` release-preparation commits of
[cozystack/address-controller#17](https://github.com/cozystack/address-controller/pull/17)
and
[cozystack/metallb-iad#11](https://github.com/cozystack/metallb-iad/pull/11).
Each controller image is pinned by digest to a `main-<sha>` build
carrying the same controller code: `address-controller:main-90e65ca`,
whose commit differs from #17 only in chart version and docs, and
`metallb-iad:main-1faf937`, whose commit differs from #11 only in chart
version and the address-controller module pin, a purely additive API
change the driver does not use. The pins move to the `v0.2.0` tags and
images once both are released. The images live under
`ghcr.io/cozystack/<name>`, outside the `ghcr.io/cozystack/cozystack/`
repositories the release tooling owns, so promotion and the nightly
mirror pass over them. The core installs its v1alpha1 CRDs with
`upgradeCRDs: CreateReplace`.

### What the wrappers add

- **Tenant access.** The upstream chart is Cozystack-agnostic and grants
only the controller itself. `cozy:addresses`, `cozy:addresses:view` and
`cozy:addresses:admin` aggregate into `cozy:tenant`, `cozy:tenant:view`
and `cozy:tenant:admin` respectively, so a tenant can manage
`IPAddressClaim`s in its own namespace, and the grant exists only while
the package is installed. The cluster-scoped `IPAddress` and
`IPAddressClass` are not granted: `cozy:tenant*` reaches a tenant
through a per-namespace RoleBinding, so a rule for either would never be
consulted. A tenant reads its address from the claim's
`status.addresses[]`.
- **The driver's admission policy, turned on for tenant namespaces.**
MetalLB honours a pin or pool selector from any writer of a Service: the
`metallb.io/` annotations, their `metallb.universe.tf/` predecessors and
`spec.loadBalancerIP`. A tenant cluster's cloud provider copies a guest
Service's annotations and `loadBalancerIP` onto the Service it creates
in the tenant namespace. The upstream `metallb-iad-service-pins` policy
reserves all of these, plus the sharing annotation, to the driver's
ServiceAccount and the cluster-admin groups. An admission policy binds
every principal regardless of RBAC, so the wrapper adds
`cozystack-cluster-admin`, the group Cozystack's OIDC administrators
authenticate as, to the chart's `system:masters` and
`kubeadm:cluster-admins`. The wrapper enables it in `Deny` mode for
namespaces carrying `namespace.cozystack.io/host`, which `tenant-root`
and every tenant namespace have and nothing in `cozy-*` does. Unchanged
values always pass, so the driver's pin on a tenant's own Service does
not lock the rest of that Service.
- **The driver's MetalLB namespace**, `cozy-metallb` instead of the
upstream default `metallb-system`.

### Variant scoping

`cozystack.metallb-iad` depends on `cozystack.address-controller`, which
is opt-in, and on `cozystack.metallb`, which is absent on `isp-hosted`,
on a slim variant that did not opt into it, and wherever
`disabledPackages` names it. The driver is emitted from the
`common-packages` helper only when the includes of MetalLB and of
`cozystack.address-controller` both rendered a Package, so it cannot be
enabled where it would sit in `DependenciesNotReady` forever, and it
follows either dependency automatically if its rules change. The core
carries no MetalLB dependency and remains available everywhere.

### Validation

`helm unittest` covers the aggregation labels and rules on the tenant
roles and the driver's emission, which requires both MetalLB and the
address core. `hack/select-install.sh --validate` passes, and the
selective-install fixture is regenerated from `hack/select-install.sh
--disabled postgres`. The admission policy is upstream's and carries no
render test here.

### Screenshots

Not a UI change.

### Downstream repositories

- [ ] No downstream repository is affected by this change
- [x] [cozystack/website](https://github.com/cozystack/website) -
follow-up:
[cozystack/website#810](https://github.com/cozystack/website/pull/810)
(component cards),
[cozystack/website#811](https://github.com/cozystack/website/pull/811)
(operator guide)
- [ ]
[cozystack/terraform-provider-cozystack](https://github.com/cozystack/terraform-provider-cozystack)
- follow-up:
- [ ]
[cozystack/ansible-cozystack](https://github.com/cozystack/ansible-cozystack)
- follow-up:
- [ ] [cozystack/ccp](https://github.com/cozystack/ccp) - follow-up:
- [ ] [cozystack/talm](https://github.com/cozystack/talm) - follow-up:
- [ ] [cozystack/cozyhr](https://github.com/cozystack/cozyhr) -
follow-up:
- [ ] [cozystack/cozy-proxy](https://github.com/cozystack/cozy-proxy) -
follow-up:
- [ ]
[cozystack/cozystack-telemetry-server](https://github.com/cozystack/cozystack-telemetry-server)
- follow-up:
- [ ]
[cozystack/external-apps-example](https://github.com/cozystack/external-apps-example)
- follow-up:
- [ ] [cozystack/examples](https://github.com/cozystack/examples) -
follow-up:
- [ ] [cozystack/community](https://github.com/cozystack/community) -
follow-up:

The website is the one repository this change reaches:
[cozystack/website#810](https://github.com/cozystack/website/pull/810)
adds the two new platform components to
`guides/platform-stack/_index.md` and
`operations/configuration/licenses.md`, and
[cozystack/website#811](https://github.com/cozystack/website/pull/811)
adds an operator guide under `networking/`. The guide restates both
image refs, so a repin here needs the same edit there.

### Release note

```release-note
feat(platform): add IP addresses as a first-class resource as two optional system packages, `cozystack.address-controller` (IPAddressClass / IPAddress / IPAddressClaim) and its MetalLB driver `cozystack.metallb-iad`. Tenants can reserve an address with an IPAddressClaim. A LoadBalancer Service a tenant Kubernetes cluster creates can name that claim with the `local.sdn.cozystack.io/ip-address-claim` annotation, or draw one through auto-claim once an admin marks an auto-claim class. An admission policy reserves MetalLB's pool, pin and sharing inputs on tenant Services to the driver. The driver is only emitted where MetalLB and the address core are.
```




<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **New Features**
* Added address management for requesting and tracking IPv4, IPv6, or
dual-stack addresses, with configurable address classes and lifecycle
status.
* Added the MetalLB IAD driver for address provisioning through MetalLB.
It is included only when the required MetalLB and address-management
components are enabled.
* Added optional admission controls for address claims and protected
MetalLB service settings.
* Added optional address-controller metrics, monitoring, and alerting
resources.
  * Added tenant access roles for viewing and managing address claims.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-11-17 15:15:03 +03:00
..