> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

## 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

<Warning>
  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
</Warning>

## Architecture

### Included Components

Argo CD Core includes only the essential GitOps components:

<Tabs>
  <Tab title="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
  </Tab>

  <Tab title="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
  </Tab>
</Tabs>

### Architecture Diagram

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

## Installation

<Steps>
  <Step title="Create the namespace">
    Create a dedicated namespace for Argo CD:

    ```bash theme={null}
    kubectl create namespace argocd
    ```
  </Step>

  <Step title="Install Argo CD Core">
    Apply the core installation manifest:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Verify the installation">
    Check that all pods are running:

    ```bash theme={null}
    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
    ```

    <Note>
      Notice that `argocd-server` and `argocd-dex-server` are **not** present in Core mode.
    </Note>
  </Step>
</Steps>

## Using Argo CD Core

### GitOps with CRDs

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

<Tabs>
  <Tab title="Application">
    Create an Application resource:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    kubectl apply -f application.yaml
    ```
  </Tab>

  <Tab title="ApplicationSet">
    Create an ApplicationSet for templating:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    kubectl apply -f applicationset.yaml
    ```
  </Tab>

  <Tab title="AppProject">
    Create an AppProject for organizing applications:

    ```yaml theme={null}
    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:

    ```bash theme={null}
    kubectl apply -f appproject.yaml
    ```
  </Tab>
</Tabs>

### 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:

<Steps>
  <Step title="Install the CLI">
    Install the Argo CD CLI ([installation guide](https://argo-cd.readthedocs.io/en/stable/cli_installation/)):

    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Login with --core flag">
    Set your kubeconfig context and login:

    ```bash theme={null}
    kubectl config set-context --current --namespace=argocd
    argocd login --core
    ```

    <Info>
      The `--core` flag tells the CLI to spawn a local API server process. This process is automatically terminated when the command completes.
    </Info>
  </Step>

  <Step title="Use CLI commands">
    All standard CLI commands work:

    ```bash theme={null}
    # 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
    ```
  </Step>
</Steps>

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

### Using the Web UI in Core Mode

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

```bash theme={null}
argocd admin dashboard -n argocd
```

The UI will be available at [http://localhost:8080](http://localhost:8080)

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

## RBAC Configuration

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

### For Developers

```yaml theme={null}
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: developer@example.com
  apiGroup: rbac.authorization.k8s.io
```

### For Admins

```yaml theme={null}
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: admin@example.com
  apiGroup: rbac.authorization.k8s.io
```

## Multi-Tenancy in Core Mode

Core mode supports GitOps-based multi-tenancy:

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

### 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

```yaml theme={null}
# 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:

<Steps>
  <Step title="Backup existing resources">
    ```bash theme={null}
    kubectl get applications,applicationsets,appprojects -n argocd -o yaml > backup.yaml
    ```
  </Step>

  <Step title="Apply multi-tenant manifest">
    ```bash theme={null}
    kubectl apply -n argocd --server-side --force-conflicts \
      -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
    ```
  </Step>

  <Step title="Verify all components">
    ```bash theme={null}
    kubectl get pods -n argocd
    ```

    You should now see `argocd-server` and `argocd-dex-server` pods.
  </Step>

  <Step title="Access the UI">
    ```bash theme={null}
    kubectl port-forward svc/argocd-server -n argocd 8080:443
    ```

    Get the admin password:

    ```bash theme={null}
    kubectl get secret argocd-initial-admin-secret -n argocd \
      -o jsonpath="{.data.password}" | base64 -d
    ```
  </Step>
</Steps>

## Uninstalling

To remove Argo CD Core:

```bash theme={null}
kubectl delete -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/core-install.yaml
kubectl delete namespace argocd
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="CLI commands fail with permission errors">
    Ensure your kubeconfig user has proper RBAC permissions on Application resources:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Applications not syncing">
    Check the application-controller logs:

    ```bash theme={null}
    kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller
    ```

    Check the application status:

    ```bash theme={null}
    kubectl get application -n argocd <app-name> -o yaml
    ```
  </Accordion>

  <Accordion title="Local dashboard won't start">
    Ensure you've set the correct namespace context:

    ```bash theme={null}
    kubectl config set-context --current --namespace=argocd
    kubectl config view --minify
    ```

    Verify connectivity:

    ```bash theme={null}
    kubectl get pods -n argocd
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Applications" icon="rocket" href="/applications/creating-apps">
    Deploy your first application with Core mode
  </Card>

  <Card title="ApplicationSets" icon="layer-group" href="/applicationset/overview">
    Use ApplicationSets for templating
  </Card>

  <Card title="Kubernetes RBAC" icon="lock" href="/configuration/rbac">
    Configure RBAC for your team
  </Card>

  <Card title="Upgrade to Multi-Tenant" icon="arrow-up" href="/installation/kubernetes">
    Add API server and Web UI
  </Card>
</CardGroup>