fix: Add blindfold example and supporting test

This adds an example using my f5xc provider to blindfold the credential
before sending to XC.

.talismanrc

@@ -9,4 +9,9 @@ fileignoreconfig:
 - filename: examples/cloud_credential/main.tf
   checksum: ce22ad3a72c39d3cc7aa37e1fd7a568859826be625d4aa6c253ec308c7f5f7e4
 - filename: examples/cloud_credential/README.md
-  checksum: 6089cfa3634b583cd119a92c3a0e54a02541489eb35007546652cd16ea42c54f
+  checksum: 6f6dcf5cbc18a21bc51e2832a24b4dec9e6b41ce55dff5f5937076f631044f9d
+- filename: examples/blindfold_cloud_credential/main.tf
+  checksum: 990ae3c7f7d585e87936bc7b4014fdd524a75517ba41822bdda523099216da2c
+- filename: examples/blindfold_cloud_credential/README.md
+  checksum: b2344a6480a1fddc01825e47512b2b862f2acef1240b59815c79dae0a2a42958
+version: "1.0"

.vscode/cSpell.json

@@ -15,6 +15,7 @@
         "talismanrc",
         "tfvars",
         "thumbsup",
+        "volterra",
         "wontfix"
     ],
     "flagWords": [

Makefile

@@ -50,7 +50,7 @@ converge: $(TF_SETUP_SENTINEL)
 converge.%: $(TF_SETUP_SENTINEL)
 	kitchen converge $*
 
-EXAMPLES := simple_project_role simple_org_role fixed_id cloud_credential
+EXAMPLES := simple_project_role simple_org_role fixed_id cloud_credential blindfold_cloud_credential
 
 $(TF_SETUP_SENTINEL): $(wildcard test/setup/*.tf) $(filter-out $(TF_SETUP_SENTINEL), $(wildcard test/setup/*.tfvars)) $(addprefix test/ephemeral/,$(addsuffix /main.tf,$(EXAMPLES)))
 	terraform -chdir=$(@D) init -input=false

README.md

@@ -93,10 +93,11 @@ module "role" {
 
 ### F5 XC Cloud Credential
 
-A deeper example that shows how to create a service account, add the custom role,
+Deeper examples that show how to create a service account, add the custom role,
 and create a Cloud Credential that can be used for GPC VPC Sites in XC.
 
-See [Cloud Credential](examples/cloud_credential) example for full details.
+See [Blindfold Cloud Credential](examples/blindfold_cloud_credential) and
+[Plaintext Cloud Credential](examples/cloud_credential) examples for full details.
 
 <!-- spell-checker:ignore markdownlint -->
 <!-- markdownlint-disable MD033 MD034 -->

examples/blindfold_cloud_credential/README.md

@@ -0,0 +1,95 @@
+# Create a Blindfolded F5 Distributed Cloud GCP Cloud Credential
+
+This example demonstrates how to use the module with Google, Volterra and [f5xc] providers
+to create an F5 Distributed Cloud custom IAM role in a project, and assign it to
+a new service account, and embed the blindfolded service account credentials into an XC Cloud
+Credential.
+
+> NOTE: The [f5xc](https://registry.terraform.io/providers/memes/f5xc/latest/docs) provider is not an F5 product and is not subject to any F5 support.
+> It is a community provider built from published API spec and does not come with any warranty or guarantee of fitness for purpose. Use at your own risk.
+>
+> NOTE 2: The [f5xc] provider requires that [vesctl] is installed and accessible through `PATH`.
+>
+> NOTE 3: This example will embed the blindfolded service account JSON key in
+> XC, but it will remain as stored plaintext in Terraform state.
+>
+> For production use you should create the split this action into
+> two phases and use Blindfold to encrypt the JSON credentials offline.
+> See https://docs.cloud.f5.com/docs/services/app-stack/secrets-management for
+> more information.
+
+## Example tfvars file
+
+* Create the custom role with randomly generated identifier with prefix `f5_xc_` in project `my-project-id`
+* Create a service account named `f5-xc@my-project-id.iam.gserviceaccount.com`
+  and attach the custom role
+* Create an F5 XC Cloud Credential named `f5-xc` in your tenant that holds the
+  service account credentials
+
+<!-- spell-checker: disable -->
+```hcl
+project_id = "my-project-id"
+name = "f5-xc"
+```
+<!-- spell-checker: enable -->
+
+### Prerequisites
+
+* Google Cloud project
+* Appropriate IAM roles in the project
+  * Create and manage IAM roles
+  * Create and manage service account
+* Appropriate roles to create Cloud Credential in an F5 XC tenant
+* [vesctl] installed and accessible through `PATH`
+
+### Resources created
+
+* Custom F5 Distributed Cloud IAM role created in the project
+* Service account with binding to custom IAM role and JSON authentication key
+* Blindfolded F5 XC Cloud Credential for GCP
+
+<!-- markdownlint-disable MD033 MD034-->
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
+| <a name="requirement_f5xc"></a> [f5xc](#requirement\_f5xc) | >= 0.1 |
+| <a name="requirement_google"></a> [google](#requirement\_google) | >= 4.58 |
+| <a name="requirement_volterra"></a> [volterra](#requirement\_volterra) | >= 0.11 |
+
+## Modules
+
+| Name | Source | Version |
+|------|--------|---------|
+| <a name="module_role"></a> [role](#module\_role) | memes/f5-distributed-cloud-role/google | 1.0.7 |
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [f5xc_blindfold.sa](https://registry.terraform.io/providers/memes/f5xc/latest/docs/resources/blindfold) | resource |
+| [google_project_iam_member.sa](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/project_iam_member) | resource |
+| [google_service_account.sa](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/service_account) | resource |
+| [google_service_account_key.sa](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/service_account_key) | resource |
+| [volterra_cloud_credentials.xc](https://registry.terraform.io/providers/volterraedge/volterra/latest/docs/resources/cloud_credentials) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_name"></a> [name](#input\_name) | The name to assign to the created service account and Cloud Credential resources. | `string` | n/a | yes |
+| <a name="input_project_id"></a> [project\_id](#input\_project\_id) | The identifier of the Google Cloud project that will contain the custom role. | `string` | n/a | yes |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| <a name="output_cloud_credential"></a> [cloud\_credential](#output\_cloud\_credential) | The unique name of the GCP Cloud Credential in your F5 XC tenant. |
+| <a name="output_qualified_role_id"></a> [qualified\_role\_id](#output\_qualified\_role\_id) | The qualified role-id for the custom F5 Distributed Cloud role. |
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+<!-- markdownlint-enable MD033 MD034 -->
+
+[f5xc]: https://registry.terraform.io/providers/memes/f5xc/latest/docs
+[vesctl]: https://gitlab.com/volterra.io/vesctl/blob/main/README.md

examples/blindfold_cloud_credential/main.tf

@@ -0,0 +1,84 @@
+# Example Terraform to create an F5 XC Cloud Credential for GCP VPC Sites, with
+# a service account assigned to the custom F5 XC role at the project level.
+
+# Only supported on Terraform 1.0+
+terraform {
+  required_version = ">= 1.0"
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = ">= 4.58"
+    }
+    volterra = {
+      source  = "volterraedge/volterra"
+      version = ">= 0.11"
+    }
+    f5xc = {
+      source  = "memes/f5xc"
+      version = ">= 0.1"
+    }
+  }
+}
+
+resource "google_service_account" "sa" {
+  project      = var.project_id
+  account_id   = var.name
+  display_name = "F5 XC"
+  description  = "Service account for F5 XC GCP VPC management"
+}
+
+resource "google_service_account_key" "sa" {
+  service_account_id = google_service_account.sa.id
+  key_algorithm      = "KEY_ALG_RSA_2048"
+  private_key_type   = "TYPE_GOOGLE_CREDENTIALS_FILE"
+  keepers = {
+    name = google_service_account.sa.name
+  }
+}
+
+module "role" {
+  source           = "memes/f5-distributed-cloud-role/google"
+  version          = "1.0.7"
+  target_id        = var.project_id
+  random_id_prefix = replace(var.name, "/[^a-z0-9_.]/", "_")
+}
+
+resource "google_project_iam_member" "sa" {
+  project = var.project_id
+  role    = module.role.qualified_role_id
+  member  = google_service_account.sa.member
+
+  depends_on = [
+    google_service_account.sa,
+    module.role,
+  ]
+}
+
+resource "f5xc_blindfold" "sa" {
+  plaintext = google_service_account_key.sa.private_key
+  policy_document = {
+    name      = "ves-io-allow-volterra"
+    namespace = "shared"
+  }
+  depends_on = [
+    google_project_iam_member.sa,
+    google_service_account_key.sa,
+  ]
+}
+
+resource "volterra_cloud_credentials" "xc" {
+  name        = var.name
+  namespace   = "system"
+  description = "Example Blindfold GCP Cloud Credential"
+  gcp_cred_file {
+    credential_file {
+      blindfold_secret_info {
+        location = format("string:///%s", f5xc_blindfold.sa.sealed)
+      }
+    }
+  }
+  depends_on = [
+    google_service_account.sa,
+    google_service_account_key.sa,
+  ]
+}

examples/blindfold_cloud_credential/outputs.tf

@@ -0,0 +1,13 @@
+output "qualified_role_id" {
+  value       = module.role.qualified_role_id
+  description = <<-EOD
+  The qualified role-id for the custom F5 Distributed Cloud role.
+  EOD
+}
+
+output "cloud_credential" {
+  value       = volterra_cloud_credentials.xc.name
+  description = <<-EOD
+  The unique name of the GCP Cloud Credential in your F5 XC tenant.
+  EOD
+}

examples/blindfold_cloud_credential/terraform.tfvars.example

@@ -0,0 +1,2 @@
+project_id = "my-project-id"
+name = "f5-xc"

examples/blindfold_cloud_credential/variables.tf

@@ -0,0 +1,13 @@
+variable "project_id" {
+  type        = string
+  description = <<-EOD
+  The identifier of the Google Cloud project that will contain the custom role.
+  EOD
+}
+
+variable "name" {
+  type        = string
+  description = <<-EOD
+  The name to assign to the created service account and Cloud Credential resources.
+  EOD
+}

examples/cloud_credential/README.md

@@ -6,8 +6,12 @@ a new service account, and embed the service account credentials into an XC Clou
 Credential.
 
 > NOTE: This example will embed the service account JSON key as plaintext in
-> XC and in Terraform state. For production use you should split this action into
-> two phases and use Blindfold to encrypt the JSON credentials.
+> XC and in Terraform state. You can choose to use my unofficial F5XC provider
+> to blindfold the secret before sending to XC, but the JSON key will remain stored
+> as plaintext in Terraform state. See [Blindfold Cloud Credential](../blindfold_cloud_credential/) for example usage.
+>
+> For production use you should create the split this action into
+> two phases and use Blindfold to encrypt the JSON credentials offline.
 > See https://docs.cloud.f5.com/docs/services/app-stack/secrets-management for
 > more information.
 

kitchen.yml

@@ -235,4 +235,30 @@ suites:
           reporter:
             - cli
             - documentation:<%= report_dir %>/<%= report_ts %>/example-cloud-credential-local.txt
-      inputs:
+  - name: example-blindfold-cloud-credential
+    transport:
+      root_module_directory: test/fixtures/examples/blindfold_cloud_credential
+    driver:
+      variables:
+        project_id: '<%= harness_outputs['project_id'] %>'
+        name: '<%= harness_outputs['prefix'] + '-bf-xc' %>'
+        f5_xc_api_url: '<%= ENV['VOLT_API_URL'] %>'
+        f5_xc_api_token: '<%= ENV['VOLTERRA_TOKEN'] %>'
+    verifier:
+      systems:
+        - name: f5-xc-role
+          backend: gcp
+          profile_locations:
+            - test/profiles/f5-xc-role
+          controls:
+            - project_role
+          reporter:
+            - cli
+            - documentation:<%= report_dir %>/<%= report_ts %>/example-blindfold-cloud-credential-gcp.txt
+        - name: local
+          backend: local
+          profile_locations:
+            - test/profiles/f5-xc-cloud-credential
+          reporter:
+            - cli
+            - documentation:<%= report_dir %>/<%= report_ts %>/example-blindfold-cloud-credential-local.txt

test/fixtures/examples/blindfold_cloud_credential/main.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_version = ">= 1.0"
+}
+
+module "test" {
+  source     = "./../../../ephemeral/blindfold_cloud_credential/"
+  project_id = var.project_id
+  name       = var.name
+}

test/fixtures/examples/blindfold_cloud_credential/outputs.tf

@@ -0,0 +1,10 @@
+#
+# Module under test outputs
+#
+output "role_id" {
+  value = module.test.qualified_role_id
+}
+
+output "cloud_credential" {
+  value = module.test.cloud_credential
+}

test/fixtures/examples/blindfold_cloud_credential/variables.tf

@@ -0,0 +1,15 @@
+variable "project_id" {
+  type = string
+}
+
+variable "name" {
+  type = string
+}
+
+variable "f5_xc_api_url" {
+  type = string
+}
+
+variable "f5_xc_api_token" {
+  type = string
+}