argo-cd/docs/getting_started.md

# ArgoCD Getting Started

An example guestbook application is provided to demonstrate how ArgoCD works.

## Requirements
* Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool
* Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`).

## 1. Install ArgoCD
```bash
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v0.9.2/manifests/install.yaml
```
This will create a new namespace, `argocd`, where ArgoCD 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
```bash
kubectl create clusterrolebinding YOURNAME-cluster-admin-binding --clusterrole=cluster-admin --user=YOUREMAIL@gmail.com
```

## 2. Download ArgoCD CLI

Download the latest ArgoCD version:

On Mac:
```bash
brew install argoproj/tap/argocd
```

On Linux:

```bash
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/download/v0.9.2/argocd-linux-amd64
chmod +x /usr/local/bin/argocd
```

## 3. Access the ArgoCD API server

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

### Service Type LoadBalancer
Change the argocd-server service type to `LoadBalancer`:

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

### Ingress
Follow the [ingress documentation](ingress.md) on how to configure ArgoCD 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
ArgoCD API server. This can be retrieved with the command:
```bash
kubectl get pods -n argocd -l app=argocd-server -o name | cut -d'/' -f 2
```

Using the above password, login to ArgoCD's external IP:
```bash
kubectl get svc -n argocd argocd-server
argocd login <EXTERNAL-IP>
```

After logging in, change the password using the command:
```bash
argocd account update-password
argocd relogin
```


## 5. Register a cluster to deploy apps to (optional)

This step registers a cluster's credentials to ArgoCD, and is only necessary when deploying to
an external cluster. When deploying internally (to the same cluster that ArgoCD 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:
```bash
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:
```bash
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. ArgoCD 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 ArgoCD 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. An example repository containing a sample 
guestbook application is available at https://github.com/argoproj/argocd-example-apps.git.

![connect repo](assets/connect_repo.png)

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

![select repo](assets/select_repo.png)
![select app](assets/select_app.png)
![select env](assets/select_env.png)
![create app](assets/create_app.png)


### Creating apps via CLI

Applications can be also be created using the ArgoCD CLI:

```bash
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](assets/guestbook-app.png)

From CLI:
```bash
$ 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:

```bash
$ 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](assets/guestbook-tree.png)

## 8. Next Steps

ArgoCD supports additional features such as automated sync, SSO, WebHooks, RBAC, Projects. See the
rest of the [documentation](./) for details.