Skip to content

Commit 6c809fc

Browse files
committed
Close the adoption race and document class deletion and held addresses
Adoption now creates the claim with spec.addressName, so the driver does not provision a different address before the pre-bound IPAddress exists; creating the IPAddress first would have it reclaimed as orphaned. The pin protection is stated as depending on metallb-iad's optional admission policy. New sections cover why a used class waits on its Released and Available addresses, and that the held annotation pauses the return to the pool but not the delay. Assisted-By: LLM Signed-off-by: Timofei Larkin <lllamnyp@gmail.com>
1 parent ad9398f commit 6c809fc

1 file changed

Lines changed: 42 additions & 3 deletions

File tree

‎docs/operating.md‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,23 @@ A Service pinned by hand to an address of a class's range keeps it while
99
it moves under the ledger, because the driver's pin equals the existing
1010
one:
1111

12-
1. Create an `IPAddressClaim` in the Service's namespace, naming the class.
12+
1. Create an `IPAddressClaim` in the Service's namespace that names the
13+
class and, in `spec.addressName`, the `IPAddress` of step 2. The MetalLB
14+
driver does not provision for a claim that names an address, so the
15+
claim waits `Pending` for that one. Where the optional `spec.addressName` admission
16+
policy is enabled, this takes an allowlisted principal.
17+
18+
```yaml
19+
apiVersion: local.sdn.cozystack.io/v1alpha1
20+
kind: IPAddressClaim
21+
metadata:
22+
name: web
23+
namespace: tenant-a
24+
spec:
25+
className: public
26+
addressName: ip-203-0-113-7
27+
```
28+
1329
2. Create the `IPAddress` pre-bound to it:
1430

1531
```yaml
@@ -31,8 +47,14 @@ one:
3147
3. Annotate the Service with `local.sdn.cozystack.io/ip-address-claim: web`.
3248
The driver records the association and pins the same address.
3349

34-
The hand-written pin stays on the Service. Under the driver's admission
35-
policy, removing it later takes an allowlisted principal.
50+
The hand-written pin stays on the Service. Where metallb-iad's optional
51+
admission policy is enabled, removing it later takes an allowlisted
52+
principal. Without that policy, removing it is not gated, and only the
53+
driver's conflict detection reports the address going to another Service.
54+
55+
Creating the `IPAddress` before the claim does not work: an address whose
56+
`claimRef` names a missing claim is reclaimed at once, `Released` under
57+
`Retain` and deleted under `Delete`.
3658

3759
## Removing the controllers
3860

@@ -71,6 +93,23 @@ The group suffix matters: `ipaddresses` alone resolves to the Kubernetes
7193
`networking.k8s.io` kind. Backend state the driver would have released,
7294
such as MetalLB placeholder Services, is then left for you to delete.
7395

96+
### Deleting a class
97+
98+
A class is held until no `IPAddress` of it is left, in any phase. Under
99+
`reclaimPolicy: Retain` a deleted claim leaves its addresses `Released`,
100+
and a class's `releaseDelay` returns them to `Available` rather than
101+
deleting them, so a class that has served claims keeps addresses that hold
102+
it. Delete those `IPAddress` objects, and the class goes. Until then the
103+
class reports a `ClassInUse` event naming them.
104+
105+
## Quarantining an address
106+
107+
`ipaddress.local.sdn.cozystack.io/held: "true"` on a `Released` address
108+
keeps its class's `releaseDelay` from returning it to the pool. The
109+
annotation pauses the return, not the delay: removing it from an address
110+
that has been `Released` for longer than `releaseDelay` returns the
111+
address on the next pass.
112+
74113
## Upgrading the CRDs
75114

76115
The API is `v1alpha1` with no conversion webhook. Helm installs the chart's

0 commit comments

Comments
 (0)