mirror of
https://github.com/argoproj/argo-cd
synced 2026-04-21 17:07:16 +00:00
232 lines
8.8 KiB
Markdown
232 lines
8.8 KiB
Markdown
# Getting Started
|
|
|
|
!!! tip
|
|
This guide assumes you have a grounding in the tools that Argo CD is based on. Please read [understanding the basics](understand_the_basics.md) to learn about these tools.
|
|
|
|
## 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 Argo CD
|
|
|
|
```bash
|
|
kubectl create namespace argocd
|
|
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](#6-create-an-application-from-a-git-repository):
|
|
|
|
`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](https://github.com/argoproj/argo-cd/releases/latest). More detailed installation instructions can be found via the [CLI installation documentation](cli_installation.md).
|
|
|
|
Also available in Mac, Linux and WSL Homebrew:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
|
|
```
|
|
|
|
### Ingress
|
|
Follow the [ingress documentation](operator-manual/ingress.md) 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
argocd login <ARGOCD_SERVER> # e.g. localhost:8080 or argocd.example.com
|
|
```
|
|
|
|
Change the password using the command:
|
|
|
|
```bash
|
|
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](../faq/#i-forgot-the-admin-password-how-do-i-reset-it)
|
|
|
|
> 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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
argocd login <ARGOCD_SERVER>
|
|
```
|
|
|
|
Change the password using the command:
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](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:
|
|
|
|
|
|
|
|
Give your app the name `guestbook`, use the project `default`, and leave the sync policy as `Manual`:
|
|
|
|
|
|
|
|
Connect the [https://github.com/argoproj/argocd-example-apps.git](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`:
|
|
|
|
|
|
|
|
For **Destination**, set cluster to `in-cluster` and namespace to `default`:
|
|
|
|
|
|
|
|
After filling out the information above, click **Create** at the top of the UI to create the `guestbook` application:
|
|
|
|
|
|
|
|
|
|
## 7. Sync (Deploy) The Application
|
|
|
|
### Syncing via CLI
|
|
|
|
Once the guestbook application is created, you can now view its status:
|
|
|
|
```bash
|
|
$ argocd app get guestbook
|
|
Name: guestbook
|
|
Server: https://kubernetes.default.svc
|
|
Namespace: default
|
|
URL: https://10.97.164.88/applications/guestbook
|
|
Repo: https://github.com/argoproj/argocd-example-apps.git
|
|
Target:
|
|
Path: guestbook
|
|
Sync Policy: <none>
|
|
Sync Status: OutOfSync from (1ff8a67)
|
|
Health Status: Missing
|
|
|
|
GROUP KIND NAMESPACE NAME STATUS HEALTH
|
|
apps Deployment default guestbook-ui OutOfSync Missing
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
|
|
|
|
|