Skip to main content
If your team manages AWS with Terraform, you can install and upgrade the HYOK stack with a Terraform module from Corsa instead of the CloudFormation console. The stack is still a CloudFormation stack, and the module deploys it for you. Everything the console install does still happens: the stack verifies the signed release, only signed code runs, your keys are protected from replacement, and the stack registers with Corsa.

​
Before you start

  • Everything in Set up HYOK → Before you start.
  • Terraform 1.5 or later, and the hashicorp/aws provider 6.0 or later.
  • Credentials in the AWS account and region you declare to Corsa, with permission to deploy the stack. Settings → Encryption → Review resources lists everything the stack creates.
  • An encrypted remote state backend, such as S3 with KMS or HCP Terraform. See Secrets and state.

​
How it works

  • Prepared for your workspace. Corsa gives you the module and a template prepared for your workspace and the release you reviewed. You commit them to your repository. They hold no secret.
  • Checks before anything changes. The plan fails if the files don’t match what Corsa shows, if they were issued for another release, or if your AWS provider is in another account or region than the one you declared.
  • Protected keys. Terraform updates follow the stack’s built-in protection. An update that would replace your keys or your Cognito users fails, and CloudFormation rolls it back.
  • Deletion. The module prevents Terraform from destroying the stack. Your HYOK data depends on the keys it holds.

​
Install

1

Start HYOK setup in Corsa

A workspace Owner opens Settings → Encryption, selects HYOK, chooses the fields to encrypt, declares the AWS account and region, and chooses the identity provider, as in the console setup.
2

Choose Terraform

In the deploy step, choose Terraform. Corsa marks your stack as managed with Terraform and shows:
  • Download Terraform module: the module from the signed release.
  • Download template: the stack definition for your workspace.
  • The values to enter in your Terraform configuration.
  • The single-use callback token, shown once.
  • The time by which you must start terraform apply.
3

Add the module

Save the module and the template in your repository. Add the module to your Terraform configuration and enter the values Corsa shows, as described on the setup screen.
4

Apply with the callback token

Pass the callback token from your shell or CI secret store, never from a file. The setup screen shows the variable to use. Then run terraform init and terraform apply.Start the apply before the time Corsa shows. If the time has passed, click Re-issue template in Corsa, which also issues a new token.The first install takes about 20 minutes. Corsa shows the progress as with a console install.
5

Remove the token and apply again

The token is used up once the stack registers. Remove it from your environment and run terraform apply once more, so the stack deletes its copy of the token. Terraform shows a warning until you do this.
6

Finish setup

Continue as in the console guide: register the first administrator in the Secure Viewer (or sign in with your identity provider), then add decryptors.

​
Upgrade

Corsa never upgrades a stack managed with Terraform. It hides Upgrade stack and shows Get Terraform template instead.
1

Review the new release

Settings → Encryption shows the installed and latest releases, the release label and changelog, and a link to the source diff. See Upgrades.
2

Get the new files

Click Get Terraform template for the release. Download the new files, update the values Corsa shows, and open a pull request. The diff shows exactly what changes in your stack.
3

Optional: check the upgrade first

Run the pre-upgrade check Corsa shows from your Terraform directory. It fails if the upgrade would replace or remove your keys or your Cognito users. Nothing is applied.
4

Apply

Run terraform apply before the time Corsa shows. When the stack reports the new release, Corsa shows it as installed.
5

Verify the running stack

Run the running-stack check Corsa shows. See Level 3: Check the running stack.

​
Roll back

You can roll back to the release installed just before the current one. Apply that release’s files again, either by reverting the commit in your repository or with Get Terraform template for that release in Corsa. The stack keeps a copy of the previous release in your account, so it doesn’t need to download it again. Corsa doesn’t accept older releases.

​
Secrets and state

  • The files from Corsa are safe to commit. They hold your workspace ID, Corsa endpoints, release digests, and a release link that expires within hours.
  • The callback token is a secret until it’s used. Pass it for the install only. Corsa issues a new one each time you re-issue the template.
  • State. After the install, Terraform state shows the token as ****. A saved plan of the install apply holds it in plain text: don’t keep that file, and use an encrypted remote backend.

​
Move a console-installed stack to Terraform

1

Mark the stack as managed with Terraform

In Settings → Encryption, an Owner turns on Managed with Terraform.
2

Get the files for your installed release

Click Get Terraform template for the release you already run, and add the module as in Install, without a callback token.
3

Import and apply

Import your existing stack into Terraform as the setup screen describes, then run terraform apply. The stack keeps its release.

​
Limitations

  • Switching from Cognito to your own OIDC provider removes your Cognito users, which the stack’s protection denies. Contact Corsa support first.
  • Termination protection. The AWS provider can’t set it. Turn it on once for the stack in the CloudFormation console.
  • Don’t mix tools. Don’t run console change sets on a stack managed with Terraform. Terraform would overwrite them on the next apply.