Reference deployment for a workload trust zone cluster in aws

AGENTS.md

@@ -28,17 +28,17 @@ When making changes that affect documentation:
 
 ## Linting and formatting
 
-`control-plane/lint.sh` runs all linting and formatting tools across the control plane:
+`lint.sh` runs all linting and formatting tools across the `control-plane/` and `workload/` directories:
 
 - `terraform fmt` on all Terraform modules and stack units
 - `terragrunt hcl fmt` on all Terragrunt stacks
 - `terraform-docs` on each module, writing output to `README.md` in the module directory. Module-level description prose is written as a `/** ... */` block comment at the very top of `main.tf` — terraform-docs picks this up as the header automatically.
-- `shellcheck` on all shell scripts under `control-plane/`
+- `shellcheck` on all shell scripts under `control-plane/` and `workload/`
 
 Stack roots are discovered via `root.hcl` and module directories are expected to be siblings of each stack root named `modules/`. Running the script requires `terraform`, `terragrunt`, `terraform-docs`, and `shellcheck` to be installed; it will report any missing tools before exiting.
 
 ```sh
-./control-plane/lint.sh
+./lint.sh
 ```
 
 ## Workloads

control-plane/lint.sh → lint.sh

@@ -14,7 +14,11 @@ if [[ ${#missing[@]} -gt 0 ]]; then
   exit 1
 fi
 
-mapfile -t STACK_DIRS < <(find "${SCRIPT_DIR}" -name "root.hcl" -not -path "*/.terragrunt-cache/*" -exec dirname {} \; | sort)
+mapfile -t STACK_DIRS < <(
+  find "${SCRIPT_DIR}/control-plane" "${SCRIPT_DIR}/workload" \
+    -name "root.hcl" -not -path "*/.terragrunt-cache/*" \
+    -exec dirname {} \; | sort
+)
 
 mapfile -t MODULES_DIRS < <(
   for stack_dir in "${STACK_DIRS[@]}"; do
@@ -51,4 +55,7 @@ done
 echo "==> shellcheck: scripts"
 while IFS= read -r script; do
   shellcheck "${script}"
-done < <(find "${SCRIPT_DIR}" -name "*.sh" -not -path "*/.terragrunt-cache/*" | sort)
+done < <(
+  find "${SCRIPT_DIR}/control-plane" "${SCRIPT_DIR}/workload" \
+    -name "*.sh" -not -path "*/.terragrunt-cache/*" | sort
+)

workload/deployment/aws/infra/stack/README.md

@@ -0,0 +1,87 @@
+# Trust Zone Infrastructure
+
+Terragrunt stack that provisions the AWS infrastructure for a Cofide Connect trust zone workload cluster. The SPIRE server is deployed onto this cluster and registered as a trust zone with the Connect control plane.
+
+The stack reuses the VPC, jump instance, and Route53 hosted zone from the control-plane stack by default. Cross-stack dependencies are optional — set the relevant values in a unit's `common.local.hcl` to deploy against different infrastructure.
+
+## Configuration
+
+### Root configuration
+
+Create the root `common.local.hcl` before running any unit:
+
+```sh
+cp common.local.hcl.example common.local.hcl
+```
+
+Edit it to set your AWS account, region, and S3 remote state bucket:
+
+```hcl
+locals {
+  aws_account_id         = "123456789012"
+  aws_region             = "eu-west-2"
+  tf_state_bucket_region = "eu-west-2"
+  tf_state_bucket_name   = "my-tf-state-bucket"
+  tf_state_key_prefix    = "connect-trust-zone"
+}
+```
+
+Use a different `tf_state_key_prefix` from the control-plane stack to avoid state key collisions.
+
+### Per-unit configuration
+
+Each unit directory contains a `common.local.hcl.example` documenting the available configuration. Copy it to `common.local.hcl` and edit it before applying. At minimum, set `cluster_admin_role_arns` in `eks-cluster/cluster/common.local.hcl`.
+
+### IAM mode
+
+The `spire-server/iam-role` unit supports two authentication modes, configured via `iam_mode` in `common.local.hcl`:
+
+- **`pod_identity`** (default) — EKS Pod Identity. Requires the `eks-pod-identity-agent` add-on, which is enabled by default in the cluster unit.
+- **`irsa`** — IAM Roles for Service Accounts. Requires `enable_irsa = true` in the cluster unit's `common.local.hcl` and `oidc_provider_arn` set in the controller unit's `common.local.hcl`.
+
+---
+
+## Deployment
+
+Before running any Terragrunt command, create and populate the root configuration file:
+
+```sh
+cp common.local.hcl.example common.local.hcl
+# Set aws_account_id, aws_region, tf_state_bucket_region, tf_state_bucket_name, tf_state_key_prefix
+```
+
+### EKS cluster
+
+The cluster unit creates the EKS control plane, node group, and add-ons. Apply it first; the controller and SPIRE units depend on its outputs.
+
+```sh
+cd eks-cluster/cluster
+cp common.local.hcl.example common.local.hcl
+# Set cluster_admin_role_arns to your IAM role ARN.
+terragrunt apply
+```
+
+See [`eks-cluster/cluster/README.md`](eks-cluster/cluster/README.md) for how to access the cluster.
+
+### SPIRE server IAM role
+
+Creates the IAM role for the SPIRE server with KMS permissions. Apply this after the cluster unit. See [`spire-server/README.md`](spire-server/README.md) for details.
+
+```sh
+cd spire-server/iam-role && terragrunt apply
+```
+
+### Connect registration
+
+Registers the trust zone, cluster, and trust zone server with Cofide Connect in a single apply. See [`connect/README.md`](connect/README.md) for details.
+
+```sh
+export COFIDE_API_TOKEN="<your-api-token>"
+
+cd connect/trust-zone
+cp common.local.hcl.example common.local.hcl
+# Set trust_domain.
+terragrunt apply
+```
+
+Once applied, run `generate-local-values.sh` in `k8s/spire-server/spire/` to populate the SPIRE server configuration — see the [k8s guide](../../k8s/README.md).

workload/deployment/aws/infra/stack/common.local.hcl.example

@@ -0,0 +1,7 @@
+locals {
+  aws_account_id = "1234567890"
+  aws_region = "eu-west-2"
+  tf_state_bucket_region = "eu-west-2"
+  tf_state_bucket_name = "example-bucket-name"
+  tf_state_key_prefix = "connect-trust-zone"
+}

workload/deployment/aws/infra/stack/connect/README.md

@@ -0,0 +1,42 @@
+# Connect Registration
+
+Terragrunt unit that registers the trust zone and cluster with Cofide Connect using the [`cofide/cofide`](https://registry.terraform.io/providers/cofide/cofide/latest/docs) Terraform provider.
+
+This unit is applied after the AWS infrastructure is provisioned and before deploying the SPIRE server onto Kubernetes. The IDs and PSAT configuration it outputs are used to populate the SPIRE server's datastore configuration.
+
+## Prerequisites
+
+- `COFIDE_API_TOKEN` — API token for the Connect API; must be set as an environment variable.
+- The control-plane `base/dns` unit must be applied — the Connect gRPC address (`<zone>:443`) is derived from its `zone_name` output. The provider prepends the `connect.` subdomain automatically. Set `connect_url` in `common.local.hcl` to override (format: `host:port`, no scheme).
+- The `eks-cluster/cluster` unit must be applied — the OIDC issuer URL is read from its outputs. Set `oidc_issuer_url` in `common.local.hcl` to override.
+
+## `trust-zone/`
+
+Registers a trust zone and cluster with Cofide Connect. The cluster is registered in the same apply as the trust zone because the SPIRE server for this trust zone lives on this cluster.
+
+**Required values in `common.local.hcl`:**
+
+| Local | Description |
+|-------|-------------|
+| `trust_domain` | SPIFFE trust domain for the trust zone (e.g. `trust-zone.example.cofide.dev`) |
+
+**Outputs:**
+
+| Name | Description |
+|------|-------------|
+| `trust_zone_id` | Trust zone ID — used in the SPIRE server datastore config |
+| `cluster_id` | Cluster ID — used in the SPIRE server datastore config |
+| `bundle_endpoint_url` | Bundle endpoint URL assigned by Connect |
+
+## Deployment
+
+```sh
+export COFIDE_API_TOKEN="<your-api-token>"
+
+cd trust-zone
+cp common.local.hcl.example common.local.hcl
+# Set trust_domain.
+terragrunt apply
+```
+
+Once applied, run `generate-local-values.sh` in `k8s/spire-server/spire/` to populate the SPIRE server configuration — see the [k8s guide](../../../k8s/README.md).

workload/deployment/aws/infra/stack/connect/trust-zone/common.local.hcl.example

@@ -0,0 +1,14 @@
+locals {
+  # Name for the trust zone in Cofide Connect.
+  trust_zone_name = "connect-trust-zone-aws-reference-arch"
+
+  # SPIFFE trust domain for this trust zone. Required — no default.
+  trust_domain = "trust-zone.example.cofide.dev"
+
+  # Name for the cluster in Cofide Connect.
+  cluster_name = "connect-trust-zone-aws-reference-arch"
+
+  # Optional: override values if not reading from their respective dependency units.
+  # connect_url     = "example.cofide.dev:443"
+  # oidc_issuer_url = "https://oidc.eks.eu-west-2.amazonaws.com/id/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+}

workload/deployment/aws/infra/stack/connect/trust-zone/main.tf

@@ -0,0 +1,17 @@
+resource "cofide_connect_trust_zone" "this" {
+  name         = var.trust_zone_name
+  trust_domain = var.trust_domain
+}
+
+resource "cofide_connect_cluster" "this" {
+  name               = var.cluster_name
+  trust_zone_id      = cofide_connect_trust_zone.this.id
+  profile            = "kubernetes"
+  oidc_issuer_url    = var.oidc_issuer_url
+  external_server    = false
+  kubernetes_context = ""
+
+  trust_provider = {
+    kind = "kubernetes"
+  }
+}

workload/deployment/aws/infra/stack/connect/trust-zone/outputs.tf

@@ -0,0 +1,24 @@
+output "trust_domain" {
+  description = "The SPIFFE trust domain for this trust zone."
+  value       = cofide_connect_trust_zone.this.trust_domain
+}
+
+output "trust_zone_id" {
+  description = "The ID of the trust zone registered with Cofide Connect."
+  value       = cofide_connect_trust_zone.this.id
+}
+
+output "bundle_endpoint_url" {
+  description = "The bundle endpoint URL for this trust zone, as assigned by Cofide Connect."
+  value       = cofide_connect_trust_zone.this.bundle_endpoint_url
+}
+
+output "cluster_id" {
+  description = "The ID of the cluster registered with Cofide Connect."
+  value       = cofide_connect_cluster.this.id
+}
+
+output "cluster_name" {
+  description = "The name of the cluster as registered with Cofide Connect."
+  value       = cofide_connect_cluster.this.name
+}

workload/deployment/aws/infra/stack/connect/trust-zone/providers.tf

@@ -0,0 +1,4 @@
+provider "cofide" {
+  connect_url = var.connect_url
+  # api_token is configured via the COFIDE_API_TOKEN environment variable.
+}

workload/deployment/aws/infra/stack/connect/trust-zone/terragrunt.hcl

@@ -0,0 +1,54 @@
+include "root" {
+  path   = find_in_parent_folders("root.hcl")
+  expose = true
+}
+
+dependency "cluster" {
+  config_path = "../../eks-cluster/cluster"
+
+  mock_outputs_allowed_terraform_commands = ["apply", "destroy", "plan", "validate"]
+  mock_outputs = {
+    oidc_issuer_url = "https://oidc.eks.eu-west-2.amazonaws.com/id/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+  }
+}
+
+dependency "cp_dns" {
+  config_path = "${get_repo_root()}/control-plane/deployment/aws/infra/stack/base/dns"
+
+  mock_outputs_allowed_terraform_commands = ["apply", "destroy", "plan", "validate"]
+  mock_outputs = {
+    zone_name = "example.cofide.dev"
+  }
+}
+
+locals {
+  default_config = {
+    trust_zone_name = "connect-trust-zone-aws-reference-arch"
+    cluster_name    = "connect-trust-zone-aws-reference-arch"
+  }
+
+  unit_config_path = "${get_terragrunt_dir()}/common.local.hcl"
+  has_local_config = fileexists(local.unit_config_path)
+  user_config      = local.has_local_config ? read_terragrunt_config(local.unit_config_path).locals : {}
+  merged_config    = merge(local.default_config, local.user_config)
+
+  # trust_domain has no default — it must be set in common.local.hcl.
+  trust_domain = local.merged_config.trust_domain
+
+  user_connect_url     = try(local.merged_config.connect_url, null)
+  user_oidc_issuer_url = try(local.merged_config.oidc_issuer_url, null)
+}
+
+terraform {
+  source = "."
+}
+
+inputs = {
+  connect_url = local.user_connect_url != null ? local.user_connect_url : "${dependency.cp_dns.outputs.zone_name}:443"
+
+  trust_zone_name = local.merged_config.trust_zone_name
+  trust_domain    = local.trust_domain
+  cluster_name    = local.merged_config.cluster_name
+
+  oidc_issuer_url = local.user_oidc_issuer_url != null ? local.user_oidc_issuer_url : dependency.cluster.outputs.oidc_issuer_url
+}

workload/deployment/aws/infra/stack/connect/trust-zone/variables.tf

@@ -0,0 +1,24 @@
+variable "connect_url" {
+  type        = string
+  description = "Cofide Connect API gRPC address in host:port form (e.g. example.cofide.dev:443). The provider prepends the connect. subdomain. No scheme."
+}
+
+variable "trust_zone_name" {
+  type        = string
+  description = "The name of the trust zone to register with Cofide Connect."
+}
+
+variable "trust_domain" {
+  type        = string
+  description = "The SPIFFE trust domain for this trust zone (e.g. trust-zone.example.cofide.dev)."
+}
+
+variable "cluster_name" {
+  type        = string
+  description = "The name of the cluster to register with Cofide Connect."
+}
+
+variable "oidc_issuer_url" {
+  type        = string
+  description = "OIDC issuer URL of the EKS cluster (e.g. https://oidc.eks.<region>.amazonaws.com/id/<id>)."
+}

workload/deployment/aws/infra/stack/connect/trust-zone/versions.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_version = ">= 1.10"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+    cofide = {
+      source  = "cofide/cofide"
+      version = "~> 0.9"
+    }
+  }
+}