GitOps with ArgoCD¶

To use GitOps you'll need a Git repository - GitHub, GitLab, Codeberg, or any other host, containing YAML files that describe your cluster's desired state. ArgoCD continuously monitors the repository and applies changes automatically, keeping the cluster in sync.

You can configure ArgoCD to:

Watch specific branches or directories; useful for managing multiple applications or environments from a single repository.
Require signed commits before applying changes, adding an extra layer of authorization.

Argo CD web address¶

Argo CD has a canonical SUNET-managed hostname. A customer admin can record an optional alias, such as argocd.example.org, in the portal's Argo CD DNS alias field. The required customer DNS record is:

argocd.example.org. CNAME argocd.<cluster-slug>.k8s-prod.sunetvdc.se.

Do not use A or AAAA records because the canonical target is platform-managed. Create the CNAME before future SUNET Gateway and cert-manager activation. Saving the portal field currently records the requested desired state only; it does not activate DNS, routing, or TLS. Continue using the canonical address until SUNET confirms activation.

The alias is only for the Argo CD web interface. It does not change the canonical SUNET-managed Kubernetes API hostname in your kubeconfig.

Connect your first repository¶

Before continuing, follow First Argo CD sign-in. Portal users do not automatically have separate Argo CD web accounts; create local accounts as described in Connecting to your cluster.

A public repository can be read without credentials. For a private repository, create a dedicated read-only deploy token or SSH deploy key scoped to that repository. Do not use a personal password or a token that can write to Git.

Using the web interface¶

Open Settings, then Repositories, and choose Connect Repo.
Select HTTPS or SSH and enter the repository URL.
For a private repository, enter its deploy-token credentials or SSH private key. Public repositories do not need credentials.
Choose Connect and verify that the connection status is Successful.

Repository credentials are shared cluster administration

Argo CD stores private-repository credentials as Kubernetes Secrets in the argocd namespace. Under the current access model, every portal user with a kubeconfig can administer that namespace and read those credentials. Add only people trusted as cluster administrators, use a separate read-only credential for each repository, and rotate it if access changes.

Using the Argo CD CLI¶

Install the Argo CD CLI, then sign in. Use the hostname without https://:

ARGOCD_SERVER=argocd.<cluster-slug>.k8s-prod.sunetvdc.se
argocd login "$ARGOCD_SERVER" --grpc-web --username admin

The command prompts for the Argo CD password. Register a public repository:

argocd repo add https://github.com/my-org/my-cluster.git --grpc-web

For a private HTTPS repository, provide its deploy-token username and read the token without recording it in shell history:

printf 'Repository token: '
read -r -s REPO_TOKEN
printf '\n'
argocd repo add https://git.example.org/my-org/my-cluster.git \
  --username <deploy-token-username> \
  --password "$REPO_TOKEN" \
  --grpc-web
unset REPO_TOKEN

For SSH, use a dedicated read-only deploy-key file:

argocd repo add git@git.example.org:my-org/my-cluster.git \
  --ssh-private-key-path ~/.ssh/my-cluster-deploy-key \
  --grpc-web

Confirm that Argo CD can reach the repository:

argocd repo list --grpc-web

Create your first application¶

An Argo CD Application points at a path in your Git repository and a destination in the cluster. In these examples, apps/my-app contains the Deployment, Service, and any other manifests for the application.

Using the web interface¶

Open Applications and choose New App.
Set Application Name to my-app and Project Name to default.
Set Sync Policy to Automatic, and enable Prune Resources and Self Heal.
Under Source, select your repository, revision main, and path apps/my-app.
Under Destination, select https://kubernetes.default.svc and enter namespace my-app.
Under Sync Options, enable Auto-Create Namespace (CreateNamespace=true).
Choose Create. Automated sync deploys the application and keeps it in sync with Git.

Using the Argo CD CLI¶

Create the equivalent Application from the command line:

argocd app create my-app \
  --app-namespace argocd \
  --project default \
  --repo https://github.com/my-org/my-cluster.git \
  --revision main \
  --path apps/my-app \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace my-app \
  --sync-policy automated \
  --auto-prune \
  --self-heal \
  --sync-option CreateNamespace=true \
  --grpc-web

Check its sync and health status:

argocd app get my-app --grpc-web
kubectl get application my-app -n argocd

Using a declarative Application manifest¶

For a reproducible setup, store the Application itself in a Git path managed by a parent Application or ApplicationSet:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/my-org/my-cluster.git
    targetRevision: main
    path: apps/my-app
  destination:
    server: https://kubernetes.default.svc
    namespace: my-app
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Argo CD renders and applies the files under apps/my-app, then keeps them in sync. With selfHeal enabled it reverts manual drift, and with prune it removes resources you delete from Git.

Applications created only through the web interface or CLI are stored in the cluster but not in Git. This is convenient during initial testing, but managing the Application manifests through a parent Application or ApplicationSet is recommended for auditability and disaster recovery.

Deploying into other namespaces¶

Although your kubectl access is scoped to the argocd namespace, ArgoCD itself runs with the permissions needed to create and manage resources elsewhere in the cluster. To deploy into another namespace, commit an Application (or ApplicationSet) manifest to your Git repository that targets the destination namespace; ArgoCD will create the namespace if it doesn't already exist (using syncOptions: CreateNamespace=true) and deploy your resources into it.

Managing many applications¶

For more than a handful of apps, an ApplicationSet generates Application resources from a template, for example one per directory or one per environment. This keeps a single source of truth for adding, updating, and removing applications across the cluster.