Sharing Cluster State


In order to instantiate cloud-based hardware the OKD Orchestrator relies on Terraform, an infrastructure as code provisioning tool by HashiCorp.

Terraform is a powerful tool that uses a declarative language, i.e. language where you tell it what you want and it does what’s required, in the right order, to satisfy your needs.

As a side-effect, Terraform creates state files in order to track the objects it creates. These files are kept in the orchestrator’s terraform directory and it’s therefore extremely important not to remove them. If lost Terraform will have difficulty adjusting or removing your cluster hardware.

The disadvantage of storing state files in the terraform directory is that only you can manage (and destroy) the cluster and, importantly, you have to keep the files until you do destroy the cluster.

Shared state storage

Instead of storing state files on your workstation you can use Terraform’s built-in remote state storage and locking feature.

For a detailed discussion of state storage and locking refer to Terraform’s own comprehensive State Storage and Locking documentation.


the OKD Orchestrator exposes the ability to store Terraform state in an AWS S3 bucket 1. You do this by defining the terraform_shared_state properties in your deployment configuration.

Before you can use shared state storage you will need to create a bucket on S3 and a related DynamoDB table, which provides state locking (preventing concurrent cluster modifications).

You need to provide the following and add the details to your deployment configuration. The properties are documented in the example compact-aws-frankfurt-3-11 configuration

  • An S3 bucket (which is a unique name in AWS)

  • A key in the bucket (a name in your bucket)

  • A dynamo DB table with a primary key string called LockID. The table name and the database region goes into your configuration.



Other backend types may be supported in future releases.