argocd-apps/migration.md

Migration Guide: Terragrunt to ArgoCD

Prerequisites

• Examine existing Terraform configuration in sources/terraform-k8s/config/<app-name>/
• Identify Helm charts, values, storage classes, secrets, and other resources

Migration Steps

1. Branch Creation

• Change back to main branch: git checkout main
• Create new branch: git checkout -b benvin/<app-name>

2. Create Base Application Structure

• Create directory: apps/base/<app-name>/
• Create apps/base/<app-name>/kustomization.yaml with resources:
  • namespace.yaml
  • vaultauth.yaml (if needed)
  • vaultstaticsecret.yaml (if needed)
  • Additional resources as required (storageclass.yaml, etc.)

3. Create Namespace

• Create apps/base/<app-name>/namespace.yaml with app namespace

4. Create Vault Integration (if needed)

• Create apps/base/<app-name>/vaultauth.yaml from Terraform vault_auth.yaml
  • Convert snake_case to camelCase for Kubernetes
  • Map Terraform fields to VaultAuth spec
• Create apps/base/<app-name>/vaultstaticsecret.yaml from vault_static_secret.yaml
  • Convert to VaultStaticSecret spec format

5. Create Additional Resources

• Create any additional resources (StorageClass, etc.) from Terraform config
• Maintain exact parameter parity with Terraform

6. Create Overlay Structure

• Create directory: apps/overlays/au-syd1/<app-name>/
• Create apps/overlays/au-syd1/<app-name>/kustomization.yaml:
  • Reference base: ../../../base/<app-name>
  • Add helmCharts section with repo, version, valuesFile
• Create apps/overlays/au-syd1/<app-name>/values.yaml from Terraform helm_release values

7. Update Project Configuration

• Add Helm repository to appropriate project in argocd/projects/
• Add namespace to project destinations (if needed)
• Add required cluster resource permissions

8. Update ApplicationSet

• Add directory pattern to appropriate ApplicationSet in argocd/applicationsets/
• Use existing patterns like apps/overlays/*/csi-* or apps/overlays/*/<app-name>

9. Validation

• Run kustomize build --enable-helm apps/overlays/au-syd1/<app-name> to generate all resources
• Check resource types: kustomize build --enable-helm apps/overlays/au-syd1/<app-name> | grep "^kind:" | sort | uniq -c
• Verify all resource types are permitted in the target project's clusterResourceWhitelist and namespaceResourceWhitelist
• Run make kubeconform to validate all resources
• Fix any validation errors

10. Git Workflow

• Add only created/modified files: git add apps/base/<app-name>/ apps/overlays/au-syd1/<app-name>/ argocd/projects/<project>.yaml argocd/applicationsets/<project>.yaml
• Never use git add .
• Create commit with descriptive message following existing patterns
• Push branch: git push -u origin benvin/<app-name>

Project Organization

Platform Project

• Core infrastructure and system components
• Examples: cert-manager, external-dns, cnpg-system, reflector-system, etc.

Storage Project

• Storage-related components
• Pattern: csi-* applications
• Examples: csi-cephfs, csi-cephrbd

Application-Specific Projects

• Create new projects for logical groupings as needed

Common Patterns

Helm Chart Integration

helmCharts:
  - name: <chart-name>
    repo: <helm-repo-url>
    version: "<version>"
    releaseName: <release-name>
    namespace: <namespace>
    valuesFile: values.yaml

VaultAuth Template

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultAuth
metadata:
  name: <auth-name>
  namespace: <namespace>
spec:
  method: kubernetes
  mount: k8s/au/syd1
  vaultConnectionRef: vso-system/default
  allowedNamespaces:
    - <namespace>
  kubernetes:
    role: <role>
    serviceAccount: <service-account>
    audiences:
      - vault
    tokenExpirationSeconds: 600

VaultStaticSecret Template

apiVersion: secrets.hashicorp.com/v1beta1
kind: VaultStaticSecret
metadata:
  name: <secret-name>
  namespace: <namespace>
spec:
  vaultAuthRef: <auth-ref>
  mount: kv
  type: kv-v2
  path: <vault-path>
  refreshAfter: 5m
  destination:
    name: <k8s-secret-name>
    create: true

Troubleshooting

Pre-commit Hook Issues

• If hooks modify files, add changes: git add -u
• Amend commit if safe: git commit --amend --no-edit
• Use git push --force-with-lease for amended commits

Validation Failures

• Check Helm chart compatibility with Kubernetes version
• Verify all required fields are present in resources
• Ensure proper YAML formatting

Missing Permissions

• Add required cluster resources to project clusterResourceWhitelist
• Add namespaces to project destinations
• Verify Helm repository is in project sourceRepos