Argo CD Getting Started

An example guestbook application is provided to demonstrate how Argo CD works.

Requirements

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

1. Install Argo CD

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

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

NOTE:

  • On GKE with RBAC enabled, you may need to grant your account the ability to create new cluster roles

    kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin --user=YOUREMAIL@gmail.com
    

Argo CD v0.11.0-rc1 is available for testing. The v0.11 dramatically improves performance and introduces new features such as support for very large applications, multi-namespaces apps and many more. Full description and CLI binaries are available via following URL: https://github.com/argoproj/argo-cd/releases/tag/v0.11.0-rc1

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v0.11.0-rc1/manifests/install.yaml

2. Download Argo CD CLI

Download the latest Argo CD version:

On Mac:

brew install argoproj/tap/argocd

On Linux:

curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/v0.10.6/argocd-linux-amd64
chmod +x /usr/local/bin/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 means to expose the Argo CD API server:

Service Type LoadBalancer

Change the argocd-server service type to LoadBalancer:

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-forward can also be used to connect to the API server without exposing the service. The API server can be accessed using the localhost address/port.

4. Login using the CLI

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

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

Using the above password, login to Argo CD's external IP:

kubectl get svc -n argocd argocd-server
argocd login <EXTERNAL-IP>

After logging in, change the password using the command:

argocd account update-password

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

argocd cluster add

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

argocd cluster add docker-for-desktop

The above command installs an argocd-manager ServiceAccount and ClusterRole into the cluster associated with the supplied kubectl context. Argo CD uses this service account token to perform its management tasks (i.e. deploy/monitoring).

6. Create an application from a git repository location

Creating apps via UI

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

Connect a git repository containing your apps if repository is private. An example repository containing a sample guestbook application is available at https://github.com/argoproj/argocd-example-apps.git.

connect repo

After connecting a git repository, select the guestbook application for creation:

select repo select app select env create app

Creating apps via CLI

Applications can be also be created using the Argo CD CLI:

argocd app create guestbook-default --repo https://github.com/argoproj/argocd-example-apps.git --path ksonnet-guestbook

7. Sync (deploy) the application

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

From UI: guestbook app

From CLI:

$ argocd app get guestbook-default
Name:          guestbook-default
Server:        https://kubernetes.default.svc
Namespace:     default
URL:           https://192.168.64.36:31880/applications/argocd/guestbook-default
Environment:   default
Repo:          https://github.com/argoproj/argocd-example-apps.git
Path:          guestbook
Target:        HEAD

KIND        NAME          STATUS     HEALTH
Service     guestbook-ui  OutOfSync
Deployment  guestbook-ui  OutOfSync

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

$ argocd app sync guestbook-default
Application:        guestbook-default
Operation:          Sync
Phase:              Succeeded
Message:            successfully synced

KIND        NAME          MESSAGE
Service     guestbook-ui  service "guestbook-ui" created
Deployment  guestbook-ui  deployment.apps "guestbook-ui" created

This command retrieves the manifests from git 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:

view app

8. Next Steps

Argo CD supports additional features such as automated sync, SSO, WebHooks, RBAC, Projects. See the rest of the documentation for details.