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