---
name: terraform-update-app-version
description: >
  Use when updating a container image version for an app managed by Terraform in
  this repository. Covers how to find where the tag is set, update dev-01 and
  prod-01 app roots safely, run sectool-wrapped OpenTofu validation and plan,
  apply changes, and verify rollout with kubectl.
---

# Terraform Update App Version Skill

## Purpose

Use this skill when you need to update the deployed container image version for an app module.

This repository usually sets the image tag in the app root module call (`terraform/apps/<cluster>/apps.tf`) and passes it to the module variable `tag`, then to `local.app_version` inside the module.

Always use pinned tags. Do not use `latest`.

---

## Scope

Update both clusters unless the request explicitly says otherwise:

- dev-01: `terraform/apps/dev-01`
- pro-01 folder: `terraform/apps/prod-01`

Note: production is often called "pro-01" in discussion, but the folder name is `prod-01`.

---

## Where to Change the Version

Common location:

- `terraform/apps/<cluster>/apps.tf`

Pattern:

```hcl
module "<app_name>" {
  source = "../../modules/apps/<app_name>"
  ...
  tag    = "<image-tag>"
}
```

Module wiring pattern:

- `terraform/modules/apps/<app_name>/variables.tf` defines `variable "tag"`
- `terraform/modules/apps/<app_name>/config.tf` typically sets `local.app_version = var.tag`
- `terraform/modules/apps/<app_name>/main.tf` uses `${local.app_version}` in image reference

If tag is not in the app root, check the module defaults and root overrides before editing.

---

## Update Workflow

Run from each app root directory (`terraform/apps/dev-01` and `terraform/apps/prod-01`) as needed.

1. Edit `apps.tf` and set the new pinned tag.
2. Validate configuration:

```bash
tofu fmt
sectool -f ../../../sectool.json exec tofu validate
```

3. Review plan:

```bash
sectool -f ../../../sectool.json exec tofu plan
```

4. Apply:

```bash
sectool -f ../../../sectool.json exec tofu apply -auto-approve
```

5. Verify rollout:

```bash
kubectl --context microk8s-<cluster> -n <namespace> rollout status deployment/<deployment> --timeout=120s
kubectl --context microk8s-<cluster> -n <namespace> get pods -o wide
kubectl --context microk8s-<cluster> -n <namespace> logs deployment/<deployment> --all-containers=true --tail=200
```

---

## Emergency Recovery

If immediate recovery is required, a targeted apply can be used temporarily:

```bash
sectool -f ../../../sectool.json exec tofu apply -auto-approve -target=module.<app_name>
```

Afterward, always run a full plan to detect drift:

```bash
sectool -f ../../../sectool.json exec tofu plan
```

---

## Review Checklist

- [ ] New image tag is pinned and explicit.
- [ ] Both cluster roots were considered (dev-01 and prod-01).
- [ ] Commands were run with `sectool -f ../../../sectool.json exec tofu`.
- [ ] Rollout and pod health were verified with kubectl.
- [ ] Any runtime hotfix used during debugging was persisted back into Terraform.