Skip to main content

Core concepts

Table of Contents​

  1. Application
  2. Project
  3. Repository
  4. Sync and Health Status
  5. Resource Hooks
  6. Hands-on exercises

1 - Application​

Definition​

An Argo CD Application represents a set of Kubernetes resources deployed from a Git source.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  
  source:
    repoURL: https://github.com/org/gitops-repo.git
    targetRevision: HEAD
    path: apps/my-app
  
  destination:
    server: https://kubernetes.default.svc
    namespace: default

Structure of an Application​

Main fields​

FieldDescription
projectArgo CD project (default by default)
source.repoURLURL of the Git repository
source.pathPath to the manifests
source.targetRevisionBranch, tag or commit
destination.serverURL of the K8s cluster
destination.namespaceTarget namespace

🔝 Back to table of contents​

2 - Project​

Definition​

A Project defines constraints and permissions for a group of applications.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  description: "Production applications"
  
  # Repositories autorisés
  sourceRepos:
    - https://github.com/org/gitops-prod.git
  
  # Clusters autorisés
  destinations:
    - namespace: production
      server: https://kubernetes.default.svc
    - namespace: monitoring
      server: https://kubernetes.default.svc
  
  # Ressources autorisées
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
  
  namespaceResourceWhitelist:
    - group: 'apps'
      kind: Deployment
    - group: ''
      kind: Service

The "default" project​

# Projet default - permet tout
spec:
  sourceRepos:
    - '*'
  destinations:
    - namespace: '*'
      server: '*'
  clusterResourceWhitelist:
    - group: '*'
      kind: '*'

Use cases for Projects​

ScenarioConfiguration
Multi-tenantOne project per team
SecurityLimit clusters/namespaces
ComplianceRestrict K8s resources

🔝 Back to table of contents​

3 - Repository​

Source types​

TypeDescriptionExample
DirectoryRaw YAML manifestspath: apps/
HelmHelm chartchart: nginx
KustomizeKustomizationpath: overlays/prod
JsonnetJsonnet filespath: jsonnet/

Directory source (YAML)​

spec:
  source:
    repoURL: https://github.com/org/gitops.git
    path: apps/my-app
    directory:
      recurse: true
      include: '*.yaml'

Helm source​

spec:
  source:
    repoURL: https://charts.bitnami.com/bitnami
    chart: nginx
    targetRevision: 15.0.0
    helm:
      values: |
        replicaCount: 3
        service:
          type: ClusterIP

Kustomize source​

spec:
  source:
    repoURL: https://github.com/org/gitops.git
    path: apps/my-app/overlays/prod
    kustomize:
      images:
        - name: my-app
          newTag: v1.2.3

Add a private repository​

# Via CLI - HTTPS avec token
argocd repo add https://github.com/org/private-repo.git \
  --username git \
  --password ghp_xxxxxxxxxxxx

# Via CLI - SSH
argocd repo add [email protected]:org/private-repo.git \
  --ssh-private-key-path ~/.ssh/id_rsa

🔝 Back to table of contents​

4 - Sync and Health Status​

Sync Status​

StatusDescription
SyncedCluster state = Git state
OutOfSyncDifference detected
UnknownUnable to determine

Health Status​

StatusDescription
HealthyAll resources OK
ProgressingDeploying
DegradedProblem detected
SuspendedIntentionally paused
MissingResource does not exist

View the status​

# Via CLI
argocd app get my-app

# Résultat
Name:               my-app
Project:            default
Server:             https://kubernetes.default.svc
Namespace:          default
URL:                https://argocd.example.com/applications/my-app
Sync Status:        Synced
Health Status:      Healthy

🔝 Back to table of contents​

5 - Resource Hooks​

Hook types​

HookExecution
PreSyncBefore synchronization
SyncDuring synchronization
PostSyncAfter synchronization
SyncFailIf the sync fails

Example: Database migration​

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration
  annotations:
    argocd.argoproj.io/hook: PreSync
    argocd.argoproj.io/hook-delete-policy: HookSucceeded
spec:
  template:
    spec:
      containers:
        - name: migrate
          image: my-app:latest
          command: ["./migrate.sh"]
      restartPolicy: Never

Hook Delete Policies​

PolicyBehavior
HookSucceededDelete on success
HookFailedDelete on failure
BeforeHookCreationDelete before recreation

🔝 Back to table of contents​

6 - Hands-on exercises​

Quiz​

Q1. What is the difference between Synced and Healthy?

Answer
  • Synced: The state in the cluster matches the state in Git
  • Healthy: The Kubernetes resources are working correctly (pods running, etc.)

An application can be Synced but not Healthy (e.g. pods in CrashLoopBackOff).

Q2. What is an AppProject for?

Answer

An AppProject defines security constraints:

  • Which repositories can be used
  • Which clusters/namespaces are allowed
  • Which K8s resources can be created

It is essential for multi-tenancy and security.

Exercise: Create a Project​

# production-project.yaml
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: production
  namespace: argocd
spec:
  description: "Applications de production"
  sourceRepos:
    - https://github.com/org/gitops-prod.git
  destinations:
    - namespace: production
      server: https://kubernetes.default.svc
  clusterResourceWhitelist:
    - group: ''
      kind: Namespace
kubectl apply -f production-project.yaml

🔝 Back to table of contents​

Key takeaways​

  • Application = deployment definition
  • Project = security constraints
  • Repository = Git source (YAML, Helm, Kustomize)
  • Sync Status = Git vs Cluster comparison
  • Health Status = state of the K8s resources
  • Hooks = actions during sync

← Previous chapter | Next chapter: Applications →