devops-infra-argo-config-gcp/skills/infra/add-tool.md

Skill: Add Tool to Cluster

Parameterized agent task for adding a new appSpec entry to a cluster values file.

Layer: 1-T (Tool-Mediated). Agent generates the diff and opens a PR.

Procedure: docs/platform/procedures/add-tool-to-cluster.md

---

When to use

Trigger on requests like:

• "Add <tool> to <cluster>"
• "Deploy <tool> on <cluster>"
• "Onboard <tool> to <cluster>"
• "Roll out <tool> to <cluster>"

---

Inputs

Parameter	Required	Example	Source
tool_name	yes	kyverno	User request
cluster	yes	k8s-farmiso-prd-ase1	User request
env	yes	prd	Derived from cluster name
namespace	yes	kyverno-farmiso-prd	Convention: <tool>-<mungedCluster>
chartDir	yes	kyverno	Must exist in devops-infra-helm-charts/helm-templates/
valuesDir	yes	kyverno	Must exist in devops-infra-helm-charts/helm-overrides/<cluster>/

---

Steps (deterministic — no branching)

Step 0: Resolve the values file path

values/<env>/incubator-infra-<cluster>-values.yaml

Halt if the file doesn't exist — the cluster may not be onboarded yet. Direct user to add-new-cluster.md.

Step 1: Verify chartDir exists in devops-infra-helm-charts

ls /path/to/devops-infra-helm-charts/helm-templates/<chartDir>/

Halt if missing. The chart must be created in the sister repo first.

Step 2: Verify valuesDir exists in devops-infra-helm-charts

ls /path/to/devops-infra-helm-charts/helm-overrides/<cluster>/<valuesDir>/custom-values.yaml

Halt if missing. The override must be created in the sister repo first.

Step 3: Compute the auto-generated Application name

Apply munging rules:

<tool_name>-<mungedCluster>-<env>

Where mungedCluster = strip k8s-, prd-, int-, dev-, -ase1; map -ase1c → -c.

Step 4: Check for name collisions

grep "^\s*- name:" values/<env>/incubator-infra-<cluster>-values.yaml

Verify the computed Application name doesn't collide with any existing entry.

Step 5: Append the appSpec entry

Add to the appSpec list in the values file:

  - name: <tool_name>
    namespace: <namespace>
    chartDir: <chartDir>
    valuesDir: <valuesDir>

Do NOT add nameOverride unless Step 4 found a collision.

Step 6: Validate

helm template generic-argo-apps-chart/ \
  -f values/<env>/incubator-infra-<cluster>-values.yaml | grep -A 20 "name: <tool_name>"

yamllint values/<env>/incubator-infra-<cluster>-values.yaml

Step 7: Open PR

Title: add <tool_name> to <cluster>

PR body checklist:

• chartDir exists in devops-infra-helm-charts/helm-templates/
• valuesDir exists in devops-infra-helm-charts/helm-overrides/<cluster>/
• Application name <= 253 characters
• No name collision
• helm template renders correctly
• Pre-commit hooks pass

---

Output

One modified file: values/<env>/incubator-infra-<cluster>-values.yaml with a new appSpec entry appended.

---

Gotchas

1. Never skip Step 1 and Step 2. A missing chartDir or valuesDir will cause ArgoCD render failure fleet-wide on auto-sync.
2. Auto-sync means immediate deploy. Once the PR merges to main, the tool is deployed. There is no "staging deploy" step.
3. Namespaces must be unique per cluster. Two tools can share a namespace (e.g., victoriametrics), but this should be intentional and documented.
4. Multi-instance tools (e.g., contour-internal-0, contour-internal-1) need unique name and valuesDir per instance.