Quickstart

This tutorial walks through the smallest complete Magos workflow: create a Project, create a Workspace that points at a Terraform module, and watch the controllers reconcile that workspace to applied state.

You should already have Magos installed in a Kubernetes cluster you can reach with kubectl. The walkthrough deliberately avoids Rollout so you can see the per-Workspace lifecycle without orchestration layered on top.

The examples below assume the default install: release name magos in the magos-system namespace. Adjust the names if you installed under a different release name or namespace.

Step 1: Open the Magos UI

Authentication is enabled by default, with a built-in admin account whose password is auto-generated on first install and stored in the magos-auth Secret. Read it back with:

kubectl -n magos-system get secret magos-auth -o jsonpath='{.data.adminPassword}' | base64 -d

The default install does not create an Ingress, so reach the UI with a port-forward:

kubectl -n magos-system port-forward svc/magos-ui 8080:80

Then open http://localhost:8080 and log in as admin with the password from the previous command. Keep this terminal running while you work through the rest of the tutorial — you can watch the Project and Workspace you are about to create reconcile in the UI as well as via kubectl.

Step 2: Create a Project

A Project is a logical boundary that groups Workspaces and supplies shared inputs. It does not execute anything itself. Create project.yaml:

apiVersion: magosproject.io/v1alpha1
kind: Project
metadata:
  name: data-platform
  namespace: default
spec:
  description: Infrastructure for the data engineering team

Apply it:

kubectl apply -f project.yaml

Confirm the Project reaches Ready:

kubectl get project data-platform

With no Rollout of the same name in the namespace, the Project controller falls back to DefaultParallel mode: any Workspace pointing at this Project will be granted execution permission automatically.

Step 3: Create a Workspace

A Workspace declares where the Terraform module lives, which revision to reconcile, and which Terraform version to run. Create workspace.yaml:

apiVersion: magosproject.io/v1alpha1
kind: Workspace
metadata:
  name: vpc-dev
  namespace: default
  labels:
    env: dev
spec:
  projectRef:
    name: data-platform
  source:
    repoURL: https://github.com/magosproject/demo.git
    targetRevision: main
    path: .
  terraform:
    version: "1.14.8"

What the fields do:

• projectRef.name binds the Workspace to the data-platform Project.
• source describes the Git module: the repository URL, the branch or tag or commit to check out, and the path inside the repository to run terraform against.
• terraform.version selects which Terraform binary the runner pod will install.

Apply it:

kubectl apply -f workspace.yaml

Step 4: Watch the reconciliation

Magos surfaces progress through Kubernetes-native status. Tail the Workspace:

kubectl get workspace vpc-dev -w

You will see the PHASE field progress through the normal lifecycle:

• Pending: waiting on orchestration to grant execution permission.
• Planning: a plan Job has been created and is running terraform plan.
• Planned: the plan succeeded; awaiting apply (or auto-applying, see below).
• Applying: an apply Job has been created and is running terraform apply.
• Applied: the run completed successfully.

By default spec.autoApply is true, so the Workspace transitions from Planned straight into Applying. To require a manual approval between plan and apply, set autoApply: false and watch the Workspace pause at Planned until you approve it.

Step 5: Inspect what ran

Inspect the full status:

kubectl get workspace vpc-dev -o yaml

The useful fields:

• status.observedRevision is the exact Git SHA Magos reconciled. When targetRevision is a branch, this is the resolved commit, not the branch name. That is what you want for auditability.
• status.currentRunID and status.lastRunStartedAt describe the run currently in flight or the most recent terminal run.
• status.conditions includes a standard Ready condition. The CamelCase reason is what you key off in alerts.

The Plan and Apply Jobs themselves are owned by the Workspace:

kubectl get jobs -l magosproject.io/workspace=vpc-dev

When the Workspace is deleted, the Jobs and their PersistentVolumeClaim are garbage-collected with it.

What you built

You declared infrastructure desired state in two Kubernetes resources, and a Kubernetes controller drove that state into reality. There is no CI pipeline, no shared runner, and no script that runs terraform apply outside the cluster.

From here, you have three natural next steps:

• Read about Architecture for a tour of the controller fleet and the isolation model.
• Read about Rollouts, a mechanism to execute Workspaces in a particular order, sequential, parallel, or layered.
• Read about Variable Sets to wire Kubernetes Secrets into Terraform inputs.