Create Charm Terraform Module

Charm Terraform Standards

Creates or reviews Terraform modules for individual Juju charms following the CC008 Charm Terraform Standards specification. A charm module provides a Terraform module for a single charm. It is only required if the charm can be used standalone — if a charm cannot be used standalone, providing a Terraform module is not mandatory.

The specification assumes the Terraform Juju provider version is pessimistically held to ~> 1.0.

Process

1. Read the module directory — Read all .tf files and README.md in the target directory to understand the current state. If creating a new module, check the charm's metadata.yaml or charmcraft.yaml to identify the charm name, endpoints (provides/requires), and whether it is subordinate. Also, add Terraform specific metadata files to the .gitignore file (see below).
2. Apply the file structure — Ensure the module provides the required file layout (see below).
3. Define inputs — Add all mandatory input variables to variables.tf with the correct names, types, and defaults. Add optional inputs as needed. Entries must be in alphabetical order.
4. Define outputs — Add all mandatory outputs to outputs.tf. Add provides and requires outputs if the charm defines those endpoints. Entries must be in alphabetical order.
5. Write main module code — In main.tf, define the juju_application resource using the input variables. If the module is large, split into applications.tf, integrations.tf, offers.tf, etc.
6. Write provider and version blocks — Ensure terraform.tf contains a terraform block with required_version and required_providers (Juju provider ~> 1.0). Do not add a provider "juju" {} configuration block — the module inherits the provider configuration from the parent (calling) module, and declaring one would override it.
7. Document the module — Write README.md following the structure defined in the README Structure section below. Use the uuid output of the juju_model model resource in the README's Usage section.
8. Validate — Check that all mandatory inputs and outputs are present with correct names and types, and that files are in alphabetical order where required. Use terraform fmt and terraform validate to validate that the module is correct.

Required file structure

Every charm module must provide these files:

• README.md — Documentation. Must clarify inputs and outputs at minimum.
• terraform.tf — A single terraform block defining required_version and required_providers. Minimum Juju provider version is >1.0.0. Must not contain a provider "juju" {} configuration block, since that would override the provider configuration from the parent module.
• main.tf — Main module code defining the juju_application resource. May be split into applications.tf, integrations.tf, offers.tf, etc. if the module is large.
• variables.tf — Input variables, in alphabetical order.
• outputs.tf — Outputs, in alphabetical order.
• locals.tf — Local variables, in alphabetical order. Not requried if the charm module does not need local variables defined.

README Structure

The README.md must follow this structure:

Title and description

# Terraform module for <charm-name>

This is a Terraform module facilitating the deployment of the <charm-name> charm using
the [Juju Terraform provider](https://github.com/juju/terraform-provider-juju).
For more information, refer to the
[documentation](https://registry.terraform.io/providers/juju/juju/latest/docs)
for the Juju Terraform provider.

Requirements section

List the minimum versions and prerequisites:

## Requirements

- Terraform >= 1.0
- Juju Terraform provider >= 1.0.0, < 2.0.0
- An existing Juju model

API section

Document all inputs and outputs under an ## API heading.

Inputs table

Use a ### Inputs sub-heading with a table containing these columns: Name, Type, Description, Default, Required. Mark required inputs (those with no default) with Y in the Required column. Leave the Required column empty for optional inputs. List entries in alphabetical order.

### Inputs

| Name          | Type        | Description                                                        | Default         | Required |
|---------------|-------------|--------------------------------------------------------------------|-----------------|:--------:|
| `app_name`    | string      | The Juju application name                                          | `"<charm>"`    |          |
| `channel`     | string      | Charm channel to deploy from                                       | `"latest/edge"` |          |
| `config`      | map(string) | Map of charm configuration options                                 | `{}`            |          |
| `model_uuid`  | string      | UUID of the Juju model to deploy the charm into                    |                 |    Y     |
| `revision`    | number      | Charm revision to deploy. Null deploys the latest on given channel | `null`          |          |
| `units`       | number      | Number of application units to deploy                              | `1`             |          |

Outputs table

Use a ### Outputs sub-heading with a table containing these columns: Name, Description.

### Outputs

| Name          | Description                              |
|---------------|------------------------------------------|
| `application` | The deployed `juju_application` resource |
| `provides`    | Map of `provides` endpoint names         |
| `requires`    | Map of `requires` endpoint names         |

If the module exposes provides or requires outputs, add a follow-up paragraph and table listing the keys and endpoint names for each:

The `requires` output exposes the following endpoint names:

| Key               | Endpoint name     |
|-------------------|-------------------|
| `<key>`           | `<endpoint>`      |

Usage section

Show a minimal usage example that references juju_model.<model>.uuid for the model_uuid input, followed by a terraform apply command:

## Usage

Ensure that Terraform is aware of the Juju model dependency of the charm module.

\```hcl
module "<charm>" {
  source     = "git::https://github.com/canonical/<charm-repo>//terraform"
  model_uuid = juju_model.my_model.uuid
}
\```

To deploy this module with its required dependency, you can run the following
command:

\```shell
terraform apply -var="model_uuid=<MODEL_UUID>" -auto-approve
\```

Files and directories to add to .gitignore

• .terraform
• .terraform.lock.hcl
• *.tfstate*

Mandatory inputs

The following variables must be present in variables.tf:

Optional inputs

The following variables may be added to variables.tf. If present, they must use the names and types listed here:

Other inputs beyond this list are also allowed.

Mandatory outputs

The following output must be present in outputs.tf:

Optional outputs

The following outputs may be added to outputs.tf. If present, they must use the names and types listed here:

Other outputs beyond this list are also allowed.

Example outputs

output "application" {
  value = juju_application.<charm>
}

output "provides" {
  value = {
    metrics = "prometheus-metrics"
  }
}

output "requires" {
  value = {
    mimir_cluster = "mimir-cluster"
  }
}

output "offers" {
  value = {
    metrics = <offer-url>
  }
}

Versioning

Tags and versions use {major}.{minor}.{patch} with no metadata, pre-release info, or additional suffixes.

• Major — Non-backward-compatible changes: renaming resources (triggers destroy/recreate), changing default config values (e.g. channel upgrades), renaming variables or outputs.
• Minor — New features: adding optional config options, adding new outputs.
• Patch — Trivial fixes: updating descriptions, non-breaking bug fixes.

Tagging conventions by repository layout

• Charm module co-located with charm code: tf-X.Y.Z
• Multiple modules in a single repository: <product>-X.Y.Z (e.g. prometheus-k8s-1.1.2)
• Dedicated repository per module: vX.Y.Z

Constraints

• DO NOT include the units variable for subordinate charms.
• DO NOT add a provider "juju" {} configuration block to the module. The provider configuration is inherited from the parent module; declaring one overrides it.
• DO NOT set both machines and units on the juju_application resource — the Juju provider throws an error if both are set. Default machines to null so units takes effect when no machines are given.
• DO NOT add metadata, pre-release info, or additional suffixes to version tags.
• DO NOT create the locals.tf file if local, non-input variables are not required.
• DO NOT use Latin words or phrases in documentation or descriptions. DO USE plain English.
• DO ensure variables.tf, outputs.tf, and locals.tf entries are in alphabetical order.
• DO ensure the minimum Juju provider version is ~> 1.0.
• DO ensure every module includes the required file structure (README.md, terraform.tf, main.tf, variables.tf, outputs.tf, locals.tf).
• DO include provides and requires outputs when the charm defines those endpoints.