mirror of
https://github.com/argoproj/argo-cd.git
synced 2026-02-20 01:28:45 +01:00
b40a443b6a
Signed-off-by: rishabh <rishank69@gmail.com> Signed-off-by: Rishabh P <32699563+allexistence@users.noreply.github.com> Co-authored-by: Nitish Kumar <justnitish06@gmail.com>
247 lines
11 KiB
Markdown
247 lines
11 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`).
|
||
* CoreDNS. Can be enabled for microk8s by `microk8s enable dns && microk8s stop && microk8s start`
|
||
|
||
## 1. Install Argo CD
|
||
|
||
```bash
|
||
kubectl create namespace argocd
|
||
kubectl apply -n argocd --server-side --force-conflicts -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
|
||
```
|
||
|
||
This will create a new `argocd` namespace where all Argo CD services and application resources will reside. It will also install Argo CD by applying the official manifests from the stable branch. Using a pinned version (like `v3.2.0`) is recommended for production.
|
||
|
||
> [!NOTE]
|
||
> **Why `--server-side --force-conflicts`?**
|
||
>
|
||
> The `--server-side` flag is required because some Argo CD CRDs (like ApplicationSet) exceed the 262KB annotation size limit imposed by client-side `kubectl apply`. Server-side apply avoids this limitation by not storing the `last-applied-configuration` annotation.
|
||
>
|
||
> The `--force-conflicts` flag allows the apply operation to take ownership of fields that may have been previously managed by other tools (such as Helm or a previous `kubectl apply`). This is safe for fresh installs and necessary for upgrades. Note that any custom modifications you've made to fields that are defined in the Argo CD manifests (like `affinity`, `env`, or `probes`) will be overwritten. However, fields not specified in the manifests (like `resources` limits/requests or `tolerations`) will be preserved.
|
||
|
||
> [!WARNING]
|
||
> The installation manifests include `ClusterRoleBinding` resources that reference `argocd` namespace. If you are installing Argo CD into a different
|
||
> namespace then make sure to update the namespace reference.
|
||
|
||
> [!TIP]
|
||
> If you are not interested in UI, SSO, and multi-cluster features, then you can install only the [core](operator-manual/core.md#installing) Argo CD components.
|
||
|
||
This default installation will have a self-signed certificate and cannot be accessed without a bit of extra work.
|
||
Do one of:
|
||
|
||
* Follow the [instructions to configure a certificate](operator-manual/tls.md) (and ensure that the client OS trusts it).
|
||
* Configure the client OS to trust the self signed certificate.
|
||
* Use the --insecure flag on all Argo CD CLI operations in this guide.
|
||
|
||
> [!NOTE]
|
||
> Default namespace for `kubectl` config must be set to `argocd`.
|
||
> This is only needed for the following commands since the previous commands have -n argocd already:
|
||
>
|
||
> ```shell
|
||
> kubectl config set-context --current --namespace=argocd
|
||
> ```
|
||
|
||
Use `argocd login --core` to [configure](./user-guide/commands/argocd_login.md) CLI access and skip steps 3-5.
|
||
|
||
> [!NOTE]
|
||
> This default installation for Redis is using password authentication. The Redis password is stored in Kubernetes secret `argocd-redis` with key `auth` in the namespace where Argo CD is installed.
|
||
>
|
||
> If you are running Argo CD on Docker Desktop or another local Kubernetes environment, refer to the [Running Argo CD Locally](developer-guide/running-locally.md) guide for the full setup instructions and configuration steps tailored for local clusters.
|
||
|
||
## 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 Argo CD
|
||
|
||
By default, Argo CD isn’t exposed outside the cluster. To access Argo CD from your browser or CLI, use one of the following methods:
|
||
|
||
### Service Type Load Balancer
|
||
Change the argocd-server service type to `LoadBalancer`:
|
||
|
||
```bash
|
||
kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'
|
||
```
|
||
After a short wait, your cloud provider will assign an external IP address to the service. You can retrieve this IP with:
|
||
|
||
```bash
|
||
kubectl get svc argocd-server -n argocd -o=jsonpath='{.status.loadBalancer.ingress[0].ip}'
|
||
```
|
||
|
||
### Ingress
|
||
Follow the [ingress documentation](operator-manual/ingress.md) 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.
|
||
|
||
```bash
|
||
kubectl port-forward svc/argocd-server -n argocd 8080:443
|
||
```
|
||
|
||
The API server can then be accessed using https://localhost:8080
|
||
|
||
|
||
## 4. Log in Using The CLI
|
||
|
||
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 the `argocd` CLI:
|
||
|
||
```bash
|
||
argocd admin initial-password -n argocd
|
||
```
|
||
|
||
> [!WARNING]
|
||
> 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.
|
||
|
||
Using the username `admin` and the password from above, log in to Argo CD's IP or hostname:
|
||
|
||
```bash
|
||
argocd login <ARGOCD_SERVER>
|
||
```
|
||
|
||
> [!NOTE]
|
||
> The CLI environment must be able to communicate with the Argo CD API server. If it isn't directly accessible as described above in step 3, you can tell the CLI to access it using port forwarding through one of these mechanisms: 1) add `--port-forward-namespace argocd` flag to every CLI command; or 2) set `ARGOCD_OPTS` environment variable: `export ARGOCD_OPTS='--port-forward-namespace argocd'`.
|
||
|
||
Change the password using the command:
|
||
|
||
```bash
|
||
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 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.
|
||
|
||
> [!NOTE]
|
||
> The following example application may only be compatible with AMD64 architecture. If you are running on a different architecture (such as ARM64 or ARMv7), you may encounter issues with dependencies or container images that are not built for your platform. Consider verifying the compatibility of the application or building architecture-specific images if necessary.
|
||
|
||
### Creating Apps Via CLI
|
||
|
||
First, set the current namespace to argocd by running the following command:
|
||
|
||
```bash
|
||
kubectl config set-context --current --namespace=argocd
|
||
```
|
||
|
||
Create the example guestbook application with the following command:
|
||
|
||
```bash
|
||
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 or locally as explained in [Try Argo CD Locally](try_argo_cd_locally.md).
|
||
|
||
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 URL to `https://kubernetes.default.svc` (or `in-cluster` for cluster name) 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
|
||
|
||
On the Applications page, click on *Sync* button of the guestbook application:
|
||
|
||
|
||
|
||
A panel will be opened and then, click on *Synchronize* button.
|
||
|
||
You can see more details by clicking at the guestbook application:
|
||
|
||
|