Set up and configure»
Steps 1–4 of the migration walkthrough: scaffold the workspace, pick a source, set its credentials, and validate the configuration before anything runs.
Before you start — what you need»
liftoff moves an estate onto Spacelift, so it needs credentials for both ends and an account ready to receive the work. Have these in place before step 1:
- A Spacelift account, and an API key with root-space admin access. The account is read from the very first step, and a repository and admin stack are created later, so a narrowly scoped key fails partway through.
- An account on the system you are migrating from, with credentials that can read everything in scope.
Each source declares exactly which keys it needs;
liftoff sourceslists them and step 4 proves them. - A VCS integration in Spacelift that can reach the repositories your source uses. Generated stacks name the integration they bind to, so one has to exist for every provider in the estate.
- At least one worker — a private worker pool with a worker attached, or the public pool. Applying the generated code is itself a Spacelift run, so an account with no worker cannot finish a migration.
- Network access to both APIs from wherever you run liftoff.
- A decision about where the generated code will live: the Spacelift-managed repository, which needs no setup, or your own git provider.
liftoff checks the ones it can rather than leaving you to find out later.
liftoff configure validate proves both key pairs, and liftoff audit reports a repository it cannot bind to an integration, one whose integration is not connected to the account it lives under, an integration Spacelift cannot reach at all, or an account with nothing to run on — all before you generate anything.
Before you start — install liftoff»
First, know which version you're meant to run.
Most operators want the current stable release, installed just below.
But if you were pointed at a release candidate — anything ending -rc, or a specific pre-release version — stop here and jump to Release candidates.
The stable brew install below and the RC cask both provide the same liftoff command, so running the stable one now would replace an RC you'd already installed, quietly and with no warning from Homebrew.
Confirm the target first; install second.
If stable is what you want, install it:
1 | |
Without Homebrew:
1 | |
On Windows, download the zip from the releases page and put liftoff.exe on your PATH.
Either way you get one binary and nothing else — no runtime, no container, no services. Check it answers and prints the version you meant to install before going further — if you were sent to a release candidate, this is where you catch having landed on stable instead:
1 | |
To upgrade later, brew upgrade liftoff, or re-run the install script.
Release candidates»
brew install spacelift-solutions/tap/liftoff is always the current stable release — a candidate can never arrive there by surprise.
Candidates are a separate cask you have to ask for by name:
1 | |
Both provide the same liftoff command, so Homebrew will not let you have both at once.
Switch back with:
1 | |
Installing a specific version»
Homebrew carries the newest build of each line and nothing older, so an exact version comes from the install script:
1 | |
The setting goes on sh, not in front of curl — in front of curl it reaches the download and not the script that reads it.
Pinning is what you want in CI, where "whatever is newest" is not a build you can reproduce. The tags are on the releases page.
INSTALL_DIR puts the binary somewhere other than /usr/local/bin — reach for it when that directory needs root:
1 | |
Step 1 — initialize the workspace»
1 | |
Creates ./.liftoff/ in the current directory with an empty config.yaml and the SQLite store.
1 2 3 4 5 6 7 8 | |
Running init again on an existing workspace reports Config Created no and changes nothing, so it is safe to repeat.
On a workspace created by an older binary it migrates the store schema forward.
The only decision here is where to stand.
init creates ./.liftoff under the current directory, one directory per migration.
Later commands walk up from $PWD to find that folder, so you can run them from a subdirectory without re-passing the path.
--config-dir or LIFTOFF_CONFIG_DIR still override the walk when you need a workspace somewhere else.
One warning, and it grows over the migration: ./.liftoff/ becomes the most sensitive thing on this machine.
config.yaml holds your source API token after step 3 (unless you kept it in an env reference), and the store — liftoff.db, a plain, unencrypted SQLite file — holds everything discover pulls, variable values included, and later the captured secret values and full Terraform state blobs the finalize steps push.
Treat the directory accordingly.
If you are running inside a git repository, ignore the workspace now:
1 | |
That .gitignore line is necessary but not the whole story — it keeps the workspace out of git, not off backups, syncs, or a shared machine, and it does nothing once the migration is done and the directory should simply be gone.
What the directory contains and how to dispose of it safely is covered at the end of the walkthrough, in finalize.
Next up, liftoff sources to see what you can migrate from.
Step 2 — pick a source»
1 | |
Lists every source this binary can migrate from, with the settings each one takes. Read-only; run it as often as you like.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 | |
What to take from this screen:
- The id in the title is what you pass to
configure --source. Here that isterraform, which covers both Terraform Cloud and self-hosted Terraform Enterprise. - Config Keys is your settings checklist.
Only the checked
Requiredkeys must be set (api_tokenhere). Everything else has aDefaultyou can live with, or aWhen Unsettelling you what not setting it means. On Terraform Enterprise you will also needapi_endpointpointed at your install. - Repair Keys are not for discover.
They feed
liftoff audit --repairin step 7 and only come into play when an audit has findings to fix. You can set them now with everything else, and change them later by re-running configure. - Mutations preview a later, opt-in step.
Discover never changes the source; the one step that does —
liftoff mutate— is opt-in and per run, so you pass--allow-mutation <name>on everymutatethat should use it, which is why mutations are not config keys. The two secret mutations are the ones worth planning for: without them, sensitive values come over empty and you re-enter them in Spacelift afterwards.secretscovers values set on a workspace.context-secretscovers values set on a variable set, and is separate because it makes a larger change — it creates a throwaway workspace to read them through, then deletes it. Both revert the source when done. Nothing to do now — the mutate step shows the flags.
The decision at this step is which source you are migrating from and, if it is self-hosted, what its API endpoint is. Note the id and move on.
Step 3 — configure the source»
1 | |
Records the source and its settings in config.yaml.
Values can reference environment variables: single-quote the reference so your shell doesn't expand it, and config.yaml stores the literal ${TFC_TOKEN} — the value is resolved when a command runs, so the token itself never has to be written to disk.
A reference that doesn't resolve is an error, not an empty string.
Pasting the raw token works too; it just lives in config.yaml (and your shell history) instead.
--set repeats, and configure is incremental — later runs merge into what's already saved:
1 | |
If a required setting is still missing, configure saves your progress and errors with exactly what's left — the specimen in when something goes wrong is this very case. With the token set:
1 2 3 4 5 6 7 | |
Values are never echoed back, only key names.
Step 4 — validate before running anything»
1 | |
The verdict on your configuration: what every key resolves to right now and what the run will mean, and — once the config is complete — it authenticates both key pairs and names who each resolved to. Read-only (it never writes), so run it as often as you like. This is the moment to catch a Spacelift endpoint pointed at the wrong account.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | |
Where liftoff sources showed templates, this shows results: every Effect is rendered with the value the run will actually use.
Two more sections appear only when something needs attention: Missing Required (required keys with no value) and Unknown Keys (settings in config.yaml the source doesn't recognize — usually a typo'd --set).
Read the Effect column top to bottom and check it against your intent.
Worth deciding now:
- Rate and concurrency (
requests_per_second,workspace_concurrency) — the defaults are safe for Terraform Cloud; a self-hosted TFE may want them lowered. - The repair keys (
module_workflow_tool,default_branch,custom_runner_image,worker_pool_id) — whatliftoff audit --repairwrites in step 6. They change nothing until an audit has findings to fix, and you can re-run configure to adjust them whenever.custom_runner_imagematters if any workspace runs a Terraform version Spacelift's runner doesn't include: those stacks migrate onto the CUSTOM workflow tool and run the tool from that image, tagged with each stack's version (generate). The image has to carry the tool. Spacelift downloads nothing for a CUSTOM stack — it runs the commands in the mountedworkflow.yml, so a missing binary surfaces assh: terraform: not foundand the run stops inINITIALIZING. Spacelift's ownrunner-terraformimage does not satisfy this; build on it and install the versions you need. Give it no tag. An untagged image is what lets the repair tag each stack with the version its workspace ran, so every stack keeps its own. If you tag it yourself —…/runner-terraform:latest, say — that exact image is written to every CUSTOM stack, so whatever tool version it carries is the one they all run.liftoff auditprints the reference it would write per stack, so you can check before repairing.worker_pool_idmatters when your Spacelift account has private worker pools: generated stacks omit the attribute (and land on the public pool — an audit error instead when the account has none) unless you set this to a pool id discover recorded, thenaudit --repairwrites it. - The mutations — opt-ins for the later
mutatestep,secretshere being one example. A mutation is never remembered: you pass--allow-mutation <name>on everymutatethat should use it, which is why they aren't config keys. Decide whether sensitive variable values should be captured (the mutate step shows the flag) or re-entered in Spacelift after the migration.
Building the runner image for CUSTOM stacks»
If any workspace runs a Terraform newer than Spacelift bundles, its stack migrates onto the CUSTOM workflow tool and runs the binary your image carries. Spacelift downloads nothing for it — you hold the licence for those versions, so you build the image.
You need one tag per version in the batch.
liftoff audit names the version in each finding, so the audit output is the list:
1 2 3 | |
A Dockerfile that adds one version on top of Spacelift's runner image.
Build on that image rather than a bare Alpine or hashicorp/terraform: the worker calls ps to watch the container, and the image has to carry the spacelift user (UID 1983) that jobs run as.
The fetch stage keeps the build from depending on which archive tools the base image ships:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
Build and push one tag per version, tagging each with the version itself — that is what the repair writes:
1 2 3 4 | |
Where you push matters.
On Spacelift's public worker pool the image must be public, and only these registries are accepted: public.ecr.aws, dkr.ecr.<region>.amazonaws.com, docker.io, registry.hub.docker.com, ghcr.io, gcr.io, docker.pkg.dev, azurecr.io, quay.io, registry.gitlab.com.
A private image requires a private worker pool: the public pool caches images across accounts, so it only ever pulls public ones.
liftoff audit checks this rather than leaving you to find out from a run that never starts: a stack heading for the public pool with an image from anywhere else is an error, runner-image-not-pullable (audit).
Then point the setting at the untagged name and repair:
1 2 | |
Each CUSTOM stack gets $REGISTRY/liftoff-runner:<its own version>.
Build for linux/amd64 — that is what Spacelift workers run.
A missing or non-executable binary shows up as sh: terraform: not found, with the run stopping in INITIALIZING.
When the effects read the way you intend and the token authenticated, you are ready for discover.