Context

Note

For simplicity, we'll use the term projects to refer to both stacks and modules.

Context is a bundle of configuration elements (environment variables and mounted files) independent of any stack that can be managed separately and attached to as many or as few stacks as necessary. Contexts are only directly accessible to administrators from the Share code & config > Contexts tab:

The list of contexts merely shows the name and description of the context. Clicking on the name allows you to edit it.

Context management

You can create, edit, attach, detach and delete contexts. We will show you how to do so through the Spacelift UI, but you can also manage contexts programmatically using our Terraform provider.

Creating a context

As an account administrator you can create a new context by navigating to Share code & config > Contexts and clicking Add context.

This takes you to a simple form where the only inputs are name and description:

• Name: What will display on the Contexts tab and on dropdown menus to attach the context. This should be concise but informative.
• Description (optional): A Markdown-supported free-form place to describe the context in more depth. This will only display on the Contexts tab.

Warning

Based on the original context name, Spacelift generates an immutable slug that serves as a unique identifier of the context. If the name and the slug diverge significantly, things may become confusing.

Although you can change the context name at any point, we strongly discourage all non-trivial changes.

Editing a context

You can edit the context from its dedicated view by clicking Edit:

This switches the context into editing mode where you can change the name and description. You can also manage configuration elements the same way you'd do for the stack environment, without overrides and computed values:

Attaching and detaching contexts

Attaching and detaching contexts actually happens from the stack management view. To attach a context, select the Contexts tab. This should show you a dropdown with all the contexts available for attaching, and a slider to set the priority of the attachment:

Info

A context can only be attached once to a given stack, so if it's already attached, it will not be visible in the dropdown menu.

For example, if you attach a context with priority 0:

Now this attached context will also contribute to the stack environment...

...and be visible on the list of attached contexts:

You can remove a context from the stack by clicking Detach.

On priority

Priority is a property of the context-stack relationship. All the contexts attached to a stack are sorted by priority (lowest first), though values don't need to be unique. This ordering establishes precedence rules between contexts should there be a conflict and multiple contexts define the same value.

You might notice that there is no priority picker for auto-attached contexts. The highest priority for all configuration elements (environment variables, mounted files, and hooks) are:

1. At the stack level.
2. Explicitly attached contexts (based on set priorities).
3. Auto-attached alphabetically for environment variables, mounted files, and after phase hooks (before phase hooks are attached reverse alphabetically).

Deleting a context

Click Delete in the context view to remove an unneeded context:

Warning

Deleting a context will also automatically detach it from all the projects it was attached to. Make sure you only delete contexts that are no longer useful. For security purposes we do not store historical data and remove the deleted data from all of our data storage systems.

Use cases

We can see two main use cases for contexts, depending on whether the context data is supplied externally or produced by Spacelift.

Shared configuration elements

You can use contexts to group configuration elements (external to Spacelift) that are meant to be shared between multiple stacks. For example, you could use contexts for cloud provider configuration, either for OpenTofu/Terraform or Pulumi. Instead of attaching the same values (some of which could be secret) to individual stacks, contexts allow you to define those once and then attach them to the stacks that need them.

A variation of this use case is collections of OpenTofu/Terraform input variables (for example, variables related to a particular system environment such as staging or production) that may be shared by multiple stacks. The collection of variables can specify:

• Environment name.
• DNS domain name or a reference to it (e.g. zone ID).
• Tags.
• References to provider accounts.

Instead of setting these on individual stacks, you can group them into a context and attach the context to eligible stacks.

Remote state alternative (Terraform-specific)

You can use contexts to group data that are produced by one or more Spacelift stacks, as an alternative to the Terraform remote state. In this use case, contexts can serve as outputs for stacks that can be consumed by (attached to) other stacks. So, instead of exposing the entire state, a stack can use the Spacelift Terraform provider to define values on a context, either managed by the same stack or externally. Managing a context externally can be particularly useful when multiple stacks contribute to a particular context.

Info

To use the Terraform provider to define contexts or its configuration elements, the stack needs the right role attachments.

As an example of this use case, imagine an organization where shared infrastructure (VPC, DNS, compute cluster, etc.) is centrally managed by a DevOps team, which exposes it as a service to be used by individual product development teams. To be able to use the shared infrastructure, each team needs to address multiple entities generated by the central infra repo. In vanilla Terraform you would likely use the remote state provider, but that could expose secrets and settings the DevOps team would rather keep it to themselves. Using a context, however, allows the team to decide (and document) what constitutes their "external API".

The proposed setup for this use case would involve two stacks with roles: one to manage all the stacks, and the other for the DevOps team.

1. The management stack would programmatically define the DevOps one, and possibly also its context.
2. The DevOps team would receive the context ID as an input variable, and use it to expose outputs as spacelift_environment_variable and/or spacelift_mounted_file resources.
3. The management stack could then attach the context populated by the DevOps stack to other stacks it defines and manages.

Extending Terraform CLI Configuration (Terraform-specific)

For some of our Terraform users, a convenient way to configure the Terraform CLI behavior is through customizing the ~/.terraformrc file.

Spacelift allows you to extend terraform CLI configuration through the use of mounted files.