Amazon S3 Remote State

Create an account

In order to create an AWS account you will need to provide a credit card. Amazon S3 provides a generous free tier which you are very unlikely to reach the limits of while using Mantle, but you should always monitor your usage to make sure you do not incur unexpected costs.

Create an AWS account from their sign up page (opens in a new tab).

Create an S3 bucket

From the AWS console, click the search bar at the top of the page and search for "S3" and select the S3 service.

From the "Buckets" tab, click the "Create bucket" button. Give your bucket a name like {your-name}-mantle-states and select an AWS region that is near your location. Ensure "Block all public access" is checked to keep your data private.

In the future, Mantle may support object locking, so you may want to expand "Advanced settings" and enable "Object lock" so that you will not need to re-create your bucket later.

Click "Create bucket" to finish creating your bucket.

Upload your existing state file

If you are migrating an existing project from local state files to remote, you will need to upload your state file to your bucket.

Before you do so though you need to pick your project name which will be used for the name of the state file in your bucket and in your Mantle configuration in the next step.

Rename your local state file to {project-name}.mantle-state.yml, then upload it to your bucket. From the S3 buckets tab, click on your new bucket's name, then click the "Upload" button. Click "Add files" and open your renamed state file. Click "Upload" to finish uploading the state file.

Configure your Mantle project

Head back to your Mantle config file and add the state configuration:

# ...your existing configuration
state:
  remote:
    region: [<aws-region>]
    bucket: <bucket-name>
    key: <project-name>

• Replace <aws-region> with the region you selected when you created your bucket (e.g. us-west-2).
• Replace <bucket-name> with the name you selected when you created your bucket.
• Replace <project-name> with the name of your project. This will be used to name the state file in your bucket. For example, if you supply pirate-wars it will create a pirate-wars.mantle-state.yml file in your bucket.

Supply your AWS credentials

At this point if you were to run mantle deploy it would attempt to download your state file from S3 but it would fail because you have not provided any authorization for your bucket.

You can read the Authentication guide for information on supplying your AWS credentials.

Once supplied, you can run mantle deploy or any other commands and they will operate on your remote state file! If you were migrating from local state to remote state, you should delete the .mantle-state.yml file from your Git repo as it will be unused and out of date.