144 lines
7.4 KiB
Markdown
144 lines
7.4 KiB
Markdown
# Google KMS Module
|
|
|
|
This module allows creating and managing KMS crypto keys and IAM bindings at both the keyring and crypto key level. An existing keyring can be used, or a new one can be created and managed by the module if needed.
|
|
|
|
When using an existing keyring be mindful about applying IAM bindings, as all bindings used by this module are authoritative, and you might inadvertently override bindings managed by the keyring creator.
|
|
|
|
<!-- BEGIN TOC -->
|
|
- [Protecting against destroy](#protecting-against-destroy)
|
|
- [Examples](#examples)
|
|
- [Keyring creation and crypto key rotation and IAM roles](#keyring-creation-and-crypto-key-rotation-and-iam-roles)
|
|
- [Using an existing keyring](#using-an-existing-keyring)
|
|
- [Crypto key purpose](#crypto-key-purpose)
|
|
- [Import job](#import-job)
|
|
- [Variables](#variables)
|
|
- [Outputs](#outputs)
|
|
<!-- END TOC -->
|
|
|
|
## Protecting against destroy
|
|
|
|
In this module **no lifecycle blocks are set on resources to prevent destroy**, in order to allow for experimentation and testing where rapid `apply`/`destroy` cycles are needed. If you plan on using this module to manage non-development resources, **clone it and uncomment the lifecycle blocks** found in `main.tf`.
|
|
|
|
## Examples
|
|
|
|
### Keyring creation and crypto key rotation and IAM roles
|
|
|
|
```hcl
|
|
module "kms" {
|
|
source = "./fabric/modules/kms"
|
|
project_id = var.project_id
|
|
keyring = {
|
|
location = var.region
|
|
name = "test-1"
|
|
}
|
|
keys = {
|
|
key-a = {
|
|
iam = {
|
|
"roles/cloudkms.admin" = ["group:${var.group_email}"]
|
|
}
|
|
}
|
|
key-b = {
|
|
rotation_period = "604800s"
|
|
iam_bindings_additive = {
|
|
key-b-iam1 = {
|
|
key = "key-b"
|
|
member = "group:${var.group_email}"
|
|
role = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
|
|
}
|
|
}
|
|
}
|
|
key-c = {
|
|
labels = {
|
|
env = "test"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=1 resources=6 inventory=basic.yaml e2e
|
|
```
|
|
|
|
### Using an existing keyring
|
|
|
|
```hcl
|
|
module "kms" {
|
|
source = "./fabric/modules/kms"
|
|
project_id = var.project_id
|
|
iam = {
|
|
"roles/cloudkms.admin" = ["group:${var.group_email}"]
|
|
}
|
|
keyring = { location = var.region, name = var.keyring.name }
|
|
keyring_create = false
|
|
keys = { key-a = {}, key-b = {}, key-c = {} }
|
|
}
|
|
# tftest skip (uses data sources) e2e
|
|
```
|
|
|
|
### Crypto key purpose
|
|
|
|
```hcl
|
|
module "kms" {
|
|
source = "./fabric/modules/kms"
|
|
project_id = var.project_id
|
|
keyring = {
|
|
location = var.region
|
|
name = "test-2"
|
|
}
|
|
keys = {
|
|
key-a = {
|
|
purpose = "ASYMMETRIC_SIGN"
|
|
version_template = {
|
|
algorithm = "EC_SIGN_P384_SHA384"
|
|
protection_level = "HSM"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
# tftest modules=1 resources=2 inventory=purpose.yaml e2e
|
|
```
|
|
|
|
### Import job
|
|
|
|
```hcl
|
|
module "kms" {
|
|
source = "./fabric/modules/kms"
|
|
project_id = var.project_id
|
|
keyring = {
|
|
location = var.region
|
|
name = "test-3"
|
|
}
|
|
import_job = {
|
|
id = "my-import-job"
|
|
import_method = "RSA_OAEP_3072_SHA1_AES_256"
|
|
protection_level = "SOFTWARE"
|
|
}
|
|
}
|
|
# tftest modules=1 resources=2 inventory=import-job.yaml e2e
|
|
```
|
|
<!-- BEGIN TFDOC -->
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [keyring](variables.tf#L64) | Keyring attributes. | <code title="object({ location = string name = string })">object({…})</code> | ✓ | |
|
|
| [project_id](variables.tf#L115) | Project id where the keyring will be created. | <code>string</code> | ✓ | |
|
|
| [iam](variables.tf#L17) | Keyring IAM bindings in {ROLE => [MEMBERS]} format. | <code>map(list(string))</code> | | <code>{}</code> |
|
|
| [iam_bindings](variables.tf#L24) | Authoritative IAM bindings in {KEY => {role = ROLE, members = [], condition = {}}}. Keys are arbitrary. | <code title="map(object({ members = list(string) role = string condition = optional(object({ expression = string title = string description = optional(string) })) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [iam_bindings_additive](variables.tf#L39) | Keyring individual additive IAM bindings. Keys are arbitrary. | <code title="map(object({ member = string role = string condition = optional(object({ expression = string title = string description = optional(string) })) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [import_job](variables.tf#L54) | Keyring import job attributes. | <code title="object({ id = string import_method = string protection_level = string })">object({…})</code> | | <code>null</code> |
|
|
| [keyring_create](variables.tf#L72) | Set to false to manage keys and IAM bindings in an existing keyring. | <code>bool</code> | | <code>true</code> |
|
|
| [keys](variables.tf#L78) | Key names and base attributes. Set attributes to null if not needed. | <code title="map(object({ destroy_scheduled_duration = optional(string) rotation_period = optional(string) labels = optional(map(string)) purpose = optional(string, "ENCRYPT_DECRYPT") skip_initial_version_creation = optional(bool, false) version_template = optional(object({ algorithm = string protection_level = optional(string, "SOFTWARE") })) iam = optional(map(list(string)), {}) iam_bindings = optional(map(object({ members = list(string) role = string condition = optional(object({ expression = string title = string description = optional(string) })) })), {}) iam_bindings_additive = optional(map(object({ member = string role = string condition = optional(object({ expression = string title = string description = optional(string) })) })), {}) }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [tag_bindings](variables.tf#L120) | Tag bindings for this keyring, in key => tag value id format. | <code>map(string)</code> | | <code>{}</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [id](outputs.tf#L17) | Fully qualified keyring id. | |
|
|
| [import_job](outputs.tf#L26) | Keyring import job resources. | |
|
|
| [key_ids](outputs.tf#L35) | Fully qualified key ids. | |
|
|
| [keyring](outputs.tf#L47) | Keyring resource. | |
|
|
| [keys](outputs.tf#L56) | Key resources. | |
|
|
| [location](outputs.tf#L65) | Keyring location. | |
|
|
| [name](outputs.tf#L74) | Keyring name. | |
|
|
<!-- END TFDOC -->
|