Add a New Application

Before You Change Anything

These steps can affect shared dev workloads or the GitOps control layer. Confirm the target repo, environment, and intended owner before mutating anything.

This guide walks through adding a new application to the ArgoCD app-of-apps structure. The process has 4 steps: vendor the chart, create values, create the Application CR, and commit.

Prerequisites

Access to the crawbl-argocd-apps repository.
Helm CLI installed (helm version).
Understanding of which existing applications your new app depends on.

Step 1

Vendor the Helm chart

Crawbl vendors third-party charts into Git so deploys do not depend on outside chart registries at sync time.

cd crawbl-argocd-apps
helm repo add <repo-name> <repo-url>
helm repo update
helm pull <repo-name>/<chart-name> --version <version> \
  --untar -d components/<name>/chart/

For OCI charts:

helm pull oci://<registry>/<chart> --version <version> \
  --untar -d components/<name>/chart/

Step 2

Create environment values

Add components/<name>/envs/dev.yaml with only the values that differ from the chart defaults.

mkdir -p components/<name>/envs

prometheus:
  prometheusSpec:
    retention: 7d
    resources:
      limits:
        memory: 512Mi
grafana:
  enabled: true
  adminPassword: "${GRAFANA_ADMIN_PASSWORD}"

If you need raw manifests outside the chart, place them in components/<name>/resources/.

Step 3

Create the Application CR

Add root/<name>.yaml so ArgoCD knows how to deploy the component.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "5"
spec:
  source:
    path: components/my-app/chart/<chart-dir-name>
    helm:
      valueFiles:
        - ../../envs/dev.yaml
  destination:
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

The sync-wave controls order, CreateNamespace=true creates the target namespace, and prune plus selfHeal keep the cluster aligned with Git.

note

The monitoring stack (VictoriaMetrics, VictoriaLogs, Fluent Bit) is prod-only and is not added to the dev cluster via this process.

Step 4

Commit and push

Commit the component and root app manifests, then push to trigger ArgoCD.

git add components/<name>/ root/<name>.yaml
git commit -m "Add <name> application to ArgoCD"
git push origin main

ArgoCD should detect the new app within a few minutes.

How to Pick the Right Sync Wave

Sync waves control deployment order. Lower waves deploy first. ArgoCD waits for all resources in a wave to be healthy before starting the next wave.

Current wave assignments:

Wave	Applications	Purpose
0	platform-resources	Shared namespaces and bootstrap manifests
1	cert-manager, envoy-gateway	Core platform addons
2	external-secrets	Secret sync controller
3	metacontroller	Metacontroller plus UserSwarm CRD/webhook/reaper
5	postgresql, redis, external-dns	Shared data services and DNS
6	orchestrator, docs, pgweb	User-facing workloads

To choose the wave for your new application:

List all applications your new app depends on.
Find the highest wave among those dependencies.
Use that wave or higher.

Example: if your new app needs PostgreSQL (wave 5) and the orchestrator (wave 6), place it at wave 7 or higher.

If your app has no dependencies on existing applications, use wave 1.

Monitor the rollout with:

kubectl get application <name> -n argocd -w

What's next: Upgrade a Vendored Chart

Prerequisites​