Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Applications and Projects

Argo CD AppProjects: Guardrails for Teams and Applications

Use AppProjects to limit which repositories, clusters, namespaces and resource kinds an Argo CD Application may use, add project roles and sync windows, and replace the permissive default project.

An Application can deploy anything the Argo CD controller is allowed to deploy, which on a typical install is everything, including cluster-admin level objects. That is fine for one person on a laptop and dangerous for a company. AppProjects are Argo CD's multi-tenancy boundary: each Application belongs to exactly one project, and the project defines what its Applications may do.

The YAML is real Argo CD configuration. The runnable code is a stand-in evaluator that applies project rules to a proposed Application so you can experiment with allow and deny lists. It is a model, not Argo CD's implementation.

The default project

Argo CD ships with a project called default that allows all source repositories, all destinations and all resource kinds. Applications with no explicit project use it. Treat it as a bootstrap convenience: create your own projects and, in mature setups, restrict or even lock default.

An AppProject manifest

YAML
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: storefront
  namespace: argocd
spec:
  description: Shop teams
  sourceRepos:
    - https://github.com/example/config.git
    - https://charts.example.com
  destinations:
    - server: https://kubernetes.default.svc
      namespace: shop-*
    - name: production-eu
      namespace: shop
  clusterResourceWhitelist: []          # no cluster-scoped kinds at all
  namespaceResourceBlacklist:
    - group: ""
      kind: ResourceQuota
    - group: ""
      kind: LimitRange
  orphanedResources:
    warn: true

What a project controls

Project guardrails

Sources Which repos are allowed
Destinations Which clusters and namespaces
Resource kinds Which kinds may be created
Roles Who can do what

An app outside the rules fails to sync.

1 / 2
  • sourceRepos: allowed repository URLs, with * wildcards and ! for exclusions. A project with an empty list allows nothing.
  • destinations: allowed server or name plus namespace combinations; wildcards such as shop-* work.
  • Cluster-scoped kinds: clusterResourceWhitelist and clusterResourceBlacklist list group/kind pairs. If a whitelist is absent, no cluster-scoped resources are allowed (so a team cannot create ClusterRoles or Namespaces unless you list them; note that CreateNamespace=true needs Namespace allowed).
  • Namespaced kinds: namespaceResourceWhitelist and namespaceResourceBlacklist. By default all are allowed except those blacklisted.
  • roles: project-level RBAC, with policies and optional JWT tokens for automation.
  • syncWindows: schedules that allow or deny syncs (for example, no production syncs on Friday evenings).
  • orphanedResources: warn about resources in the namespace that no Application manages.
  • signatureKeys: require commits to be GPG-signed by listed keys.
  • sourceNamespaces: which namespaces may host Applications of this project.

Roles inside a project

YAML
spec:
  roles:
    - name: deployer
      description: Can sync apps in this project
      policies:
        - p, proj:storefront:deployer, applications, get, storefront/*, allow
        - p, proj:storefront:deployer, applications, sync, storefront/*, allow
      groups:
        - my-org:storefront-engineers

Policy lines follow the pattern p, subject, resource, action, object, effect. Here the object storefront/* means every application in project storefront. Mapping groups to SSO groups gives a whole team those rights. The security chapter covers RBAC in detail.

Sync windows

YAML
spec:
  syncWindows:
    - kind: deny
      schedule: '0 17 * * 5'     # Fridays at 17:00
      duration: 64h               # until Monday 09:00
      applications: ['*']
      manualSync: false
    - kind: allow
      schedule: '0 9 * * 1-4'
      duration: 8h
      namespaces: ['shop-*']

A deny window stops automated syncs (and, with manualSync: false, manual ones too). Use windows to avoid risky changes at bad times.

Stand-in: evaluate an Application against a project

The stand-in below checks a proposed Application against a project and explains every violation. Try changing the repository, namespace or kinds.

JS Stand-in: project rule checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: sync window

The second stand-in decides whether a sync is allowed at a given time with a simplified weekly deny window.

JS Stand-in: sync window

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Good practices

  1. One project per team or product, not per application.
  2. Never put team applications into default.
  3. List exact repositories; avoid * in sourceRepos in shared installs.
  4. Whitelist only the cluster-scoped kinds a team truly needs.
  5. Keep the AppProject manifests in Git, owned by the platform team.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many projects does each Application belong to?

    Each Application names exactly one project in spec.project.
  2. 2. A project has no clusterResourceWhitelist. Can its apps create a ClusterRole?

    Without a whitelist entry, cluster-scoped resource kinds are denied.
  3. 3. Which field lets you block production syncs at certain times?

    syncWindows define allow and deny schedules for syncing.
  4. 4. Why should team apps not live in the default project?

    default is unrestricted, so it provides no guardrails.

Summary

  • AppProjects are the multi-tenancy boundary: sources, destinations, resource kinds, roles and sync windows.
  • Every Application belongs to one project; default is permissive and best left for bootstrapping.
  • Cluster-scoped kinds need an explicit whitelist; namespaced kinds can be blacklisted.
  • Project roles give teams narrow rights and can map to SSO groups.
  • Keep project manifests in Git and give each team its own project.

Next: Repositories and Credentials