S3 backend configuration reference

Introduction

Lokomotive supports remote backend (S3 only) for storing Terraform state. Lokomotive also supports optional state locking feature for S3 backend.

Backend configuration is OPTIONAL. If no backend configuration is provided then local backend is used.

NOTE: lokoctl does not support multiple backends, configure only one.

Prerequisites

  • AWS S3 bucket to be used should already be created. You can do this by running the following AWS CLI command:
aws s3 mb s3://kinvolk-lokomotive-test --region=eu-central-1
  • DynamoDB table to be used for state locking should already be created. The table must have a primary key named LockID. You can create it with the following AWS CLI command:
aws dynamodb create-table --table-name kinvolk-lokomotive-test \
--attribute-definitions AttributeName=LockID,AttributeType=S \
--key-schema AttributeName=LockID,KeyType=HASH \
--billing-mode=PAY_PER_REQUEST

Configuration

To use a backend, we need to define a configuration in the .lokocfg file.

Example configuration file s3_backend.lokocfg:

backend "s3" {
  bucket         = "<bucket_name>"
  key            = "<path_in_s3_bucket>"
  region         = "<aws_region>"
  aws_creds_path = "<aws_credentials_file_path>"
  dynamodb_table = "<dynamodb_table_name>"
}

Attribute reference

Argument Description Default Type Required
backend.s3 AWS S3 backend configuration block. - object false
backend.s3.bucket Name of the S3 bucket where Lokomotive stores cluster state. - string true
backend.s3.key Path in the S3 bucket to store the cluster state. - string true
backend.s3.region AWS Region of the S3 bucket. - string false
backend.s3.aws_creds_path Path to the AWS credentials file. - string false
backend.s3.dynamodb_table Name of the DynamoDB table for locking the cluster state. The table must have a primary key named LockID. - string false

NOTE: In order for the installer to configure the credentials for S3 backend either pass them as environment variables or in the config above.

NOTE: If no value is passed for dynamodb_table, installer will not use the state locking feature.

IAM permissions

The following permissions are required for using the AWS S3 backend:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<BUCKET_NAME>"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>/<KEY>"
    }
  ]
}

When using state locking, that is, when the backend.s3.dynamodb_table option is specified, the following permissions are required as well:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:DeleteItem"
      ],
      "Resource": "arn:aws:dynamodb:*:*:table/<TABLE_NAME>"
    }
  ]
}