From d6bdaf574d95c6050d295af900f19ac859ad3e1e Mon Sep 17 00:00:00 2001 From: Jonathan Lacefield Date: Wed, 4 Sep 2024 12:06:46 -0400 Subject: [PATCH] Updated example (#118) --- docs/resources/namespace.md | 70 +++++++++++++++++++ examples/README.md | 4 +- .../temporalcloud_namespace/resource.tf | 70 +++++++++++++++++++ 3 files changed, 142 insertions(+), 2 deletions(-) diff --git a/docs/resources/namespace.md b/docs/resources/namespace.md index 1e1e689..ab09a53 100644 --- a/docs/resources/namespace.md +++ b/docs/resources/namespace.md @@ -15,6 +15,10 @@ Provisions a Temporal Cloud namespace. ```terraform terraform { required_providers { + tls = { + source = "hashicorp/tls" + version = ">= 2.0.0" + } temporalcloud = { source = "temporalio/temporalcloud" } @@ -25,12 +29,78 @@ provider "temporalcloud" { } +// the following example demonstrates how to manage a namespace resource with a CA cert generated outside of Terrafrom + resource "temporalcloud_namespace" "terraform" { name = "terraform" regions = ["aws-us-east-1"] accepted_client_ca = base64encode(file("${path.module}/ca.pem")) retention_days = 14 } + +// the following example demonstrates how to use the hashi tls provider to generate certs for use in a namespace and end-entity +// the hasicorp tls provider is used to generate the namespace's ca cert +// for more information see the provider's documentation here https://registry.terraform.io/providers/hashicorp/tls/latest/docs +provider "tls" { +} + +// root CA example - the namespace cert +// This cert is not stored anywhere locally. +// If new certificates are needed you need to regenerate all of them (including the client end-entity certs). +resource "tls_self_signed_cert" "ca" { + private_key_pem = tls_private_key.ca.private_key_pem + subject { + // arguments to to supply for the format function are the namespace name, region, and account id + common_name = format("%s-%s.%s", "terraform2", ["aws-us-east-1"], "terraform") + // this should represent your organization name + organization = "terraform" + } + allowed_uses = [ + "cert_signing", + "server_auth", + "client_auth", + ] + validity_period_hours = 8760 // 1 year + is_ca_certificate = true +} + +resource "tls_private_key" "default" { + algorithm = "RSA" +} + +resource "tls_cert_request" "default" { + private_key_pem = tls_private_key.default.private_key_pem + dns_names = [] + subject { + // arguments to to supply for the format function are the namespace name, region, and account id + common_name = format("%s-%s.%s", "terraform2", ["aws-us-east-1"], "terraform") + // this should represent your organization name + organization = "terraform" + } +} + +// This is the end-entity cert that is used to authorize the workers connecting to temporal cloud. +// Store this cert in KMS as a best practice +// Reference your KMS's provider documentation for details on how to store a cert in KMS +resource "tls_locally_signed_cert" "default" { + cert_request_pem = tls_cert_request.default.cert_request_pem + ca_private_key_pem = tls_private_key.ca.private_key_pem + ca_cert_pem = tls_self_signed_cert.ca.cert_pem + validity_period_hours = var.certificate_expiration_hours + allowed_uses = [ + "client_auth", + "digital_signature" + ] + is_ca_certificate = false +} + +// example namespace that uses the CA cert generated in this example +resource "temporalcloud_namespace" "terraform2" { + name = "terraform2" + regions = ["aws-us-east-1"] + accepted_client_ca = base64encode(tls_self_signed_cert.ca.cert_pem) + retention_days = 14 +} ``` diff --git a/examples/README.md b/examples/README.md index 026c42c..b3957e2 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,8 +2,8 @@ This directory contains examples that are mostly used for documentation, but can also be run/tested manually via the Terraform CLI. -The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or ar testable even if some parts are not relevant for the documentation. +The document generation tool looks for files in the following locations by default. All other *.tf files besides the ones mentioned below are ignored by the documentation tool. This is useful for creating examples that can run and/or are testable even if some parts are not relevant for the documentation. * **provider/provider.tf** example file for the provider index page * **data-sources/`full data source name`/data-source.tf** example file for the named data source page -* **resources/`full resource name`/resource.tf** example file for the named data source page +* **resources/`full resource name`/resource.tf** example file for the named data source page \ No newline at end of file diff --git a/examples/resources/temporalcloud_namespace/resource.tf b/examples/resources/temporalcloud_namespace/resource.tf index 1a0f610..002c8ed 100644 --- a/examples/resources/temporalcloud_namespace/resource.tf +++ b/examples/resources/temporalcloud_namespace/resource.tf @@ -1,5 +1,9 @@ terraform { required_providers { + tls = { + source = "hashicorp/tls" + version = ">= 2.0.0" + } temporalcloud = { source = "temporalio/temporalcloud" } @@ -10,9 +14,75 @@ provider "temporalcloud" { } +// the following example demonstrates how to manage a namespace resource with a CA cert generated outside of Terrafrom + resource "temporalcloud_namespace" "terraform" { name = "terraform" regions = ["aws-us-east-1"] accepted_client_ca = base64encode(file("${path.module}/ca.pem")) retention_days = 14 } + +// the following example demonstrates how to use the hashi tls provider to generate certs for use in a namespace and end-entity +// the hasicorp tls provider is used to generate the namespace's ca cert +// for more information see the provider's documentation here https://registry.terraform.io/providers/hashicorp/tls/latest/docs +provider "tls" { +} + +// root CA example - the namespace cert +// This cert is not stored anywhere locally. +// If new certificates are needed you need to regenerate all of them (including the client end-entity certs). +resource "tls_self_signed_cert" "ca" { + private_key_pem = tls_private_key.ca.private_key_pem + subject { + // arguments to to supply for the format function are the namespace name, region, and account id + common_name = format("%s-%s.%s", "terraform2", ["aws-us-east-1"], "terraform") + // this should represent your organization name + organization = "terraform" + } + allowed_uses = [ + "cert_signing", + "server_auth", + "client_auth", + ] + validity_period_hours = 8760 // 1 year + is_ca_certificate = true +} + +resource "tls_private_key" "default" { + algorithm = "RSA" +} + +resource "tls_cert_request" "default" { + private_key_pem = tls_private_key.default.private_key_pem + dns_names = [] + subject { + // arguments to to supply for the format function are the namespace name, region, and account id + common_name = format("%s-%s.%s", "terraform2", ["aws-us-east-1"], "terraform") + // this should represent your organization name + organization = "terraform" + } +} + +// This is the end-entity cert that is used to authorize the workers connecting to temporal cloud. +// Store this cert in KMS as a best practice +// Reference your KMS's provider documentation for details on how to store a cert in KMS +resource "tls_locally_signed_cert" "default" { + cert_request_pem = tls_cert_request.default.cert_request_pem + ca_private_key_pem = tls_private_key.ca.private_key_pem + ca_cert_pem = tls_self_signed_cert.ca.cert_pem + validity_period_hours = var.certificate_expiration_hours + allowed_uses = [ + "client_auth", + "digital_signature" + ] + is_ca_certificate = false +} + +// example namespace that uses the CA cert generated in this example +resource "temporalcloud_namespace" "terraform2" { + name = "terraform2" + regions = ["aws-us-east-1"] + accepted_client_ca = base64encode(tls_self_signed_cert.ca.cert_pem) + retention_days = 14 +} \ No newline at end of file