diff --git a/docs/importing_autokey_key_handles.md b/docs/importing_autokey_key_handles.md index 1046d87..9bf6c9c 100644 --- a/docs/importing_autokey_key_handles.md +++ b/docs/importing_autokey_key_handles.md @@ -1,53 +1,118 @@ # Importing Autokey Key Handles Guidance -If you have any existing [Autokey Key Handles](https://cloud.google.com/kms/docs/resource-hierarchy#key_handles) previously created manually or using [terraform-google-autokey](https://registry.terraform.io/modules/GoogleCloudPlatform/autokey/google) module, it is possible to import them to [autokey submodule](../modules/autokey/README.md) Terraform state by following the steps below. - -**Note:** You don't need to import the existing [Autokey configuration](https://cloud.google.com/kms/docs/enable-autokey#enable-autokey-folder) resource. The [autokey submodule](../modules/autokey/README.md) apply process will handle that automatically. - -## Importing from terraform-google-autokey considerations -1. **WARNING:** [terraform-google-autokey](https://registry.terraform.io/modules/GoogleCloudPlatform/autokey/google) module can be used to create your Autokey folder, Autokey KMS project, Autokey resource project and additional resources (e.g: a Cloud Storage Bucket configured with Autokey), so **DO NOT RUN** a `terraform destroy` for the module, even after the Key Handle import, unless you just used the module for Autokey configuration and the Key Handle creations only. -1. If you are migrating from [terraform-google-autokey](https://registry.terraform.io/modules/GoogleCloudPlatform/autokey/google) module, you should copy the terraform outputs provided by the module and jump directly to step 4. - -## Steps - -1. Identify your existing Autokey folder number used to configure [Autokey configuration](https://cloud.google.com/kms/docs/enable-autokey#enable-autokey-folder). - 1. This value will be referenced as: `AUTOKEY-FOLDER-NUMBER` -1. Identify your existing project ID used to [configure Cloud KMS resources created by Autokey](https://cloud.google.com/kms/docs/enable-autokey#set-up-key-project). - 1. This value will be referenced as: `AUTOKEY-KMS-PROJECT-ID` -1. Indentify your existing [Autokey Key Handle](https://cloud.google.com/kms/docs/resource-hierarchy#key_handles) configuration. It's composed by the following: - 1. Autokey Resource Project ID; (e.g: A Cloud Storage Bucket project ID configured with Autokey); - 1. This value will be referenced as: `AUTOKEY-RESOURCE-PROJECT-ID`; - 1. Key Handle location; (e.g: A Cloud Storage Bucket location configured with Autokey); - 1. This value will be referenced as: `AUTOKEY-LOCATION`; - 1. Key Handle name; (e.g: The Key Handle name configured for Cloud Storage Bucket); - 1. This value will be referenced as: `AUTOKEY-KEYHANDLE-NAME`; -1. Run `cd` to your [autokey submodule](../modules/autokey/README.md) folder; -1. Create a `terraform.tfvars` file with the following code, replacing all the values in caps lock with your info: +If you have any existing [Autokey Key Handles](https://cloud.google.com/kms/docs/resource-hierarchy#key_handles) previously created using [terraform-google-autokey](https://registry.terraform.io/modules/GoogleCloudPlatform/autokey/google) module, it is recommended to import them to [autokey submodule](../modules/autokey/README.md) Terraform state by following the steps below. - ``` terraform - project_id = "AUTOKEY-KMS-PROJECT-ID" - autokey_folder_number = "AUTOKEY-FOLDER-NUMBER" - autokey_handles = { - YOUR_SERVICE_ALIAS = { - name = "AUTOKEY-KEYHANDLE-NAME", - project = "AUTOKEY-RESOURCE-PROJECT-ID", - resource_type_selector = "SERVICE.googleapis.com/TYPE", - location = "AUTOKEY-LOCATION" - }, - # Note: If you have multiple Key Handles, you can append it here, following the same pattern. - # Note 2: YOUR_SERVICE_ALIAS can be any meaningful string, e.g. "storage_bucket" - } +**Note:** You don't need to import the existing state for [Autokey configuration](https://cloud.google.com/kms/docs/enable-autokey#enable-autokey-folder) resource. The [autokey submodule](../modules/autokey/README.md) apply process will handle that automatically. + +**Note 2:** These instructions were made using [terraform-google-autokey v1.1.1](https://github.com/GoogleCloudPlatform/terraform-google-autokey/releases/tag/v1.1.1) as reference. Future releases versions might require changes in this document. + +**WARNING:** [terraform-google-autokey](https://registry.terraform.io/modules/GoogleCloudPlatform/autokey/google) module can be used to create your Autokey folder, Autokey KMS project, Autokey resource project and additional resources (e.g: a Cloud Storage Bucket configured with Autokey), so **DO NOT RUN** a `terraform destroy` for the module, even after the Key Handle import process is completed, unless you just used the module for Autokey configuration and the Key Handle creations only. + +## Getting the existing Autokey state from terraform-google-autokey module +1. Run `cd REPLACE-WITH-YOUR-PATH` to your `terraform-google-autokey/examples/cloud_autokey_example` module path; + 1. If you didn't use `examples/cloud_autokey_example`, make sure you update the output names below according your terraform files. +1. Run `terraform output` to get the name of the Autokey folder number and Autokey Key project: + ```bash + export AUTOKEY_FOLDER_NUMBER=$(terraform output -raw module.autokey.autokey_config | cut -d'/' -f2) + export AUTOKEY_KMS_PROJECT_ID=$(terraform output -raw module.autokey.key_project_id) + echo AUTOKEY_FOLDER_NUMBER: $AUTOKEY_FOLDER_NUMBER + echo AUTOKEY_KMS_PROJECT_ID: $AUTOKEY_KMS_PROJECT_ID ``` -1. Run `terraform init` -1. Run `terraform import google_kms_key_handle.primary["/YOUR_SERVICE_ALIAS"/] projects/AUTOKEY-RESOURCE-PROJECT-ID/locations/AUTOKEY-LOCATION/keyHandles/AUTOKEY-KEYHANDLE-NAME`. You should receive the following output: + **Note:** You must see values set for both echos: `AUTOKEY_FOLDER_NUMBER` and `AUTOKEY_KMS_PROJECT_ID`. +1. Run `terraform output` to get the KeyHandle's names, locations and projects: + ```bash + echo Getting Bigquery Dataset KeyHandle + export AUTOKEY_BQ_KEY_HANDLE_PROJECT=$(terraform output -raw bq_key_handle | cut -d'/' -f2 + export AUTOKEY_BQ_KEY_HANDLE_LOCATION=$(terraform output -raw bq_key_handle | cut -d'/' -f4 + export AUTOKEY_BQ_KEY_HANDLE_NAME=$(terraform output -raw bq_key_handle | cut -d'/' -f6 + echo AUTOKEY_BQ_KEY_HANDLE_PROJECT: $AUTOKEY_BQ_KEY_HANDLE_PROJECT + echo AUTOKEY_BQ_KEY_HANDLE_LOCATION: $AUTOKEY_BQ_KEY_HANDLE_LOCATION + echo AUTOKEY_BQ_KEY_HANDLE_NAME: $AUTOKEY_BQ_KEY_HANDLE_NAME + echo Getting Compute Disk KeyHandle + export AUTOKEY_DISK_KEY_HANDLE_PROJECT=$(terraform output -raw disk_key_handle | cut -d'/' -f2 + export AUTOKEY_DISK_KEY_HANDLE_LOCATION=$(terraform output -raw disk_key_handle | cut -d'/' -f4 + export AUTOKEY_DISK_KEY_HANDLE_NAME=$(terraform output -raw disk_key_handle | cut -d'/' -f6 + echo AUTOKEY_DISK_KEY_HANDLE_PROJECT: $AUTOKEY_DISK_KEY_HANDLE_PROJECT + echo AUTOKEY_DISK_KEY_HANDLE_LOCATION: $AUTOKEY_DISK_KEY_HANDLE_LOCATION + echo AUTOKEY_DISK_KEY_HANDLE_NAME: $AUTOKEY_DISK_KEY_HANDLE_NAME + + echo Getting Storage Bucket KeyHandle + export AUTOKEY_GCS_KEY_HANDLE_PROJECT=$(terraform output -raw disk_key_handle | cut -d'/' -f2 + export AUTOKEY_GCS_KEY_HANDLE_LOCATION=$(terraform output -raw disk_key_handle | cut -d'/' -f4 + export AUTOKEY_GCS_KEY_HANDLE_NAME=$(terraform output -raw disk_key_handle | cut -d'/' -f6 + echo AUTOKEY_GCS_KEY_HANDLE_PROJECT: $AUTOKEY_GCS_KEY_HANDLE_PROJECT + echo AUTOKEY_GCS_KEY_HANDLE_LOCATION: $AUTOKEY_GCS_KEY_HANDLE_LOCATION + echo AUTOKEY_GCS_KEY_HANDLE_NAME: $AUTOKEY_GCS_KEY_HANDLE_NAME ``` - Import successful! + **Note:** You must see values just for the KeyHandles you have deployed. In other words: If you just have a KeyHandle for Bigquery, you'll just see values for: `AUTOKEY_BQ_KEY_HANDLE_PROJECT`, `AUTOKEY_BQ_KEY_HANDLE_LOCATION` and `AUTOKEY_BQ_KEY_HANDLE_NAME` echos. - The resources that were imported are shown above. These resources are now in - your Terraform state and will henceforth be managed by Terraform. +## Initialize the Autokey submodule +1. Run `cd` to your [autokey submodule](../modules/autokey/README.md) folder; +1. Create a `terraform.tfvars` file template by running the following command: + ``` shell + echo " + project_id = "$AUTOKEY_KMS_PROJECT_ID" + autokey_folder_number = "$AUTOKEY_FOLDER_NUMBER" + " > terraform.tfvars +1. Run `terraform init`; +1. Run `terraform plan`; +1. Run `terraform apply`. This apply should create the existing Autokey configuration resource state; +1. Run `terraform output` to get the Autokey random suffix created: + ``` shell + export AUTOKEY_SUBMODULE_RANDOM=$(terraform output -raw random_suffix) + echo AUTOKEY_SUBMODULE_RANDOM: $AUTOKEY_SUBMODULE_RANDOM + ``` + +## Importing the existing Autokey state from terraform-google-autokey module using autokey submodule. +1. Run `cd` to your [autokey submodule](../modules/autokey/README.md) folder; +1. Append the existing `terraform.tfvars` file by running the following command: + ``` shell + echo " + autokey_handles = { + # Delete this block if you don't have KeyHandle for Bigquery + bq_dataset = { + name = "$AUTOKEY_BQ_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM", + project = "$AUTOKEY_BQ_KEY_HANDLE_PROJECT", + resource_type_selector = \"bigquery.googleapis.com/Dataset\", + location = "$AUTOKEY_BQ_KEY_HANDLE_LOCATION" + }, + # Delete this block if you don't have KeyHandle for Compute + compute_disk = { + name = "$AUTOKEY_DISK_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM", + project = "$AUTOKEY_DISK_KEY_HANDLE_PROJECT", + resource_type_selector = \"compute.googleapis.com/Disk\", + location = "$AUTOKEY_DISK_KEY_HANDLE_LOCATION" + }, + # Delete this block if you don't have KeyHandle for Storage + gcs_bucket = { + name = "$AUTOKEY_GCS_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM", + project = "$AUTOKEY_GCS_KEY_HANDLE_PROJECT", + resource_type_selector = \"storage.googleapis.com/Bucket\", + location = "$AUTOKEY_GCS_KEY_HANDLE_LOCATION" + }, + } + " >> terraform.tfvars ``` +1. Run one `terraform import` command for each KeyHandle you have declared in your `.tfvars` file. + 1. For Bigquey: + ``` shell + terraform import google_kms_key_handle.primary["/bq_dataset"/] projects/$AUTOKEY_BQ_KEY_HANDLE_PROJECT/locations/$AUTOKEY_BQ_KEY_HANDLE_LOCATION/keyHandles/$AUTOKEY_BQ_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM + ``` + 1. For Compute: + ``` shell + terraform import google_kms_key_handle.primary["/compute_disk"/] projects/$AUTOKEY_DISK_KEY_HANDLE_PROJECT/locations/$AUTOKEY_DISK_KEY_HANDLE_LOCATION/keyHandles/$AUTOKEY_DISK_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM + ``` + 1. For Storage: + ``` shell + terraform import google_kms_key_handle.primary["/gcs_bucket"/] projects/$AUTOKEY_GCS_KEY_HANDLE_PROJECT/locations/$AUTOKEY_GCS_KEY_HANDLE_LOCATION/keyHandles/$AUTOKEY_GCS_KEY_HANDLE_NAME-$AUTOKEY_SUBMODULE_RANDOM + ``` + 1. **Note:** For each import, you should receive the following output: - # Note: If you have multiple Key Handles, you can add it here following the same pattern. + ``` + Import successful! -1. Run `terraform apply`. This apply should create the existing Autokey configuration resource state. + The resources that were imported are shown above. These resources are now in + your Terraform state and will henceforth be managed by Terraform. + ``` +1. Run `terraform plan`. No changes should be required anymore. **You successfully imported the Autokey state**. diff --git a/examples/autokey_example/main.tf b/examples/autokey_example/main.tf index 41d522c..bb95e2d 100644 --- a/examples/autokey_example/main.tf +++ b/examples/autokey_example/main.tf @@ -15,7 +15,8 @@ */ module "autokey" { - source = "terraform-google-modules/kms/google//modules/autokey" + source = "terraform-google-modules/kms/google//modules/autokey" + version = "3.1.0" project_id = var.project_id autokey_folder_number = var.folder_id diff --git a/modules/autokey/README.md b/modules/autokey/README.md index d9fdf59..772e8c0 100644 --- a/modules/autokey/README.md +++ b/modules/autokey/README.md @@ -17,5 +17,6 @@ This is a submodule built to make [KMS Autokey](https://cloud.google.com/kms/doc |------|-------------| | autokey\_config\_id | An Autokey configuration identifier. | | autokey\_keyhandles | A map of KeyHandles created. | +| random\_suffix | Random 4 digits suffix used in Autokey submodule. | diff --git a/modules/autokey/main.tf b/modules/autokey/main.tf index 9a60255..4b31fbd 100644 --- a/modules/autokey/main.tf +++ b/modules/autokey/main.tf @@ -27,8 +27,6 @@ resource "google_kms_autokey_config" "primary" { } resource "random_string" "suffix" { - count = local.create_autokey_key_handles ? 1 : 0 - length = 4 special = false upper = false @@ -39,7 +37,7 @@ resource "google_kms_key_handle" "primary" { provider = google-beta project = each.value.project - name = "${each.value.name}-${random_string.suffix[0].result}" + name = "${each.value.name}-${random_string.suffix.result}" location = each.value.location resource_type_selector = each.value.resource_type_selector diff --git a/modules/autokey/outputs.tf b/modules/autokey/outputs.tf index 1d1ffec..b04af0f 100644 --- a/modules/autokey/outputs.tf +++ b/modules/autokey/outputs.tf @@ -23,3 +23,8 @@ output "autokey_keyhandles" { description = "A map of KeyHandles created." value = local.create_autokey_key_handles ? google_kms_key_handle.primary : {} } + +output "random_suffix" { + description = "Random 4 digits suffix used in Autokey submodule." + value = random_string.suffix.result +}