API Reference
Auto-generated reference for every Magos custom resource. Do not edit by hand; regenerate with 'make generate-api-reference' in the website repo.
API Reference
Packages
magosproject.io/v1alpha1
Package v1alpha1 contains API Schema definitions for the v1alpha1 API group.
Resource Types
Project
Project is the Schema for the projects API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | magosproject.io/v1alpha1 | ||
kind string | Project | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec ProjectSpec | spec defines the desired state of Project | Required: {} |
ProjectSpec
ProjectSpec defines the desired state of Project
| Field | Description | Default | Validation |
|---|---|---|---|
description string | Description provides a human-readable description of the project's purpose. | Optional: {} | |
variableSetRef VariableSetReference array | VariableSetRef references one or more VariableSets to be applied to all Workspaces within this Project. | Optional: {} | |
validation ValidationSpec | Validation is the default plan-time validation configuration applied to Workspaces in this Project that do not define their own. A Workspace with an explicit Validation fully overrides this default. | Optional: {} |
ValidationSpec
ValidationSpec configures how Terraform plans are evaluated against Kyverno ValidatingPolicy resources before apply. The same shape is used on both Project (where it defines the default for member Workspaces) and Workspace (where it overrides the Project default).
| Field | Description | Default | Validation |
|---|---|---|---|
policySelector LabelSelector | PolicySelector selects Kyverno ValidatingPolicy resources (policies.kyverno.io) by label. When nil, no policy validation is performed. An empty selector ({}) matches every ValidatingPolicy in the cluster. On a Project this acts as the default for any Workspace that does not set its own Validation; on a Workspace this fully overrides the Project default. | Optional: {} |
VariableSetReference
VariableSetReference references a VariableSet resource
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the VariableSet. | MinLength: 1 Required: {} |
Workspace
Workspace is the Schema for the workspaces API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | magosproject.io/v1alpha1 | ||
kind string | Workspace | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec WorkspaceSpec | spec defines the desired state of Workspace | Required: {} |
WorkspaceSpec
WorkspaceSpec defines the desired state of Workspace
| Field | Description | Default | Validation |
|---|---|---|---|
projectRef ProjectReference | ProjectRef is a reference to the project this workspace belongs to | Required: {} | |
autoApply boolean | AutoApply dictates whether the workspace should automatically apply after a successful plan | true | Optional: {} |
annotations object (keys:string, values:string) | Annotations to propagate to both plan and apply Job pod templates. Per-phase annotations in spec.plan or spec.apply take precedence on conflict. | Optional: {} | |
plan JobOverrides | Plan holds overrides applied only to plan Jobs. | Optional: {} | |
apply JobOverrides | Apply holds overrides applied only to apply Jobs. | Optional: {} | |
source SourceSpec | Source defines the Git repository configuration | Required: {} | |
terraform TerraformSpec | Terraform defines the Terraform or OpenTofu configuration | Required: {} | |
validation ValidationSpec | Validation configures plan-time policy validation for this Workspace. When nil, the parent Project's Validation applies if set. When non-nil, this fully overrides the Project default rather than merging with it. | Optional: {} | |
variableSetRef VariableSetReference array | VariableSetRef references one or more VariableSets that contribute Terraform input variables to this Workspace. They layer on top of the VariableSets attached to the parent Project: Project sets are applied first in declaration order, then Workspace sets, and within that combined order a later set's variable shadows an earlier set's variable of the same name. Values resolved from VariableSets are exposed to terraform as TF_VAR_<name> environment variables on the plan and apply pods, which means they take precedence over any matching variable declared in spec.terraform.tfvarsPath (env beats .tfvars in Terraform's precedence rules). | Optional: {} | |
serviceAccountName string | ServiceAccountName is the ServiceAccount that plan and apply Job pods run under. The ServiceAccount must exist in the same namespace as the Workspace. Defaults to magos-job, which the Helm chart creates with get;list;watch on validatingpolicies.policies.kyverno.io so the job can fetch ValidatingPolicies at runtime. Override this to run pods under a different identity, for example to bind a GKE Workload Identity or AWS IRSA annotation; the replacement must carry the same RBAC. | magos-job | Optional: {} |
ProjectReference
ProjectReference references a Project resource
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the Project. | MinLength: 1 Required: {} |
JobOverrides
JobOverrides holds per-phase configuration that is merged on top of the shared spec-level settings. Fields set here take precedence over the corresponding shared field.
| Field | Description | Default | Validation |
|---|---|---|---|
annotations object (keys:string, values:string) | Annotations to add to the Job's pod template. Merged on top of spec.annotations; values here win on conflict. | Optional: {} | |
timeoutSeconds integer | TimeoutSeconds sets the activeDeadlineSeconds on the Kubernetes Job. If the Job does not finish within this duration, Kubernetes marks it as Failed, preventing a Workspace from being stuck in Planning or Applying indefinitely. When unset, DefaultJobTimeoutSeconds (86400) is used. | Optional: {} |
SourceSpec
SourceSpec defines the Git repository configuration
| Field | Description | Default | Validation |
|---|---|---|---|
repoURL string | RepoURL is the URL of the Git repository to clone | Required: {} | |
targetRevision string | TargetRevision defines the commit, tag, or branch to checkout | Required: {} | |
path string | Path is the directory path within the Git repository | . | Optional: {} |
TerraformSpec
TerraformSpec defines the Terraform or OpenTofu configuration
| Field | Description | Default | Validation |
|---|---|---|---|
version string | Version is the Terraform or OpenTofu version to use | Required: {} | |
tfvarsPath string | TfvarsPath is the path to the tfvars file within the repository | Optional: {} |
Rollout
Rollout is the Schema for the rollouts API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | magosproject.io/v1alpha1 | ||
kind string | Rollout | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec RolloutSpec | spec defines the desired state of Rollout | Required: {} |
RolloutSpec
RolloutSpec defines the desired state of Rollout
| Field | Description | Default | Validation |
|---|---|---|---|
projectRef string | ProjectRef is a reference to the project this rollout orchestrates | Required: {} | |
strategy RolloutStrategy | Strategy defines the rollout execution plan | Required: {} |
RolloutStrategy
RolloutStrategy defines how the rollout should proceed
| Field | Description | Default | Validation |
|---|---|---|---|
steps RolloutStep array | Steps defines the sequential stages of the rollout | Required: {} |
RolloutStep
RolloutStep defines a single step in a rollout strategy
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the step | Required: {} | |
selector LabelSelector | Selector to match workspaces for this step | Required: {} |
VariableSet
VariableSet is the Schema for the variablesets API
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string | magosproject.io/v1alpha1 | ||
kind string | VariableSet | ||
metadata ObjectMeta | Refer to Kubernetes API documentation for fields of metadata. | Optional: {} | |
spec VariableSetSpec | spec defines the desired state of VariableSet | Required: {} |
VariableSetSpec
VariableSetSpec defines the desired state of VariableSet.
A VariableSet is a reusable bundle of Terraform input variables that is composed onto Workspaces by reference. Values can be literal strings or drawn from a Kubernetes Secret or ConfigMap in the same namespace. The workspace controller is what actually injects the resolved values into the plan and apply Job pods as TF_VAR_<name> environment variables; this controller is only responsible for validating references and surfacing their status.
| Field | Description | Default | Validation |
|---|---|---|---|
description string | Description is a human-readable purpose for this VariableSet. Optional and not consumed by any controller; it exists so that operators can document intent in the same place as the data. | Optional: {} | |
variables Variable array | Variables is the ordered list of Terraform variables this set contributes. Each entry becomes TF_VAR_<name> on the plan and apply pods of any Workspace that references this set. Order is preserved on the wire so that consumers can rely on a stable iteration order when computing hashes, but ordering does not change semantics within a single set: duplicate names are rejected. | MinItems: 1 |
Variable
Variable is a single Terraform input variable definition. Exactly one of Value or ValueFrom must be set; the CEL rule on the type enforces that so the API server rejects misconfigured objects before they ever reach the controller.
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name is the Terraform variable name. The workspace controller exposes it on the pod as TF_VAR_<name>, so it must be a valid Terraform identifier: letters, digits, and underscores, not starting with a digit. | MaxLength: 253 MinLength: 1 Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ Required: {} | |
value string | Value is an inline literal. Use this only for non-sensitive data because the value is stored verbatim in the CR and is visible to anyone with read access to VariableSets in the namespace. For sensitive material use ValueFrom.SecretKeyRef instead: the controller never writes the resolved value to the CR, status, or logs, and the kubelet performs the actual read from the source Secret at pod start. | Optional: {} | |
valueFrom VariableSource | ValueFrom sources the variable's value from another resource in the same namespace. Mutually exclusive with Value. | Optional: {} |
VariableSource
VariableSource describes where a variable's value should be read from. Exactly one of SecretKeyRef or ConfigMapKeyRef must be set.
| Field | Description | Default | Validation |
|---|---|---|---|
secretKeyRef KeySelector | SecretKeyRef reads the value from a key inside a Kubernetes Secret in the same namespace as the VariableSet. The kubelet resolves the value at pod startup time when the workspace controller wires it into the plan or apply Job, so the controller process never holds the secret bytes in memory. | Optional: {} | |
configMapKeyRef KeySelector | ConfigMapKeyRef reads the value from a key inside a ConfigMap in the same namespace. Useful for non-sensitive shared settings (region, account IDs, feature flags) that you still want versioned alongside your application configuration. | Optional: {} |
KeySelector
KeySelector references a specific key inside a Secret or ConfigMap.
| Field | Description | Default | Validation |
|---|---|---|---|
name string | Name of the Secret or ConfigMap. | MinLength: 1 Required: {} | |
key string | Key inside the resource's data map. Must be present on the source object unless Optional is true. | MinLength: 1 Required: {} | |
optional boolean | Optional, when true, treats a missing resource or missing key as a no-op rather than an error. The variable is omitted from the pod environment, and the missing reference is not reported in VariableSetStatus.UnresolvedReferences. Useful for variables that are only present in some environments (e.g. an optional staging-only override). | Optional: {} |