gsadmin/spinifex
1
0
Fork 0
mirror of https://github.com/mulgadc/spinifex.git synced 2026-10-15 09:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: record EKS add-on activation review decisions

Browse Source
This commit is contained in:
joshsiv-mulga
2026-10-09 10:54:26 +10:00
parent 7e504c1dd2
commit 0fc4d449bf
2 changed files with 13 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/package-boundary/eks-addon-v2-contract-design.md
+3 -2
View File
@@ -145,7 +145,7 @@ Static-credential fallback VMs have no session name and can never be executors (
| Order | Check | v2 reason | HTTP |
|---|---|---|---|
| 1 | SigV4, IAM policy, CP-agent class | existing gateway envelope (`AccessDenied`); these run before the v2 handler | 403 |
| 2 | Activation record present (P2) | `NotActivated` | 503 |
| 2 | Activation record present (P2) | `NotActivated` if the record is absent; `ActivationStateUnavailable` if it is unreadable, invalid or unavailable | 503 |
| 3 | Caller is a member of the named cluster in the named account (`IsControlPlaneMember`, `internal_authz.go:74`) | `NotClusterMember` | 403 |
| 4 | Executor record names an instance | `NoActiveExecutor` | 503 |
| 5 | `Caller.SessionName == executor.instanceId` | `NotActiveExecutor` | 403 |
@@ -347,7 +347,7 @@ Reasons are internal contract values, not AWS error codes (R7); the owner maps s
| `DeletePending` | `removing` | none | Delete issued; objects still present without a finalizer cause. |
No reason exists for an unreachable apiserver: the guest sends nothing for that add-on, as the lifecycle design specifies, and silence is handled by deadlines.
The gateway-side rejection reasons of Section 4.3 (`NotActivated`, `NotClusterMember`, `NoActiveExecutor`, `NotActiveExecutor`, `StaleExecutorEpoch`, `UnknownContractMajor`, `MalformedReport`) are response reasons, never report reasons.
The gateway-side rejection reasons of Section 4.3 (`NotActivated`, `ActivationStateUnavailable`, `NotClusterMember`, `NoActiveExecutor`, `NotActiveExecutor`, `StaleExecutorEpoch`, `UnknownContractMajor`, `MalformedReport`) are response reasons, never report reasons.
The reason table above is the closed set for `contractVersion: 2` (V4; Q-75, ADR-0006 S3).
A genuinely new wire-level reason has new semantics and therefore requires a new major, never a silent addition to this enum; free-form detail that does not need enum-level routing belongs in `message`, not in an unbounded `reason` value.
@@ -528,6 +528,7 @@ Writing that would make every N-1 `ListAddons` and `DescribeAddon` on the cluste
| V8 | An executor is not v2-capable merely because it fetched a directive. Capability is marked only after the first valid, fenced v2 report is accepted (Section 2.3, Section 4.1). A fetch may be retained as diagnostic evidence only. |
| V9 | Activation (Section 3, P2) is EKS-add-on-specific for now. The release-membership mechanism should be reusable, but this design does not build a platform-wide activation framework. |
| V10 | Automatic executor fencing (Section 4.4) uses only authoritative evidence that the former instance terminated or no longer exists. A lookup error, network issue or partition is never evidence of termination. The alternative is an audited operator assertion. |
| V11 | `ActivationStateUnavailable` (HTTP 503, retryable) is defined in v2 from the outset for an unreadable, invalid or unavailable activation record. Only an absent record is `NotActivated`, and only `NotActivated` is eligible for the bounded fallback (V1); `ActivationStateUnavailable` never triggers fallback, because it is not evidence that v2 is inactive. |
The v1 `PublishInternal` authorization-binding gap and the `serviceAccountRoleArn` format-validation gap (Sections 5.3 and 7) are being fixed directly on the v1 path as standalone security corrections, not as v2 lifecycle work; v2 keeps its own binding and its own guest-side validation regardless of either fix's timing.
docs/package-boundary/eks-release-membership-and-activation-design.md
+10 -6
View File
@@ -136,10 +136,11 @@ On re-activation, no earlier `addonContract: 2` marking counts until a fresh fen
|---|---|
| Every daemon and awsgw slot capable; no legacy observation since activation | No N-1 host remains |
| Every record migrated; every awsgw and daemon projects the v1 listing from records | Manifest keys stop being written |
| Every non-deleting cluster's current executor epoch proven v2 under the current activation generation; no executor, or a `FAILED` cluster with running VMs, refuses | A v1 guest served from manifest keys would remove every add-on (`handlers/eks/addons.go:132-134`) |
| Every cluster explicitly activated onto v2 has current proof: its executor epoch proven v2 under the current activation generation; such a cluster with no executor, or `FAILED` with running VMs, refuses | A v1 guest served from manifest keys would remove every add-on (`handlers/eks/addons.go:132-134`) |
| Every cluster still on v1 is enumerated as legacy in the finalisation output and audit entry | v1 clusters are visible, never silently treated as compatible |
| Explicit `--confirm eks-addon-lifecycle/2` | Q-75, ADR-0006:S5 step 4 |
Finalisation permits stopping, then removing, the manifest key and legacy top-level fields; it makes deactivation and any N-1 rejoin impossible; it does not retire the v1 routes or v1 guest mode, which stay an ADR-0006:S6 retirement.
Finalisation permits stopping, then removing, the manifest key and legacy top-level fields; it makes deactivation and any N-1 rejoin impossible; it ends rollback for the activated v2 track only, and does not retire the v1 routes or v1 guest mode or permit removing their support, which stay an ADR-0006:S6 retirement.
### 3.6 Coverage
@@ -194,8 +195,11 @@ Future service work can reuse or challenge the generic concepts in Section 2; th
9. Not every reader of `spinifex-cluster-state` was confirmed (`operator/cli/admin_jsprobe.go:82` opens it).
10. The restore path's successor-first ordering still blocks automatic epoch advance after re-activation (v2 design Section 4.4).
## 7. Open questions for the reviewer
## 7. Review decisions
1. Finalisation: require every cluster to prove v2 (as written), or allow it once the v1 listing is projected from records and leave v1 guests wholly to ADR-0006:S6 retirement?
2. Should a post-activation legacy observation freeze add-on mutations Region-wide (as written) or only alarm?
3. For an unreadable activation record, add a new v2 response reason or reuse `NotActivated` with HTTP 503?
| # | Decision |
|---|---|
| M1 | Finalisation requires current v2 proof only for clusters explicitly activated onto v2. Clusters remaining on v1 are enumerated as legacy, never treated as compatible. Finalisation ends rollback for the activated v2 track; it does not retire v1 or permit removing its support (Section 3.5). |
| M2 | An older relevant binary detected after activation freezes EKS add-on mutations Region-wide. Reads continue; create, update, delete, activation and executor reassignment fail closed until an operator upgrades or removes the incompatible writer or performs an explicit controlled rollback. The freeze covers the add-on contract only, not the platform. |
| M3 | An unreadable, invalid or unavailable activation record returns the retryable v2 reason `ActivationStateUnavailable` (HTTP 503), defined in v2 from the outset. Only an absent record is `NotActivated`, the sole case eligible for the bounded v2-to-v1 fallback (v2 design V1, V11). |
| M4 | The old-writer gap (Section 6 items 2 and 3), the unenrolled-node gap (items 7 and 8) and restore-before-fencing (item 10) are explicit prerequisites for eventual activation, recorded as design debt. They are not package-boundary work and do not extend it. |