### CI Injection Pattern for Quickstart Attributes

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

The CI pipeline injects real values into quickstart files using sed substitution. This example shows how a commented-out line for setting the region is activated by removing the leading '# '.

```bash
# SCW: set region
sed -i 's/# region = "fr-par"/region = "fr-par"/g' scw_zero_cluster.tf || true
```

--------------------------------

### Quickstart Placeholder for Precondition-Guarded Attributes

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

In quickstart files, represent attributes guarded by a lifecycle precondition as a commented-out example line. This ensures users receive a helpful precondition error message if they forget to set required values.

```hcl
# region = "eu-west-1"
```

--------------------------------

### Example README.md for Plain YAML Manifest

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

This example shows the structure and content for a README.md file when using the plain YAML path. It includes details about the upstream source, version, and update instructions.

```markdown
# <feature_name>

## Upstream source

- Project: <upstream project URL>
- Manifest URL: <exact URL fetched>
- Version: <version>

## Updating

1. Find the new release at <upstream releases URL>.
2. Fetch the new manifest: `curl -L <new manifest URL> -o modules/<feature_name>/manifests/upstream.yaml`
3. Review the diff for breaking changes.
4. Commit `manifests/upstream.yaml` and follow the GitOps workflow.

```

--------------------------------

### Cluster Identifier Examples by Provider

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Provides concrete examples of cluster identifiers for different cloud providers (AWS EKS, Google GKE, Azure AKS, Scaleway). These examples demonstrate the application of the cluster identifier format.

```plaintext
eks_gc0_eu-west-1
gke_gc0_europe-west1
aks_gc0_westeurope
scw_gc0_fr-par
```

--------------------------------

### Checkout New Branch and Commit Changes

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

Start by checking out a new branch from main and making your configuration changes. Commit these changes with a meaningful message and push the branch to your remote repository.

```shell
# checkout a new branch from main
git checkout -b examplechange main

# make your changes

# commit your changes
git commit  # write a meaningful commit message

# push your changes
git push origin examplechange
```

--------------------------------

### EKS Taint and Label Example

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example configuration for an EKS node pool dedicated to GPU workloads, demonstrating the use of taints for scheduling restrictions and labels for scheduling preferences.

```terraform
apps = {
  name             = "gpu"
  instance_types   = ["g4dn.xlarge"]
  min_size         = 0
  max_size         = 4
  desired_capacity = 0

  taints = [
    {
      key    = "nvidia.com/gpu"
      value  = "true"
      effect = "NO_SCHEDULE"
    }
  ]

  labels = {
    "nvidia.com/gpu" = "true"
  }
}
```

--------------------------------

### Kustomization Overlay Module Usage

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example of how to use the Kustomization overlay module in Terraform. Ensure the source URL and version reference are correct.

```hcl
module "<feature_name>" {
  providers = {
    kustomization = kustomization
  }

  source = "github.com/kbst/terraform-kubestack//kustomization/overlay?ref=<version>"

  configuration = {
    apps = {
      resources = [
        "${path.module}/manifests/upstream.yaml",
      ]
    }

    ops = {}
  }
}
```

--------------------------------

### EKS Example: Scaling Down Non-Production Node Pools

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Illustrates how to set production-scale values in the 'apps' environment and override cost-sensitive attributes like instance types and sizes for the 'ops' environment.

```terraform
configuration = {
  apps = {
    # ... other required attributes ...
    default_node_pool = {
      instance_types   = ["m5.xlarge"]
      min_size         = 3
      max_size         = 18
      desired_capacity = 3
    }
  }

  ops = {
    default_node_pool = {
      instance_types   = ["t3.medium"]
      min_size         = 1
      max_size         = 3
      desired_capacity = 1
    }
  }
}
```

--------------------------------

### Example README.md for Helm Chart Documentation

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Document upstream source details, the command used to regenerate `upstream.yaml`, and update instructions. This README serves as a reference for managing the Helm chart.

```markdown
# <feature_name>

## Upstream source

- Project: <upstream project URL>
- Chart: oci://<registry>/<chart>  (or <repo-name>/<chart-name> from <repo-url>)
- Version: <chart-version>

## Regenerating upstream.yaml

Run the following command from the repository root, then commit the result:

    helm template <release-name> oci://<registry>/<chart> \
      --version <chart-version> \
      --values modules/<feature_name>/values.yaml \
      --namespace <namespace> \
      --create-namespace \
      --include-crds \
      > modules/<feature_name>/manifests/upstream.yaml

## Updating

1. Find the new chart version at <upstream releases URL>.
2. Update the `--version` flag in the command above.
3. Re-run the command, review the diff for breaking changes.
4. Update the Version line in this file.
5. Commit `manifests/upstream.yaml` and `README.md` and follow the GitOps workflow.
```

--------------------------------

### Cluster Name Format Example

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Illustrates the structure of a cluster name, combining a name prefix, workspace, and region. This format is used for identifying clusters.

```plaintext
<name_prefix>-<workspace>-<region>
e.g. gc0-apps-eu-west-1
```

--------------------------------

### Cluster FQDN Format Example

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Shows how the Fully Qualified Domain Name (FQDN) for a cluster is constructed using the cluster name, provider short name, and base domain. This is used for DNS and TLS configuration.

```plaintext
<cluster_name>.<provider_short>.<base_domain>
e.g. gc0-apps-eu-west-1.aws.infra.example.com
```

--------------------------------

### Kubestack Module Source References

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Examples of how to reference Kubestack framework modules in Terraform configurations, specifying the GitHub source and the framework version.

```terraform
source = "github.com/kbst/terraform-kubestack//aws/cluster?ref=v0.18.1-beta.0"
```

```terraform
source = "github.com/kbst/terraform-kubestack//aws/cluster/node-pool?ref=v0.18.1-beta.0"
```

```terraform
source = "github.com/kbst/terraform-kubestack//kustomization/overlay?ref=v0.18.1-beta.0"
```

--------------------------------

### Terraform Moved Block Example

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

Demonstrates the use of a `moved` block in `moved.tf` to manage resource renames or moves within Terraform. This file should only contain `moved` blocks and be created only when necessary.

```hcl
moved {
  from = "aws_instance.example"
  to   = "aws_instance.new_example"
}
```

--------------------------------

### AKS Example: Scaling Down Non-Production Node Pools

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Demonstrates AKS node pool configuration for the 'ops' environment, overriding VM size and count parameters to reduce costs for non-production workloads.

```terraform
ops = {
  default_node_pool = {
    vm_size   = "Standard_B2s"
    min_count = 1
    max_count = 3
  }
}
```

--------------------------------

### Reduce Replica Count in Ops Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example of reducing the replica count for a specific deployment in the 'ops' environment using the 'replicas' attribute.

```hcl
configuration = {
  apps = {
    resources = [
      "${path.module}/manifests/upstream.yaml",
    ]
  }

  ops = {
    replicas = [
      {
        name  = "<deployment-name>"
        count = 1
      }
    ]
  }
}
```

--------------------------------

### Inject Workspace Label in Apps Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example of injecting a label with the current Terraform workspace name onto all resources in the 'apps' environment.

```hcl
configuration = {
  apps = {
    resources = [
      "${path.module}/manifests/upstream.yaml",
    ]
    common_labels = {
      "env" = terraform.workspace
    }
  }

  ops = {}
}
```

--------------------------------

### GKE Example: Scaling Down Non-Production Node Pools

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Shows how to configure node pool settings for GKE, specifying machine type and node counts for the 'ops' environment, which are typically scaled down from production.

```terraform
ops = {
  default_node_pool = {
    machine_type   = "e2-medium"
    min_node_count = 1
    max_node_count = 1
  }
}
```

--------------------------------

### Use Debug Image Tag in Ops Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example of overriding an image tag with a debug tag for a specific container in the 'ops' environment.

```hcl
configuration = {
  apps = {
    resources = [
      "${path.module}/manifests/upstream.yaml",
    ]
  }

  ops = {
    images = [
      {
        name    = "<container-name>"
        new_tag = "<debug-tag>"
      }
    ]
  }
}
```

--------------------------------

### Apply JSON Patch in Ops Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Example of applying a JSON patch to modify a Kubernetes resource in the 'ops' environment when the 'replicas' attribute is insufficient.

```hcl
configuration = {
  apps = {
    resources = [
      "${path.module}/manifests/upstream.yaml",
    ]
  }

  ops = {
    patches = [
      {
        patch = <<-EOF
          - op: replace
            path: /spec/replicas
            value: 1
        EOF
        target = {
          kind = "Deployment"
          name = "<deployment-name>"
        }
      }
    ]
  }
}
```

--------------------------------

### Initialize and Plan Terraform

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

Initialize your Terraform configuration and then run `terraform plan` to review the proposed infrastructure changes.

```shell
# run terraform init
terraform init

# run, e.g. terraform plan
terraform plan
```

--------------------------------

### Build and Run Kubestack Container

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

Build the Kubestack Docker image and run it interactively. Mount the current directory as a volume and include the Docker socket for local development purposes.

```shell
# Build the container image
docker build -t kubestack .

# Exec into the container image
# add docker socket mount for local dev
# -v /var/run/docker.sock:/var/run/docker.sock
docker run --rm -ti \
   -v `pwd`:/infra \
   kubestack
```

--------------------------------

### Default Two-Environment Configuration Layout

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Sets up a basic configuration with 'apps' as the primary environment and 'ops' inheriting from it.

```terraform
configuration = {
  apps = {
    # All required and optional attributes go here.
    # ops inherits everything and may override individual values.
  }

  ops = {}
}
```

--------------------------------

### Tag Commit for Promotion to Apps Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

After successful application to the _ops_ environment, tag the merge commit with a prefix like `apps-deploy-` to promote the same changes to the _apps_ environment. Increment the counter for multiple deploys on the same day.

```shell
# make sure you're on the correct commit
git checkout main
git pull
git log -1

# if correct, tag the current commit
# any tag prefixed with `apps-deploy-`
# will trigger the pipeline
git tag apps-deploy-$(date -I)-0

# in case of multiple deploys on the same day,
# increase the counter
# e.g. git tag apps-deploy-2020-05-14-1
```

--------------------------------

### Initialize and Upgrade Terraform Providers

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Command to run after updating framework versions to refresh the Terraform lock file and ensure compatibility with new provider versions.

```bash
tofu init -upgrade
```

--------------------------------

### Render Helm Chart with Helm Repository

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use `helm template` to render a Helm repository-based chart with specified values and options. Requires adding the Helm repository first. Ensure `--include-crds` and `--create-namespace` are used.

```bash
helm repo add <repo-name> <repo-url>
helm template <release-name> <repo-name>/<chart-name> \
  --version <chart-version> \
  --values modules/<feature_name>/values.yaml \
  --namespace <namespace> \
  --create-namespace \
  --include-crds \
  > modules/<feature_name>/manifests/upstream.yaml
```

--------------------------------

### Git Short Hash for Bucket Naming

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Demonstrates how to obtain the short git hash of the repository's initial commit, used for creating globally unique object storage bucket names.

```bash
git rev-parse --short HEAD
```

--------------------------------

### Kustomization Overlay Resources Configuration

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Define resources for the kustomization overlay configuration. Always reference `upstream.yaml` via `${path.module}` to ensure correct path resolution.

```hcl
configuration = {
  apps = {
    # -------------------------------------------------------------------------
    # resources (required in the base environment)
    # List of paths to YAML files or Kustomization directories to deploy.
    # Always reference upstream.yaml via ${path.module} so the path resolves
    # correctly regardless of where OpenTofu is invoked from.
    # -------------------------------------------------------------------------
    resources = [
      "${path.module}/manifests/upstream.yaml",
    ]

```

--------------------------------

### Configure GKE Providers with Terraform

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Sets up the Google provider, kustomization provider for cluster access, and Kubernetes provider using raw kubeconfig. Ensure the provider aliases match the cluster module.

```terraform
provider "google" {
  alias = "gke_gc0_europe-west1"
  # project and region are passed inside the cluster module configuration.
  # Set them here only if you want a provider-level default.
  # project = "my-gcp-project"
  # region  = "europe-west1"
}

provider "kustomization" {
  alias          = "gke_gc0_europe-west1"
  kubeconfig_raw = module.gke_gc0_europe-west1.kubeconfig
}

locals {
  gke_gc0_europe-west1_kubeconfig = yamldecode(module.gke_gc0_europe-west1.kubeconfig)
}

provider "kubernetes" {
  alias = "gke_gc0_europe-west1"

  host                   = local.gke_gc0_europe-west1_kubeconfig["clusters"][0]["cluster"]["server"]
  cluster_ca_certificate = base64decode(local.gke_gc0_europe-west1_kubeconfig["clusters"][0]["cluster"]["certificate-authority-data"])
  token                  = local.gke_gc0_europe-west1_kubeconfig["users"][0]["user"]["token"]
}
```

--------------------------------

### Configure Scaleway Providers with Terraform

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Sets up the Scaleway provider, kustomization provider for cluster access, and Kubernetes provider using raw kubeconfig. Ensure the provider aliases match the cluster module.

```terraform
provider "scaleway" {
  alias  = "scw_gc0_fr-par"
  region = "fr-par"
}

provider "kustomization" {
  alias          = "scw_gc0_fr-par"
  kubeconfig_raw = module.scw_gc0_fr-par.kubeconfig
}

locals {
  scw_gc0_fr-par_kubeconfig = yamldecode(module.scw_gc0_fr-par.kubeconfig)
}

provider "kubernetes" {
  alias = "scw_gc0_fr-par"

  host                   = local.scw_gc0_fr-par_kubeconfig["clusters"][0]["cluster"]["server"]
  cluster_ca_certificate = base64decode(local.scw_gc0_fr-par_kubeconfig["clusters"][0]["cluster"]["certificate-authority-data"])
  token                  = local.scw_gc0_fr-par_kubeconfig["users"][0]["user"]["token"]
}
```

--------------------------------

### Three-Environment Configuration Layout with Production Base

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Defines a 'apps-prod' base configuration for production, with 'apps' and 'ops' environments inheriting and overriding as needed.

```terraform
configuration_base_key = "apps-prod"

configuration = {
  apps-prod = {
    # Production values — this is the base all others inherit from.
  }

  apps = {
    # Non-prod overrides, e.g. smaller instance type or replica count.
  }

  ops = {
    # Internal validation environment overrides.
  }
}
```

--------------------------------

### Configure AKS Providers with Terraform

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Sets up the Azure provider, kustomization provider for cluster access, and Kubernetes provider using raw kubeconfig. Ensure the provider aliases match the cluster module.

```terraform
provider "azurerm" {
  alias = "aks_gc0_westeurope"
  features {}
}

provider "kustomization" {
  alias          = "aks_gc0_westeurope"
  kubeconfig_raw = module.aks_gc0_westeurope.kubeconfig
}

locals {
  aks_gc0_westeurope_kubeconfig = yamldecode(module.aks_gc0_westeurope.kubeconfig)
}

provider "kubernetes" {
  alias = "aks_gc0_westeurope"

  host                   = local.aks_gc0_westeurope_kubeconfig["clusters"][0]["cluster"]["server"]
  cluster_ca_certificate = base64decode(local.aks_gc0_westeurope_kubeconfig["clusters"][0]["cluster"]["certificate-authority-data"])
  token                  = local.aks_gc0_westeurope_kubeconfig["users"][0]["user"]["token"]
}
```

--------------------------------

### Select Terraform Environment

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

Select the desired Terraform workspace for either the 'ops' or 'apps' environment before running Terraform commands.

```shell
# for ops
terraform workspace select ops

# or for apps
terraform workspace select apps
```

--------------------------------

### Setting Resource Arguments with Defaults

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

This pattern is used to set resource argument values, preferring upstream provider defaults. It uses `try(coalesce(local.cfg.<attribute>, null), <default>)` to handle cases where a Kubestack-level default is required, ensuring defaults are specified only once.

```hcl
endpoint_private_access = try(coalesce(local.cfg.cluster_endpoint_private_access, null), false)
endpoint_public_access  = try(coalesce(local.cfg.cluster_endpoint_public_access, null), true)
```

--------------------------------

### Exposing Merged Configuration Locally

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

After calling the `common/configuration` module, expose the merged configuration for the current workspace as a local value named `cfg`. This local value should be referenced for resource arguments.

```hcl
locals {
  cfg = module.configuration.merged[terraform.workspace]
}
```

--------------------------------

### Create Feature Branch and Stage Changes

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use these commands to create a new feature branch and stage modified Terraform files before committing. This is the first step in the GitOps workflow.

```bash
git checkout -b <descriptive-branch-name>
git add <list of changed files>
```

--------------------------------

### Render Helm Chart with OCI Distribution

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use `helm template` to render an OCI-distributed Helm chart with specified values and options. Ensure `--include-crds` and `--create-namespace` are used for a self-contained output.

```bash
helm template <release-name> oci://<registry>/<chart> \
  --version <chart-version> \
  --values modules/<feature_name>/values.yaml \
  --namespace <namespace> \
  --create-namespace \
  --include-crds \
  > modules/<feature_name>/manifests/upstream.yaml
```

--------------------------------

### Run Unit Tests for Common Modules

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

After changes to common/configuration or common/metadata, run the affected module's unit tests directly. This is necessary because 'make validate' does not cover these common modules.

```bash
make -C common/configuration test
```

```bash
make -C common/metadata test
```

--------------------------------

### Calling the Common Configuration Module

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

This snippet shows how to call the `common/configuration` module in your `main.tf` file to merge environment-specific configurations. It requires the `configuration` and `configuration_base_key` variables.

```hcl
module "configuration" {
  source        = "../../common/configuration"
  configuration = var.configuration
  base_key      = var.configuration_base_key
}
```

--------------------------------

### Promote Changes with Git Tag

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Tag the merge commit with an 'apps-deploy-*' timestamp to promote changes to the 'apps' environment. This triggers the GitOps pipeline to apply changes to the 'apps' workspace.

```bash
git tag apps-deploy-$(date +%Y%m%d%H%M%S)
git push origin --tags
```

--------------------------------

### Kubestack Terraform Module Directory Structure

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

Illustrates the standard directory layout for Kubestack Terraform modules, separating common and provider-specific components.

```plaintext
<repo-root>/
  common/              # Modules shared across all cloud providers
  <provider>/          # Provider-specific modules; directory name = TF provider name (aws, azurerm, google, scaleway, …)
    cluster/           # Cluster module
      node-pool/       # Node-pool submodule
```

--------------------------------

### Authenticate Cloud Providers

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

Authenticate with your cloud providers using their respective CLI tools. Credentials are typically cached in the `.user` directory, which is excluded from Git.

```shell
# for AWS
aws configure

# for Azure
az login

# for GCP
gcloud init
gcloud auth application-default login

# for Scaleway
scw init
```

--------------------------------

### Kubeconfig Generation using yamlencode

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

This HCL code demonstrates how to construct a kubeconfig as a local value using `yamlencode()`. It follows the standard Kubernetes kubeconfig structure and includes placeholders for cluster details, authentication tokens, and certificates.

```hcl
locals {
  kubeconfig = yamlencode({
    apiVersion = "v1"
    kind       = "Config"
    clusters = [{
      cluster = {
        server                     = "<cluster endpoint>"
        certificate-authority-data = "<base64-encoded CA certificate>"
      }
      name = "<cluster name>"
    }]
    users = [{
      user = { token = "<authentication token>" }   # or client-certificate-data / client-key-data
      name = "<cluster name>"
    }]
    contexts = [{
      context = {
        cluster = "<cluster name>"
        user    = "<cluster name>"
      }
      name = "<cluster name>"
    }]
    current-context = "<cluster name>"
    preferences     = {}
  })
}
```

--------------------------------

### Mandatory Module Variables

Source: https://github.com/kbst/terraform-kubestack/blob/master/AGENTS.md

All Kubestack modules must define these two variables exactly as shown. The `configuration` variable accepts a map of environment-specific configurations, and `configuration_base_key` defaults to 'apps'.

```hcl
variable "configuration" {
  type     = map(object({ ... }))   # map key = environment name (workspace)
  nullable = false
}

variable "configuration_base_key" {
  type     = string
  default  = "apps"                 # optional for module users; MUST be defined in all modules
  nullable = false
}
```

--------------------------------

### Prefix and Suffix Resource Names

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

The 'name_prefix' and 'name_suffix' attributes prepend or append strings to the metadata.name of every resource.

```hcl
name_prefix = "prefix-"
name_suffix = "-suffix"
```

--------------------------------

### Apply File-Based Strategic Merge Patch

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use the 'patches' attribute with the 'path' key to apply strategic merge patches from a file. The 'target' block can specify detailed selection criteria.

```hcl
patches = [
  {
    # File-based strategic merge patch:
    path = "${path.module}/manifests/patch.yaml"
    target = {
      group               = "apps"
      version             = "v1"
      kind                = "Deployment"
      name                = "example"
      namespace           = "example"
      label_selector      = "app=example"
      annotation_selector = "env=ops"
    }
  }
]
```

--------------------------------

### Scaleway Object Storage Remote State Backend Configuration

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Configures the Scaleway Object Storage backend, which is S3-compatible. The bucket must already exist. Ensure SCW_ACCESS_KEY and SCW_SECRET_KEY environment variables are set.

```terraform
terraform {
  backend "s3" {
    bucket = "<bucket-name>"
    key    = "tfstate"

    region   = "<region>"
    endpoint = "https://s3.<region>.scw.cloud"

    skip_credentials_validation = true
    skip_metadata_api_check     = true
    skip_region_validation      = true
    skip_requesting_account_id  = true
    use_path_style              = true
  }
}
```

--------------------------------

### Helm Chart Values Configuration

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Configure Helm values for the most critical environment (production-faithful baseline). Overrides for less critical environments should be applied via kustomization, not in this file.

```yaml
# values.yaml — configured for the <base_environment> (most critical) environment.
# Overrides for less critical environments are applied via the kustomization/overlay
# configuration map in main.tf, not here.
```

--------------------------------

### Commit and Push Branch

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Commit staged changes with a descriptive message and push the feature branch to the remote repository. This initiates the GitOps pipeline for planning.

```bash
git commit -m "<short description of what changed>"
git push -u origin <descriptive-branch-name>
```

--------------------------------

### Set Namespace for Resources

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use the 'namespace' attribute to set the metadata.namespace on resources that lack one, or to enforce all resources into a single namespace.

```hcl
namespace = "example"
```

--------------------------------

### Push Review Changes

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/README.md

If reviewers require changes, make them in the same branch, commit, and push them to your remote repository for re-review.

```shell
# make sure you're in the correct branch
git checkout examplechange

# make changes required by the review

# commit and push the required changes
git commit  # write a meaningful commit message
git push origin examplechange
```

--------------------------------

### Refresh Provider Lock File

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

If updating the framework version, refresh the provider lock file using 'tofu init -upgrade' and stage the updated '.terraform.lock.hcl' file. This ensures consistent provider versions for the new release.

```bash
tofu init -upgrade
git add .terraform.lock.hcl
```

--------------------------------

### Configure Scaleway Cluster with Terraform

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Defines a Scaleway (Kapsule) cluster module, specifying the source, version, and application/operations configurations. Ensure 'region' and node pool settings are correctly configured.

```terraform
module "scw_gc0_fr-par" {
  providers = {
    scaleway = scaleway.scw_gc0_fr-par
  }

  source = "github.com/kbst/terraform-kubestack//scaleway/cluster?ref=<version>"

  configuration = {
    apps = {
      name_prefix = "gc0"
      base_domain = "infra.example.com"

      region = "fr-par"

      default_node_pool = {
        node_type = "PRO2-S"

        zones = ["fr-par-1", "fr-par-2", "fr-par-3"]

        min_size = 1
        max_size = 3
      }
    }

    ops = {}
  }
}
```

--------------------------------

### Add Common Annotations to Resources

Source: https://github.com/kbst/terraform-kubestack/blob/master/quickstart/src/configurations/_shared/AGENTS.md

Use 'common_annotations' to add or override annotations on all resources. This is helpful for metadata that applies globally.

```hcl
common_annotations = {
  "example-annotation" = "value"
}
```