diff --git a/docs/assets/screenshots/Create_Stack_Ansible.png b/docs/assets/screenshots/Create_Stack_Ansible.png deleted file mode 100644 index 41c2805b1..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Ansible.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_CF.png b/docs/assets/screenshots/Create_Stack_CF.png deleted file mode 100644 index 5813e50cb..000000000 Binary files a/docs/assets/screenshots/Create_Stack_CF.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Cloud_Integrations.png b/docs/assets/screenshots/Create_Stack_Cloud_Integrations.png deleted file mode 100644 index 4909c0f97..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Cloud_Integrations.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Define_Behavior.png b/docs/assets/screenshots/Create_Stack_Define_Behavior.png deleted file mode 100644 index 86c7f994a..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Define_Behavior.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Hooks.png b/docs/assets/screenshots/Create_Stack_Hooks.png deleted file mode 100644 index 046ef5111..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Hooks.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_K8s.png b/docs/assets/screenshots/Create_Stack_K8s.png deleted file mode 100644 index 09835c0cc..000000000 Binary files a/docs/assets/screenshots/Create_Stack_K8s.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Labels.png b/docs/assets/screenshots/Create_Stack_Labels.png deleted file mode 100644 index 202f5ea57..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Labels.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_OpenTofu.png b/docs/assets/screenshots/Create_Stack_OpenTofu.png deleted file mode 100644 index 29c72d1e5..000000000 Binary files a/docs/assets/screenshots/Create_Stack_OpenTofu.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Overview.png b/docs/assets/screenshots/Create_Stack_Overview.png deleted file mode 100644 index d1e7a5737..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Overview.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Policies.png b/docs/assets/screenshots/Create_Stack_Policies.png deleted file mode 100644 index 891c85420..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Policies.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Pulumi.png b/docs/assets/screenshots/Create_Stack_Pulumi.png deleted file mode 100644 index 57e9c95b3..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Pulumi.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Stack_Details.png b/docs/assets/screenshots/Create_Stack_Stack_Details.png deleted file mode 100644 index 4bbbdf402..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Stack_Details.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Terraform.png b/docs/assets/screenshots/Create_Stack_Terraform.png deleted file mode 100644 index e1d94b05f..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Terraform.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_Terragrunt.png b/docs/assets/screenshots/Create_Stack_Terragrunt.png deleted file mode 100644 index 7ed87d539..000000000 Binary files a/docs/assets/screenshots/Create_Stack_Terragrunt.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_Stack_VCS.png b/docs/assets/screenshots/Create_Stack_VCS.png deleted file mode 100644 index de043bb9d..000000000 Binary files a/docs/assets/screenshots/Create_Stack_VCS.png and /dev/null differ diff --git a/docs/assets/screenshots/Create_stack_contexts.png b/docs/assets/screenshots/Create_stack_contexts.png deleted file mode 100644 index 3524ad788..000000000 Binary files a/docs/assets/screenshots/Create_stack_contexts.png and /dev/null differ diff --git a/docs/assets/screenshots/Stack_Created.png b/docs/assets/screenshots/Stack_Created.png deleted file mode 100644 index c487b7879..000000000 Binary files a/docs/assets/screenshots/Stack_Created.png and /dev/null differ diff --git a/docs/assets/screenshots/create_stack_summary_v2.png b/docs/assets/screenshots/create_stack_summary_v2.png deleted file mode 100644 index e7888b6f0..000000000 Binary files a/docs/assets/screenshots/create_stack_summary_v2.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-1.png b/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-1.png deleted file mode 100644 index 44ceb23f4..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-1.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-2.png b/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-2.png deleted file mode 100644 index 0aa30ffa6..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-2.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-3.png b/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-3.png deleted file mode 100644 index fe006f0e7..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-3.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-4.png b/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-4.png deleted file mode 100644 index 9d330f6d4..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-4.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/copy-role-arn.png b/docs/assets/screenshots/integrations/cloud-providers/aws/copy-role-arn.png deleted file mode 100644 index 5e748c24a..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/copy-role-arn.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/inception-meme.png b/docs/assets/screenshots/integrations/cloud-providers/aws/inception-meme.png deleted file mode 100644 index 400efe554..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/inception-meme.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/setup-aws-role.png b/docs/assets/screenshots/integrations/cloud-providers/aws/setup-aws-role.png deleted file mode 100644 index ec1233c1d..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/setup-aws-role.png and /dev/null differ diff --git a/docs/assets/screenshots/integrations/cloud-providers/aws/setup-integration-step-1.png b/docs/assets/screenshots/integrations/cloud-providers/aws/setup-integration-step-1.png deleted file mode 100644 index 730016f65..000000000 Binary files a/docs/assets/screenshots/integrations/cloud-providers/aws/setup-integration-step-1.png and /dev/null differ diff --git a/docs/assets/screenshots/stack/delete-stack.png b/docs/assets/screenshots/stack/delete-stack.png new file mode 100644 index 000000000..972ae04f3 Binary files /dev/null and b/docs/assets/screenshots/stack/delete-stack.png differ diff --git a/docs/assets/screenshots/stack/filter-views-default.png b/docs/assets/screenshots/stack/filter-views-default.png new file mode 100644 index 000000000..5eab67ce0 Binary files /dev/null and b/docs/assets/screenshots/stack/filter-views-default.png differ diff --git a/docs/assets/screenshots/stack/filter-views-reset.png b/docs/assets/screenshots/stack/filter-views-reset.png new file mode 100644 index 000000000..52cb18944 Binary files /dev/null and b/docs/assets/screenshots/stack/filter-views-reset.png differ diff --git a/docs/assets/screenshots/stack/list/saved-view-default-highlight.png b/docs/assets/screenshots/stack/list/saved-view-default-highlight.png deleted file mode 100644 index 310e9bcda..000000000 Binary files a/docs/assets/screenshots/stack/list/saved-view-default-highlight.png and /dev/null differ diff --git a/docs/assets/screenshots/stack/list/saved-view-reset-highlight.png b/docs/assets/screenshots/stack/list/saved-view-reset-highlight.png deleted file mode 100644 index 4004207a7..000000000 Binary files a/docs/assets/screenshots/stack/list/saved-view-reset-highlight.png and /dev/null differ diff --git a/docs/assets/screenshots/stack/scheduling/schedule-drift-detection.png b/docs/assets/screenshots/stack/scheduling/schedule-drift-detection.png new file mode 100644 index 000000000..4312f237d Binary files /dev/null and b/docs/assets/screenshots/stack/scheduling/schedule-drift-detection.png differ diff --git a/docs/assets/screenshots/stack/settings/stack-deletion_form.png b/docs/assets/screenshots/stack/settings/stack-deletion_form.png deleted file mode 100644 index 46de33b5a..000000000 Binary files a/docs/assets/screenshots/stack/settings/stack-deletion_form.png and /dev/null differ diff --git a/docs/assets/screenshots/stack/settings/stack-details_set-folder-label.png b/docs/assets/screenshots/stack/settings/stack-details_set-folder-label.png deleted file mode 100644 index 03f3aa124..000000000 Binary files a/docs/assets/screenshots/stack/settings/stack-details_set-folder-label.png and /dev/null differ diff --git a/docs/concepts/run/task.md b/docs/concepts/run/task.md index dc44b2654..eccf6b928 100644 --- a/docs/concepts/run/task.md +++ b/docs/concepts/run/task.md @@ -24,7 +24,7 @@ With the above caveat, let's go through the main benefits of using Spacelift tas Tasks are always treated as operations that may change the underlying state, and are thus serialized. No two tasks will ever run simultaneously, nor will a task execute while a [tracked run](tracked.md) is in progress. This prevents possible concurrent updates to the state that would be possible without a centrally managed mutex. -What's more, some tasks will be more sensitive than others. While a simple `ls` is probably nothing to be afraid of, the two-way state migration described above could have gone wrong in great many different ways. The [stack locking mechanism](../stack/stack-locking.md) thus allows taking exclusive control over one or more stacks by a single individual, taking the possibility of coordination to a whole new level. +What's more, some tasks will be more sensitive than others. While a simple `ls` is probably nothing to be afraid of, the two-way state migration described above could have gone wrong in great many different ways. The [stack locking mechanism](../stack/creating-a-stack.md#lock-a-stack-in-spacelift) thus allows taking exclusive control over one or more stacks by a single individual, taking the possibility of coordination to a whole new level. ### Safe diff --git a/docs/concepts/stack/README.md b/docs/concepts/stack/README.md index 937057b15..dc35a0197 100644 --- a/docs/concepts/stack/README.md +++ b/docs/concepts/stack/README.md @@ -1,23 +1,26 @@ # Stack -_Stack_ is one of the core concepts in Spacelift. A stack is an isolated, independent entity and the choice of the word mirrors products like [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacks.html){: rel="nofollow"}, or [Pulumi](https://www.pulumi.com/docs/intro/concepts/stack/){: rel="nofollow"} (of which we support both). You can think about a stack as a combination of source code, current state of the managed infrastructure (eg. Terraform state file) and configuration in the form of [environment](../configuration/environment.md) variables and mounted files. +If you're managing your infrastructure in Spacelift, you're managing them with stacks. A stack is a combination of source code, the current state of the managed infrastructure (e.g. Terraform state file) and the configuration ([environment](../configuration/environment.md) variables and mounted files). A stack is also an isolated, independent entity. -Unless you're using Spacelift only to host and test private [Terraform modules](../../vendors/terraform/module-registry.md), your account should probably contain one or more stacks to be of any use. For example: +Unless you're only using Spacelift to host and test private [Terraform modules](../../vendors/terraform/module-registry.md), your account should contain one or more stacks. -![](<../../assets/screenshots/stack/list/page-view.png>) +![Stacks list in UI](<../../assets/screenshots/stack/list/page-view.png>) -Here's a few helpful articles about stacks: +## What can I do with stacks? -- In [this article](creating-a-stack.md), you can learn how to create a new stack; -- [Here](stack-settings.md) you can see all the settings that are available for the stack; -- [Here](stack-locking.md#stack-locking) you can learn about stack locking; +- [Create, delete, and lock](./creating-a-stack.md) stacks. +- [Organize](./organizing-stacks.md) stacks. +- Configure [stack settings](./stack-settings.md). +- [Schedule](./scheduling.md) stack runs. +- Set up [stack dependencies](./stack-dependencies.md). +- [Detect drift](./drift-detection.md) in managed stacks. ## Stack state -Similar to [runs](../run/README.md) and [tasks](../run/task.md), stacks also have states. -A stack's state is the last state of its most recently processed [tracked run](../run/README.md#where-do-runs-come-from) that has progressed beyond the [queued](../run/README.md#queued) state and which was not [canceled](../run/README.md#canceled). -Only if the stack has no runs yet a special state "None" is applied: +Similar to [runs](../run/README.md) and [tasks](../run/task.md), stacks also have states that are generally equal to their most recent [tracked run state](../run/README.md#common-run-states). -![](<../../assets/screenshots/stack/list/none-state-item.png>) +The state is set to "None" on stacks with no runs: -Stack states allow users to see at a glance the overall health of their infrastructure, and the level of development activity associated with it. +![None state](<../../assets/screenshots/stack/list/none-state-item.png>) + +Stack states show users the overall health of their infrastructure, and the level of development activity associated with it, at a glance. diff --git a/docs/concepts/stack/creating-a-stack.md b/docs/concepts/stack/creating-a-stack.md index 05eb6b0c3..c1acb5c06 100644 --- a/docs/concepts/stack/creating-a-stack.md +++ b/docs/concepts/stack/creating-a-stack.md @@ -1,213 +1,224 @@ -# Creating a stack +# Create, delete, and lock stacks -Unless you're defining a stack programmatically using our [Terraform provider](../../vendors/terraform/terraform-provider.md), you will be creating one from the root of your Spacelift account: +## Create a stack in Spacelift -![](<../../assets/screenshots/Create_Stack_Overview.png>) +[Creating a stack](../../concepts/stack/creating-a-stack.md) involves 9 steps, most of which are optional. Required tasks are marked with an asterisk here: + +1. *[Name, describe, and label](#1-stack-details) the stack. +2. *[Create a link](#2-connect-to-source-code) between your new stack and an existing source code repository. +3. *[Choose the backend vendor](#3-choose-vendor). +4. [Define common behavior](#4-define-behavior) of the stack. +5. [Create stack hooks](#5-add-hooks). +6. [Attach a cloud integration](#6-attach-cloud). +7. [Attach policies](#7-attach-policies). +8. [Attach contexts](#8-attach-context). +9. *[Review the summary and create your stack](#9-summary). !!! info You need to be an admin to create a stack. By default, GitHub account owners and admins are automatically given Spacelift admin privileges, but this can be customized using [login policies](../policy/login-policy.md) and/or [SSO integration](../../integrations/single-sign-on/README.md). -The stack creation process involves nine simple steps: - -1. [Naming, describing and labeling](creating-a-stack.md#name-your-stack); -2. [Creating a link between your new stack and an existing Git repository](#integrate-vcs); -3. [Defining backend-specific behavior](creating-a-stack.md#configure-backend) (different for each supported backend, eg. [Terraform](creating-a-stack.md#terraform), [AWS CloudFormation](../../vendors/cloudformation/README.md), [Pulumi](creating-a-stack.md#pulumi), or [Kubernetes](../../vendors/kubernetes/README.md)) -4. [Defining common behavior of the stack](#define-behavior); -5. [Creating stack hooks](#create-stack-hooks); -6. [Attaching a cloud integration](#attach-stack-cloud-integration); -7. [Attaching policies](#attach-stack-policies); -8. [Attaching contexts](#attach-stack-contexts); -9. [Review the summary and create your stack](#summary); - -## Name your stack - -![](<../../assets/screenshots/Create_Stack_Stack_Details.png>) - -Starting with the most difficult step - naming things. Here's where you give your new stack a nice informative [name and an optional description](stack-settings.md#name-and-description) - this one even supports Markdown: - -![](<../../assets/screenshots/Create_Stack_Labels.png>) - -You'll be able to change the name and description later, too - with one caveat. Based on the original _name_, Spacelift generates an immutable slug that serves as a unique identifier of this stack. If the name and the slug diverge significantly, things may become confusing. - -Here you will be able to choose which [space](../spaces/README.md) your stack belongs to. Initially, you start with a root and a legacy space. The root space is the top-level space of your account, while the legacy space exists for backward compatibility with pre-spaces RBAC. - -Also, this is the opportunity to set a few [labels](stack-settings.md#labels). Labels are useful for searching and grouping things, but also work extremely well with policies. +To get started, click **Create stack** on the _Stacks_ page or **Create first stack** from the _LaunchPad_ if you haven't set up a stack before. -## Integrate VCS +![Create a new stack](<../../assets/screenshots/CreateStackGS.png>) -![](<../../assets/screenshots/Create_Stack_VCS.png>) +### 1. Stack details -In this step, you will need to tell Spacelift where to look for the IaC code for the stack - if you have multiple integrations per VCS type, then you'll need to choose the one which includes your repository. Please note that only those VCS integrations will appear which the stack Space (set in the previous step) has access to. For example, if the stack Space is `ParentSpace` and the VCS integration Space is `ChildSpace` with inheritance enabled, it will appear. Integrations marked as default will always appear here, regardless of the stack Space. Take a look at the [source control](../../integrations/source-control/README.md) docs for more details. +Fill in required _stack details_. -The branch that you specify set here is what we called a _tracked_ branch. By default, anything that you push to this branch will be considered for deployment. Anything you push to a different branch will be tested for changes against the current state. +![Fill in stack details](<../../assets/screenshots/getting-started/create-stack/Stack-details.png>) - The project root configuration is where inside the repository Spacelift should look for the infra project source code (e.g. create a stack for a specific folder in the repository). +1. **Name**: Enter a unique, descriptive name for your stack. +2. **Space**: Select the [space](../../concepts/stack/README.md) to create the stack in. +3. [**Labels**](../../concepts/stack/stack-settings.md#labels) (optional): Add labels to help sort and filter your stacks. +4. **Description** (optional): Enter a (markdown-supported) description of the stack and the resources it manages. +5. Click **Continue**. -A few things worth noting: +### 2. Connect to source code -- you can point multiple Spacelift stacks to the same repository, even the same branch; -- the default behavior can be tweaked extensively to work with all sorts of Git and deployment workflows (yes, we like monorepos, too) using [push](../policy/push-policy/README.md) and [trigger](../policy/trigger-policy.md) policies, which are more advanced topics; -- in order to learn what exactly our Git hosting provider integration means, please refer to [GitHub](../../integrations/source-control/github.md) and [GitLab](../../integrations/source-control/gitlab.md) integration documentation; +Connect your [VCS provider](../../getting-started/integrate-source-code/README.md) and fill in the details. -!!! info - If you're using our default GitHub App integration, we only list the repositories you've given us access to. If some repositories appear to be missing in the selection dropdown, it's likely that you've installed the app on a few selected repositories. That's fine, too, just [whitelist the desired repositories](../../integrations/source-control/github.md) and retry. - -## Configure backend +![](<../../assets/screenshots/getting-started/create-stack/connect-source-code.png>) -At this point you'll probably know whether you want to create a [Terraform](creating-a-stack.md#terraform), [OpenTofu](creating-a-stack.md#opentofu), [Terragrunt](creating-a-stack.md#terragrunt), [AWS CloudFormation](../../vendors/cloudformation/README.md), [Pulumi](creating-a-stack.md#pulumi), [Ansible](creating-a-stack.md#ansible) or [Kubernetes](../../vendors/kubernetes/README.md) stack. Each of the supported vendors has some settings that are specific to it, and the backend configuration step is where you can define them. +1. **Integration**: Verify the VCS integration name is correct. +2. **Repository**: Select the repository to manage in Spacelift. If you have multiple repositories linked to one VCS, leave blank. +3. **Branch**: Select the branch of the repository to manage with this stack. +4. [**Project root**](../../concepts/stack/stack-settings.md#project-root) (optional): If the entrypoint of the stack is different than the root of the repo, enter its path here. +5. [**Project globs**](../../concepts/stack/stack-settings.md#project-globs) (optional): Enter additional files and directories that should be managed by the stack. +6. Click **Continue**. -### Terraform +### 3. Choose vendor -![](<../../assets/screenshots/Create_Stack_Terraform.png>) +Select your IaC vendor and fill in the required details, then click **Create & continue**. -When selecting **Terraform**, you can choose which **version of Terraform** to start with - we support Terraform 0.12.0 and above, up to the latest version of MPL Terraform. You don't need to dwell on this decision since you can change the version later - Spacelift supports full [Terraform version management](../../vendors/terraform/version-management.md) allowing you to even preview the impact of upgrading to a newer version. +![](<../../assets/screenshots/getting-started/create-stack/choose-vendor.png>) -The next decisions involves your Terraform state. First, whether you want us to provide a Terraform state backend for your state. We do offer that as a convenience feature, though Spacelift works just fine with any remote backend, like Amazon S3. +#### OpenTofu/Terraform -!!! info - If you want to bring your own backend, there's no point in doing additional [state locking](https://www.terraform.io/docs/state/locking.html){: rel="nofollow"} - Spacelift itself provides a more sophisticated state access control mechanism than Terraform. - -If you choose not to use our state backend, feel free to proceed. If you do want us to manage your state, you have an option to import an existing state file from your previous backend. This is only relevant if you're migrating an existing Terraform project to Spacelift. If you have no state yet and Spacelift will be creating resources from scratch, this step is unnecessary. +We support Terraform 0.12.0 and above, and all OpenTofu versions. Spacelift also supports full [Terraform version management](../../vendors/terraform/version-management.md) allowing you to preview the impact of upgrading to a newer version. !!! warning - Remember - this is the only time you can ask Spacelift to be the state backend for a given stack, so choose wisely. You can read more about state management [here](../../vendors/terraform/state-management.md). - -In addition to these options, we also offer [external state access](../../vendors/terraform/external-state-access.md) for read-only purposes, this is available for administrative stacks or users with write permission to this Stack's space. - -### OpenTofu - -![](<../../assets/screenshots/Create_Stack_OpenTofu.png>) - -Right now, creating an OpenTofu has only one slight difference from creating a Terraform stack and that difference refers to setting the workflow tool to OpenTofu. - -### Pulumi -![](<../../assets/screenshots/Create_Stack_Pulumi.png>) + This is the only time you can ask Spacelift to be the state backend for a given [OpenTofu/Terraform stack](../../vendors/terraform/state-management.md). -When creating a Pulumi stack, you will need to provide two things. First, the login URL to your Pulumi state backend, as currently we don't provide one like we do for Terraform, so you will need to bring your own. +1. **Workflow tool**: Set to OpenTofu, Terraform (FOSS), or [Custom](../../vendors/terraform/workflow-tool.md). + - With OpenTofu or Terraform (FOSS), select a specific **version** or enter a **version range**. +2. **Smart Sanitization** (recommended): Choose whether Spacelift attempts to sanitize sensitive resources created by OpenTofu/Terraform. +3. **Manage State** (recommended): Choose whether Spacelift should handle the OpenTofu/Terraform state. + 1. If **disabled**: Optionally enter a **workspace**. + 2. If **enabled**: Configure these options: + - [**External state access**](../../vendors/terraform/external-state-access.md): Allow external read-only access for administrative stacks or users with write permissions to the Stack's space. + - **Import existing state file**: Enable to import a state file from your previous backend. +4. Click **Create & continue**. -Second, you need to specify the name of the Pulumi stack. This is separate from the name of the Spacelift stack, which you will specify in the [next step](creating-a-stack.md#define-behaviour). That said, nothing prevents you from keeping them in sync. +#### Pulumi -### CloudFormation +1. **Login URL**: Enter the URL to your Pulumi state backend. +2. **Stack name**: Enter a name for your Pulumi stack. This is separate from the name of the Spacelift stack, but you can give both the same name. +3. Click **Create & continue**. -![](<../../assets/screenshots/Create_Stack_CF.png>) +#### AWS CloudFormation -If you're using CloudFormation with Spacelift, there are a few pieces of information you'll need to provide. First, you'll need to specify the region where your CloudFormation stack will be located. +1. **Region**: Enter the AWS region your stack will be located in (e.g. `us-east-2`). +2. **Stack name**: Enter the name of the corresponding CloudFormation stack. +3. **Entry template file**: Enter the path to the template file in your repo describing the root CloudFormation stack. +4. **Template bucket**: Enter the location of the S3 bucket to store processed CloudFormation templates, so Spacelift can manage the state properly. +5. Click **Create & continue**. -Additionally, you'll need to provide the name of the corresponding CloudFormation stack for this Spacelift stack. This will help us keep track of the different resources in your infrastructure. +#### Kubernetes -You'll also need to provide the path to the template file in your repository that describes the root CloudFormation stack and finally you'll need to specify the S3 bucket where your processed CloudFormation templates will be stored. This will enable us to manage your CloudFormation state and ensure that all changes are properly applied. +1. **Namespace** (optional): Enter the namespace of the Kubernetes cluster you want to run commands on. Leave blank for multi-namespace stacks. +2. **Workflow tool**: Select the tool used to execute workflow commands. + - **Kubernetes**: Provide the **kubectl version** the worker will download. + - **Custom**: No configuration needed. +3. Click **Create & continue**. -### Kubernetes +#### Terragrunt -![](<../../assets/screenshots/Create_Stack_K8s.png>) +1. **Terragrunt version**: Select a specific Terraform **version** or enter a **version range**. +2. **Tool**: Select the tool used to make infrastructure changes: + - **OpenTofu/Terraform (FOSS)**: Select a specific Terraform version or enter a version range. + - **Manually provisioned**: Outside of Spacelift, ensure the tool is available to the worker via a custom image or hook and set the `TERRAGRUNT_TFPATH` environment variable to tell Terragrunt where to find it. +3. **Smart Sanitization** (recommended): Choose whether Spacelift attempts to sanitize sensitive resources created by OpenTofu/Terraform. +4. **Use All Run**: Enable to use Terragrunt's run-all feature. +5. Click **Create & continue**. -When you create a Kubernetes stack in Spacelift, you have the option to specify the namespace of the Kubernetes cluster that you want to run commands on. You can leave this empty for multi-namespace Stacks. +#### Ansible -You can also provide the version of kubectl that you want the worker to download. This is useful if you need to work with a specific version of kubectl for compatibility or testing purposes. The worker will download the specified version of kubectl at runtime, ensuring that the correct version is available for executing commands on the cluster. +1. **Playbook**: Enter the playbook file to run in the stack. +2. Click **Create & continue**. -### Terragrunt +Once you've configured your vendor information, click **Continue** to **Define stack behavior**. -![](<../../assets/screenshots/Create_Stack_Terragrunt.png>) -Creating a Terragrunt stack in Spacelift, gives you the option to specify the Terraform and Terragrunt versions you want to use. +![Define stack behavior](<../../assets/screenshots/DefineStackBehaviorGS.png>) -You also have the possibility of enabling the run-all feature of Terragrunt, which is useful in scenarios where organizations rely on this in their current process and are unable to do a full migration yet. +### 4. Define behavior -Support is currently in Beta. +Determine and set additional behaviors for your stack. -### Ansible +1. **Worker pool**: Choose which [worker pool](../../concepts/worker-pools/README.md) to use (default is public workers). +2. **Runner image**: Use a custom runner for your runtime environment. +3. [**Administrative**](../../concepts/stack/stack-settings.md#administrative): Choose whether a stack has privileges to create ohter Spacelift resources via our [Terraform provider](https://registry.terraform.io/providers/spacelift-io/spacelift/latest/docs). +4. **Allow** [**run promotion**](../../concepts/run/run-promotion.md): Allows you to promote a proposed run to a tracked run (i.e. deploy from a feature branch). +5. **Autodeploy**: Automatically deploy changes to your code. +6. [**Autoretry**](../../concepts/stack/stack-settings.md#autoretry): Automatically retry deployment of invalidated proposed runs. For stacks using private workers only. +7. **Enable local preview**: Preview how code changes will execute with the [spacectl](https://github.com/spacelift-io/spacectl){: rel="nofollow"} CLI feature. +8. **Enable** [**secret masking**](../../concepts/stack/stack-settings.md#enable-well-known-secret-masking): Automatically redact secret patterns from logs. +9. **Protect from deletion** (recommended): Protect your stacks from accidental deletion. +10. **Transfer sensitive outputs across dependencices**: Pass sensitive outputs from this stack to dependent stacks. -![](<../../assets/screenshots/Create_Stack_Ansible.png>) +Once you've configured your settings, click **Save & continue**. -When you create an Ansible stack in Spacelift, you have the option to select the playbook file you want to use. You can define policies for your stack as you would do for any other stack. +### 5. Add hooks -Support is currently in Beta. +You also have the ability to control what happens before and after each runner phase using [stack hooks](../../concepts/stack/stack-settings.md#customizing-workflow). Define commands that run during the following phases: -### Stack Created - -![](<../../assets/screenshots/Stack_Created.png>) - -With the exception of Pulumi, which requires additional mandatory steps first. After selecting the vendor for your stack, you're brought to a new screen indicating that your stack has been successfully created. This screen serves as a branching point where you can enhance the functionality of your stack through various integrations and customizations. - -You have the flexibility to either take shortcuts to specific configurations or continue through the standard process of setting up your stack. - -## Define behavior +- Initialization +- Planning +- Applying +- Destroying +- Performing +- Finally -Regardless of which of the supported backends (Terraform, Pulumi etc.) you're setting up your stack to use, there are a few common settings that apply to all of them. You'll have a chance to define them in the next step: +Once you've added all hooks, click **Save & continue**. -![](<../../assets//screenshots/Create_Stack_Define_Behavior.png>) +### 6. Attach cloud -The behavior settings are: +If desired, attach your [cloud provider integration](../../getting-started/integrate-cloud/README.md). -- whether the stack is [administrative](./stack-settings.md#administrative); -- [worker pool](../worker-pools) to use, if applicable (default uses the Spacelift public worker pool); -- whether the changes should [automatically deploy](./stack-settings.md#autodeploy); -- whether obsolete tests should be [automatically retried](./stack-settings.md#autoretry); -- whether or not to protect the stack from deletion; -- whether or not to enable the local preview [spacectl](https://github.com/spacelift-io/spacectl){: rel="nofollow"} CLI feature; -- whether or not [run promotion](../run/run-promotion.md) is enabled; -- optionally specify a custom Docker image to use to for your job container; +1. Select the cloud provider the stack will use. +2. **Attach integration**: Choose the name of the integration the stack will use. +3. **Read**: Use the integration during read phases. +4. **Write**: Use the integration during write phases. +5. Click **Attach**. +6. Click **Continue**. -## Create Stack Hooks +### 7. Attach policies -![](<../../assets/screenshots/Create_Stack_Hooks.png>) +If you're just following the LaunchPad steps, you won't have any [policies](../../concepts/policy/README.md) yet. If you did configure policies, you will be able to attach them here: -You also have the ability to control what happens before and after each runner phase using Stack Hooks. In this phase, you can define commands that run in between the following phases: +- [Approval](../../concepts/policy/approval-policy.md): Who can approve or reject a run and how a run can be approved. +- [Plan](../../concepts/policy/terraform-plan-policy.md): Which changes can be applied. +- [Push](../../concepts/policy/push-policy/README.md): How Git push events are interpreted. +- [Trigger](../../concepts/policy/trigger-policy.md): What happens when blocking runs terminate. -- Initialization -- Planning -- Applying -- Destroying -- Performing -- Finally +Click **Continue**. -You can read more about stack hooks [here](../stack/stack-settings.md#customizing-workflow). +### 8. Attach context -## Attach Stack Cloud Integration +Contexts are sets of environment variables and related configuration, including hooks, that can be shared across multiple stacks. By attaching a context, you ensure your stack has all the necessary configuration elements it needs to operate, without repeating the setup for each stack. -![](<../../assets/screenshots/Create_Stack_Cloud_Integrations.png>) +If you're just following the LaunchPad steps, you won't have any [contexts](../../concepts/configuration/context.md) yet. If you did configure contexts, you will be able to attach them here. -Here you have the ability to attach any Cloud Integrations you have configured. +Click **Continue**. -Cloud integrations allow Spacelift to manage your resources without the need for long-lived static credentials. +### 9. Summary -Spacelift integrates with identity management systems from major cloud providers to dynamically generate short-lived access tokens that can be used to configure their corresponding Terraform providers. +Review your settings before finalizing your stack, then click **Confirm**. -Currently, AWS, Azure and GCP are natively supported. +## Delete a stack in Spacelift -You can read more about Cloud integrations [here](../../integrations/cloud-providers/README.md). +If you want to save the state file before deleting a stack, you can retrieve it with a task. -## Attach Stack Policies +1. On the _Stacks_ tab, click the three dots next to the stack you want to delete. +2. Click **Settings**, then click **Stack deletion**. +3. Choose whether to delete or keep the stack's resources. +4. Type "**delete**" in the box, then click **Delete**. -![](<../../assets/screenshots/Create_Stack_Policies.png>) +![Delete a stack](<../../assets/screenshots/stack/delete-stack.png>) -Spacelift as a development platform is built around the concept of policies and allows defining policies that involve various decision points in the application. +!!! info + Resource deletion is not currently supported while using the native Terragrunt support. -In this section, you can attach the following policy types: +### Deleting resources managed by a stack -- [Approval:](../../concepts/policy/approval-policy.md) who can approve or reject a run and how a run can be approved; -- [Plan:](../../concepts/policy/terraform-plan-policy.md) which changes can be applied; -- [Push:](../../concepts/policy/push-policy/README.md) how Git push events are interpreted; -- [Trigger:](../../concepts/policy/trigger-policy.md) what happens when blocking runs terminate; +Depending on the backend of your stack, there are different commands you can run as a [task](../run/task.md) before deleting the stack. -Policies can be automatically attached to stacks using the `autoattach:label` special label where `label` is the name of a label attached to stacks and/or modules in your Spacelift account you wish the policy to be attached to. +| Backend | Command | +| -------------- | ------------------------------------------------------------ | +| **Terraform** | `terraform destroy -auto-approve` | +| **OpenTofu** | `tofu destroy -auto-approve` | +| **CloudFormation** | `aws cloudformation delete-stack --stack-name ` | +| **Pulumi** | `pulumi destroy --non-interactive --yes` | +| **Kubernetes** | `kubectl delete --ignore-not-found -l spacelift-stack= $(kubectl api-resources --verbs=list,create -o name | paste -s -d, -)` | -You can read more about policies [here](../../concepts/policy/README.md). +!!! tip + For Terraform, you can also run a task through our CLI tool [spacectl](../../vendors/terraform/provider-registry.md#use-our-cli-tool-called-spacectl). -## Attach Stack Contexts +### Scheduled delete -![](<../../assets/screenshots/Create_stack_contexts.png>) +You can use [scheduling to delete a stack](./scheduling.md) at a specified time and date. -Contexts are sets of environment variables and related configuration,including hooks that can be shared across multiple stacks. By attaching a context, you ensure your stack has all the necessary configuration elements it needs to operate, without repeating the setup for each stack. +### Using the API -Contexts can be automatically attached to stacks using the `autoattach:label` special label where `label` is the name of a label attached to stacks and/or modules in your Spacelift account you wish the context to be attached to. +You can also use Spacelift's [GraphQL API to delete a stack](../../integrations/api.md). -You can read more about contexts [here](../../concepts/configuration/context.md). +## Lock a stack in Spacelift -## Summary +Spacelift supports locking a stack for one person's exclusive use. This is useful to prevent someone else's changes to the strack from impacting delicate operations. Every stack [writer](../policy/stack-access-policy.md#readers-and-writers) can lock a stack unless it's already locked. -![](<../../assets/screenshots/create_stack_summary_v2.png>) +The owner of the lock is the only one who can trigger [runs](../run/README.md) and [tasks](../run/task.md) for the entire duration of the lock. Locks never expire, and only its creator and Spacelift admins can release it. - On the summary section, you can now review your settings before finalizing the creation of your stack. This modular approach ensures your stack gets set up with all the necessary components. +![Lock a stack](<../../assets/screenshots/lockstackss.png>) - Congratulations on creating your stack! 🚀 +!!! info + Note that while a stack is locked, [auto deploy](stack-settings.md#autodeploy) is disabled to prevent accidental deployments. diff --git a/docs/concepts/stack/deleting-a-stack.md b/docs/concepts/stack/deleting-a-stack.md deleted file mode 100644 index 76dbac1d8..000000000 --- a/docs/concepts/stack/deleting-a-stack.md +++ /dev/null @@ -1,31 +0,0 @@ -# Deleting a Stack - -When you are ready to delete your stack, you can do so by navigating to the Stack deletion tab in your stack settings. You will get a choice to keep or delete any of the resources that this stack manages. To delete your stack, type the stack's name into the confirmation box and click on the delete button. - -![](<../../assets/screenshots/stack/settings/stack-deletion_form.png>) - -!!! warn - Resource deletion is not currently supported while using the native Terragrunt support. - -## Deleting Resources Managed by a Stack - -Depending on the backend of your stack, there are different commands you can run as a [task](../run/task.md) before deleting the stack. - -| Backend | Command | -| -------------- | ------------------------------------------------------------ | -| **Terraform** | `terraform destroy -auto-approve` | -| **OpenTofu** | `tofu destroy -auto-approve` | -| **CloudFormation** | `aws cloudformation delete-stack --stack-name ` | -| **Pulumi** | `pulumi destroy --non-interactive --yes` | -| **Kubernetes** | `kubectl delete --ignore-not-found -l spacelift-stack= $(kubectl api-resources --verbs=list,create -o name | paste -s -d, -)` | - -!!! tip - For Terraform, you can also run a task through our CLI tool [spacectl](../../vendors/terraform/provider-registry.md#use-our-cli-tool-called-spacectl). - -## Scheduled Delete - -If you would like to schedule to delete a stack, please see our documentation on [Scheduling](../stack/scheduling.md). - -## Using the API - -If you would like to delete a stack using our API, please see our documentation on GraphQL [API](../../integrations/api.md). diff --git a/docs/concepts/stack/organizing-stacks.md b/docs/concepts/stack/organizing-stacks.md index e50e27dcc..085ed447e 100644 --- a/docs/concepts/stack/organizing-stacks.md +++ b/docs/concepts/stack/organizing-stacks.md @@ -1,100 +1,106 @@ -# Organizing stacks +# Organize stacks -Depending on the complexity of your infrastructure, the size of your team, your particular needs and your preferred way of working you may end up managing a lot of stacks. This obviously makes it harder to quickly find what you're looking for. As practitioners ourselves, we're providing you a few tools to make this process more manageable - from the basic [query-based searching](organizing-stacks.md#query-based-searching-and-filtering) to [filtering by status](organizing-stacks.md#label-based-folders) and the coolest of all, [label-based folders](organizing-stacks.md#label-based-folders). +Depending on the complexity of your infrastructure, the size of your team, your particular needs, and your preferred way of working, you may end up managing a lot of stacks. Spacelift offers several options for searching through your stacks, from basic [query-based searching](organizing-stacks.md#query-based-search-and-filter) to [filtering by status](organizing-stacks.md#label-based-folders) and' [label-based folders](organizing-stacks.md#label-based-folders). ## Video Walkthrough
-## Customizing table view +## Customize your table view -Based on the table configuration, you'll be able to customize the view to suit your needs. A settings drawer for customizing the list is available under the icon in the top right corner. -![](<../../assets/screenshots/stack/list/customize-list-button.png>) +You can customize the table view to suit your needs. Click the **Customize list** gear icon at the top-right to open a customizing drawer. -Clicking the icon opens a drag-and-drop menu where you can hide columns (except for _name_) or rearrange their order: -![](<../../assets/screenshots/stack/list/customize-list-drawer.png>) +![Customize list icon](<../../assets/screenshots/stack/list/customize-list-button.png>) +![Customize list drawer](<../../assets/screenshots/stack/list/customize-list-drawer.png>) -To reset your settings, use the _Reset to default_ button located at the bottom of the customization drawer. +1. Drag and drop columns to rearrange or hide them from view. The _name_ column cannot be hidden. + - Alternatively, outside the customize list drawer, hover over the column header and click **Hide**. + ![Hide column](<../../assets/screenshots/stack/list/column-options-highlight.png>) +2. To reset your settings, click **Reset to default** at the bottom of the customization drawer. -Each column can be resized by dragging the column separator: -![](<../../assets/screenshots/stack/list/resize-column-highlight.png>) +You can also resize columns in the list by dragging the separator: +![Column resize separator](<../../assets/screenshots/stack/list/resize-column-highlight.png>) -Additionally, you can hover over one of the column headers and leverage the dropdown menu to hide them: -![](<../../assets/screenshots/stack/list/column-options-highlight.png>) +## Query-based search and filter -## Query-based searching and filtering +![Stacks list search](../../assets/screenshots/stack/list/search-highlight.png) -Historically the first tool we offered was the search bar: +You can search and filter by these stack properties in the search bar: -![](../../assets/screenshots/stack/list/search-highlight.png) +- name +- ID (slug) +- any of its [labels](stack-settings.md#labels) -The search bar allows you to search and filter by the following stack properties: +## Filter by state -- name; -- ID (slug); -- any of its [labels](stack-settings.md#labels); +Filtering stacks by state is useful for identifying action items like plans pending confirmation ([unconfirmed](../run/tracked.md#unconfirmed) state) or [failed](../run/README.md#failed) jobs that require fixing. Use the _State_ section on the left-hand sidebar, which displays all states attached to your stacks. Click state checkboxes to filter the list of stacks. -## Filtering by state - -Filtering stacks by state is a very useful mechanism for identifying action items like plans pending confirmation ([unconfirmed](../run/tracked.md#unconfirmed) state) or [failed](../run/README.md#failed) jobs that require fixing. For that, use the _State_ section on the sidebar to the left. Clicking on any status filters the list of stacks to show only those with the selected status, - -![](<../../assets/screenshots/stack/list/finished-filter.png>) - -Note that if no stacks in the account have a particular status at the moment, that status is missing from the list. +![Filter stacks in the list by state](<../../assets/screenshots/stack/list/finished-filter.png>) You can also use our predefined tabs to filter some specific group of states: -![](<../../assets/screenshots/stack/list/tab-filters-highlight.png>) +![Predefined tabs](<../../assets/screenshots/stack/list/tab-filters-highlight.png>) -- Needs Attention: _unconfirmed_ state -- Failed: _failed_ state -- On Hold: _none_, _confirmed_ or _replan-requested_ states -- In progress: _applying_, _destroying_, _initializing_, _planning_, _preparing-apply_ or _preparing-replan_ states -- Finished: _finished_ state +| **Predefined Tab Label** | **State** | +| ----------------------- | --------- | +| Needs Attention | _unconfirmed_ | +| Failed | _failed_ | +| On Hold | _none_, _confirmed_, or _replan-requested_ | +| In Progress | _applying_, _destroying_, _initializing_, _planning_, _preparing-apply_, or _preparing-replan_ | +| Finished | _finished_ | ## Label-based folders -Probably the most useful way of grouping stacks is by attaching folder labels to them. You can read more about [labels](stack-settings.md#labels) here, including how to set them, and folder labels are just regular labels, prefixed with `folder:`. In order to make it more obvious in the GUI and save some screen real estate, we replace the `folder:` prefix by the folder icon... - -![](<../../assets/screenshots/stack/list/labels-folders-highlight.png>) +You can group stacks by attaching folder labels to them, which are [regular labels](./stack-settings.md#labels) prefixed with `folder:`. In the stacks list, the `folder:` prefix is replaced width a folder icon. -...but once you start editing labels, the magic is gone: +![Folder icon for prefix](<../../assets/screenshots/stack/list/labels-folders-highlight.png>) -![](../../assets/screenshots/stack/settings/stack-details_set-folder-label.png) +Your folder labels will appear in the _Folders_ section of the _Filters_ sidebar menu, allowing you to use the checkboxes to filter the list by folder labels. -For every folder label, a sidebar section is included in the _Folders_ menu, allowing you to search by that label. The number to the right hand side indicates that number of stacks with that label: - -![](<../../assets/screenshots/stack/list/folder-section-highlight.png>) +![Filter by folder labels](<../../assets/screenshots/stack/list/folder-section-highlight.png>) ### Nesting and multiple folder labels -Perhaps worth mentioning is the fact that folder labels can be nested, allowing you to create either hierarchies, or arbitrary classifications of your stacks. +Folder labels can be nested, allowing you to create hierarchies or arbitrary classifications of your stacks. -Also, a single stack can have any number of folder labels set, in which case it belongs to all the collections. In that, folder labels are like labels in Gmail rather than directories in your filesystem. +A single stack can have _any number of folder labels_ set, in which case it belongs to **all** the collections. If you use more than one folder label on a single stack, they act more like labels in e-mail inboxes rather than directories in your filesystem. -## Saving filters in views +## Save filters in views -It is possible to save your filters with a Filters Tab. You can select all the filters that you would like to apply, add a search query or sorting in the top right corner, click New View, enter the view name, and click Save. This view is now saved for this account. You can also mark your new view as your default view during creation. Next time you log in or navigate to stacks, your personal default view will be applied. +You can save filter views to easily apply filters to your stacks list. -![](../../assets/screenshots/stack/list/saved-view-create-highlight.png) +![Create filter view](<../../assets/screenshots/stack/list/saved-view-create-highlight.png>) -If you forgot to mark your view as default then you can easily do the same thing in the Views Tab. +1. Select all filters you would like to apply. +2. If desired, add a search query or sorting option in the top-right. +3. Click **New View**, then enter a descriptive name for the filter view. +4. Check the box to set the new view as your default, if desired. + - If you want to edit your default view, click **Views**, click the three dots beside the view name you want to use as default, then click **Use as your default view**. + ![Set filter view as default](<../../assets/screenshots/stack/filter-views-default.png>) +5. Click **Save**. -![](../../assets/screenshots/stack/list/saved-view-default-highlight.png) +If you set a filter view as your default, the next time you log in or navigate to the _Stacks_ tab, your personal default view will be applied. ### Shared views -Views can be shared or private. While first creating the view, it is available only to your user. If you have admin access, you can make it public for all the users of the account by hovering over the saved view and clicking the small eye icon "Share within account". This way, all the users within this application can see the saved view and who created it. +Filter views can be private (default for new views) or public to all users of the account. To share a filter view, if you are an admin user, click the three dots beside the view name and click **Share within the account**. The view will now be visible for all users within the account. + +### Reset to default view -### Resetting +To quickly reset your default view to Spacelift's default (no active filters): -To quickly reset your default view to Spacelift default state, click the "Reset to Spacelift default view" button. It will result in clearing all sorting, search, and filter parameters, as well as managed filter settings. +1. Click **Views** to see your available filter views. +2. Click the three dots beside the view name you're using as default. +3. Click **Reset to Spacelift default view**. +4. All sorting, search, and filter parameters will be cleared. -![](../../assets/screenshots/stack/list/saved-view-reset-highlight.png) +![Reset filter view](<../../assets/screenshots/stack/filter-views-reset.png>) ### Manage view -- If you change your filter, search and/or sorting settings, you can update the currently selected view by clicking on Update item under "Manage view" button. The blue icon on the manage view button indicates an update possibility. -- Edit name allows editing name of the current view -- Delete allows removing your private view (Shared and Spacelift default views can not be removed). You can delete the view from the Views tab as well. +Manage existing views when you click the three dots next to _New view_. + +- Click **Update** to update your current filter view with any new filters, searches, and/or sorting settings. +- Click **Edit name** to change the name of the current filter view. +- Click **Delete** to remove a private view. If the view has been shared with other users on the account, it cannot be deleted. -![](../../assets/screenshots/stack/list/saved-view-manage-highlight.png) +![Manage view menu](../../assets/screenshots/stack/list/saved-view-manage-highlight.png) diff --git a/docs/concepts/stack/scheduling.md b/docs/concepts/stack/scheduling.md index e19a2c356..8b23b72cc 100644 --- a/docs/concepts/stack/scheduling.md +++ b/docs/concepts/stack/scheduling.md @@ -1,44 +1,66 @@ -# Scheduling - -## What is scheduling? +# Scheduling stack actions {% if is_saas() %} !!! Info 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 %} -Scheduling allows you to trigger a stack deletion or task at a specific time or periodically based on the cron rules defined. +If you are using [private workers](../../concepts/worker-pools/README.md#private-worker-pool), you can schedule stack deletion or other tasks at a specific time or periodically based on cron rules you define. If your stack is using public workers, you can still create the schedules, but they **will not trigger** until the stack is using private workers. + +![Scheduling tab](<../../assets/screenshots/stack/scheduling/page-view.png>) + +## Schedule stack deletion -![](../../assets/screenshots/stack/scheduling/page-view.png) +You can schedule when a stack should be deleted (and, optionally, its resources). -## Scheduled Delete Stack (TTL) +1. Click the stack you would like to delete. +2. Click **Create schedule**, then **Stack deletion**. +3. Select a date and time for deletion, either in your local timezone or UTC. +4. Choose whether Spacelift retains or deletes the stack's resources. +5. Click **Create**. -A Delete Stack schedule allows you to delete the stack and (optionally) its resources at the specific timestamp (UNIX timestamp). +If you chose to delete the stack's resources, a destruction run will trigger on the stack at the specified time, and then the stack will be deleted when that is successful. If you chose to keep the stack's resources, the stack will be deleted at the specified time. -Add a schedule with the Delete Stack type from the Scheduling section of your stack. +![Schedule stack deletion](<../../assets/screenshots/stack/scheduling/create-delete-stack.png>) -Actions when the schedule defines that the resources should be deleted: +## Schedule drift detection -- a destruction run will be triggered at the specified time. -- after this run is successful, the stack will be deleted. +You can schedule [drift detection](./drift-detection.md) on your stack to find differences between the desired and actual states of your infrastructure. -When the resources should not be deleted, we will delete the stack at the specified time. +1. Click the stack you would like to check for drift. +2. Click **Create schedule**, then **Drift detectionn**. +3. Set the cron expression(s) for how often you'd like to perform drift detection. +4. Select the desired _timezone_. +5. Select additional options: + 1. **Reconcile**: Enable Spacelift to automatically create and trigger [reconciliation runs](./drift-detection.md#to-reconcile-or-not-to-reconcile) to resolve drift. + 2. **Ignore state**: Enable to allow Spacelift to perform drift detection on stacks regardless of state. If disabled, drift detection will only run on stacks with the _Finished_ state. +6. Click **Create**. -![](../../assets/screenshots/stack/scheduling/create-delete-stack.png) +![Schedule drift detection](<../../assets/screenshots//stack/scheduling/schedule-drift-detection.png>) -## Scheduled Task +## Schedule task -A scheduled task enables you to run a command at a specific timestamp or periodically based on the cron rules defined. +You can schedule tasks to run commands on a stack at a specified timestamp or periodically based on cron rules you define. -Add a schedule with the Task type from the Scheduling section of your stack. -After creating this schedule, a task will be triggered with the defined command (at a specific timestamp or periodically based on the cron rules defined). +1. Click the stack you would like to schedule a task on. +2. Click **Create schedule**, then **Task**. +3. Enter the task command you would like to run. +4. Choose a specific date and time, or set a cron rule for recurring tasks. +5. Select the desired _timezone_. +6. Click **Create**. -![](../../assets/screenshots/stack/scheduling/create-task.png) +![Schedule task](<../../assets/screenshots/stack/scheduling/create-task.png>) -## Scheduled Run +## Schedule run -You can also set up a schedule based on which a tracked run will be created. +You can also set up a schedule based on when a tracked run will be created. -![](../../assets/screenshots/stack/scheduling/create-run.png) +1. Click the stack you would like to schedule a run on. +2. Click **Create schedule**, then **Run**. +3. (Optionally) Enter a name for the run schedule. +4. **Attach custom runtime config**: Click the slider to enable this setting, then enter a [custom runtime config](../run//tracked.md#triggering-runs-with-a-custom-runtime-config). +5. Choose a specific date and time, or set a cron rule for recurring tasks. +6. Select the desired _timezone_. +7. Click **Create**. -Additionally, if you mark **Attach custom runtime config**, you will be able to attach a custom runtime config to the schedule, similarly to when [triggering a run with custom runtime config](../run/tracked.md#triggering-runs-with-a-custom-runtime-config). +![Schedule run](<../../assets/screenshots/stack/scheduling/create-run.png>) diff --git a/docs/concepts/stack/stack-dependencies.md b/docs/concepts/stack/stack-dependencies.md index d5a34ba1f..7444cd142 100644 --- a/docs/concepts/stack/stack-dependencies.md +++ b/docs/concepts/stack/stack-dependencies.md @@ -1,8 +1,6 @@ # Stack dependencies -Stacks can depend on other stacks. This is useful when you want to run a stack -only after another stack have finished running. For example, you might want to -deploy a database stack before a stack that uses the database. +Stacks can depend on other stacks. This is useful when you want to run a stack only after another stack have finished running. For example, you might want to deploy a database stack before a stack that uses the database. !!! info Stack dependencies only respect [tracked runs](../run/tracked.md). [Proposed runs](../run/proposed.md) and [tasks](../run/task.md) are not considered. diff --git a/docs/concepts/stack/stack-locking.md b/docs/concepts/stack/stack-locking.md deleted file mode 100644 index 0da2dce34..000000000 --- a/docs/concepts/stack/stack-locking.md +++ /dev/null @@ -1,10 +0,0 @@ -# Stack locking - -Spacelift supports locking the stack for one person's exclusive use. This can be very handy if a delicate operation is taking place that could easily be affected by someone else making changes in the meantime. Every stack [writer](../policy/stack-access-policy.md#readers-and-writers) can lock the stack unless it's already locked. - -The owner of the lock is the only one who can trigger [runs](../run/README.md) and [tasks](../run/task.md) for the entire duration of the lock. Locks never expire, and only its creator and Spacelift admins can release it. - -![](<../../assets/screenshots/lockstackss.png>) - -!!! info - Note that while a stack is locked, [auto deploy](stack-settings.md#autodeploy) is disabled to prevent accidental deployments. diff --git a/docs/concepts/stack/stack-settings.md b/docs/concepts/stack/stack-settings.md index f99c0ecc9..affedb90d 100644 --- a/docs/concepts/stack/stack-settings.md +++ b/docs/concepts/stack/stack-settings.md @@ -1,6 +1,11 @@ # Stack settings -This article explains all the settings that can be configured **directly on the stack**. However, these are not the only settings that influence how [runs](../run/README.md) and [tasks](../run/task.md) within a stack are processed. Other factors, such as [environment variables](../configuration/environment.md), attached [contexts](../configuration/context.md), [runtime configuration](../configuration/runtime-configuration/README.md), and various integrations, also play a significant role. +Many settings can be configured directly on the stack to influence how [runs](../run/README.md) and [tasks](../run/task.md) within a stack are processed. Other factors that influence runs and tasks include: + +- [Environment variables](../configuration/environment.md) +- Attached [contexts](../configuration/context.md) +- [Runtime configuration](../configuration/runtime-configuration/README.md) +- Integrations ## Video Walkthrough @@ -8,6 +13,13 @@ This article explains all the settings that can be configured **directly on the ## Common settings +You can configure these settings when you first [create a stack](../../getting-started/create-stack/README.md) or when it's already created. If you're editing an existing stack's settings: + +1. Navigate to the _Stacks_ page in Spacelift. +2. Click the three dots beside a stack name you want to configure. +3. Click **Settings**, then click **Behavior**. +4. Make your adjustments and click **Save**. + ### Administrative This setting determines whether a stack has administrative privileges within its [space](../spaces/README.md). Administrative stacks receive an API token that grants them elevated access to a subset of the Spacelift API, which is used by the [Terraform provider](../../vendors/terraform/terraform-provider.md). This allows them to create, update, and destroy Spacelift resources. @@ -15,7 +27,7 @@ This setting determines whether a stack has administrative privileges within its !!! info Administrative stacks get the Admin role in the [space they belong to](../spaces/access-control.md#access-control). -The primary use case for administrative stacks is to declaratively manage Spacelift resources, such as other stacks, their [environments](../configuration/environment.md), [contexts](../configuration/context.md), [policies](../policy/README.md), [modules](../../vendors/terraform/module-registry.md), and [worker pools](../worker-pools). This approach helps avoid manual configuration, often referred to as "ClickOps." +Administrative stacks can declaratively manage other stacks, their [environments](../configuration/environment.md), [contexts](../configuration/context.md), [policies](../policy/README.md), [modules](../../vendors/terraform/module-registry.md), and [worker pools](../worker-pools). This approach helps avoid manual configuration, often referred to as "ClickOps." Another common pattern is exporting stack outputs as a [context](../configuration/context.md) to avoid exposing the entire state through Terraform's remote state or external storage mechanisms like [AWS Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html){: rel="nofollow"} or [Secrets Manager](https://aws.amazon.com/secrets-manager/){: rel="nofollow"}. diff --git a/docs/getting-started/create-stack/README.md b/docs/getting-started/create-stack/README.md index 8a95850be..6d2649f86 100644 --- a/docs/getting-started/create-stack/README.md +++ b/docs/getting-started/create-stack/README.md @@ -43,7 +43,7 @@ Connect your VCS provider as configured during [LaunchPad step 1](../integrate-s ## 3. Choose vendor -Select your IaC vendor and fill in the required details, then click **Create & continue**. You can find more details on each vendor and how they interact with Spacelift stacks in our [stack documentation](../../concepts/stack/creating-a-stack.md#configure-backend). +Select your IaC vendor and fill in the required details, then click **Create & continue**. ![](<../../assets/screenshots/getting-started/create-stack/choose-vendor.png>) @@ -166,4 +166,4 @@ Review your settings before finalizing your stack, then click **Confirm**. ✅ Step 3 of the LaunchPad is complete! Now you can [invite teammates](../invite-teammates/README.md). -![](<../../assets/screenshots/getting-started/create-stack/Launchpad-step3-complete.png>) +![LaunchPad step 3 complete](<../../assets/screenshots/getting-started/create-stack/Launchpad-step3-complete.png>) diff --git a/docs/getting-started/integrate-cloud/AWS.md b/docs/getting-started/integrate-cloud/AWS.md index 71a67e9e3..cbbb25cb3 100644 --- a/docs/getting-started/integrate-cloud/AWS.md +++ b/docs/getting-started/integrate-cloud/AWS.md @@ -151,8 +151,37 @@ Given the format of the External ID passed by Spacelift, you can further secure 3. Click **Set up**. !!! warning - If you receive an error message when trying to set up the integration in Spacelift, see [Troubleshooting Trust Relationship Issues](../../integrations/cloud-providers/aws.md#troubleshooting-trust-relationship-issues). + If you receive an error message when trying to set up the integration in Spacelift, see [Troubleshoot trust relationship issues](#troubleshoot-trust-relationship-issues). ✅ Step 2 of the LaunchPad is complete! Now you can [create your first stack](../create-stack/README.md). -![](<../../assets/screenshots/getting-started/cloud-provider/Launchpad-step-2-complete.png>) +![Launchpad Step 2 complete](<../../assets/screenshots/getting-started/cloud-provider/Launchpad-step-2-complete.png>) + +## Troubleshoot trust relationship issues + +If you get the error `you need to configure trust relationship section in your AWS account` when attaching a cloud integration to a stack: + +![](<../../assets/screenshots/integrations/cloud-providers/aws/trust-policy-error.png>) + +There are a couple of common causes to check. + +### Incorrect or missing trust relationship policy + +The error message in the UI includes a tailored trust relationship policy example. This policy allows Spacelift to assume the IAM role and must be added to the **Trust relationships** section of your role in AWS IAM. See [Step 2: Configure trust policy](#step-2-configure-trust-policy) for more information. + +### STS (Security Token Service) not enabled + +{% if is_saas() %} +This error can occur if the [AWS STS (Security Token Service)](https://spacelift.io/blog/aws-sts) is not enabled in your account. + +Make sure STS is enabled in the following regions: + +- **eu-west-1** +- **eu-central-1** (used for disaster recovery failover) + +You can enable STS by following [this AWS guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate){: rel="nofollow"}. +{% endif %} + +{% if is_self_hosted() %} +This error can be caused by STS not being enabled in the AWS region where your Spacelift instance is deployed. Check your region settings and ensure STS is active. Learn more about [AWS STS here](https://spacelift.io/blog/aws-sts). +{% endif %} diff --git a/docs/getting-started/integrate-source-code/GitHub.md b/docs/getting-started/integrate-source-code/GitHub.md index 4af3d3f8a..66426bcf8 100644 --- a/docs/getting-started/integrate-source-code/GitHub.md +++ b/docs/getting-started/integrate-source-code/GitHub.md @@ -146,7 +146,7 @@ Once your GitHub app has been created and configured in Spacelift, you can insta === "Via GitHub UI" 1. Find your Spacelift app on the _GitHub Apps_ page in your account settings, and click **Edit**: - ![](<../..0n m/assets/screenshots/image (58).png>) + ![](<../../assets/screenshots/image (58).png>) 2. In the _Install App_ section, click **Install** next to the account you want Spacelift to access: ![](<../../assets/screenshots/image (59).png>) 3. Choose whether you want to allow Spacelift access to all repositories or only specific ones in the account: @@ -156,4 +156,4 @@ Once your GitHub app has been created and configured in Spacelift, you can insta ✅ Step 1 of the LaunchPad is complete! Now you can [connect your cloud account](../integrate-cloud/README.md). -![](<../../assets/screenshots/getting-started/source-code/Launchpad-step-1-complete.png>) +![LaunchPad step 1 complete](<../../assets/screenshots/getting-started/source-code/Launchpad-step-1-complete.png>) diff --git a/docs/integrations/cloud-providers/README.md b/docs/integrations/cloud-providers/README.md index f680f019d..f02b8527e 100644 --- a/docs/integrations/cloud-providers/README.md +++ b/docs/integrations/cloud-providers/README.md @@ -1,14 +1,22 @@ -# Cloud Integrations +# Spacelift cloud provider integrations -Cloud integrations allow Spacelift to manage your resources without the need for long-lived static credentials. When using infrastructure-as-code automation tools such as Terraform, AWS CloudFormation, or Pulumi, these tools typically require credentials to execute. Usually, these are very powerful credentials, administrative credentials, sometimes. And these can do _a lot of damage_. Typically, you'd provide those credentials statically - think AWS credentials, GCP service keys, etc. This is dangerous, and against security best practices. +Infrastructure-as-code automation tools such as Terraform, AWS CloudFormation, or Pulumi require powerful credentials to execute. Typically, you'd provide static credentials (such as AWS credentials, GCP service keys, etc.), which goes against security best practices. Spacelift's cloud integrations manage your resources _without_ the need for long-lived static credentials, dynamically generating short-lived access tokens to connect cloud providers with IaC providers. -That's why Spacelift integrates with identity management systems from major cloud providers to dynamically generate short-lived access tokens that can be used to configure their corresponding Terraform providers. +Spacelift currently supports [AWS](./aws.md){% if is_saas() %}, [Azure](./azure.md), and [GCP](./gcp.md){% endif %} natively. A generic [OpenID Connect](../cloud-providers/oidc/README.md) integration is also available to work with any compatible service provider. + +!!! hint "Public vs private workers" + This feature is designed for customers using the shared public [worker pool](../../concepts/worker-pools/README.md). When hosting Spacelift workers on your own infrastructure, you can use your cloud providers' ambient credentials (e.g. EC2 instance role or EKS worker role on AWS). + +## Set up your cloud provider integration {% if is_saas() %} -Currently, [AWS](aws.md), [Azure](azure.md) and [GCP](gcp.md) are natively supported. A generic [OpenID Connect](oidc/README.md) integration is also available to work with any compatible service provider. -{% else %} -Currently [AWS](aws.md) is natively supported. A generic [OpenID Connect](oidc/README.md) integration is also available to work with any compatible service provider. +Select your cloud provider to set up the integration: + +- [Amazon Web Services (AWS)](./aws.md) +- [Microsoft Azure](./azure.md) +- [Google Cloud Platform (GCP)](./gcp.md) {% endif %} +{% if is_self_hosted() %} +- Configure [Amazon Web Services (AWS)](./aws.md).{% endif %} -!!! hint - This feature is designed for clients using the shared public worker pool. When hosting Spacelift workers on your infrastructure you can use your cloud providers' ambient credentials (eg. EC2 instance role or EKS worker role on AWS). +You can also use [OIDC](../cloud-providers/oidc/README.md) for available cloud providers. diff --git a/docs/integrations/cloud-providers/aws.md b/docs/integrations/cloud-providers/aws.md index 0f2377546..e4b6fbce9 100644 --- a/docs/integrations/cloud-providers/aws.md +++ b/docs/integrations/cloud-providers/aws.md @@ -7,219 +7,26 @@ description: >- # Amazon Web Services (AWS) -## Let's Explain - -The AWS integration allows either Spacelift [runs](../../concepts/run/README.md) or [tasks](../../concepts/run/task.md) to automatically [assume an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html){: rel="nofollow"} in your AWS account, and in the process, generate a set of **temporary credentials.** These credentials are then exposed as [computed environment variables](../../concepts/configuration/environment.md#computed-values) during the run/task that takes place on the particular Spacelift stack that the integration is attached to. +The AWS integration allows Spacelift [runs](../../concepts/run/README.md) or [tasks](../../concepts/run/task.md) to automatically [assume an IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html){: rel="nofollow"} in your AWS account, and in the process, generate a set of _temporary credentials_. These credentials are then exposed as [computed environment variables](../../concepts/configuration/environment.md#computed-values) during the run/task that takes place on the Spacelift stack where the integration is attached. - `AWS_ACCESS_KEY_ID` - `AWS_SECRET_ACCESS_KEY` - `AWS_SECURITY_TOKEN` - `AWS_SESSION_TOKEN` -This is enough for both the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables){: rel="nofollow"} and/or [Amazon S3 state backend](https://www.terraform.io/docs/backends/types/s3.html){: rel="nofollow"} to generate a fully authenticated AWS session without further configuration. However, you will likely need to select one of the available regions with the former. - -### Usage - -To utilize the AWS integration, you need to set up at least one cloud integration, and then attach that integration to any stacks that need it. Please follow the [Setup Guide](#setup-guide) for more information on this process. - -## Trust Policy - -When setting up a Spacelift AWS Cloud Integration you need to specify the ARN of an IAM Role to use. The Trust Policy for this role must be configured to allow Spacelift to assume the role and generate temporary credentials. - -When completing the role assumption, Spacelift will pass extra information in the `ExternalId` attribute, allowing you to optionally add additional layers of security to your role. - -**External ID Format:** `@@@` - -- ``: the name of the Spacelift account that initiated the role assumption. -- ``: the ID of the AWS Cloud Integration that initiated the role assumption. -- ``: the slug of the stack that the AWS Cloud Integration is attached to, that initiated the role assumption. -- ``: set to either `read` or `write` based upon the event occurring that has initiated the role assumption. The [Planning phase](../../concepts/run/proposed.md#planning) utilizes `read` while the [Applying phase](../../concepts/run/tracked.md#applying) utilizes `write`. - -## Setup Guide - -Prerequisites: - -- The ability to create IAM Roles in your AWS account. -- Admin access to your Spacelift account. - -### Setup a Role in AWS - -Before creating the Spacelift AWS integration, you need to have an [AWS IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html){: rel="nofollow"} within your AWS account that the cloud integration will use. - -Within your AWS account, navigate to AWS IAM and click the **Create role** button. - -![Within AWS IAM, click Create role](<../../assets/screenshots/integrations/cloud-providers/aws/setup-aws-role.png>) - -!!! hint - To allow this integration to access multiple AWS accounts, you can extend this role to have cross-account permissions to the target accounts. See [AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html){: rel="nofollow"} for more details. - -#### Configure Trust Policy - -Next, we want to configure the [Trust Policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html){: rel="nofollow"} for the role to allow Spacelift to assume the role. - -Here's an example trust policy statement you can use, that allows any stack within your Spacelift account to use this IAM Role: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Action": "sts:AssumeRole", - "Condition": { - "StringLike": { - "sts:ExternalId": "yourSpaceliftAccountName@*" - } - }, - "Effect": "Allow", - "Principal": { - "AWS": "" - } - } - ] -} -``` - -!!! info - Be sure to replace **yourSpaceliftAccountName** in the example above with your actual Spacelift account name. - -{% if is_saas() %} -!!! info - Ensure you replace `` based on your environment. +These temporary credentials are enough for both the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs#environment-variables){: rel="nofollow"} and the [Amazon S3 state backend](https://www.terraform.io/docs/backends/types/s3.html){: rel="nofollow"} to generate a fully authenticated AWS session without further configuration. - - for [spacelift.io](https://spacelift.io), use `324880187172`. - - for [us.spacelift.io](https://us.spacelift.io), use `577638371743`. -{% endif %} +To use the AWS integration, you need to set it up and attach it to any stacks that need it. -#### Optionally Configure Further Constraints on the Trust Policy +## Spacelift UI setup -!!! info - By default, Spacelift passes the `ExternalId` value in this format: `@@@` - -Knowing the format of the External ID passed by Spacelift, you can further secure your IAM Role trust policies if you desire a deeper level of granular security. +See [Integrate Spacelift with Amazon Web Services](../../getting-started/integrate-cloud/AWS.md) to configure your AWS IAM role, trust policy, and the integration within Spacelift. -For example, you may wish to lock down an IAM Role so that it can only be used by a specific stack. The following example shows how to lock down an IAM Role so that it can only be assumed by the stack `stack-a` in a Spacelift account called `example`: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Action": "sts:AssumeRole", - "Condition": { - "StringLike": { - "sts:ExternalId": "example@*@stack-a@*" - } - }, - "Effect": "Allow", - "Principal": { - "AWS": "" - } - } - ] -} -``` - -!!! info - Ensure you replace `` based on your environment. - - - for [spacelift.io](https://spacelift.io), use `324880187172`. - - for [us.spacelift.io](https://us.spacelift.io), use `577638371743`. - -#### Configure Role Permissions - -Next, you need to attach at least one IAM Policy to your IAM Role to provide it with sufficient permissions to deploy any resources that your IaC code defines. - -!!! info - For Terraform users that are managing their own state file, don't forget to give your role sufficient permissions to access your state (Terraform documents the permissions required for S3-managed state [here](https://www.terraform.io/language/settings/backends/s3#s3-bucket-permissions){: rel="nofollow"}, and for DynamoDB state locking [here](https://www.terraform.io/language/settings/backends/s3#dynamodb-table-permissions){: rel="nofollow"}). - -#### Create IAM Role - -Once you have your IAM Role's trust policy and IAM Policies configured, you can finish creating the role. Take a note of the IAM Role ARN, as you'll need this when setting up the integration in Spacelift in the next section. - -![](../../assets/screenshots/integrations/cloud-providers/aws/copy-role-arn.png) - -### Navigate to Cloud Integrations - -Now that you have an IAM Role created, navigate to the _Cloud Integrations_ page from the Spacelift navigation sidebar. - -![Navigate to the Cloud integrations page](<../../assets/screenshots/integrations/cloud-providers/aws/setup-integration-step-1.png>) - -### Create an Integration - -Click on the **Set up integration** button and select **AWS** in the drop-down menu to start configuring your integration: - -![](<../../assets/screenshots/integrations/cloud-providers/aws/setup-integration-step-2.png>) - -When creating an integration, you will immediately notice that you need to specify two required fields: **Name** and **Role ARN.** Give the integration a name of your choosing, and paste in the ARN of the IAM Role that you just created. - -If you enable the **assume role on worker** option, the role assumption will be performed on your private worker rather than at Spacelift's end. When role assumption on the worker is enabled, you can also optionally specify a custom External ID to use during role assumption. - -!!! info - **When creating your role in AWS, you need to ensure the role has a trust policy that allows Spacelift to assume the role to generate temporary credentials for runs.** Assuming you are following this guide, you should have configured this in the [previous section](#configure-trust-policy). For troubleshooting, refer to the [Troubleshooting Trust Relationship Issues](#troubleshooting-trust-relationship-issues) section. - -### Using the Integration - -Now that the integration has been created, you need to attach it to one or more stacks. To do this, navigate to a stack that you want to attach your integration to: - -![](<../../assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-1.png>) - -Next, go to the stack's settings: - -![](<../../assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-2.png>) - -Choose the integrations tab: - -![](<../../assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-3.png>) - -Click **Attach cloud integration** button, then select the **AWS** option, choose your integration, and select whether it should be used for read, write or both read and write phases: - -![](<../../assets/screenshots/integrations/cloud-providers/aws/attach-integration-step-4.png>) - -#### Read vs Write - -You can attach an AWS integration as read, write or read-write, and you can attach at most two integrations to any single stack. **Read** indicates that this integration will be used during read phases of runs (for example, plans), and **Write** indicates that this integration will be used during write phases of runs (for example, applies). - -#### Role Assumption Verification - -If the Cloud Integration has the "Assume Role on Worker" setting disabled, Spacelift will verify the role assumption as soon as you click the attach button. If role assumption succeeds, it will try to assume the role **without the unique external ID**, and this time it **expects to fail**. If Spacelift fails the latter check, we consider the integration is safely configured. - -!!! success - This somewhat counterintuitive extra check is to prevent against malicious takeover of your account by someone who happens to know your AWS account ID, which isn't all that secret, really. The security vulnerability we're addressing here is known as the [_confused deputy problem_](https://en.wikipedia.org/wiki/Confused_deputy_problem){: rel="nofollow"}. - -### Troubleshooting Trust Relationship Issues - -If you get the error `you need to configure trust relationship section in your AWS account` when attaching a cloud integration to a stack: - -![](../../assets/screenshots/integrations/cloud-providers/aws/trust-policy-error.png) - -There are a couple of common causes to check. - -#### Incorrect or Missing Trust Relationship Policy - -The error message in the UI includes a tailored trust relationship policy example. This policy allows Spacelift to assume the IAM role and must be added to the **Trust relationships** section of your role in AWS IAM. Check [previous section](#configure-trust-policy) for more information on how to configure the trust policy. - -#### STS (Security Token Service) Not Enabled - -{% if is_saas() %} -This error can occur if the [AWS STS (Security Token Service)](https://spacelift.io/blog/aws-sts) is not enabled in your account. - -Make sure STS is enabled in the following regions: - -- **eu-west-1** -- **eu-central-1** (used for disaster recovery failover) - -You can enable STS by following [this AWS guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate){: rel="nofollow"}. -{% endif %} - -{% if is_self_hosted() %} -This error can be caused by STS not being enabled in the AWS region where your Spacelift instance is deployed. Check your region settings and ensure STS is active. Learn more about [AWS STS here](https://spacelift.io/blog/aws-sts). -{% endif %} - -## Programmatic Setup +## Programmatic setup You can also use the [Spacelift Terraform provider](../../vendors/terraform/terraform-provider.md) in order to create an AWS Cloud integration from an [administrative stack](../../concepts/stack/stack-settings.md#administrative), including the trust relationship. Note that in order to do that, your administrative stack will require AWS credentials itself, and ones powerful enough to be able to deal with IAM. -Here's a little example of what that might look like to create a Cloud Integration programmatically: +Here's an example of what it might look like to create an AWS cloud integration programmatically: ```terraform data "aws_caller_identity" "current" {} @@ -283,9 +90,9 @@ resource "spacelift_aws_integration_attachment" "this" { !!! info Please always refer to the [provider documentation](https://github.com/spacelift-io/terraform-provider-spacelift){: rel="nofollow"} for the most up-to-date documentation. -### Attaching a Role to Multiple Stacks +### Attach a role to multiple stacks -The previous example explained how to use the `spacelift_aws_integration_attachment_external_id` data-source to generate the assume role policy for using the integration with a single stack, but what if you want to attach the integration to multiple stacks? The simplest option would be to create multiple instances of the data-source - one for each stack - but you can also use a Terraform `for_each` condition to reduce the amount of code required: +The previous example explained how to use the `spacelift_aws_integration_attachment_external_id` data-source to generate the assume role policy for using the integration with a single stack, but what if you want to attach the integration to multiple stacks? The simplest option would be to create multiple instances of the data-source (one for each stack) but you can also use a Terraform `for_each` condition to reduce the amount of code required: ```terraform locals { @@ -365,35 +172,35 @@ This will generate a trust relationship that looks something like this: } ``` +{% if is_saas() %} !!! info - The value of `` will be based on your environment. - - for [spacelift.io](https://spacelift.io), it will be `324880187172`. - - for [us.spacelift.io](https://us.spacelift.io), it will be `577638371743`. + Make sure to replace: + - `spacelifter` with your actual Spacelift account name. + - `` based on your environment: + - for [spacelift.io](https://spacelift.io), use `324880187172`. + - for [us.spacelift.io](https://us.spacelift.io), use `577638371743`. +{% endif %} -## Is it safe? +## Are my credentials safe? -Assuming roles and generating credentials **on the private worker** is **perfectly safe**. Those credentials are never leaked to us in any shape or form. Hence, the rest of this section discusses the trust relationship established between the Spacelift account and your AWS account for the purpose of dynamically generating short-lived credentials. So, how safe is that? +Assuming roles and generating credentials **on private worker** is perfectly safe. Those credentials are never leaked to us in any shape or form. -Probably safer than storing static credentials in your stack environment. Unlike user keys that you'd normally have to use, role credentials are dynamically created and short-lived. We use the default expiration which is **1 hour**, and do not store them anywhere. Leaking them **accidentally** through the logs is not an option either because we mask AWS credentials. +As for the trust relationship established between the Spacelift account and your AWS account for the purpose of dynamically generating short-lived credentials, this is considered much safer than storing static credentials in your stack environment. Unlike user keys that you'd normally have to use, role credentials are dynamically created and short-lived. We use the default expiration which is **1 hour**, and do not store them anywhere. Leaking them **accidentally** through the logs is not an option either because we mask AWS credentials. The most tangible safety feature of the AWS integration is the breadcrumb trail it leaves in [CloudTrail](https://aws.amazon.com/cloudtrail/){: rel="nofollow"}. Every resource change can be mapped to an individual Terraform [run](../../concepts/run/README.md) or [task](../../concepts/run/task.md) whose ID automatically becomes the username as the [`sts:AssumeRole`](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html){: rel="nofollow"} API call with that ID as `RoleSessionName`. In conjunction with AWS tools like [Config](https://aws.amazon.com/config/){: rel="nofollow"}, it can be a very powerful compliance tool. Let's have a look at a CloudTrail event showing an IAM role being created by what seems to be a Spacelift run: -![](../../assets/screenshots/integrations/cloud-providers/aws/cloud-trail-management-console.png) +![](<../../assets/screenshots/integrations/cloud-providers/aws/cloud-trail-management-console.png>) -`01DSJ63P40BAZY4VW8BXXG7M4K` is indeed a run ID we can then trace back even further. +`01DSJ63P40BAZY4VW8BXXG7M4K` is a run ID we can then trace back even further. ## Roles assuming other roles -OK, we get it. Using everyone's favorite Inception meme: - -![](../../assets/screenshots/integrations/cloud-providers/aws/inception-meme.png) - -Indeed, the AWS Terraform provider allows you to [assume an IAM role during setup](https://www.terraform.io/docs/providers/aws/index.html#assume-role){: rel="nofollow"}, effectively doing the same thing over again. This approach is especially useful if you want to control resources in multiple AWS accounts from a single Spacelift stack. This is totally fine - in IAM, roles can assume other roles, though what you need to do on your end is set up the trust relationship between the role you have Spacelift assume and the role for each provider instance to assume. But let's face it - at this level of sophistication, you sure know what you're doing. +The AWS Terraform provider allows you to [assume an IAM role during setup](https://www.terraform.io/docs/providers/aws/index.html#assume-role){: rel="nofollow"}, effectively doing the same thing over again. This approach is especially useful if you want to control resources in multiple AWS accounts from a single Spacelift stack. This is totally fine; in IAM, roles can assume other roles, though you need to set up the trust relationship between the role you have Spacelift assume and the role for each provider instance to assume. -One bit you might not want to miss though, is the guaranteed ability to map the change to a particular [run](../../concepts/run/README.md) or [task](../../concepts/run/task.md) that we described in the [previous section](#is-it-safe). One way of fixing that would be to use the `TF_VAR_spacelift_run_id` [computed environment variable](../../concepts/configuration/environment.md#computed-values) available to each Spacelift workflow. Conveniently, it's already a [Terraform variable](https://www.terraform.io/docs/configuration/variables.html#environment-variables){: rel="nofollow"}, so a setup like this should do the trick: +One thing you want to watch is the guaranteed ability to map the change to a particular [run](../../concepts/run/README.md) or [task](../../concepts/run/task.md) that we described in the [previous section](#are-my-credentials-safe). One way of fixing this would be to use the `TF_VAR_spacelift_run_id` [computed environment variable](../../concepts/configuration/environment.md#computed-values) available to each Spacelift workflow. It's already a [Terraform variable](https://www.terraform.io/docs/configuration/variables.html#environment-variables){: rel="nofollow"}, so you can set it up like this: ```terraform variable "spacelift_run_id" {} diff --git a/markdown-link-check.json b/markdown-link-check.json index 9e3fdf9ad..3fc3b9c29 100644 --- a/markdown-link-check.json +++ b/markdown-link-check.json @@ -50,6 +50,18 @@ }, { "pattern": "^https://feedback.spacelift.io/" + }, + { + "pattern": "^https://aur.archlinux.org/packages/spacectl-bin/" + }, + { + "pattern": "^https://aur.archlinux.org/" + }, + { + "pattern": "^https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=spacectl-bin" + }, + { + "pattern": "^https://api.github.com/" } ] } \ No newline at end of file diff --git a/nav.self-hosted.yaml b/nav.self-hosted.yaml index 32fc12865..b7fad6993 100644 --- a/nav.self-hosted.yaml +++ b/nav.self-hosted.yaml @@ -58,11 +58,9 @@ nav: - concepts/stack/creating-a-stack.md - concepts/stack/stack-settings.md - concepts/stack/organizing-stacks.md - - concepts/stack/stack-locking.md - concepts/stack/stack-dependencies.md - concepts/stack/drift-detection.md - concepts/stack/scheduling.md - - concepts/stack/deleting-a-stack.md - Blueprint: - concepts/blueprint/README.md - Configuration: diff --git a/nav.yaml b/nav.yaml index 6781efc1e..a869c1497 100644 --- a/nav.yaml +++ b/nav.yaml @@ -24,11 +24,9 @@ nav: - concepts/stack/creating-a-stack.md - concepts/stack/stack-settings.md - concepts/stack/organizing-stacks.md - - concepts/stack/stack-locking.md - concepts/stack/stack-dependencies.md - concepts/stack/drift-detection.md - concepts/stack/scheduling.md - - concepts/stack/deleting-a-stack.md - Blueprint: - concepts/blueprint/README.md - Configuration: