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

The necessary IAM permissions for S3 and DynamoDB.

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>"
    }
  ]
}