Install and expose ArgoCD

Our clusters ship without ArgoCD installed. Running your own is useful if you want to have full control over GitOps delivery into your cluster.

The guide is based on the upstream Argo CD Helm chart (argo/argo-cd).

Prerequisites

Helm needs to be provided with the correct repository:

1. Setup helm repo

   helm repo add argo https://argoproj.github.io/argo-helm
   

2. Make sure to update repo cache

   helm repo update
   

3. Make sure kubectl is configured for the cluster you want to install into.

4. To reach the ArgoCD UI over HTTPS you need an Ingress controller and cert-manager. You can either use our managed add-ons or install your own:

   • Our guide to ingress-nginx can be found here
   • Our guide to installing cert-manager can be found here
   • More on using Ingress with us here

Install

1. Create the namespace

   kubectl create namespace argocd
   

2. Run Helm install, pinning an explicit chart version:

   helm install argocd argo/argo-cd \
     --namespace argocd \
     --create-namespace \
     --version 10.1.4
   

   A full list of available Helm values is on ArgoCD’s ArtifactHub page.

   Note: If you already know you want the UI reachable via Ingress, you can supply a values.yaml up front instead of running helm upgrade afterwards, see the Expose the ArgoCD UI section below.

Verify the installation

1. Check that all pods are running:

   kubectl get pods -n argocd
   

2. Retrieve the initial admin password:

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

3. Log in with the ArgoCD CLI over a port-forward:

   kubectl port-forward svc/argocd-server -n argocd 8080:443
   argocd login localhost:8080 --username admin
   

Expose the ArgoCD UI

1. Interim / quick access

   While you’re deciding how to expose ArgoCD, you can always reach the UI with a port-forward:

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

   The UI is then available at https://localhost:8080.

2. Via Ingress (recommended)

   Enable the built-in Ingress in values.yaml and let cert-manager issue the certificate:

   configs:
     params:
       server.insecure: true
   server:
     ingress:
       enabled: true
       ingressClassName: nginx
       hostname: argocd.example.tld
       annotations:
         cert-manager.io/issuer: letsencrypt-prod
       tls: true
   

   Note: The ArgoCD server multiplexes gRPC and HTTP/HTTPS on the same port and terminates TLS itself by default. To terminate TLS at the Ingress instead, set server.insecure: true as above so the server serves plain HTTP behind the Ingress. If you’d rather keep TLS on the backend, use ssl-passthrough instead — see the upstream ArgoCD Ingress documentation for both approaches.

   Apply the values with:

   helm upgrade --install argocd argo/argo-cd --namespace argocd --version 10.1.4 --values values.yaml
   

3. Restrict access while the domain is undecided

   If you don’t have a hostname picked yet, you can still put ArgoCD behind an Ingress and restrict it to your own IP with an annotation:

   server:
     ingress:
       annotations:
         nginx.ingress.kubernetes.io/whitelist-source-range: "<your-ip>/32"
   

   A wildcard-DNS helper such as sslip.io can act as a temporary hostname against the Ingress’ floating IP until a real domain is chosen. See Load balancers for how the floating IP is assigned.

Connect a private Git repository

Add a repository with credentials via the CLI:

argocd repo add <repo-url> --username <user> --password <token>

For Azure DevOps, use a Personal Access Token scoped to Code: Read, or an SSH deploy key instead of username/password.

Alternatively, declare the repository as a Secret labelled for ArgoCD:

apiVersion: v1
kind: Secret
metadata:
  name: private-repo
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  url: <repo-url>
  username: <user>
  password: <token>

Note: Avoid committing credentials in plaintext to git. See Managing secrets below for options to keep this manifest encrypted at rest in your repository.

Pull images from a private registry

Create an imagePullSecret in the namespace your application is deployed to:

kubectl create secret docker-registry regcred \
  --namespace <app-namespace> \
  --docker-server=<registry-server> \
  --docker-username=<user> \
  --docker-password=<password>

This works for any registry (Docker Hub, ACR, GCR, Quay, …). Reference the secret from your workload’s ServiceAccount imagePullSecrets, or set it via your Helm chart’s values.

Managing secrets

Since ArgoCD deploys straight from git, secrets should not be committed in plaintext. Two common options, both customer-installed:

• Sealed Secrets — encrypt secrets client-side with kubeseal so only the controller in your cluster can decrypt them, safe to commit to git.
• External Secrets — sync secrets from an external secret store (e.g. Vault, cloud provider secret managers) into Kubernetes Secret resources.

Deploy your first application

Create a file called application.yaml:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: <repo-url>
    targetRevision: HEAD
    path: <path-to-manifests>
  destination:
    server: https://kubernetes.default.svc
    namespace: <app-namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

If you’re deploying a Helm chart instead of plain manifests, use a Helm source:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: <repo-url>
    targetRevision: HEAD
    path: <path-to-chart>
    helm:
      valueFiles:
        - values.yaml
  destination:
    server: https://kubernetes.default.svc
    namespace: <app-namespace>
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Then create the resource in the cluster by running:

kubectl apply -f application.yaml

Upgrade

helm upgrade --install argocd argo/argo-cd --namespace argocd --version <new-version>

Uninstall

1. Remove the release

   helm uninstall argocd -n argocd
   

2. Remove the namespace if necessary

   kubectl delete namespace argocd