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
```yaml
helmCharts:
  - name: <chart-name>
    repo: <helm-repo-url>
    version: "<version>"
    releaseName: <release-name>
    namespace: <namespace>
    valuesFile: values.yaml
```

### VaultAuth Template
```yaml
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
```yaml
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