## Set up Argo CD

<Steps>

<Step>Install Argo CD</Step>

> [!NOTE]
> There are several ways to install Argo CD. This setup uses Helm; to install it another 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 these values.

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 title="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"
        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 Syself Autopilot management cluster, and is needed as you'll be adding Syself 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:

```console
$ helm repo add argo https://argoproj.github.io/argo-helm
$ helm repo update
$ kubectl create namespace argocd
$ helm install argocd argo/argo-cd --namespace argocd --values argocd-values.yaml
```

<Step>Install Argo CD CLI</Step>

Run the installation commands for your environment:

<Tabs id="operating-systems" items={['Linux', 'macOS', 'Windows']}>

<TabItem value="Linux">

```console
$ 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
```

</TabItem>

<TabItem value="macOS">

```console
$ ARCH=$(uname -m | sed 's/x86_64/amd64/')
$ curl -sSL -o argocd-darwin-$ARCH https://github.com/argoproj/argo-cd/releases/latest/download/argocd-darwin-$ARCH
$ sudo install -m 555 argocd-darwin-$ARCH /usr/local/bin/argocd
$ rm argocd-darwin-$ARCH
```

</TabItem>

<TabItem value="Windows">

```powershell title="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")
```

</TabItem>

</Tabs>

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

<Step>Access the Argo CD API server</Step>

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

```console
$ kubectl port-forward service/argocd-server 8080:443 -n argocd
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Handling connection for 8080
```

And connect using the CLI:

```console
$ argocd login localhost:8080 \
--insecure \
--username admin \
--password $(kubectl get secret argocd-initial-admin-secret -n argocd -o json | \
jq -r '.data.password' | \
base64 -d)
'admin:login' logged in successfully
Context 'localhost:8080' updated
```

<Step>Add the Syself Autopilot cluster to Argo CD</Step>

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

```console
$ argocd cluster add oidc@autopilot-1 \
--system-namespace org-<your-company> \
--namespace 'org-<your-company>' \
--name autopilot \
--kubeconfig <./path-to/autopilot/kubeconfig> \
--service-account gitops -y
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.

> [!NOTE]
> The `--kubeconfig` here should be a scoped kubeconfig for the management cluster, obtained through [Headless access](/docs/hetzner/apalla/clusters/gitops/headless-access). The `gitops` service account it uses is deliberately scoped to your organization namespace, so do not grant it cluster-admin. Argo CD only needs to apply your `Cluster` declarations, nothing wider.

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:

```console
$ kubectl get secret $(kubectl get secrets -n argocd --no-headers -o custom-columns=":metadata.name" | grep syself) -o yaml -n argocd
```

What follows is 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>Add a repository</Step>

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:

```console
$ argocd repo add https://github.com/your-company/gitops-repo.git \
--username <your-git-username> \
--password <your-github-token>
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
```

> [!WARNING]
> This Secret holds a Git access token in plain text, so do not commit it to Git. Apply it out of band, or reference it through a sealed secret or an external secret store. The same rule applies to every Secret your cluster needs: keep the secret material out of your GitOps repository.

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. For cluster management, the manifests in this repository include your `Cluster` object itself, so Argo CD syncs the cluster's declaration from Git. 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:

```console
$ argocd app create gitops-example \
--repo https://github.com/your-company/gitops-repo.git \
--path resources \
--dest-server https://autopilot-1.autopilot-prod.k8s.syself.net:443 \
--dest-namespace org-<your-company> \
--sync-policy auto
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 Syself 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:

      prune: false
```

> [!WARNING]
> Keep `prune` off for any Application that manages a `Cluster`. With pruning on, deleting a manifest file in Git would delete the running cluster. Tearing a cluster down should be a deliberate, separate action, never a side effect of removing a file.

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 Syself Autopilot. You should copy these and add to your cluster manifest to avoid Argo CD forcing reconciliation of your cluster.

</Steps>

## 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.

A short list of things you can do:

- [Set up self-management with GitOps](/docs/hetzner/apalla/clusters/gitops/self-management-pattern) for managing your Syself Autopilot resources from Git
- Keep your cluster-topology declarations in a separate repository from your application manifests, so cluster changes and app changes review and roll out independently
- Get a scoped, non-interactive kubeconfig for CI and headless environments with [Headless access](/docs/hetzner/apalla/clusters/gitops/headless-access)
- [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/)