exoscale_kms_key_store (Resource)

Manage Exoscale KMS External Key Stores.

-> External Key Store is in beta and may change.

An External Key Store connects Exoscale KMS to an XKS proxy that you operate, so that the key material of exoscale_kms_key resources can be held in your own key manager. See Set Up an External Key Store for the proxy requirements.

Corresponding data source: exoscale_kms_key_store.

~> proxy.secret_key_wo is a write-only attribute: it requires Terraform 1.11 or later.

Example Usage

resource "exoscale_kms_key_store" "my_key_store" {
  zone = "ch-gva-2"
  name = "my-key-store"

  proxy = {
    endpoint              = "https://xks.example.com/kms/xks/v1"
    access_key            = var.xks_access_key
    secret_key_wo         = var.xks_secret_key
    secret_key_wo_version = 1
  }

  # KMS keys can only be created in a connected key store.
  connected = true
}

Next step is to create exoscale_kms_key(s) backed by the key store, with xks.

Please refer to the examples directory for complete configuration examples.

Schema

Required

• name (String) ❗ The name of the key store, unique within the organization in this zone.
• proxy (Attributes) The customer-managed XKS proxy. A change of endpoint or of the credentials is only saved if the proxy passes a health check with the new settings. (see below for nested schema)
• zone (String) ❗ The Exoscale Zone name.

Optional

• connected (Boolean) Whether the key store is connected (default: false). A key store is created disconnected; KMS keys can only be created in, and used from, a connected key store.
• description (String) A description of the key store.
• timeouts (Block, Optional) (see below for nested schema)

Read-Only

• created_at (String) The creation date of the key store.
• health (Attributes) The latest periodic health check of the proxy. Only connected key stores are checked, every 10 minutes, and a change to the key store resets it: it is usually empty right after an apply. (see below for nested schema)
• id (String) The ID of this resource.
• status (String) The connection status of the key store (connected or disconnected).
• status_since (String) When the status last changed.
• type (String) The key store type (external-key-store).

Nested Schema for proxy

Required:

• access_key (String) The access key used to sign requests to the proxy. Changing it requires to also change secret_key_wo_version.
• endpoint (String) The HTTPS base URL of the XKS API on the proxy (e.g. https://xks.example.com/kms/xks/v1).
• secret_key_wo (String, Sensitive) The secret key used to sign requests to the proxy. Write-only: it is never stored in the Terraform state; change secret_key_wo_version to send a new value. Requires Terraform 1.11 or later.
• secret_key_wo_version (Number) Any number, changed to send secret_key_wo (and access_key) to the API again.

Nested Schema for timeouts

Optional:

• create (String) A string that can be parsed as a duration consisting of numbers and unit suffixes, such as “30s” or “2h45m”. Valid time units are “s” (seconds), “m” (minutes), “h” (hours).
• delete (String) A string that can be parsed as a duration consisting of numbers and unit suffixes, such as “30s” or “2h45m”. Valid time units are “s” (seconds), “m” (minutes), “h” (hours). Setting a timeout for a Delete operation is only applicable if changes are saved into state before the destroy operation occurs.
• read (String) A string that can be parsed as a duration consisting of numbers and unit suffixes, such as “30s” or “2h45m”. Valid time units are “s” (seconds), “m” (minutes), “h” (hours). Read operations occur during any refresh or planning operation when refresh is enabled.
• update (String) A string that can be parsed as a duration consisting of numbers and unit suffixes, such as “30s” or “2h45m”. Valid time units are “s” (seconds), “m” (minutes), “h” (hours).

Nested Schema for health

Read-Only:

• checked_at (String) When the check completed.
• error_detail (String) A short description of the failure, when the check failed.
• status (String) healthy, unhealthy or unknown.
• status_reason (String) The reason for the status (e.g. active, timeout, credential_error).

-> The symbol ❗ in an attribute indicates that modifying it, will force the creation of a new resource.

Connection

A key store is created disconnected. While it is disconnected, KMS keys cannot be created in it and its keys cannot be used for cryptographic operations. Set connected = true to have the provider connect it: its keys can then be used, and Exoscale KMS checks the health of the proxy periodically. Set connected = false (the default) to keep it disconnected, or to suspend every key of the key store at once. If the key store is connected or disconnected outside of Terraform, the next apply restores the configured value.

Creating, connecting or updating the endpoint or the credentials of a key store runs a health check against the proxy, and fails if the proxy is unhealthy: a key store is only created if its proxy passes the check.

With connected = true, the provider connects the key store right after creating it, and retries for about 30 seconds while the proxy fails the health check. If it still cannot connect, the key store is kept and the apply ends with a warning instead of an error, so that the key store is not deleted and created again. The key store then stays disconnected (status = "disconnected"), and the next apply tries to connect it again.

The endpoint of a key store can only be changed while it is disconnected. When proxy.endpoint changes on a connected key store, the provider disconnects it, updates it and connects it again in the same apply: its keys cannot be used for cryptographic operations in the meantime. If the update fails, the provider connects the key store again with its previous settings.

Proxy credentials

The secret key is never stored in the Terraform state, so Terraform cannot detect a change of secret_key_wo. To send new credentials, configure them on the proxy first, then change secret_key_wo_version (to any other value) together with secret_key_wo and, if needed, access_key. Changing access_key alone is rejected, as the API requires both keys together.

Description

description is optional. Once set, it can be changed but not removed: removing it from the configuration keeps the current description.

Deletion

A key store is deleted immediately, but only once no KMS key references it. KMS keys keep referencing it while they are scheduled for deletion (at least 7 days after being destroyed): until then, destroying the key store fails. Your proxy and external keys are not affected.

Import

An existing key store may be imported by <ID>@<zone>:

terraform import \
  exoscale_kms_key_store.my_key_store \
  a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab@ch-gva-2

The secret key cannot be imported: the first apply after the import sends secret_key_wo to the API.