Skip to content

HOWTO – Bootstrap Argo CD on On-Prem RKE2

Install Argo CD on an existing RKE2 cluster and wire the root workloads Application using platform/onprem/argocd-bootstrap. At the end of this HOWTO, Argo CD is running in the argocd namespace and the hyops-workloads-root Application is synced against the clusters/onprem path in hybridops-workloads.

Difficulty: Intermediate Prerequisites: platform/onprem/rke2-cluster state is ok; Ansible control machine has kubectl available; for private repo access, ARGOCD_REPO_SSH_PRIVATE_KEY set in vault.

Context

The module runs Ansible locally against 127.0.0.1: it applies kubectl and Helm operations from the control machine, not from within the cluster. It imports kubeconfig_path from rke2-cluster state by default; set kubeconfig_state_ref to an alternative state ref if the cluster was provisioned differently.

Automated sync is enabled by default:

Setting Default Effect
sync_automated_prune true Resources removed from the repo are deleted from the cluster
sync_automated_self_heal true Out-of-band changes are reverted

Module ref: platform/onprem/argocd-bootstrap Driver: config/ansible · Profile: onprem-linux@v1.0 Dependency: platform/onprem/rke2-cluster (kubeconfig import)

Preconditions and safety checks

  1. Confirm the RKE2 cluster is healthy:

    hyops state show --env <env> --module platform/onprem/rke2-cluster
kubectl --kubeconfig <path> get nodes

  2. If using SSH repo access, confirm the key is in vault:

    hyops secrets ensure --env <env> ARGOCD_REPO_SSH_PRIVATE_KEY

  3. Confirm the target revision (commit SHA or branch) exists in the workloads repo and the clusters/onprem path is present at that revision.

Steps

1. Initialise the inputs file

hyops module init --env <env> \
  --module platform/onprem/argocd-bootstrap \
  --dest-name argocd-bootstrap.yml

Edit ~/.hybridops/envs/<env>/config/modules/argocd-bootstrap.yml:

Public repo (default):

kubeconfig_state_ref: "platform/onprem/rke2-cluster"

argocd_namespace: "argocd"
argocd_wait_timeout_s: 300

root_app_name: "hyops-workloads-root"
workloads_repo_url: "https://github.com/hybridops-tech/hybridops-workloads.git"
workloads_revision: "<commit-sha-or-branch>"
workloads_target_path: "clusters/onprem"
repo_access_mode: "public"

sync_automated_prune: true
sync_automated_self_heal: true

Private repo (SSH key):

repo_access_mode: "ssh"
repo_secret_name: "hyops-workloads-repo"
repo_ssh_private_key_env: "ARGOCD_REPO_SSH_PRIVATE_KEY"
workloads_repo_url: "git@github.com:hybridops-tech/hybridops-workloads.git"

Pin workloads_revision to a specific commit SHA in production. Using a branch name means the next hyops apply will track HEAD at that point, not a fixed state.

2. Apply the module

hyops apply --env <env> \
  --module platform/onprem/argocd-bootstrap \
  --inputs ~/.hybridops/envs/<env>/config/modules/argocd-bootstrap.yml

The module:

  1. Applies the ArgoCD install manifest to the argocd namespace.
  2. Waits up to argocd_wait_timeout_s for all ArgoCD pods to reach Running.
  3. Creates the repo secret (if repo_access_mode: ssh).
  4. Creates the hyops-workloads-root Application resource.
  5. Publishes state including kubeconfig_path, argocd_namespace, and cap.gitops.argocd.

3. Confirm root Application sync

hyops state show --env <env> --module platform/onprem/argocd-bootstrap

Then verify via kubectl or the ArgoCD CLI:

kubectl --kubeconfig <path> -n argocd get application hyops-workloads-root
argocd app get hyops-workloads-root --server localhost:8080

Expected: STATUS: Synced, HEALTH: Healthy.

Verification

  • All ArgoCD pods running in the argocd namespace:

    kubectl --kubeconfig <path> -n argocd get pods

  • Root Application is Synced and Healthy.

  • Resources from clusters/onprem at the pinned revision are present in the cluster:

    kubectl --kubeconfig <path> get applications -n argocd

  • Module state is ok with cap.gitops.argocd published.

Post-actions

  • Access the ArgoCD UI via port-forward or through the published ingress if configured:

    kubectl --kubeconfig <path> port-forward svc/argocd-server -n argocd 8080:443

  • Set the initial ArgoCD admin password from the auto-generated secret:

    kubectl --kubeconfig <path> -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath='{.data.password}' | base64 -d && echo

  • Rotate or disable the initial admin password per your access policy after first login.

  • To add workloads, merge to clusters/onprem in the workloads repo. Argo CD will reconcile within the default sync interval.

References

License: MIT-0 for code, CC-BY-4.0 for documentation