## Step 1: Install Argo CD

{% callout type="note" %}
There are many options for installing Argo CD to your cluster, but for the purposes of this guide we'll install it using Helm. If you want to install it in a different way, see the [official Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/operator-manual/installation/).

If you've already installed Argo CD on your workload cluster, you'll need to patch the `argocd-cm` ConfigMap with the values shown in this section.
{% /callout %}

Before installing the Argo CD Helm chart to your workload cluster, it is recommended you configure it to better suit your needs. Reference for the values can be found [here](https://github.com/argoproj/argo-helm/tree/main/charts/argo-cd).

In addition to configuring it for your environment, you should add the following patch to the values:

```yaml
/// argocd-values.yaml
configs:
  cm:
    resource.inclusions: |
      - apiGroups:
          - "infrastructure.cluster.x-k8s.io"
          - "cluster.x-k8s.io"
          - "controlplane.cluster.x-k8s.io"
          - "bootstrap.cluster.x-k8s.io"
          - "ipam.cluster.x-k8s.io"
          - "clusterstack.x-k8s.io"
          - "infrastructure.clusterstack.x-k8s.io"
        kinds:
          - '*'
        clusters:
          - https://autopilot-1.autopilot-prod.k8s.syself.net:443
```

This tells Argo CD to only manage the resources specified and ignore all others in the Autopilot management cluster, and is needed as you'll be adding the Autopilot as an external cluster where you don't have complete access to all resources.

It is safe to deploy it now and configure it later, so you can proceed with the installation:

{% terminal height="10rem" steps="[{\"command\":\"helm repo add argo https://argoproj.github.io/argo-helm\"},{\"command\":\"helm repo update\"},{\"command\":\"kubectl create namespace argocd\"},{\"command\":\"helm install argocd argo/argo-cd --namespace argocd --values argocd-values.yaml\"}]" /%}

## Step 2: Install Argo CD CLI

Run the installation commands for your environment:

{% tabs #operating-systems %}

{% tab title="Linux" %}

```shell
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd
rm argocd-linux-amd64
```

{% /tab %}

{% tab title="macOS" %}

```shell
VERSION=$(curl --silent "https://api.github.com/repos/argoproj/argo-cd/releases/latest" | grep '"tag_name"' | sed -E 's/.*"([^"]+)".*/\1')
curl -sSL -o argocd-darwin-amd64 https://github.com/argoproj/argo-cd/releases/download/$VERSION/argocd-darwin-amd64
sudo install -m 555 argocd-darwin-amd64 /usr/local/bin/argocd
rm argocd-darwin-amd64
```

{% /tab %}

{% tab title="Windows" %}

```shell
/// Powershell
$version = (Invoke-RestMethod https://api.github.com/repos/argoproj/argo-cd/releases/latest).tag_name
$url = "https://github.com/argoproj/argo-cd/releases/download/" + $version + "/argocd-windows-amd64.exe"
$output = "argocd.exe"

Invoke-WebRequest -Uri $url -OutFile $output
[Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Path\To\ArgoCD-CLI", "User")
```

{% /tab %}

{% /tabs %}

You can test if the installation was successful with the `argocd version` command.

## Step 3: Access Argo CD API Server

Create a port-forwarding to be able to connect to the API server without exposing the service:

{% terminal height="10rem" steps="[{\"command\":\"kubectl port-forward service/argocd-server 8080:443 -n argocd\",\"delay\":200,\"output\":\"Forwarding from 127.0.0.1:8080 -> 8080\\nForwarding from [::1]:8080 -> 8080\\nHandling connection for 8080\"}]" /%}

And connect using the CLI:

{% terminal height="16rem" steps="[{\"command\":\"argocd login localhost:8080 \\\\\\n--insecure \\\\\\n--username admin \\\\\\n--password $(kubectl get secret argocd-initial-admin-secret -n argocd -o json | \\\\\\njq -r '.data.password' | \\\\\\nbase64 -d)\",\"delay\":500,\"output\":\"'admin' logged in successfully\\nContext 'localhost:8080' updated\"}]" /%}

## Step 4: Add Autopilot Cluster to Argo CD

Replace `<your-company>` with your company name and `<./path-to/autopilot/kubeconfig>` to the path where you stored the kubeconfig to the Autopilot management cluster, and run:

{% terminal height="14rem" steps="[{\"command\":\"argocd cluster add oidc@autopilot-1 \\\\\\n--system-namespace org-<your-company> \\\\\\n--namespace 'org-<your-company>' \\\\\\n--name autopilot \\\\\\n--kubeconfig <./path-to/autopilot/kubeconfig> \\\\\\n--service-account gitops -y\",\"delay\":200,\"output\":\"Cluster 'https://autopilot-1.autopilot-prod.k8s.syself.net:443' added\"}]" /%}

You might need to authenticate after running this command. In this case, re-run the command if it times out after authentication.

Now Argo CD is now fully configured to work with Syself Autopilot!

If you want to manage the added cluster declaratively, you can get the resulting manifest created by the Argo CD CLI with this command:

{% terminal height="5rem" steps="[\"kubectl get secret $(kubectl get secrets -n argocd --no-headers -o custom-columns=\\\":metadata.name\\\" | grep syself) -o yaml -n argocd\"]" /%}

The rest of this guide will cover an example setup, but you can operate it in the same way you would any other Argo CD installation, in accordance with your preferred practices.

## Step 5: Use it!

To use your new Argo CD setup, the first thing you need to do is add a repository. You can do this either through the user interface or through the CLI. For example, we'll use the CLI to add a private repository hosted on GitHub and authenticate with an access token:

{% terminal height="10rem" steps="[{\"command\":\"argocd repo add https://github.com/your-company/gitops-repo.git \\\\\\n--username <your-git-username> \\\\\\n--password <your-github-token>\",\"delay\":200,\"output\":\"Repository 'https://github.com/your-company/gitops-repo.git' added\"}]" /%}

Another option is to add it declaratively, by applying a secret to your cluster:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-gitops-repository
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
  annotations:
    managed-by: argocd.argoproj.io
stringData:
  username: mygitusername
  password: ghp_mytoken
  type: git
  url: https://github.com/your-company/gitops-repo.git
type: Opaque
```

You can see all the options for adding a repository in the [Argo CD documentation](https://argo-cd.readthedocs.io/en/stable/user-guide/private-repositories/).

With a repository added, you can tell Argo CD to deploy all manifests saved in it to a cluster, by using an Application. This is the content of our example repository, all under the `resources/` directory:

![Image showing file contents](/images/gitops-resources.avif)

Now we are ready to create an Application to deploy these resources:

{% terminal height="14rem" steps="[{\"command\":\"argocd app create gitops-example \\\\\\n--repo https://github.com/your-company/gitops-repo.git \\\\\\n--path resources \\\\\\n--dest-server https://autopilot-1.autopilot-prod.k8s.syself.net:443 \\\\\\n--dest-namespace org-<your-company> \\\\\\n--sync-policy auto\",\"delay\":200,\"output\":\"application 'gitops-example' created\"}]" /%}

This command created an Application called `gitops-example`, with the manifests fetched from the `resources/` directory in the `https://github.com/your-company/gitops-repo.git` repository to be deployed in the `org-<your-company>` namespace of the Autopilot management cluster.

You can also create the Application declaratively:

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: gitops-example
  namespace: argocd
spec:
  destination:
    server: https://autopilot-1.autopilot-prod.k8s.syself.net:443
    namespace: org-<your-company>
  project: default
  source:
    repoURL: https://github.com/your-company/gitops-repo.git
    path: resources
  syncPolicy:
    automated: {}
```

You can see the state of the Application in the Argo CD web UI. If you click in the cluster resource and go to the `DIFF` tab, you'll be able to see some default variables that were set by Autopilot. You should copy these and add to your cluster manifest to avoid Argo CD forcing reconciliation of your cluster.

## Deploy with Argo CD

Once the initial configuration is complete, we recommend that you familiarize yourself with the Argo CD documentation and make any necessary adjustments to your setup. Additionally, we suggest that you change the initial admin user password.

Here is a short list of things you can do:

- [Set up self-management with GitOps](/docs/hetzner/apalla/how-to-guides/gitops/self-management) for managing your Autopilot resources from Git
- [Let Argo CD manage itself](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#manage-argo-cd-using-argo-cd)
- [Handle your Clusters, Repositories and Applications declaratively](https://argo-cd.readthedocs.io/en/stable/operator-manual/declarative-setup/#declarative-setup)
- [Setup notifications](https://argo-cd.readthedocs.io/en/stable/operator-manual/notifications/)