Getting Started

Tip

This guide assumes you have a grounding in the tools that Argo CD is based on. Please read understanding the basics to learn about these tools.

Requirements

  • Installed kubectl command-line tool.
  • Have a kubeconfig file (default location is ~/.kube/config).

1. Install Argo CD

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

This will create a new namespace, argocd, where Argo CD services and application resources will live.

Note

If you are not interested in UI, SSO, multi-cluster management and just want to pull changes into the cluster then you can disable authentication using --disable-auth flag and access Argo CD via CLI using --port-forward or --port-forward-namespace flags and proceed to step #6:

kubectl patch deploy argocd-server -n argocd -p '[{"op": "add", "path": "/spec/template/spec/containers/0/command/-", "value": "--disable-auth"}]' --type json

2. Download Argo CD CLI

Download the latest Argo CD version from https://github.com/argoproj/argo-cd/releases/latest. More detailed installation instructions can be found via the CLI installation documentation.

Also available in Mac Homebrew:

  1. brew install argocd

3. Access The Argo CD API Server

By default, the Argo CD API server is not exposed with an external IP. To access the API server, choose one of the following techniques to expose the Argo CD API server:

Service Type Load Balancer

Change the argocd-server service type to LoadBalancer:

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

Ingress

Follow the ingress documentation on how to configure Argo CD with ingress.

Port Forwarding

Kubectl port-forwarding can also be used to connect to the API server without exposing the service.

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

The API server can then be accessed using the localhost:8080

4. Login Using The CLI

Warning

We strongly advise to change the initially generated administrative password as soon as after your first login to the system.

Depending on the Argo CD version you are installing, the method how to get the initial password for the admin user is different.

Argo CD 1.8 and earlier

The initial password is autogenerated to be the pod name of the Argo CD API server. This can be retrieved with the command:

  1. kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o name | cut -d'/' -f 2

Using the username admin and the password from above, login to Argo CD’s IP or hostname:

  1. argocd login <ARGOCD_SERVER>  # e.g. localhost:8080 or argocd.example.com

Change the password using the command:

  1. argocd account update-password

Note

The initial password is set in a kubernetes secret, named argocd-secret, during ArgoCD’s initial start up. This means if you edit the deployment in any way which causes a new pod to be deployed, such as disabling TLS on the Argo CD API server. Take note of the initial pod name when you first install Argo CD, or reset the password by following these instructions

Argo CD v1.9 and later

The initial password for the admin account is auto-generated and stored as clear text in the field password in a secret named argocd-initial-admin-secret in your Argo CD installation namespace. You can simply retrieve this password using kubectl:

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

For better readability, e.g. if you want to copy & paste the generated password, you can simply append && echo to above command, which will add a newline to the output.

Using the username admin and the password from above, login to Argo CD’s IP or hostname:

  1. argocd login <ARGOCD_SERVER>

Change the password using the command:

  1. argocd account update-password

Note

You should delete the argocd-initial-admin-secret from the Argo CD namespace once you changed the password. The secret serves no other purpose than to store the initially generated password in clear and can safely be deleted at any time. It will be re-created on demand by Argo CD if a new admin password must be re-generated.

5. Register A Cluster To Deploy Apps To (Optional)

This step registers a cluster’s credentials to Argo CD, and is only necessary when deploying to an external cluster. When deploying internally (to the same cluster that Argo CD is running in), https://kubernetes.default.svc should be used as the application’s K8s API server address.

First list all clusters contexts in your current kubeconfig:

  1. kubectl config get-contexts -o name

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

The above command installs a ServiceAccount (argocd-manager), into the kube-system namespace of that kubectl context, and binds the service account to an admin-level ClusterRole. Argo CD uses this service account token to perform its management tasks (i.e. deploy/monitoring).

Note

The rules of the argocd-manager-role role can be modified such that it only has create, update, patch, delete privileges to a limited set of namespaces, groups, kinds. However get, list, watch privileges are required at the cluster-scope for Argo CD to function.

6. Create An Application From A Git Repository

An example repository containing a guestbook application is available at https://github.com/argoproj/argocd-example-apps.git to demonstrate how Argo CD works.

Creating Apps Via CLI

Note

You can access Argo CD using port forwarding: add --port-forward-namespace argocd flag to every CLI command or set ARGOCD_OPTS environment variable: export ARGOCD_OPTS='--port-forward-namespace argocd':

argocd app create guestbook --repo https://github.com/argoproj/argocd-example-apps.git --path guestbook --dest-server https://kubernetes.default.svc --dest-namespace default

Creating Apps Via UI

Open a browser to the Argo CD external UI, and login by visiting the IP/hostname in a browser and use the credentials set in step 4.

After logging in, click the + New App button as shown below:

+ new app button

Give your app the name guestbook, use the project default, and leave the sync policy as Manual:

app information

Connect the https://github.com/argoproj/argocd-example-apps.git repo to Argo CD by setting repository url to the github repo url, leave revision as HEAD, and set the path to guestbook:

connect repo

For Destination, set cluster to in-cluster and namespace to default:

destination

After filling out the information above, click Create at the top of the UI to create the guestbook application:

destination

7. Sync (Deploy) The Application

Syncing via CLI

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

  1. $ argocd app get guestbook
  2. Name:               guestbook
  3. Server:             https://kubernetes.default.svc
  4. Namespace:          default
  5. URL:                https://10.97.164.88/applications/guestbook
  6. Repo:               https://github.com/argoproj/argocd-example-apps.git
  7. Target:
  8. Path:               guestbook
  9. Sync Policy:        <none>
  10. Sync Status:        OutOfSync from  (1ff8a67)
  11. Health Status:      Missing
  13. GROUP  KIND        NAMESPACE  NAME          STATUS     HEALTH
  14. apps   Deployment  default    guestbook-ui  OutOfSync  Missing
  15.        Service     default    guestbook-ui  OutOfSync  Missing

The application status is initially in OutOfSync state since the application has yet to be deployed, and no Kubernetes resources have been created. To sync (deploy) the application, run:

  1. argocd app sync guestbook

This command retrieves the manifests from the repository and performs a kubectl apply of the manifests. The guestbook app is now running and you can now view its resource components, logs, events, and assessed health status.

Syncing via UI

guestbook app view app