Skip to content

Commit

Permalink
Add specific instructions to import existing state
Browse files Browse the repository at this point in the history
  • Loading branch information
@romanini-ciandt
romanini-ciandt committed Sep 26, 2024
1 parent c6c99a2 commit ed14225
Show file tree
Hide file tree
Showing 5 changed files with 117 additions and 47 deletions.
151 changes: 108 additions & 43 deletions docs/importing_autokey_key_handles.md
View file
Original file line number Diff line number Diff line change
@@ -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**.
3 changes: 2 additions & 1 deletion examples/autokey_example/main.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions modules/autokey/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
4 changes: 1 addition & 3 deletions modules/autokey/main.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
5 changes: 5 additions & 0 deletions modules/autokey/outputs.tf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

0 comments on commit ed14225

Please sign in to comment.