Skip to content

Modernize docs #787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Modernize docs #787

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b3d975b
Modernize docs landing copy
marcinwyszynski Apr 21, 2025
ce1c239
Cover OpenTofu, fix broken HCP links
marcinwyszynski Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 49 additions & 27 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,51 +1,73 @@
---
description: Take your Infrastructure as Code to the next level
---
# Hello, Spacelift!

# 👋 Hello, Spacelift!
Spacelift is a specialized CI/CD platform designed to address the collaborative challenges of Infrastructure as Code (IaC). While traditional CI/CD tools excel at stateless applications, infrastructure management presents unique challenges that Spacelift was specifically built to solve.

Spacelift is a sophisticated, continuous integration and deployment (CI/CD) platform for _infrastructure-as-code,_ supporting [Terraform](vendors/terraform/README.md), [OpenTofu](https://opentofu.org/){: rel="nofollow"}, [Terragrunt](vendors/terragrunt/README.md), [Pulumi](vendors/pulumi/README.md), [AWS CloudFormation](vendors/cloudformation/README.md), [AWS CDK](vendors/cloudformation/integrating-with-cdk.md), [Kubernetes](vendors/kubernetes/README.md), [Ansible](vendors/ansible/README.md), and more. It's designed and implemented by long-time DevOps practitioners based on previous experience with large-scale installations - dozens of teams, hundreds of engineers, and tens of thousands of cloud resources.
## Infrastructure as Code: The Multiplayer Challenge

At the same time, Spacelift is super easy to get started with - you can go from zero to fully managing your cloud resources within less than a minute, with no pre-requisites. It integrates nicely with the large players in the field - notably [GitHub](integrations/source-control/github.md) and [AWS](integrations/cloud-providers/aws.md).
Infrastructure as Code projects create a unique set of challenges:

If you're new to Spacelift, please spend some time browsing through the articles in the same order as they appear in the menu - start with the main concepts and follow with integrations. If you're more advanced, you can navigate directly to the article you need, or use the search feature to find a specific piece of information. If you still have questions, feel free to [reach out to us.](https://spacelift.io/contact){: rel="nofollow"}
- **State management**: Unlike application code, infrastructure changes rely on state files that track what's currently deployed
- **Coordination**: Multiple team members working on the same infrastructure can create conflicts
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a super nit, so feel free to leave it as is, but I guess certain tools like CloudFormation don't use state files.

- **Dependencies**: Infrastructure components often depend on one another, creating complex deployment ordering requirements
- **Security**: Infrastructure credentials have significant privileges and require careful handling

## Do I need another CI/CD for my infrastructure?
Spacelift transforms infrastructure management from a risky solo endeavor into a collaborative experience with guardrails.

Yes, we believe it's a good idea. While in an ideal world one CI system would be enough to cover all use cases, we don't live in an ideal world. Regular CI tools can get you started easily, but Terraform has a rather unusual execution model and a highly stateful nature. Also, mind the massive blast radius when things go wrong. We believe Spacelift offers a perfect blend of regular CI's versatility and methodological rigor of a specialized, security-conscious infrastructure tool - enough to give it a shot even if you're currently happy with your infra-as-code CI/CD setup.
## The Graph of Graphs Problem

In the following sections, we'll try to present the main challenges of running Terraform in a general purpose CI system, as well as show how Spacelift addresses those. At the end of the day, it's mostly about two things - collaboration and security.
Most organizations face what we call the "graph of graphs" problem - the challenge of managing not just individual infrastructure stacks, but the complex relationships between them:

### Collaboration
1. **Stack Dependencies**: Infrastructure projects often depend on outputs from other stacks
2. **Deployment Order**: Changes must be applied in the correct sequence to maintain system integrity
3. **Cross-team Collaboration**: Different teams maintain different components with interdependencies

> Wait, aren't CIs built for collaboration?
Spacelift's [Stack Dependencies](concepts/stack/stack-dependencies.md) feature elegantly solves this by allowing you to:

Yes, assuming stateless tools and processes. Running stateless builds and tests is what regular CIs are exceptionally good at. But many of us have noticed that deployments are actually trickier to get right. And that's hardly a surprise. They're more stateful, they may depend on what's already running. Terraform and your infrastructure, in general, is an **extreme example of a stateful system**. It's so stateful that it actually has something called [**state**](https://www.terraform.io/docs/state/index.html){: rel="nofollow"} (see what we just did there?) as one of its core concepts.
- Define explicit relationships between stacks
- Automatically receive outputs from upstream stacks as inputs
- Trigger dependent stacks when upstream changes occur
- Visualize the complete dependency graph of your infrastructure

CIs generally struggle with that. They don't really _understand_ the workflows they run, so they can't for example serialize certain types of jobs. Like `terraform apply`, which introduces actual changes to your infrastructure. As far as your CI system is concerned, running those in parallel is fair game. But what it does to Terraform is nothing short of a disaster - your state is confused and no longer represents any kind of reality. Untangling this mess can take forever.
## Self-service Infrastructure with Blueprints

> But you can add manual approval steps
Blueprints enable controlled self-service for your organization, allowing platform teams to create standardized infrastructure templates while giving application teams the freedom to deploy what they need.

Yes, you can. But the whole point of your CI/CD system is to automate your work. First of all, becoming a human semaphore for a software tool isn't the best use of a highly skilled and motivated professional. Also, over-reliance on humans to oversee software processes will inevitably lead to costly mistakes because we, humans, are infinitely more fallible than well-programmed machines. It's ultimately much cheaper to use the right tool for the job than turn yourself into a part of a tool.
With [Blueprints](concepts/blueprint/README.md), you can:

> But you can do [state locking](https://www.terraform.io/docs/state/locking.html){: rel="nofollow"}!
- **Standardize Infrastructure**: Create templated stack configurations that enforce best practices
- **Enable Self-service**: Allow developers to provision infrastructure without deep IaC expertise
- **Maintain Governance**: Embed security guardrails and compliance controls directly in templates
- **Streamline Onboarding**: Reduce the time needed for teams to provision new environments

Yup, we hear you. In theory, it's a great feature. In practice, it has its limitations. First, it's a massive pain when working as a team. Your CI won't serialize jobs that can write state, and state locking means that all but one of the parallel jobs will simply fail. It's a safe default, that's for sure, but not a great developer experience. And the more people work on your infrastructure, the more frustrating the process will become.
Blueprints transform the platform team from a bottleneck into enablers of developer productivity while maintaining control over infrastructure standards and security.

And that's just _applying_ changes. By default, running `terraform plan` locks the state, too. So you can't really run multiple CI jobs in parallel, even if they're only meant to preview changes, because each of them will attempt to lock the state. Yes, you can work around this by explicitly _not_ locking state in CI jobs that you know won't make any state changes, but at this point, you've already put so much work into creating a pipeline that's fragile at best and requires you to manually synchronize it.
## Key Features

And we haven't even discussed security yet.
Spacelift supports a wide range of IaC tools including:

### Security
- [OpenTofu](https://opentofu.org/) and [Terraform](vendors/terraform/README.md)
- [Ansible](vendors/ansible/README.md)
- [Terragrunt](vendors/terragrunt/README.md)
- [Pulumi](vendors/pulumi/README.md)
- [AWS CloudFormation](vendors/cloudformation/README.md) and [AWS CDK](vendors/cloudformation/integrating-with-cdk.md)
- [Kubernetes](vendors/kubernetes/README.md)

Terraform is used to manage infrastructure, which normally requires credentials. Usually, very powerful credentials. Administrative credentials, sometimes. And these can do _a lot of damage_. The thing with CIs is that you need to provide those credentials statically, and once you do, there's no way you can control how they're used.
With enterprise-grade capabilities:

And that's what makes CIs powerful - after all, they let you run arbitrary code, normally based on some configuration file that you have checked in with your Terraform code. So, what's exactly stopping a prankster from adding `terraform destroy -auto-approve` as an extra CI step? Or printing out those credentials and using them to mine their crypto of choice?
- **Policy as Code**: Define [governance rules](concepts/policy/README.md) for who can do what, when, and how
- **Private Workers**: Run jobs within your own infrastructure for enhanced security
- **RBAC & Spaces**: Organize resources and control access with fine-grained permissions
- **Cloud Integrations**: Native integration with AWS, Azure, and GCP for secure credential management
- **VCS Integrations**: Connect with GitHub, GitLab, Bitbucket, and Azure DevOps

> There are better ways to get fired.
## Getting Started

...you'll say and we hear you. Those jobs _are_ audited after all. No, if we were disgruntled employees we'd never do something as stupid. We'd get an SSH session and leak those precious credentials this way. Since it's unlikely you rotate them every day, we'd take our sweet time before using them for our nefarious purposes. Which wouldn't be possible with Spacelift BTW, which generates [one-off temporary credentials](integrations/cloud-providers/aws.md) for major cloud providers.
New to Spacelift? We recommend exploring our documentation in this order:

> But nobody does that!
1. [Core Concepts](concepts/stack/README.md) - Understand stacks, runs, and policies
2. [Stack Dependencies](concepts/stack/stack-dependencies.md) - Learn how to manage inter-project dependencies
3. [Blueprints](concepts/blueprint/README.md) - Discover how to enable self-service infrastructure
4. [Integrations](integrations/source-control/README.md) - Connect Spacelift to your existing tools
5. [Workers](concepts/worker-pools/README.md) - Execute jobs securely in your environment

Yes, you don't hear many of those stories. Most mistakes happen to well-meaning people. But in the world of infrastructure, even the tiniest of mistakes can cause major outages - like that typo we once made in our DNS config. That's why Spacelift adds an extra layer of [policy](concepts/policy/README.md) that allows you to control - separately from your infrastructure project! - [what code can be executed](concepts/policy/run-initialization-policy.md), [what changes can be made](concepts/policy/terraform-plan-policy.md), [when and by whom](concepts/policy/stack-access-policy.md). This isn't only useful to protect yourself from the baddies, but allows you to implement an [automated code review pipeline](concepts/policy/terraform-plan-policy.md#automated-code-review).
If you're ready to try Spacelift, [sign up for a free trial](https://spacelift.io/free-trial) or [contact our team](https://spacelift.io/contact) for a personalized demo.
18 changes: 9 additions & 9 deletions docs/concepts/blueprint/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
This feature is only available on the Business plan and above. Please check out our [pricing page](https://spacelift.io/pricing){: rel="nofollow"} for more information.
{% endif %}

There are multiple ways to create [stacks](../stack/README.md) in Spacelift. Our recommended way is to use [our Terraform provider](../../vendors/terraform/terraform-provider.md) and programmatically create stacks using an [administrative](../stack/stack-settings.md#administrative) stack.
There are multiple ways to create [stacks](../stack/README.md) in Spacelift. Our recommended way is to use [our OpenTofu/Terraform provider](../../vendors/terraform/terraform-provider.md) and programmatically create stacks using an [administrative](../stack/stack-settings.md#administrative) stack.

However, some users might not be comfortable using Terraform code to create stacks. This is where Blueprints come in handy.
However, some users might not be comfortable using OpenTofu/Terraform code to create stacks. This is where Blueprints come in handy.

## What is a Blueprint?

Expand Down Expand Up @@ -122,14 +122,14 @@ inputs:
type: secret
# secret means the input will be masked in the UI
- id: tf_version
name: Terraform version of the stack
name: OpenTofu/Terraform version of the stack
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you can just change all the OpenTofu/Terraform updates in this example to OpenTofu. The reason is that this Blueprint example is explicitly creating an OpenTofu stack and not Terraform, so OpenTofu/Terraform is actually misleading here.

type: select
options:
- "1.3.0"
- "1.4.6"
- "1.5.0"
- id: manage_state
name: Should Spacelift manage the state of Terraform
name: Should Spacelift manage the state of OpenTofu/Terraform
default: true
type: boolean
- id: destroy_task_epoch
Expand All @@ -149,7 +149,7 @@ stack:
is_disabled: ${{ inputs.environment != 'prod' }}
labels:
- Environment/${{ inputs.environment }}
- Vendor/Terraform
- Vendor/OpenTofu
- Owner/${{ context.user.login }}
- Blueprint/${{ context.blueprint.name }}
- Space/${{ context.blueprint.space }}
Expand Down Expand Up @@ -380,9 +380,9 @@ stack:
name: 'yes-my-stack'
```

### Interaction with Terraform `templatefile`
### Interaction with OpenTofu/Terraform `templatefile`

When using the Terraform [`templatefile`](https://developer.hashicorp.com/terraform/language/functions/templatefile){: rel="nofollow"} function to generate a Blueprint template body, you can run into issues because the Blueprint template engine and `templatefile` both use `$` as template delimiters. This can result in error messages like the following:
When using the OpenTofu/Terraform [`templatefile`](https://opentofu.org/docs/language/functions/templatefile/){: rel="nofollow"} function to generate a Blueprint template body, you can run into issues because the Blueprint template engine and `templatefile` both use `$` as template delimiters. This can result in error messages like the following:

{% raw %}

Expand Down Expand Up @@ -654,7 +654,7 @@ Note that this is not a working example as it is missing a few things (`inputs`

## Stack Configuration

Stacks can be configured in a similar fashion as if you were using the Terraform provider or the UI. Most of the options are straightforward; however, some require deeper knowledge and are covered in the sections below. For a full list of available options, please refer to the [Schema](#schema) section below.
Stacks can be configured in a similar fashion as if you were using the OpenTofu/Terraform provider or the UI. Most of the options are straightforward; however, some require deeper knowledge and are covered in the sections below. For a full list of available options, please refer to the [Schema](#schema) section below.

### Dependencies

Expand Down Expand Up @@ -873,7 +873,7 @@ The up-to-date schema of a Blueprint is available through a [GraphQL query](../.
```

!!! tip
Remember that there are multiple ways to interact with Spacelift. You can use the [GraphQL API](../../integrations/api.md), the [CLI](https://github.com/spacelift-io/spacectl){: rel="nofollow"}, the [Terraform Provider](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs){: rel="nofollow"}, or the web UI itself if you're feeling fancy.
Remember that there are multiple ways to interact with Spacelift. You can use the [GraphQL API](../../integrations/api.md), the [CLI](https://github.com/spacelift-io/spacectl){: rel="nofollow"}, the [OpenTofu/Terraform Provider](https://search.opentofu.org/provider/spacelift-io/spacelift/latest){: rel="nofollow"}, or the web UI itself if you're feeling fancy.

For simplicity, here is the current schema, but it might change in the future:

Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/configuration/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ While Spacelift stacks typically link source code with infrastructure resources,
This section focuses on three aspects of configuration, each of which warrants its own help article:

- [Direct stack environment](environment.md), that is environment variables and mounted files;
- [Contexts](context.md), that is environments (often partially defined) shared between [stacks](../stack/README.md) and/or [Terraform modules](../../vendors/terraform/module-registry.md);
- [Contexts](context.md), that is environments (often partially defined) shared between [stacks](../stack/README.md) and/or [OpenTofu/Terraform modules](../../vendors/terraform/module-registry.md);
- [Runtime configuration](runtime-configuration/README.md) as defined in the `.spacelift/config.yml` file;

## A general note on precedence
Expand Down
Loading
Loading