Awesome

spacelift-automation

This Terraform child module provides infrastructure automation for projects in Spacelift.

Overview

The spacelift-automation root module is designed to streamline the deployment and management of all Spacelift infrastructure, including itself.

It automates the creation of "child" stacks and all the required accompanying Spacelift resources. For each enabled root module it creates:

1. Spacelift Stack You can think about a stack as a combination of source code, state file and configuration in the form of environment variables and mounted files.
2. Spacelift Stack Destructor Required to destroy the resources of a Stack before deleting it. Destroying this resource will delete the resources in the stack. If this resource needs to be deleted and the resources in the stacks are to be preserved, ensure that the deactivated attribute is set to true.
3. Spacelift AWS Integration Attachment Associates a specific AWS IAM role with a stack to allow it to assume that role. The IAM role typically has permissions to manage specific AWS resources, and Spacelift assumes this role to run the operations required by the stack.
4. Spacelift Initialization Hook Prepares your environment before executing infrastructure code. This custom script copies corresponding Terraform tfvars files into a working directory before either run or task as a spacelift.auto.tfvars file. It's automatically loaded into the OpenTofu/Terraform execution environment.

Usage

Spacelift Automation logic is opinionated and heavily relies on the Git repository structure. This module is configured to track all the files in the provided root module directory and create the stack based on the provided configuration (if any).

Structure requirements are:

• Stack configs are placed in <root_module>/stacks directory.
• Terraform variables are placed in <root_module>/tfvars directory.
• Stack config file and tfvars file must be equal to OpenTofu/Terraform workspace, e.g. dev.yaml and dev.tfvars.
• Common configs are placed in <root_module>/stacks/common.yaml file. This is useful when you know that some values should be shared across all the stacks created for a root module, e.g. all stacks that manage Spacelift Policy must be Administrative. You can override this file name using Terraform variable.

Let's check the example. Input repo structure:

├── root-modules
│   ├── spacelift-aws-role
│   │   ├── stacks
│   │   │   └── dev.yaml
│   │   │   └── stage.yaml
│   │   │   └── common.yaml
│   │   ├── tfvars
│   │   │   └── dev.tfvars
│   │   │   └── stage.tfvars
│   │   ├── variables.tf
│   │   └── versions.tf
│   ├── k8s-cluster
│   │   ├── stacks
│   │   │   └── dev.yaml
│   │   │   └── prod.yaml
│   │   │   └── common.yaml
│   │   ├── tfvars
│   │   │   └── dev.tfvars
│   │   │   └── prod.tfvars
│   │   ├── variables.tf
│   │   ├── main.tf
│   │   └── versions.tf
...

Root module inputs:

aws_integration_id = "ZDPP8SKNVG0G27T4"

# GitHub configuration
github_enterprise = {
  namespace = "masterpointio"
}
repository = "terraform-spacelift-automation"

# Stacks configurations
root_modules_path    = "root-modules"
enabled_root_modules = ["spacelift-aws-role"]

The configuration above creates the following stacks:

• spacelift-aws-role-dev
• spacelift-aws-role-stage

These stacks have the following configuration:

• Stacks track changes in GitHub repo github.com/masterpointio/terraform-spacelift-automation, branch main (the default), and directrory root-modules.
• Common configuration is defined in root-modules/spacelift-aws-role/stacks/common.yaml and applied to both Stacks. However, if there is an override in a Stack config (e.g. root-modules/spacelift-aws-role/stacks/dev.yaml), it takes precedence over common configs.
• Corresponding Terraform variables are generated by an Initialization Hook and placed in the root of each Stack's working directory during each run or task. For example, the content of the file root-modules/spacelift-aws-role/tfvars/dev.tfvars will be copied to working directory of the Stack spacelift-aws-role-dev as file spacelift.auto.tfvars allowing the OpenTofu/Terraform inputs to be automatically loaded.
  • If you would like to disable this functionality, you can set tfvars.enabled in the Stack's YAML file to false.

FAQs

Why are variable values provided separately in tfvars/ and not in the yaml file?

This is to support easy local and outside-spacelift operations. Keeping variable values in a tfvars file per workspace allows you to simply pass that file to the relevant CLI command locally via the -var-file option so that you don't need to provide values individually.

Can I create a Spacelift Stack for Spacelift Automation? (Recommended)

Spacelift Automation can manage itself as a Stack as well, and we recommend this so you can fully automate your Stack management upon merging to your given branch. Follow these next steps to achieve that:

1. Create a new vanilla OpenTofu/Terraform root module that consumes this child module and supplies the necessary configuration for your unique setup. In other words, it's a configuration that uses the default capabilities of either OpenTofu or Terraform without any customization, or third-party tools or plugins.
2. Optionally, create a Terraform workspace that will be used for your Automation configuration, e.g.:

   tofu workspace new masterpoint
   

   Remember that Stack config and tfvars file name must be equal to the workspace, which can be default.
3. Apply the vanilla OpenTofu/Terraform configuration.
4. Move the Automation configs to the <root-modules>/spacelift-automation/stacks directory and push the changes to the tracked repo and branch.
5. From this moment, Spacelift Automation is tracking the changes to its Stack configs and Terraform variables.

Check out an example of such a configuration in the examples/complete.

NOTE to Masterpoint team: We might want to create a small wrapper to automatize this using Taskit. On hold for now.

Requirements

Providers

Modules

Resources

Inputs

Outputs

Contributing

Contributions are welcome and appreciated!

Found an issue or want to request a feature? Open an issue

Want to fix a bug you found or add some functionality? Fork, clone, commit, push, and PR and we'll check it out.

If you have any issues or are waiting a long time for a PR to get merged then feel free to ping us at hello@masterpoint.io.

Built By