Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Help improve this page

To contribute to this user guide, choose the Edit this page on GitHub link that is located in the right pane of every page.

Working with Argo CD Projects

Argo CD Projects (AppProject) provide logical grouping and access control for Applications. Projects define which Git repositories, target clusters, and namespaces Applications can use, enabling multi-tenancy and security boundaries in shared Argo CD instances.

When to use projects

Use Projects to:

Default project

Every Argo CD capability includes a default project that allows access to all repositories, clusters, and namespaces. While useful for initial testing, create dedicated projects with explicit restrictions for production use.

For details on the default project configuration and how to restrict it, see The Default Project in the Argo CD documentation.

Create a project

Create a Project by applying an AppProject resource to your cluster.

Example: Team-specific Project

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  description: Applications for Team A

  # Source repositories this project can deploy from
  sourceRepos:
    - 'https://github.com/my-org/team-a-*'
    - 'https://github.com/my-org/shared-libs'


  # Source namespaces (required for EKS capability)
  sourceNamespaces:
    - argocd
    - team-a-gitops

  # Destination clusters and namespaces
  destinations:
    - name: dev-cluster
      namespace: team-a-dev
    - name: prod-cluster
      namespace: team-a-prod

  # Allowed resource types
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace

  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
    - group: ''
      kind: ConfigMap

Apply the Project:

kubectl apply -f team-a-project.yaml

Project configuration

Source repositories

Control which Git repositories Applications in this project can use:

spec:
  sourceRepos:
    - 'https://github.com/my-org/app-*'  # Wildcard pattern
    - 'https://github.com/my-org/infra'  # Specific repo

You can use wildcards and negation patterns (! prefix) to allow or deny specific repositories. For details, see Managing Projects in the Argo CD documentation.

Source namespaces

When using the EKS Argo CD capability, the spec.sourceNamespaces field is required in your custom AppProject definition. This field controls which namespaces can contain Applications or ApplicationSets that reference the project. Create AppProject resources in the primary Argo CD namespace, even when the Applications and ApplicationSets are in additional namespaces.

Default AppProject behavior

The default AppProject is broadly permissive and automatically works for resources in the primary Argo CD namespace. Don’t add team-controlled additional namespaces to the default project. Instead, create a custom AppProject for each team or trust boundary and restrict its source repositories, destinations, and resource types.

Custom AppProject configuration

The following example keeps the AppProject in the primary argocd namespace and permits Applications and ApplicationSets from team-a-gitops:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  description: Applications for Team A

  # Required: Include the primary namespace and each permitted source namespace
  sourceNamespaces:
    - argocd
    - team-a-gitops

  # Source repositories this project can deploy from
  sourceRepos:
    - 'https://github.com/my-org/team-a-*'

  # Destination restrictions
  destinations:
    - namespace: 'team-a-*'
      server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster

Destination restrictions

Limit where Applications can deploy:

spec:
  destinations:
    - name: prod-cluster  # Specific cluster by name
      namespace: production
    - name: '*'  # Any cluster
      namespace: team-a-*  # Namespace pattern

You can use wildcards and negation patterns to control destinations. For details, see Managing Projects in the Argo CD documentation.

Resource restrictions

Control which Kubernetes resource types can be deployed:

Cluster-scoped resources:

spec:
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
    - group: 'rbac.authorization.k8s.io'
      kind: Role

Namespace-scoped resources:

spec:
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service
    - group: ''
      kind: ConfigMap
    - group: 's3.services.k8s.aws'
      kind: Bucket

Use blacklists to deny specific resources:

spec:
  namespaceResourceBlacklist:
    - group: ''
      kind: Secret  # Prevent direct Secret creation

Assign applications to projects

When creating an Application, specify the project in the spec.project field:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: team-a  # Assign to team-a project
  source:
    repoURL: https://github.com/my-org/my-app
    path: manifests
  destination:
    name: prod-cluster
    namespace: team-a-prod

Applications without a specified project use the default project.

Project roles and RBAC

Projects can define custom roles for fine-grained access control. Map project roles to AWS Identity Center users and groups in your capability configuration to control who can sync, update, or delete applications.

Example: Project with developer and admin roles

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  sourceRepos:
    - '*'
  destinations:
    - name: '*'
      namespace: 'team-a-*'

  roles:
    - name: developer
      description: Developers can sync applications
      policies:
        - p, proj:team-a:developer, applications, sync, team-a/*, allow
        - p, proj:team-a:developer, applications, get, team-a/*, allow
      groups:
        - team-a-developers

    - name: admin
      description: Admins have full access
      policies:
        - p, proj:team-a:admin, applications, *, team-a/*, allow
      groups:
        - team-a-admins

For details on project roles, JWT tokens for CI/CD pipelines, and RBAC configuration, see Project Roles in the Argo CD documentation.

Common patterns

Environment-based Projects

Create separate projects for each environment:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/*'
  destinations:
    - name: prod-cluster
      namespace: '*'
  # Strict resource controls for production
  clusterResourceWhitelist: []
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service

Team-based Projects

Isolate teams with dedicated projects:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: platform-team
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/platform-*'
  destinations:
    - name: '*'
      namespace: 'platform-*'
  # Platform team can manage cluster resources
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'

Multi-cluster Projects

Deploy to multiple clusters with consistent policies:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: global-app
  namespace: argocd
spec:
  sourceRepos:
    - 'https://github.com/my-org/global-app'
  destinations:
    - name: us-west-cluster
      namespace: app
    - name: eu-west-cluster
      namespace: app
    - name: ap-south-cluster
      namespace: app

Best practices

Start with restrictive Projects: Begin with narrow permissions and expand as needed rather than starting with broad access.

Use namespace patterns: Leverage wildcards in namespace restrictions (like team-a-*) to allow flexibility while maintaining boundaries.

Separate production Projects: Use dedicated Projects for production with stricter controls and manual sync policies.

Document Project purposes: Use the description field to explain what each Project is for and who should use it.

Review Project permissions regularly: Audit Projects periodically to ensure restrictions still align with team needs and security requirements.

Additional resources