diff --git a/modules/kms/README.md b/modules/kms/README.md index 55a0e944..69ceb882 100644 --- a/modules/kms/README.md +++ b/modules/kms/README.md @@ -1,40 +1,71 @@ # Google KMS Module -Simple Cloud KMS module that allows managing a keyring, zero or more keys in the keyring, and IAM role bindings on individual keys. +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. -The `protected` flag in the `key_attributes` variable sets the `prevent_destroy` lifecycle argument on an a per-key basis. +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. + +## 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 -### Minimal example +### Using an existing keyring ```hcl module "kms" { - source = "../modules/kms" - project_id = "my-project" - keyring = "test" - location = "europe" - keys = ["key-a", "key-b"] + source = "../modules/kms" + project_id = "my-project" + iam_roles = ["roles/owner"] + iam_members = { + "roles/owner" = ["user:user1@example.com"] + } + keyring = { location = "europe-west1", name = "test" } + keyring_create = false + keys = { key-a = null, key-b = null, key-c = null } } ``` -### Granting access to keys via IAM +### Keyring creation and crypto key rotation and IAM roles ```hcl module "kms" { - source = "../modules/kms" - project_id = "my-project" - keyring = "test" - location = "europe" - keys = ["key-a", "key-b"] - iam_roles = { - key-a = ["roles/cloudkms.cryptoKeyDecrypter"] + source = "../modules/kms" + project_id = "my-project" + key_iam_roles = { + key-a = ["roles/owner"] } - iam_members = { + key_iam_members = { key-a = { - "roles/cloudkms.cryptoKeyDecrypter" = ["user:me@example.org"] + "roles/owner" = ["user:user1@example.com"] } } + keyring = { location = "europe-west1", name = "test" } + keys = { + key-a = null + key-b = { rotation_period = "604800s", labels = null } + key-c = { rotation_period = null, labels = { env = "test" } } + } +} +``` + +### Crypto key purpose + +```hcl +module "kms" { + source = "../modules/kms" + project_id = "my-project" + key_purpose = { + key-c = { + purpose = "ASYMMETRIC_SIGN" + version_template = { + algorithm = "EC_SIGN_P384_SHA384" + protection_level = null + } + } + } + keyring = { location = "europe-west1", name = "test" } + keys = { key-a = null, key-b = null, key-c = null } } ``` @@ -43,14 +74,16 @@ module "kms" { | name | description | type | required | default | |---|---|:---: |:---:|:---:| -| keyring | Keyring name. | string | ✓ | | -| location | Location for the keyring. | string | ✓ | | +| keyring | Keyring attributes. | object({...}) | ✓ | | | project_id | Project id where the keyring will be created. | string | ✓ | | -| *iam_members* | IAM members keyed by key name and role. | map(map(list(string))) | | {} | -| *iam_roles* | IAM roles keyed by key name. | map(list(string)) | | {} | -| *key_attributes* | Optional key attributes per key. | map(object({...})) | | {} | -| *key_defaults* | Key attribute defaults. | object({...}) | | ... | -| *keys* | Key names. | list(string) | | [] | +| *iam_members* | Keyring IAM members. | map(list(string)) | | {} | +| *iam_roles* | Keyring IAM roles. | list(string) | | [] | +| *key_iam_members* | IAM members keyed by key name and role. | map(map(list(string))) | | {} | +| *key_iam_roles* | IAM roles keyed by key name. | map(list(string)) | | {} | +| *key_purpose* | Per-key purpose, if not set defaults will be used. If purpose is not `ENCRYPT_DECRYPT` (the default), `version_template.algorithm` is required. | map(object({...})) | | {} | +| *key_purpose_defaults* | Defaults used for key purpose when not defined at the key level. If purpose is not `ENCRYPT_DECRYPT` (the default), `version_template.algorithm` is required. | object({...}) | | ... | +| *keyring_create* | Set to false to manage keys and IAM bindings in an existing keyring. | bool | | true | +| *keys* | Key names and base attributes. Set attributes to null if not needed. | map(object({...})) | | {} | ## Outputs @@ -59,25 +92,7 @@ module "kms" { | key_self_links | Key self links. | | | keyring | Keyring resource. | | | keys | Key resources. | | -| location | Keyring self link. | | -| name | Keyring self link. | | +| location | Keyring location. | | +| name | Keyring name. | | | self_link | Keyring self link. | | - -## Requirements - -These sections describe requirements for using this module. - -### IAM - -The following roles must be used to provision the resources of this module: - -- Cloud KMS Admin: `roles/cloudkms.admin` or -- Owner: `roles/owner` - -### APIs - -A project with the following APIs enabled must be used to host the -resources of this module: - -- Google Cloud Key Management Service: `cloudkms.googleapis.com` diff --git a/modules/kms/main.tf b/modules/kms/main.tf index 18c14eff..b488ac71 100644 --- a/modules/kms/main.tf +++ b/modules/kms/main.tf @@ -15,59 +15,74 @@ */ locals { - # distinct is needed to make the expanding function argument work - iam_pairs = flatten([ - for name, roles in var.iam_roles : + key_iam_pairs = flatten([ + for name, roles in var.key_iam_roles : [for role in roles : { name = name, role = role }] ]) - iam_keypairs = { - for pair in local.iam_pairs : + key_iam_keypairs = { + for pair in local.key_iam_pairs : "${pair.name}-${pair.role}" => pair } - key_attributes = { - for name in var.keys : - name => lookup(var.key_attributes, name, var.key_defaults) + key_purpose = { + for key, attrs in var.keys : key => try( + var.key_purpose[key], var.key_purpose_defaults + ) } - keys = merge( - { for name, resource in google_kms_crypto_key.keys : name => resource }, - { for name, resource in google_kms_crypto_key.keys-ephemeral : name => resource } + keyring = ( + var.keyring_create + ? google_kms_key_ring.default.0 + : data.google_kms_key_ring.default.0 ) } -resource "google_kms_key_ring" "key_ring" { - name = var.keyring +data "google_kms_key_ring" "default" { + count = var.keyring_create ? 0 : 1 project = var.project_id - location = var.location + name = var.keyring.name + location = var.keyring.location } -resource "google_kms_crypto_key" "keys" { - for_each = { - for name, attrs in local.key_attributes : - name => attrs if attrs.protected - } +resource "google_kms_key_ring" "default" { + count = var.keyring_create ? 1 : 0 + project = var.project_id + name = var.keyring.name + location = var.keyring.location + # lifecycle { + # prevent_destroy = true + # } +} + +resource "google_kms_key_ring_iam_binding" "default" { + for_each = toset(var.iam_roles) + key_ring_id = local.keyring.self_link + role = each.value + members = lookup(var.iam_members, each.value, []) +} + +resource "google_kms_crypto_key" "default" { + for_each = var.keys + key_ring = local.keyring.self_link name = each.key - key_ring = google_kms_key_ring.key_ring.self_link - rotation_period = each.value.rotation_period - lifecycle { - prevent_destroy = true + rotation_period = try(each.value.rotation_period, null) + labels = try(each.value.labels, null) + purpose = try(local.key_purpose[each.key].purpose, null) + dynamic version_template { + for_each = local.key_purpose[each.key].version_template == null ? [] : [""] + content { + algorithm = local.key_purpose[each.key].version_template.algorithm + protection_level = local.key_purpose[each.key].version_template.protection_level + } } + # lifecycle { + # prevent_destroy = true + # } } -resource "google_kms_crypto_key" "keys-ephemeral" { - for_each = { - for name, attrs in local.key_attributes : - name => attrs if ! attrs.protected - } - name = each.key - key_ring = google_kms_key_ring.key_ring.self_link - rotation_period = each.value.rotation_period -} - -resource "google_kms_crypto_key_iam_binding" "bindings" { - for_each = local.iam_keypairs +resource "google_kms_crypto_key_iam_binding" "default" { + for_each = local.key_iam_keypairs role = each.value.role - crypto_key_id = local.keys[each.value.name].self_link + crypto_key_id = google_kms_crypto_key.default[each.value.name].self_link members = lookup( - lookup(var.iam_members, each.value.name, {}), each.value.role, [] + lookup(var.key_iam_members, each.value.name, {}), each.value.role, [] ) } diff --git a/modules/kms/outputs.tf b/modules/kms/outputs.tf index de30ea17..d92190a5 100644 --- a/modules/kms/outputs.tf +++ b/modules/kms/outputs.tf @@ -16,30 +16,51 @@ output "keyring" { description = "Keyring resource." - value = google_kms_key_ring.key_ring + value = local.keyring + depends_on = [ + google_kms_key_ring_iam_binding.default + ] } output "location" { - description = "Keyring self link." - value = google_kms_key_ring.key_ring.location + description = "Keyring location." + value = local.keyring.location + depends_on = [ + google_kms_key_ring_iam_binding.default + ] } output "name" { - description = "Keyring self link." - value = google_kms_key_ring.key_ring.name + description = "Keyring name." + value = local.keyring.name + depends_on = [ + google_kms_key_ring_iam_binding.default + ] } output "self_link" { description = "Keyring self link." - value = google_kms_key_ring.key_ring.self_link + value = local.keyring.self_link + depends_on = [ + google_kms_key_ring_iam_binding.default + ] } output "keys" { description = "Key resources." - value = local.keys + value = google_kms_crypto_key.default + depends_on = [ + google_kms_crypto_key_iam_binding.default + ] } output "key_self_links" { description = "Key self links." - value = { for name, resource in local.keys : name => resource.self_link } + value = { + for name, resource in google_kms_crypto_key.default : + name => resource.self_link + } + depends_on = [ + google_kms_crypto_key_iam_binding.default + ] } diff --git a/modules/kms/variables.tf b/modules/kms/variables.tf index e976b72b..42ec689b 100644 --- a/modules/kms/variables.tf +++ b/modules/kms/variables.tf @@ -15,53 +15,79 @@ */ variable "iam_members" { + description = "Keyring IAM members." + type = map(list(string)) + default = {} +} + +variable "iam_roles" { + description = "Keyring IAM roles." + type = list(string) + default = [] +} + +variable "key_iam_members" { description = "IAM members keyed by key name and role." type = map(map(list(string))) default = {} } -variable "iam_roles" { +variable "key_iam_roles" { description = "IAM roles keyed by key name." type = map(list(string)) default = {} } -variable "keyring" { - description = "Keyring name." - type = string -} - -variable "key_attributes" { - description = "Optional key attributes per key." +variable "key_purpose" { + description = "Per-key purpose, if not set defaults will be used. If purpose is not `ENCRYPT_DECRYPT` (the default), `version_template.algorithm` is required." type = map(object({ - protected = bool - rotation_period = string + purpose = string + version_template = object({ + algorithm = string + protection_level = string + }) })) default = {} } -variable "key_defaults" { - description = "Key attribute defaults." +variable "key_purpose_defaults" { + description = "Defaults used for key purpose when not defined at the key level. If purpose is not `ENCRYPT_DECRYPT` (the default), `version_template.algorithm` is required." type = object({ - protected = bool - rotation_period = string + purpose = string + version_template = object({ + algorithm = string + protection_level = string + }) }) default = { - protected = true - rotation_period = "100000s" + purpose = null + version_template = null } } -variable "keys" { - description = "Key names." - type = list(string) - default = [] +# cf https://cloud.google.com/kms/docs/locations + +variable "keyring" { + description = "Keyring attributes." + type = object({ + location = string + name = string + }) } -# cf https://cloud.google.com/kms/docs/locations -variable "location" { - description = "Location for the keyring." - type = string +variable "keyring_create" { + description = "Set to false to manage keys and IAM bindings in an existing keyring." + type = bool + default = true +} + +variable "keys" { + description = "Key names and base attributes. Set attributes to null if not needed." + type = map(object({ + rotation_period = string + labels = map(string) + })) + default = {} } variable "project_id" { diff --git a/tests/modules/kms/__init__.py b/tests/modules/kms/__init__.py new file mode 100644 index 00000000..6913f02e --- /dev/null +++ b/tests/modules/kms/__init__.py @@ -0,0 +1,13 @@ +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. diff --git a/tests/modules/kms/fixture/main.tf b/tests/modules/kms/fixture/main.tf new file mode 100644 index 00000000..f027f978 --- /dev/null +++ b/tests/modules/kms/fixture/main.tf @@ -0,0 +1,29 @@ +/** + * Copyright 2020 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +module "test" { + source = "../../../../modules/kms" + iam_members = var.iam_members + iam_roles = var.iam_roles + key_iam_members = var.key_iam_members + key_iam_roles = var.key_iam_roles + key_purpose = var.key_purpose + key_purpose_defaults = var.key_purpose_defaults + keyring = var.keyring + keyring_create = var.keyring_create + keys = var.keys + project_id = var.project_id +} diff --git a/tests/modules/kms/fixture/outputs.tf b/tests/modules/kms/fixture/outputs.tf new file mode 100644 index 00000000..77b8211f --- /dev/null +++ b/tests/modules/kms/fixture/outputs.tf @@ -0,0 +1,19 @@ +/** + * Copyright 2020 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +output "module" { + value = module.test +} diff --git a/tests/modules/kms/fixture/variables.tf b/tests/modules/kms/fixture/variables.tf new file mode 100644 index 00000000..10f3f318 --- /dev/null +++ b/tests/modules/kms/fixture/variables.tf @@ -0,0 +1,113 @@ +/** + * Copyright 2020 Google LLC + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +variable "iam_members" { + type = map(list(string)) + default = { + "roles/owner" = ["user:ludo@ludomagno.net"] + } +} + +variable "iam_roles" { + type = list(string) + default = ["roles/owner"] +} + +variable "key_iam_members" { + type = map(map(list(string))) + default = { + key-a = { + "roles/owner" = ["user:ludo@ludomagno.net"] + } + } +} + +variable "key_iam_roles" { + type = map(list(string)) + default = { + key-a = ["roles/owner"] + } +} + +variable "key_purpose" { + type = map(object({ + purpose = string + version_template = object({ + algorithm = string + protection_level = string + }) + })) + default = { + key-b = { + purpose = "ENCRYPT_DECRYPT" + version_template = null + } + key-c = { + purpose = "ASYMMETRIC_SIGN" + version_template = { + algorithm = "EC_SIGN_P384_SHA384" + protection_level = null + } + } + } +} + +variable "key_purpose_defaults" { + type = object({ + purpose = string + version_template = object({ + algorithm = string + protection_level = string + }) + }) + default = { + purpose = null + version_template = null + } +} + +variable "keyring" { + type = object({ + location = string + name = string + }) + default = { + location = "europe-west1" + name = "test-module" + } +} + +variable "keyring_create" { + type = bool + default = true +} + +variable "keys" { + type = map(object({ + rotation_period = string + labels = map(string) + })) + default = { + key-a = null + key-b = { rotation_period = "604800s", labels = null } + key-c = { rotation_period = null, labels = { env = "test" } } + } +} + +variable "project_id" { + type = string + default = "my-project" +} diff --git a/tests/modules/kms/test_plan.py b/tests/modules/kms/test_plan.py new file mode 100644 index 00000000..cd9d6c7c --- /dev/null +++ b/tests/modules/kms/test_plan.py @@ -0,0 +1,33 @@ +# Copyright 2020 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + + +import os +import pytest + + +FIXTURES_DIR = os.path.join(os.path.dirname(__file__), 'fixture') + + +def test_resources(plan_runner): + "Test module resources." + _, resources = plan_runner(FIXTURES_DIR) + assert sorted(r['type'] for r in resources) == [ + 'google_kms_crypto_key', + 'google_kms_crypto_key', + 'google_kms_crypto_key', + 'google_kms_crypto_key_iam_binding', + 'google_kms_key_ring', + 'google_kms_key_ring_iam_binding' + ]