store block reference

Use thestore 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.

Thestore block lets you access a variable set from your deployment configuration. When defining astore 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 separatestore 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 thestable keyword. To learn more, refer toPersist 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

Thestore block supports the following arguments based on store type:

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

Complete configuration

All available arguments are defined in the followingstore 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 eitherid orname in yourstore block, but not both. After defining astore block you can reference specific variables within the associated variable set usingstore.<STORE_TYPE>.<STORE_LABEL>.<VARIABLE_NAME> syntax.

Specification

Astore block supports the following configuration.

store "<STORE_TYPE>" "<LABEL>"

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

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

varset store type

Use thevarset store type to let your Stacks accessvariable 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 thestable keyword. To learn more, refer toPersist store values for deployments.

Arguments

The following arguments are supported for thevarset store type:

id

Theid 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, ifname not specified.

name

Thename 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, ifid not specified.

category

Thecategory argument specifies whether to useTerraform 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>"}

Eachstore 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 separatestore blocks.

Summary

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

Examples

The following examples demonstrate common use cases forstore blocks.

Define a store and access variables

The following example defines avarset store namedapi_keys that accesses a variable set namedapi_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  }}

Theproduction deployment accesses thedb_password andexternal_api_key variables from theapi_keys store to authenticate the providers for that deployment. After defining a store, use the syntaxstore.<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 thestable keyword.

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

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

Thestable 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, thelicenses store accesses a variable set namedCONSUL_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 ofconsul_license_key in the state of theproduction deployment, but does not store the value ofgcp_service_account_key because it is not marked asstable. Note that you cannot change the value ofconsul_license_key after it has been marked asstable.

After referencing a value from a variable set using thestable keyword, you cannot reference that same value again in yourdeployment configuration withoutstable. For example, the following configuration is invalid because it referencesconsul_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, theapi_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, twostore blocks access the same variable set, but onestore 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 astore 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 separatestore blocks.