store block reference

Use the store block to access the values of HCP Terraform variable sets in your deployment configuration and use those secrets in deployments.

Background

In HCP Terraform, variable sets are collections of reusable variables that you can assign to multiple workspaces or Stacks. Variable sets help you manage common configuration values, such as API keys or database passwords, across different environments.

The store block lets you access a variable set from your deployment configuration. When defining a store block, you specify the variable set you want to access and the type of variables you want to retrieve. If you want to access both Terraform and environment variables from the same variable set, you must define two separate store blocks.

By default, variable set values are ephemeral in a Stack deployment. Terraform uses variable set values during the current operation, but does not store them in your deployment's state. To avoid this behavior you can use the stable keyword. To learn more, refer to Persist store values for deployments.

Your Stack must have access to the variable set you are targeting, meaning it must be globally available or assigned to the project containing your Stack or the Stack itself.

Configuration model

The store block supports the following arguments based on store type:

• store "<STORE_TYPE>" "<LABEL>"   block
  • id   string | mutually exclusive with name
  • name   string | mutually exclusive with id
  • category   string

Complete configuration

All available arguments are defined in the following store block:

store "<STORE_TYPE>" "<LABEL>" {
  id       = "<VARIABLE_SET_ID>" # mutually exclusive with name
  name     = "<VARIABLE_SET_NAME>" # mutually exclusive with id
  category = "<terraform|env>"
}

You must define either id or name in your store block, but not both. After defining a store block you can reference specific variables within the associated variable set using store.<STORE_TYPE>.<STORE_LABEL>.<VARIABLE_NAME> syntax.

Specification

A store block supports the following configuration.

store "<STORE_TYPE>" "<LABEL>"

The store block requires two labels: the store type and a unique name for the store within your deployment configuration. The varset store type is the only available store type.

The store label can be any valid identifier and must be unique among all stores in the same deployment configuration file.

varset store type

Use the varset store type to let your Stacks access variable sets in HCP Terraform. Your Stack must have access to the variable set you are targeting, meaning it must be globally available, assigned to the project containing your Stack, or assigned to the Stack itself.

After referencing a value from a variable set, HCP Terraform discards that value and does not store it in deployment state. To persist a variable set value in your deployment state, you must explicitly use the stable keyword. To learn more, refer to Persist store values for deployments.

Arguments

The following arguments are supported for the varset store type:

id

The id argument specifies the external ID of the variable set you want to access. You can find this ID in the HCP Terraform UI or by using the HCP Terraform API.

store "varset" "<LABEL>" {
  id       = "<VARIABLE_SET_ID>"
  category = "<terraform|env>"
}

Summary

• Data type: String
• Default: None
• Required: Yes, if name not specified.

name

The name argument specifies the name of the variable set you want to access. You can find the variables set name in the HCP Terraform UI or by using the HCP Terraform API.

store "varset" "<LABEL>" {
  name     = "<VARIABLE_SET_NAME>"
  category = "<terraform|env>"
}

Summary

• Data type: String
• Default: None
• Required: Yes, if id not specified.

category

The category argument specifies whether to use Terraform variables or environment variables from the variable set. Specify either "terraform" or "env" depending on the type of variables you want to access.

store "varset" "<LABEL>" {
  id       = "<VARIABLE_SET_ID>"
  category = "<terraform|env>"
}

Each store block can only access one category of variables. If you need to access both Terraform and environment variables from the same variable set, define two separate store blocks.

Summary

• Data type: String
• Default: None
• Required: Yes

Examples

The following examples demonstrate common use cases for store blocks.

Define a store and access variables

The following example defines a varset store named api_keys that accesses a variable set named api_keys_default_project:

store "varset" "api_keys" {
  name       = "api_keys_default_project"
  category = "terraform"
}

deployment "production" {
  inputs = {
    database_password = store.varset.api_keys.db_password
    api_key           = store.varset.api_keys.external_api_key
  }
}

The production deployment accesses the db_password and external_api_key variables from the api_keys store to authenticate the providers for that deployment. After defining a store, use the syntax store.<STORE_TYPE>.<STORE_NAME>.<VARIABLE_NAME> to reference specific variables.

Persist store values for deployments

By default, Stacks deployments do not save the values of variable sets into their state. This is because variable set values usually include sensitive data, such as passwords or API keys. For variables that need to persist in your deployment state, such as license keys, you can use the stable keyword.

To store a variable set value in the state of your deployment, append .stable when referencing that variable from your store:

store.varset.<STORE_NAME>.stable.<VARIABLE_NAME>

The stable keyword tells Terraform to store that variable value in the state of your deployment, so the deployment can reference that value later.

In the following example, the licenses store accesses a variable set named CONSUL_LICENSES to retrieve a Consul license key:

store "varset" "licenses" {
  name     = "CONSUL_LICENSES"
  category = "terraform"
}

store "varset" "credentials" {
  name     = "GCP_CREDS"
  category = "terraform"
}

deployment "production" {
  inputs = {
    gcp_credentials = store.varset.credentials.gcp_service_account_key
    consul_license  = store.varset.licenses.stable.consul_license_key
  }
}

HCP Terraform stores the value of consul_license_key in the state of the production deployment, but does not store the value of gcp_service_account_key because it is not marked as stable. Note that you cannot change the value of consul_license_key after it has been marked as stable.

After referencing a value from a variable set using the stable keyword, you cannot reference that same value again in your deployment configuration without stable. For example, the following configuration is invalid because it references consul_license_key twice:

deployment "production" {
  inputs = {
    consul_license_non_ephemeral = store.varset.licenses.stable.consul_license_key
    consul_license_ephemeral = store.varset.licenses.consul_license_key
  }
}

Variable set access using name

In the following example, the api_config store accesses a variable set by its name in HCP Terraform, API_CONFIGURATION:

store "varset" "api_config" {
  name     = "API_CONFIGURATION"
  category = "terraform"
}

deployment "production" {
  inputs = {
    api_endpoint = store.varset.api_config.endpoint_url
    api_timeout  = store.varset.api_config.timeout_seconds
  }
}

Separate Terraform and environment variables

In the following example, two store blocks access the same variable set, but one store retrieves Terraform variables and the other retrieves environment variables:

store "varset" "terraform_vars" {
  id       = "varset-abc123def456"
  category = "terraform"
}

store "varset" "env_vars" {
  id       = "varset-abc123def456"
  category = "env"
}

deployment "production" {
  inputs = {
    # From Terraform variables
    instance_count    = store.varset.terraform_vars.instance_count
    database_password = store.varset.terraform_vars.db_password

    # From environment variables
    log_level         = store.varset.env_vars.LOG_LEVEL
    debug_mode        = store.varset.env_vars.DEBUG_ENABLED
  }
}

When defining a store block, you specify the variable set you want to access and the type of variables you want to retrieve. If you want to access both Terraform and environment variables from the same variable set, you must define two separate store blocks.