GitOps Kubernetes

How to Deploy and Configure ArgoCD in Kubernetes (Step-by-Step)

Install ArgoCD on Kubernetes with kubectl, expose the UI via LoadBalancer or Ingress, get the initial admin password, register clusters, deploy apps from Git, and configure repository credentials and AppProjects.

ArgoCD is a declarative GitOps continuous delivery tool for Kubernetes. It watches Git repositories (and optionally Helm or Kustomize) and keeps your cluster state in sync with what’s defined in Git, so deployments are auditable and easy to roll back. This guide walks you through deploying and configuring ArgoCD: installing it with the official manifests, exposing the API server (LoadBalancer, port-forward, or Ingress), logging in and changing the admin password, registering clusters, deploying an app from Git, and setting up repository credentials and AppProjects.

In this guide you’ll:

  • Install ArgoCD in the argocd namespace and optionally use the core-only install
  • Install the argocd CLI and access the server (LoadBalancer, port-forward, or Ingress with TLS)
  • Retrieve the initial admin password, log in, and change the password
  • Register external clusters (or use the in-cluster API) and deploy an application from a Git repo
  • Configure repository credentials for private repos and create an AppProject to scope sources and destinations

Related: How to set up ArgoCD Slack notifications · Deploy to Kubernetes with ArgoCD, GitHub Actions, and Helm

Prerequisites

Before you start, ensure you have:

  • kubectl installed and configured
  • A kubeconfig pointing at the cluster where you want to run ArgoCD (default: ~/.kube/config)
  • Cluster access sufficient to create namespaces, deployments, and services (e.g. cluster-admin or equivalent)

Install ArgoCD

Create the argocd namespace and set it as the current context:

1
2

kubectl create ns argocd
kubectl config set-context --current --namespace=argocd

Install ArgoCD using the official install manifest (includes UI, SSO, multi-cluster support):

1

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

If you don’t need the UI, SSO, or multi-cluster features, you can install only the core components:

1

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

Install the ArgoCD CLI

You need the argocd CLI to log in and manage applications from the terminal. Download the latest version from the ArgoCD releases page, or see the CLI installation docs for other methods.

On macOS, Linux, and WSL you can use Homebrew:

1

brew install argocd

Access the ArgoCD API server

By default, the ArgoCD API server is not exposed outside the cluster. Choose one of the following ways to access it.

Option 1: LoadBalancer

Patch the argocd-server service to use type LoadBalancer (works well on cloud providers that support it):

1

kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

Option 2: Port forwarding

For local access without exposing the service, use kubectl port-forward:

1

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

Then open https://localhost:8080 in your browser (accept the TLS warning if needed).

Option 3: Ingress

To expose ArgoCD behind an Ingress (e.g. with Traefik or NGINX and cert-manager), the server must run with TLS disabled and let the Ingress terminate TLS. Set server.insecure: "true" in the argocd-cmd-params-cm ConfigMap.

Edit the configmap:

1

kubectl edit cm argocd-cmd-params-cm

Update it to look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

apiVersion: v1
kind: ConfigMap
metadata:
  annotations:
  labels:
    app.kubernetes.io/name: argocd-cmd-params-cm
    app.kubernetes.io/part-of: argocd
  name: argocd-cmd-params-cm
  namespace: argocd
data:
  server.insecure: "true"

Restart the argocd-server deployment so it picks up the config:

1

kubectl rollout restart deploy argocd-server -n argocd

Create an Ingress resource. Save the following as ingress.yaml (replace the host and ingress class with yours; ArgoCD server listens on port 80 when insecure):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-server
  namespace: argocd
  labels:
    app.kubernetes.io/name: argocd-server
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod-issuer
spec:
  ingressClassName: traefik
  rules:
    - host: argocd.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: argocd-server
                port:
                  number: 80
  tls:
    - hosts:
        - argocd.example.com
      secretName: argocd-server-tls

Apply it:

1

kubectl apply -f ingress.yaml

Log in and change the admin password

The initial admin password is auto-generated and stored in the secret argocd-initial-admin-secret in the argocd namespace. Retrieve it with the CLI:

1

argocd admin initial-password -n argocd

Or decode the Kubernetes secret directly:

1

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

Log in with username admin and that password. Replace <ARGOCD_SERVER> with your server address (e.g. localhost:8080 if using port-forward, or the LoadBalancer hostname, or your Ingress host):

1

argocd login <ARGOCD_SERVER>

If the server is not directly reachable (e.g. you’re on another machine), use port-forward from your laptop or add --port-forward-namespace argocd to the login command, or set export ARGOCD_OPTS='--port-forward-namespace argocd' so the CLI port-forwards automatically.

Change the admin password (recommended before doing anything else):

1

argocd account update-password

After changing the password, you can delete argocd-initial-admin-secret from the argocd namespace; ArgoCD will recreate it if you need to regenerate the admin password later.

Register a cluster (for external deployments)

Registering a cluster is only needed when you want ArgoCD to deploy to a different cluster than the one ArgoCD runs on. When deploying to the same cluster where ArgoCD is installed, use https://kubernetes.default.svc as the destination server in your Application; that cluster is already known to ArgoCD.

First list all clusters contexts in your current kubeconfig:

1

kubectl config get-contexts -o name

By default, the cluster where Argo CD is deployed is already configured by Argo CD. You can also see the list of clusters by CLI:

1

argocd cluster list

Choose a context name from the list and supply it to argocd cluster add CONTEXTNAME. For example, for docker-desktop context, run:

1

argocd cluster add docker-desktop

That command creates a ServiceAccount (argocd-manager) in the target cluster’s kube-system namespace and binds it to a ClusterRole so ArgoCD can deploy and manage resources there.

Enable Helm for Kustomize (optional)

If you use Kustomize that references Helm charts, you must pass --enable-helm to the kustomize build. To do that globally in ArgoCD, set kustomize.buildOptions in the argocd-cm ConfigMap:

Edit configmap:

1

kubectl edit cm argocd-cm

Then update it to look like this:

1
2
3
4
5
6
7

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  kustomize.buildOptions: --enable-helm

Restart the ArgoCD components that read this config (repo-server and server):

1

kubectl rollout restart deploy argocd-repo-server argocd-server -n argocd

Deploy an application from Git

You can now register an application that points at a Git repo. ArgoCD will sync the manifests (or Helm/Kustomize output) from that repo into the cluster.

Set the current namespace to argocd and register your app:

1

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

Then run the following CLI command to register your app:

1
2
3
4
5
6
7

$ argocd app create argo-demo \
  --repo https://github.com/<username>/<repo>.git \
  --path . \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace argo-demo

application 'argo-demo' created

Let’s unpack what’s happening here:

  • The --repo flag specifies the URL of your Git repository.
  • The --path flag instructs Argo to search for Kubernetes manifests, Helm charts, and other deployable assets inside this path within your repo. . is used here because the example manifests are stored in the repo’s root.
  • The --dest-server flag specifies the URL of the Kubernetes cluster to deploy to. You can use kubernetes.default.svc when you’re deploying to the same cluster that Argo’s running in.
  • --dest-namespace sets the Kubernetes namespace that your app will be deployed into. This should match the metadata.namespace fields set on your resources.

Your app will now be registered with Argo. You can retrieve its details with the argocd app list command:

1
2

NAME              CLUSTER                         NAMESPACE   PROJECT  STATUS     HEALTH   SYNCPOLICY  CONDITIONS  REPO                                                   PATH  TARGET
argocd/argo-demo  https://kubernetes.default.svc  argo-demo   default  OutOfSync  Missing  <none>      <none>      https://github.com/ilmiont/spacelift-argo-cd-demo.git

The app also shows up in the Argo UI:

The sync results display in your terminal. You should see the Namespace, Service, and Deployment objects all get synced into your cluster, as in the command output above. The messages for all three objects confirm they were created successfully.

Repeat the apps list command to check the app’s new status:

1

argocd app list

Now the app is Synced and Healthy! It’s also green in the Argo UI:

As a final proof, use Kubectl to inspect the deployments in the app’s namespace. This should confirm that nginx is up and running three replicas:

1
2
3

$ kubectl get deployment -n argo-demo
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
nginx   3/3     3            3           7m56s

Once the application is created, you can now view its status:

1

argocd app get argo-demo

To manually sync the application (pull from Git and apply):

1

argocd app sync argo-demo

ArgoCD will fetch the manifests from the repo and apply them to the cluster.

Repository credentials (private Git repos)

For private Git repositories, ArgoCD needs credentials. You add them as a Kubernetes Secret with the label argocd.argoproj.io/secret-type: repository. ArgoCD discovers these secrets automatically.

Use stringData so you don’t have to base64-encode values (Kubernetes will encode them). Replace the URL, username, and token with your repo and a fine-grained or classic GitHub token with repo scope (read is enough for ArgoCD):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

apiVersion: v1
kind: Secret
metadata:
  name: my-repo-credentials
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
  annotations:
    managed-by: argocd.argoproj.io
stringData:
  type: git
  url: https://github.com/your-org/your-repo.git
  username: git
  password: ghp_your_github_token_here

Then apply:

1

kubectl apply -f my-repo-credentials.yaml

In the ArgoCD UI, go to Settings → Repositories and confirm the repo appears and connects successfully.

Application projects (AppProject)

AppProjects group applications and let you restrict what can be deployed:

  • Source repos — Which Git repositories are allowed
  • Destinations — Which clusters and namespaces apps can deploy to
  • Resource allow/deny — Which Kubernetes resource kinds are allowed (e.g. limit to certain CRDs or forbid NetworkPolicy)
  • RBAC — Project roles tied to OIDC or JWT for team access

Every Application belongs to one project. If you don’t set one, the app uses the default project, which allows any repo and any destination. For tighter control, create a custom AppProject and set spec.project on your Applications.

Example: create a project that only allows a specific Git repo and the in-cluster API:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: main-cluster-apps
  namespace: argocd
  # Finalizer that ensures that project is not deleted until it is not referenced by any application
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  description: Project for argocd local cluster argocd-releases related resources

  # Allow manifests to deploy from kubernetes Git repo
  sourceRepos:
    - "https://github.com/etowett/argocd-releases.git"

  # Permit applications to deploy to any namespace in local argocd cluster
  destinations:
    - namespace: "*"
      server: "https://kubernetes.default.svc"

  # Allow to deploy any resource
  clusterResourceWhitelist:
    - group: "*"
      kind: "*"

Apply the project:

1

kubectl apply -f local-cluster.yaml

When you create Applications (via CLI or YAML), set --project main-cluster-apps or spec.project: main-cluster-apps so they use this project.

Frequently Asked Questions (FAQ)

What is ArgoCD?

ArgoCD is a GitOps continuous delivery tool for Kubernetes. It watches Git repositories (and optionally Helm or Kustomize) and keeps cluster state in sync with what’s in Git. You get declarative deployments, audit history in Git, and easy rollback by reverting or changing the source path.

How do I get the ArgoCD admin password?

The initial password is in the secret argocd-initial-admin-secret in the argocd namespace. Run argocd admin initial-password -n argocd or kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo. Log in with username admin, then change the password with argocd account update-password.

What is the difference between full install and core install?

The full install (install.yaml) includes the UI, SSO, and multi-cluster features. The core install (core-install.yaml) is a smaller footprint with only the components needed for GitOps sync. Use core if you don’t need the web UI or SSO.

How do I deploy to the same cluster where ArgoCD runs?

Use https://kubernetes.default.svc as the destination server when creating the Application. The in-cluster API is already registered; you only need to run argocd cluster add for other clusters.

How do I add a private Git repo to ArgoCD?

Create a Secret in the argocd namespace with label argocd.argoproj.io/secret-type: repository and fields url, username, and password (or sshPrivateKey). Use a fine-grained or classic GitHub token with minimal scope. ArgoCD will pick up the secret and use it for that repo.

Conclusion

You’ve installed ArgoCD in Kubernetes, exposed the server (LoadBalancer, port-forward, or Ingress), logged in and changed the admin password, and deployed an application from Git. You also configured repository credentials for private repos and created an AppProject to scope sources and destinations. For Slack alerts on sync and health, see how to set up ArgoCD Slack notifications. For a full CI/CD pipeline that builds images, runs Helm template, and pushes manifests to a GitOps repo for ArgoCD, see deploy to Kubernetes with ArgoCD, GitHub Actions, and Helm.

comments powered by Disqus
© 2020 - 2026 Citizix, Ltd.
Citizix Ltd
Built with Hugo
Theme Stack designed by Jimmy