How to create your first stack

Last updated: June 29, 2024

Creating a Stack in Spacelift

Unless you're defining a stack programmatically using our Terraform provider, you will be creating one from the root of your Spacelift account.

Note: You need to be an admin to create a stack.

Step 1: Name Your Stack

  1. Click on the Create Stack button.

  2. Give your stack a name and click Continue. The name should be informative and fit within the dropdown menus without cutting off important information. You can also provide an optional description using Markdown for more detailed context and links.

Step 2: Integrate VCS

  1. Choose Your VCS Provider:

    • Select the repository that you gave access to Spacelift in the initial setup.

    • Select the branch you want to attach to your Stack.

  2. Configure Project Root:

    • The project root configuration specifies where inside the repository Spacelift should look for the infrastructure project source code (e.g., creating a stack for a specific folder in the repository). This is particularly useful for Monorepos.

  3. Set Project Globs:

    • The project globs option allows you to specify files and directories outside of the project root that the stack cares about.

Step 3: Configure Backend

  1. Choose Your Backend:

    • Select Terraform as your backend with a supported version. You can leave the default option to let Spacelift manage state for this stack. For other backend options like OpenTofu, Pulumi, CloudFormation, etc., provide the necessary configuration specific to each.

  2. State Management:

    • Decide whether you want Spacelift to manage the state for this stack or use an external state backend. You can import an existing state file if you're migrating an existing Terraform project.

Step 4: Define Stack Behavior

  1. Common Behavior Settings:

    • Set whether the stack is administrative.

    • Choose the worker pool to use.

    • Enable or disable automatic deployments.

    • Set other options like retrying obsolete tests, protecting the stack from deletion, and enabling local previews.

  2. Create Stack Hooks:

    • Define commands that run before and after each phase of the stack lifecycle (Initialization, Planning, Applying, Destroying, Performing, Finally).

Step 5: Attach Cloud Integration

  1. Cloud Integrations:

    • Attach any configured Cloud Integrations. These allow Spacelift to manage resources without long-lived static credentials, using identity management systems from major cloud providers to generate short-lived access tokens.

Step 6: Attach Policies

  1. Policies:

    • Attach policies such as Approval, Plan, Push, and Trigger to control various decision points in the stack lifecycle.

Step 7: Attach Contexts

  1. Contexts:

    • Attach contexts to share environment variables and configuration elements across multiple stacks, ensuring consistent setup.

Step 8: Review Summary

  1. Review Settings:

    • Check all the settings and configurations before finalizing the stack creation.

  2. Create the Stack:

    • Click on Confirm to finalize the creation of your stack.

For more detailed instructions on creating your first Spacelift stack, refer to the Spacelift documentation​​.