Core Mode Installation

Install Argo CD Core for headless GitOps operation

Argo CD Core is a lightweight, headless installation that provides GitOps functionality without the API server, Web UI, or Argo CD RBAC. It’s ideal for cluster administrators who want to use Argo CD’s GitOps engine with Kubernetes RBAC only.

Argo CD Core runs Argo CD in headless mode with a minimal set of components. It’s perfect for single-cluster, single-admin scenarios where the full Argo CD feature set isn’t needed.

When to Use Core Mode

Choose Argo CD Core if:

• ✅ You’re a cluster admin who wants to rely on Kubernetes RBAC only
• ✅ You want to automate deployments using the Kubernetes API only
• ✅ You don’t need to provide Argo CD UI or CLI to developers
• ✅ You prefer a simpler, more minimalist installation
• ✅ You’re managing a single cluster with a small team

Argo CD Core is not recommended if you need:

• Multi-tenancy with Argo CD RBAC
• Full-featured Web UI
• OIDC/SSO authentication
• Notifications controller
• Remote API access for CI/CD

Architecture

Included Components

Argo CD Core includes only the essential GitOps components:

Installed

• Application Controller (argocd-application-controller)
  • Monitors applications and reconciles state
  • Syncs desired state from Git to clusters
• Repository Server (argocd-repo-server)
  • Clones Git repositories
  • Generates manifests (Helm, Kustomize, etc.)
• Redis (argocd-redis)
  • Caching layer
  • Improves performance and reduces API load
• ApplicationSet Controller (argocd-applicationset-controller)
  • Manages ApplicationSet resources
  • Enables multi-app templating

Not Included

The following components are not included in Core mode:

• ❌ API Server (argocd-server)
  • No Web UI
  • No REST/gRPC API
• ❌ Dex Server (argocd-dex-server)
  • No OIDC/SSO support
• ❌ Notifications Controller
  • No Slack, email, or webhook notifications
• ❌ Argo CD RBAC
  • Relies on Kubernetes RBAC instead

Architecture Diagram

┌─────────────────────────────────────────┐
│         Argo CD Core                    │
│                                         │
│  ┌────────────────┐  ┌──────────────┐  │
│  │  Application   │  │  Repository  │  │
│  │  Controller    │──│   Server     │  │
│  └────────────────┘  └──────────────┘  │
│          │                   │          │
│          └───────┬───────────┘          │
│                  │                      │
│          ┌───────▼────────┐             │
│          │     Redis      │             │
│          └────────────────┘             │
│                                         │
│  ┌────────────────────────────────┐    │
│  │  ApplicationSet Controller     │    │
│  └────────────────────────────────┘    │
└─────────────────────────────────────────┘
              │
              ▼
      Kubernetes API
   (Uses kubeconfig RBAC)

Installation

1. Create the namespace

   Create a dedicated namespace for Argo CD:

   kubectl create namespace argocd
   
2. Install Argo CD Core

   Apply the core installation manifest:

   kubectl apply -n argocd --server-side --force-conflicts \
     -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/core-install.yaml
   

   For a specific version:

   export ARGOCD_VERSION=v2.14.0
   kubectl apply -n argocd --server-side --force-conflicts \
     -f https://raw.githubusercontent.com/argoproj/argo-cd/$ARGOCD_VERSION/manifests/core-install.yaml
   
3. Verify the installation

   Check that all pods are running:

   kubectl get pods -n argocd
   

   Expected output:

   NAME                                               READY   STATUS
   argocd-application-controller-0                    1/1     Running
   argocd-applicationset-controller-xxx               1/1     Running
   argocd-redis-xxx                                   1/1     Running
   argocd-repo-server-xxx                             1/1     Running
   

   Notice that argocd-server and argocd-dex-server are not present in Core mode.

Using Argo CD Core

GitOps with CRDs

The primary way to interact with Argo CD Core is through Kubernetes CRDs:

Application

Create an Application resource:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: guestbook
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/argoproj/argocd-example-apps.git
    targetRevision: HEAD
    path: guestbook
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Apply it:

kubectl apply -f application.yaml

ApplicationSet

Create an ApplicationSet for templating:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-apps
  namespace: argocd
spec:
  generators:
  - list:
      elements:
      - cluster: dev
        url: https://dev.example.com
      - cluster: prod
        url: https://prod.example.com
  template:
    metadata:
      name: '{{cluster}}-app'
    spec:
      project: default
      source:
        repoURL: https://github.com/example/apps.git
        targetRevision: HEAD
        path: 'apps/{{cluster}}'
      destination:
        server: '{{url}}'
        namespace: default

Apply it:

kubectl apply -f applicationset.yaml

AppProject

Create an AppProject for organizing applications:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: my-project
  namespace: argocd
spec:
  description: My application project
  sourceRepos:
  - '*'
  destinations:
  - namespace: '*'
    server: '*'
  clusterResourceWhitelist:
  - group: '*'
    kind: '*'

Apply it:

kubectl apply -f appproject.yaml

Using the CLI in Core Mode

The Argo CD CLI can still be used with Core mode, but it spawns a temporary local API server:

1. Install the CLI

   Install the Argo CD CLI (installation guide):

   # Linux
   curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
   sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
   
   # macOS
   brew install argocd
   
2. Login with --core flag

   Set your kubeconfig context and login:

   kubectl config set-context --current --namespace=argocd
   argocd login --core
   

   The --core flag tells the CLI to spawn a local API server process. This process is automatically terminated when the command completes.

3. Use CLI commands

   All standard CLI commands work:

   # List applications
   argocd app list
   
   # Get application details
   argocd app get guestbook
   
   # Sync an application
   argocd app sync guestbook
   
   # Create an application
   argocd app create myapp \
     --repo https://github.com/argoproj/argocd-example-apps.git \
     --path guestbook \
     --dest-server https://kubernetes.default.svc \
     --dest-namespace default
   

The CLI in Core mode requires proper Kubernetes RBAC permissions on Application and ApplicationSet resources in the argocd namespace.

Using the Web UI in Core Mode

You can run the Web UI locally for a better visual experience:

argocd admin dashboard -n argocd

The UI will be available at http://localhost:8080

The local dashboard spawns a temporary API server on your machine. It uses your kubeconfig credentials and requires proper RBAC permissions.

RBAC Configuration

Since Core mode uses Kubernetes RBAC, you need to grant appropriate permissions:

For Developers

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argocd-app-developer
  namespace: argocd
rules:
- apiGroups:
  - argoproj.io
  resources:
  - applications
  - applicationsets
  verbs:
  - get
  - list
  - watch
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argocd-app-developer-binding
  namespace: argocd
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: argocd-app-developer
subjects:
- kind: User
  name: [e-mail]
  apiGroup: rbac.authorization.k8s.io

For Admins

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: argocd-app-admin
  namespace: argocd
rules:
- apiGroups:
  - argoproj.io
  resources:
  - applications
  - applicationsets
  - appprojects
  verbs:
  - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: argocd-app-admin-binding
  namespace: argocd
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: argocd-app-admin
subjects:
- kind: User
  name: [e-mail]
  apiGroup: rbac.authorization.k8s.io

Multi-Tenancy in Core Mode

Core mode supports GitOps-based multi-tenancy:

Multi-tenancy in Core mode is enforced by Git repository permissions, not Argo CD RBAC.

Strategy

1. Git-based permissions: Teams push to their own Git paths/branches
2. Kubernetes RBAC: Controls who can create/modify Application resources
3. AppProjects: Define allowed sources and destinations per team

Example Setup

# Team A Project
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-a
  namespace: argocd
spec:
  description: Team A Applications
  sourceRepos:
  - https://github.com/company/team-a-apps.git
  destinations:
  - namespace: team-a-*
    server: https://kubernetes.default.svc
  namespaceResourceWhitelist:
  - group: '*'
    kind: '*'
---
# Team A RBAC
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: team-a-argocd
  namespace: argocd
rules:
- apiGroups:
  - argoproj.io
  resources:
  - applications
  verbs:
  - '*'
  resourceNames:
  - team-a-*  # Only apps starting with team-a-

Comparison: Core vs Multi-Tenant

Feature	Core Mode	Multi-Tenant
Web UI	Local only (argocd admin dashboard)	Full remote access
CLI	Via --core flag	Standard login
API Server	No (spawned locally)	Yes
Authentication	Kubernetes RBAC	Argo CD RBAC + OIDC
Multi-tenancy	Git + K8s RBAC	Argo CD RBAC
Notifications	No	Yes
SSO/OIDC	No	Yes
Use Case	Single admin/cluster	Multiple teams
Complexity	Low	Higher

Upgrading from Core to Multi-Tenant

To upgrade from Core to full multi-tenant installation:

1. Backup existing resources

   kubectl get applications,applicationsets,appprojects -n argocd -o yaml > backup.yaml
   
2. Apply multi-tenant manifest

   kubectl apply -n argocd --server-side --force-conflicts \
     -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
   
3. Verify all components

   kubectl get pods -n argocd
   

   You should now see argocd-server and argocd-dex-server pods.

4. Access the UI

   kubectl port-forward svc/argocd-server -n argocd 8080:443
   

   Get the admin password:

   kubectl get secret argocd-initial-admin-secret -n argocd \
     -o jsonpath="{.data.password}" | base64 -d
   

Uninstalling

To remove Argo CD Core:

kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/core-install.yaml
kubectl delete namespace argocd

Troubleshooting

CLI commands fail with permission errors

Ensure your kubeconfig user has proper RBAC permissions on Application resources:

kubectl auth can-i get applications -n argocd
kubectl auth can-i create applications -n argocd

If these return “no”, you need to create appropriate Roles and RoleBindings.

Applications not syncing

Check the application-controller logs:

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller

Check the application status:

kubectl get application -n argocd <app-name> -o yaml

Local dashboard won't start

Ensure you’ve set the correct namespace context:

kubectl config set-context --current --namespace=argocd
kubectl config view --minify

Verify connectivity:

kubectl get pods -n argocd

Next Steps

Create Applications

Deploy your first application with Core mode

ApplicationSets

Use ApplicationSets for templating

Kubernetes RBAC

Configure RBAC for your team

Upgrade to Multi-Tenant

Add API server and Web UI