Annotations
Annotations the Magos controllers honor on Workspace, Project, and credential Secret resources.
Magos uses annotations for runtime signals that should not be part of the desired-state spec: manual reconcile requests, approval grants, drift-detection cadence overrides, and inter-controller handoffs.
Workspace annotations
| Annotation | Value | Set by | Read by | Effect |
|---|---|---|---|---|
magosproject.io/finalizer | magosproject.io/finalizer | Workspace controller | Workspace controller | Guarantees handleDeletion runs before the object is reaped. |
magosproject.io/execution-allowed | "true" | Project or Rollout controller | Workspace controller | Authorises the Workspace to start a plan or apply Job. |
magosproject.io/approved | runID matching status.awaitingApproval.runID | Operator | Workspace controller | Releases an approval-gated run (Planned from spec.autoApply: false, or PlannedWithViolations from Audit-mode policy violations) into the apply phase. A value that does not match the current run is silently ignored, so a stale approval can never release a newer plan. Cleared by the controller when the run reaches a terminal phase. |
magosproject.io/reconcile-request | any unique string (timestamp recommended) | Operator | Workspace controller | One-shot manual trigger for a fresh plan and apply run. Consumed and cleared by the controller. |
magosproject.io/reconcile-interval | Go duration (e.g. 5m, 1h) | Operator | Workspace controller | Overrides the default 3-minute drift-detection interval for this Workspace. |
magosproject.io/detected-revision | Git commit SHA | RefWatcher controller | Workspace controller | Signals that the RefWatcher resolved spec.source.targetRevision to a new commit. Triggers a fresh run; the workspace controller consumes the annotation after a successful apply. |
magosproject.io/git-poll-interval | Go duration | Operator | RefWatcher controller | Overrides the default 30-second git poll interval for this Workspace. |
magosproject.io/tf-log-level | TRACE, DEBUG, INFO, WARN, ERROR | Operator | Workspace controller | Sets TF_LOG on the plan and apply Pods. Useful for debugging Terraform behavior; remove the annotation to disable logging again. Changes do not trigger a new run on their own. |
Approval contract
The magosproject.io/approved value must equal status.awaitingApproval.runID. Approving a Workspace from the command line is therefore a two-step lookup:
kubectl annotate workspace vpc-prod \
magosproject.io/approved=$(kubectl get workspace vpc-prod -o jsonpath='{.status.awaitingApproval.runID}')
The UI button on the workspace detail page does the equivalent through the API. To abandon the current plan and start a fresh one, set magosproject.io/reconcile-request instead; while gated, that annotation supersedes the approval gate and forces a new run.
Project annotations
The Project controller does not honor any Project-specific annotations today. It reads Workspace annotations (specifically magosproject.io/execution-allowed, see above) as part of its orchestration loop.
Credential Secret labels
Repository credential Secrets are discovered by label, not annotation:
| Label | Value | Required | Description |
|---|---|---|---|
magosproject.io/secret-type | repository | yes | Marks the Secret as a Magos repository credential. The workspace controller's cache is restricted to this label. |
The Secret's data map must include repoURL (matching spec.source.repoURL of the consuming Workspace) and one of:
username+passwordfor HTTPS authentication, orsshPrivateKeyfor SSH authentication.
See Guides → Connecting Git Repositories for full examples.
ValidatingPolicy labels
ValidatingPolicy resources targeted by Magos are selected via Project.spec.validation.policySelector or Workspace.spec.validation.policySelector. A common convention is to label policies by compliance framework, owning team, and enforcement mode so Projects can opt in to the slice that applies to them:
metadata:
labels:
compliance: pci-dss
owner: cloud-security
enforcement: blocking
The label keys are your choice. Pick whatever fits your organisation's conventions; Magos only cares that the selector on a Project or Workspace matches the labels you put on the policies.