Amazon Web Services (AWS)

This page describes Spacelift's native integration with AWS, which allows users to generate short-lived credentials for runs and tasks orchestrated by Spacelift.

Let's Explain

The AWS integration allows either Spacelift runs or tasks to automatically assume an IAM role in your AWS account, and in the process, generate a set of temporary credentials. These credentials are then exposed as computed environment variables during the run/task that takes place on the particular Spacelift stack that the integration is attached to.

• AWS_ACCESS_KEY_ID

• AWS_SECRET_ACCESS_KEY

• AWS_SECURITY_TOKEN

• AWS_SESSION_TOKEN

This is enough for both the AWS Terraform provider and/or S3 state backend 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'll need to setup at least one cloud integration, and then attach that integration to any stack(s) that you'd like to have utilize that integration. Please follow the Setup Guide for more information on this process.

Trust Policy

When setting up a Spacelift AWS Cloud Integration you'll need to specify the ARN of an IAM Role to use. This role, will need to have its Trust Policy 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:

<spacelift-account-name>@<integration-id>@<stack-slug>@<read|write>

• <spacelift-account-name>

  • The name of the Spacelift account that initiated the role assumption.

• <integration-id>

  • The ID of the AWS Cloud Integration that initiated the role assumption.

• <stack-slug>

  • The slug of the stack that the AWS Cloud integration is attached to, that initiated the role assumption.

• <read|write>

  • This will either be set to read or write based upon the event occurring that has initiated the role assumption.

    • Planning: Utilizes read

    • Applying: Utilizes write

Setup Guide

Pre-Requisites:

• Ability to create IAM Roles in your AWS account.

• Admin access to your Spacelift account.

Setup a Role in AWS

First things first - before proceeding, you'll want to have an AWS IAM Role within your AWS account that we will be configuring this cloud integration to use.

Navigate to AWS IAM

Within your AWS account, navigate to AWS IAM and click the Create role button.

Within AWS IAM, click Create role

Configure Trust Policy

Next, we want to configure the Trust Policy for the role to allow Spacelift to assume the role.

Here's the format of a custom trust policy statement you can use, that allows any stack within your Spacelift account to use this IAM Role:

{
	"Version": "2012-10-17",
	"Statement": [
          {
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringLike": {
                "sts:ExternalId": "yourSpaceliftAccountName@*"
              }
            },
            "Effect": "Allow",
            "Principal": {
              "AWS": "324880187172"
            }
          }
	]
}

Be sure to replace yourSpaceliftAccountName in the example above with your actual Spacelift account name.

Configure a Custom Trust Policy on the IAM Role

Optionally Configure Further Constraints on the Trust Policy

By default, Spacelift passes the ExternalId value in this format:

<spacelift-account-name>@<integration-id>@<stack-slug>@<read|write>

Knowing the format of the external id passed by Spacelift, users can further secure their IAM Role trust policies if they desire a deeper level of granular security.

For example, users may wish to lock down an IAM Role, to only be used by a specific stack (e.g. stack-a in their Spacelift account example). In such a case, they could add the stack-slug into their Trust Policy like so:

{
	"Version": "2012-10-17",
	"Statement": [
          {
            "Action": "sts:AssumeRole",
            "Condition": {
              "StringLike": {
                "sts:ExternalId": "example@*@stack-a@*"
              }
            },
            "Effect": "Allow",
            "Principal": {
              "AWS": "324880187172"
            }
          }
	]
}

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.

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, and for DynamoDB state locking here).

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.

Navigate to Cloud Integrations

Now that you have an IAM Role created, navigate to the Cloud Integration page from the Spacelift navigation sidebar.

Navigate to the Cloud integrations page

Create an Integration

Click the button to begin the creation of your first integration.

When creating an integration, you'll 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 we just created.

When assuming the role on private workers, the process is straightforward: you provide the IAM role to assume, and, optionally, an external ID.

When creating your role in AWS, you'll 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.

Note that we have no way of validating whether your worker has the ability to assume the said role. You will need to trigger a job to verify that.

Using the Integration

Now that you've created the integration, we need to attach it to the Spacelift Stack that you wish to use this integration.

Navigate to Chosen Stack

This part's up to you - navigate to a stack that you wish to attach the integration you just created to.

Navigate to Settings of the Stack

Select the Integrations Tab

Select the AWS Integration Option, and Select your Integration

Read indicates that this integration will be used during read phases of runs (for example, plans).

Write indicates that this integration will be used during write phases of runs (for example, applies).

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.

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.

Programmatic Setup

You can also use the Spacelift Terraform provider in order to create an AWS Cloud integration from an administrative stack, 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:

example.tf

data "aws_caller_identity" "current" {}

locals {
  role_name = "example-role"
  role_arn  = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:role/${local.role_name}"
}

resource "spacelift_stack" "this" {
  name         = "Example Stack"
  repository   = "your-awesome-repo"
  branch       = "main"
}

resource "spacelift_aws_integration" "this" {
  name = local.role_name

  # We need to set this manually rather than referencing the role to avoid a circular dependency
  role_arn                       = local.role_arn
  generate_credentials_in_worker = false
}

data "spacelift_aws_integration_attachment_external_id" "this" {
  integration_id = spacelift_aws_integration.this.id
  stack_id       = spacelift_stack.this.id
  read           = true
  write          = true
}

resource "aws_iam_role" "this" {
  name = local.role_name

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      jsondecode(data.spacelift_aws_integration_attachment_external_id.this.assume_role_policy_statement),
    ]
  })
}

resource "aws_iam_role_policy_attachment" "this" {
  policy_arn = "arn:aws:iam::aws:policy/PowerUserAccess"
  role       = aws_iam_role.this.name
}

resource "spacelift_aws_integration_attachment" "this" {
  integration_id = spacelift_aws_integration.this.id
  stack_id       = spacelift_stack.this.id
  read           = true
  write          = true

  # The role needs to exist before we attach since we test role assumption during attachment.
  depends_on = [
    aws_iam_role.this
  ]
}

Please always refer to the provider documentation for the most up-to-date documentation.

Is it safe?

Assuming role 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?

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.

The most tangible safety feature of the AWS integration is the breadcrumb trail it leaves in CloudTrail. Every resource change can be mapped to an individual Terraform run or task whose ID automatically becomes the username as the sts:AssumeRole API call with that ID as RoleSessionName. In conjunction with AWS tools like Config, 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:

01DSJ63P40BAZY4VW8BXXG7M4K is indeed a run ID we can then trace back even further:

Roles assuming other roles

OK, we get it. Using everyone's favorite Inception meme:

Indeed, AWS Terraform provider allows you to assume an IAM role during setup, 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.

One bit you might not want to miss though, is the guaranteed ability to map the change to a particular run or task that we described in the previous section. One way of fixing that would be to use the TF_VAR_spacelift_run_id computed environment variable available to each Spacelift workflow. Conveniently, it's already a Terraform variable, so a setup like this should do the trick:

aws.tf

variable "spacelift_run_id" {}

# That's our default provider with credentials generated by Spacelift.
provider "aws" {}

# That's where Terraform needs to run sts:AssumeRole with your
# Spacelift-generated credentials to obtain ones for the second account.
provider "aws" {
  alias = "second-account"

  assume_role {
    role_arn     = "<up-to-you>"
    session_name = var.spacelift_run_id
    external_id  = "<up-to-you>"
  }
}