From ff7c9406f21afbcf09476ee12020234f802d5ac4 Mon Sep 17 00:00:00 2001 From: ocofaigh Date: Fri, 30 May 2025 11:43:27 +0100 Subject: [PATCH 1/2] refactor prefix docs --- README.md | 2 + docs/_sidebar.md | 4 +- docs/da-implementation-guidelines.md | 69 ++++++++++++---------------- docs/prefix.md | 38 +++++++++++++++ 4 files changed, 72 insertions(+), 41 deletions(-) create mode 100644 docs/prefix.md diff --git a/README.md b/README.md index cdf9c40..16450ec 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,8 @@ You can see the published documentation at https://terraform-ibm-modules.github. - [About module badges](https://terraform-ibm-modules.github.io/documentation/#/badge-status.md) - [Release versioning](https://terraform-ibm-modules.github.io/documentation/#/versioning.md) - Governance +- Deployable Architecture consumer tips + - [Prefix](https://terraform-ibm-modules.github.io/documentation/#/prefix.md) - Troubleshooting - [Known issues](https://terraform-ibm-modules.github.io/documentation/#/issues.md) - [How do I address errors when I run tests?](https://terraform-ibm-modules.github.io/documentation/#/ts-go-cache.md) diff --git a/docs/_sidebar.md b/docs/_sidebar.md index e5dd769..6fa45ce 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -13,13 +13,15 @@ - [About merging pull requests](merging.md) - Reference - [Module authoring guidelines](implementation-guidelines.md) - - [Deployable Architecture authoring guidelines](da-implementation-guidelines.md) + - [DA authoring guidelines](da-implementation-guidelines.md) - [Design guidelines](design-guidelines.md) - [Module structure](module-structure.md) - [Metadata file (index.yml)](module-catalog-metadata.md) - [About module badges](badge-status.md) - [Release versioning](versioning.md) - Governance +- DA consumer tips + - [Prefix](prefix.md) - Troubleshooting - [Known issues](issues.md) - [How do I address errors when I run tests?](ts-go-cache.md) diff --git a/docs/da-implementation-guidelines.md b/docs/da-implementation-guidelines.md index fd33cab..eb2c166 100644 --- a/docs/da-implementation-guidelines.md +++ b/docs/da-implementation-guidelines.md @@ -1,51 +1,40 @@ # Deployable Architecture authoring guidelines -## Prefix in Deployable Architecture - -The **`prefix`** input variable allows you to prepend a custom string to the names of all resources created by this automation. This is especially useful for: - -- **Avoiding naming collisions** when deploying the same solution multiple times within the same account. -- **Creating identical infrastructure** across multiple regions or environments. -- **Improving resource traceability** by embedding environment or region identifiers into resource names. - -If you do not wish to use a prefix, you may set the value to `null` or an empty string (`""`). - -**Important**: The automation automatically inserts a hyphen between the prefix and the resource name. Therefore, you do not need to include a hyphen in the prefix yourself. - -### Examples - -Here are some common patterns for using the prefix: - -- **Environment-based**: - - `dev`, `test`, `prod` -- **Environment + Region**: - - `dev-eu-gb`, `prod-us-south`, `test-jp-tok` -- **Project-specific**: - - `webapp-dev`, `ml-prod`, `iot-test` -- **Team or department identifiers**: - - `fin-dev`, `hr-prod`, `eng-test` -- **Date or version-based** (for temporary or experimental deployments): - - `exp-202505`, `v2-dev` - -These conventions help ensure that resources are clearly grouped and easily identifiable, especially in shared or multi-tenant accounts. - -### Naming Rules - -To ensure compatibility and consistency, the prefix must follow these rules: - -- Must begin with a **lowercase letter** -- May contain only **lowercase letters**, **digits**, and **hyphens (`-`)** -- Must **not end** with a hyphen (`-`) -- Must **not contain consecutive hyphens** (`--`) -- Maximum length: **16 characters** +Below you will find some guidance on best practises that should be used when authoring a new Deployable Architecture (DA). In addition, there is some common guidance available in the following links: +- [Best practices for creating deployable architectures](https://cloud.ibm.com/docs/secure-enterprise?topic=secure-enterprise-best-practice-deployable-arch) +- [Best practices for Terraform on IBM Cloud](https://cloud.ibm.com/docs/terraform-on-ibm-cloud?topic=terraform-on-ibm-cloud-white-paper#deployable-architecture-overview) + +## Prefix + +All Deployable Architecture solutions should have an optional **`prefix`** input variable that complies with the following criteria: +- Input should have no default value, but set `nullable = true` to allow user to pass `null` incase they do not wish to use a prefix. This would be for advanced users who may need full control over resource naming. +- Add validation to the variable. See the below code snippet for the recommended validation to be added across all DAs. Ideally all DAs should have the same validation so the `prefix` value is accepted for all DAs for the case where it may be used for input mapping when configuring dependant (add-on) DAs. +- Ensure to include the details of the required format in the variable description, an example value, and link to the helper doc just like what is shown in the code snippet below. This should be consistent across all DAs. +- The prefix variable logic should be handled in a local variable so logic does not have repeated in the terraform code. For example: + ```hcl + locals { + prefix = var.prefix != null ? trimspace(var.prefix) != "" ? "${var.prefix}-" : "" : "" + instance_name = "${local.prefix}${var.instance_name}" + } + ``` +- Ensure that every variable that will use the prefix includes details about the prefix in the variable description. For example: + ```hcl + variable "instance_name" { + type = string + default = "instance" + description = "The name for the instance provisioned by this solution. If a prefix input variable is specified, the prefix is added to the name in the `-` format." + nullable = false + } + ``` -Here is the code snippet for your reference. +### Code snippet example +The following code should be used consistently across all DAs (tweak the example value that is included in the description so it is relevant to the DA being created): ```hcl variable "prefix" { type = string nullable = true - description = "The prefix to be added to all resources created by this solution. To skip using a prefix, set this value to null or an empty string. The prefix must begin with a lowercase letter and may contain only lowercase letters, digits, and hyphens '-'. It should not exceed 16 characters, must not end with a hyphen('-'), and can not contain consecutive hyphens ('--'). Example: prod-0205-cos." + description = "The prefix to be added to all resources created by this solution. To skip using a prefix, set this value to null or an empty string. The prefix must begin with a lowercase letter and may contain only lowercase letters, digits, and hyphens '-'. It should not exceed 16 characters, must not end with a hyphen('-'), and can not contain consecutive hyphens ('--'). Example: prod-0205-cos. [Learn more](https://terraform-ibm-modules.github.io/documentation/#/prefix.md)." validation { # - null and empty string is allowed diff --git a/docs/prefix.md b/docs/prefix.md new file mode 100644 index 0000000..822c7d1 --- /dev/null +++ b/docs/prefix.md @@ -0,0 +1,38 @@ +# Prefix in Deployable Architecture + +The **`prefix`** input variable allows you to prepend a custom string to the names of all resources created by this automation. This is especially useful for: + +- **Avoiding naming collisions** when deploying the same solution multiple times within the same account. +- **Creating identical infrastructure** across multiple regions or environments. +- **Improving resource traceability** by embedding environment or region identifiers into resource names. + +If you do not wish to use a prefix, you may set the value to `null` or an empty string (`""`). + +**Important**: The automation automatically inserts a hyphen between the prefix and the resource name. Therefore, you do not need to include a hyphen in the prefix yourself. + +### Examples + +Here are some common patterns for using the prefix: + +- **Environment-based**: + - `dev`, `test`, `prod` +- **Environment + Region**: + - `dev-eu-gb`, `prod-us-south`, `test-jp-tok` +- **Project-specific**: + - `webapp-dev`, `ml-prod`, `iot-test` +- **Team or department identifiers**: + - `fin-dev`, `hr-prod`, `eng-test` +- **Date or version-based** (for temporary or experimental deployments): + - `exp-202505`, `v2-dev` + +These conventions help ensure that resources are clearly grouped and easily identifiable, especially in shared or multi-tenant accounts. + +### Naming Rules + +To ensure compatibility and consistency, the prefix must follow these rules: + +- Must begin with a **lowercase letter** +- May contain only **lowercase letters**, **digits**, and **hyphens (`-`)** +- Must **not end** with a hyphen (`-`) +- Must **not contain consecutive hyphens** (`--`) +- Maximum length: **16 characters** From dad5ff770287a343dd062f90a71bb54a792e7e92 Mon Sep 17 00:00:00 2001 From: terraform-ibm-modules-ops Date: Fri, 30 May 2025 10:44:54 +0000 Subject: [PATCH 2/2] docs: README ToC updated from sidebar [skip ci] --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 16450ec..d8cc1f1 100644 --- a/README.md +++ b/README.md @@ -23,14 +23,14 @@ You can see the published documentation at https://terraform-ibm-modules.github. - [About merging pull requests](https://terraform-ibm-modules.github.io/documentation/#/merging.md) - Reference - [Module authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/implementation-guidelines.md) - - [Deployable Architecture authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/da-implementation-guidelines.md) + - [DA authoring guidelines](https://terraform-ibm-modules.github.io/documentation/#/da-implementation-guidelines.md) - [Design guidelines](https://terraform-ibm-modules.github.io/documentation/#/design-guidelines.md) - [Module structure](https://terraform-ibm-modules.github.io/documentation/#/module-structure.md) - [Metadata file (index.yml)](https://terraform-ibm-modules.github.io/documentation/#/module-catalog-metadata.md) - [About module badges](https://terraform-ibm-modules.github.io/documentation/#/badge-status.md) - [Release versioning](https://terraform-ibm-modules.github.io/documentation/#/versioning.md) - Governance -- Deployable Architecture consumer tips +- DA consumer tips - [Prefix](https://terraform-ibm-modules.github.io/documentation/#/prefix.md) - Troubleshooting - [Known issues](https://terraform-ibm-modules.github.io/documentation/#/issues.md)