Output files

Please make sure you NEVER commit your terraform state file in your version control. Read more about what files you could or couldn't commit on this section.

Stackmate generates configuration files when running any of its commands. Let's break them down and see what can be committed to source control and what not.

The default location would be right next to your configuration file, but you can specify a different directory when running the commands, for example:

npx @stackmate/stackmate -c myconfig.yml -d stackmate/

Assuming that you are deploying a simple web application, you can use .stackmate as a configuration directory that holds your config.yml configuration file and the generated stacks.

my-project
│   ...
├── .stackmate
│   └── config.yml
├── ...
└── index.html

What files are generated by stackmate

When running any stackmate command, the following files get generated:

• Project stacks - Stackmate generates a set of JSON files, which are then used by Terraform to deploy your stacks. These are generated by CDKTF and further documentation can be found on CDKTF's documentation page.

• Terraform state files - Whether we're storing our project's state locally or not, terraform will be creating a state file to use for subsequent deployments.

• Terraform internal files - When using stackmate, we run Terraform for you, which creates a set files used internally.

An example structure of the files created, is illustrated below:

my-project
│   ...
├── .stackmate
│   │   stacks/
│   │   └── production
│   │        ├── .terraform
│   │        │     ├── providers
│   │        │     └── terraform.tfstate
│   │        ├── .terraform.lock.hcl
│   │        ├── main.tf.json
│   │        └── plan # optionally, if you run stackmate preview
│   │         
│   └── config.yml
├── ...
└── index.html

Should I commit the files that are generated by Stackmate?

The one thing to keep in mind is NEVER, never, never, EVER commit your state on your source control.

The reason for stressing this so much is that your Terraform state contains sensitive information about your infrastructure, which you don't want to fall into the wrong hands. Even if you're working solo, you should still avoid committing this file into source control because if for example your GitHub account gets compromised and your private repository is checked out, the attackers would also gain access to your entire infrastructure too.

One file you could consider committing to source control, is the .terraform.lock.hcl file, which is the dependency lock file for Terraform. This file is used by Terraform to download providers locally while running operations (for example the AWS provider) and it's practically forcing Terraform to use a specific provider version. Otherwise, Terraform uses the most recent provider version. You can learn more on this Terraform documentation page.

The rest of the files are up to you too but you could have a look on the file's contents first. For convenience, we have a list of files you could append to .gitignore :

# file: .gitignore
stacks/
*.tfstate
.terraform.lock.hcl

Where does stackmate keep my secrets?

Stackmate doesn't know anything about your secrets. They're generated when you deploy a stage as random values and they're safely stored in your provider's credentials service (for example AWS secrets store)