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