Maxwell MorrisandClaude Sonnet 5
92c3ad3191
A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on bare metal, a demo app, and a progressive docs/ walkthrough with a CLAUDE.md tutor persona and guided bootstrap checklist. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
# Installing Argo CD — command reference
|
|
|
|
Companion to [`docs/03-installing-argocd.md`](../docs/03-installing-argocd.md)
|
|
and [`docs/04-app-of-apps.md`](../docs/04-app-of-apps.md). Read those for the
|
|
why; this is the exact commands.
|
|
|
|
Run these once `kubectl get nodes` shows your node `Ready` (see
|
|
[`talos/README.md`](../talos/README.md)).
|
|
|
|
## 1. Install Argo CD
|
|
|
|
```sh
|
|
kubectl create namespace argocd
|
|
kubectl apply --server-side -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
|
|
```
|
|
|
|
`--server-side` matters here, not just as a nice-to-have: one of Argo CD's
|
|
CRDs (`applicationsets.argoproj.io`) is large enough that a normal
|
|
(client-side) `kubectl apply` fails outright — it tries to stash the whole
|
|
manifest into an annotation for its 3-way-merge bookkeeping, and that
|
|
annotation hits Kubernetes' size limit. Server-side apply has the API
|
|
server do that diffing instead, so this limit doesn't apply.
|
|
|
|
This is an **imperative** install: a plain `kubectl apply` of a manifest
|
|
bundle that the Argo CD project maintains, rather than a Helm chart or
|
|
operator. It's the officially documented quickstart path, and it means
|
|
Argo CD itself isn't part of your GitOps loop — you install it once, by
|
|
hand, and *it* then manages everything else declaratively. Bootstrapping
|
|
has to start somewhere outside the loop; this is that starting point.
|
|
|
|
The `stable` in that URL is a moving tag maintained by the Argo CD project
|
|
that always points at the latest stable release — convenient here, but not
|
|
reproducible: what it installs today may differ from what it installs in
|
|
six months. For a production setup, pin an explicit version instead, e.g.
|
|
`.../v2.13.0/manifests/install.yaml` — see [releases](https://github.com/argoproj/argo-cd/releases)
|
|
for current tags.
|
|
|
|
Wait for everything to come up:
|
|
|
|
```sh
|
|
kubectl -n argocd wait --for=condition=Available --timeout=300s deployment --all
|
|
```
|
|
|
|
## 2. Get the initial admin password
|
|
|
|
```sh
|
|
kubectl -n argocd get secret argocd-initial-admin-secret \
|
|
-o jsonpath="{.data.password}" | base64 -d; echo
|
|
```
|
|
|
|
This secret is auto-generated on first install. Save the password
|
|
somewhere; you'll change it in a moment.
|
|
|
|
## 3. Reach the UI and CLI
|
|
|
|
Argo CD doesn't expose itself outside the cluster by default. For this
|
|
learning setup, forward its port to your machine:
|
|
|
|
```sh
|
|
kubectl -n argocd port-forward svc/argocd-server 8080:443
|
|
```
|
|
|
|
Leave that running in its own terminal. In another terminal:
|
|
|
|
```sh
|
|
argocd login localhost:8080 --username admin --password <password-from-above> --insecure
|
|
```
|
|
|
|
`--insecure` here means "skip TLS certificate verification" — the server's
|
|
certificate is self-signed by default and there's nothing on the other end
|
|
but your own port-forward, so this is fine for local access. It is **not**
|
|
something to carry into a setup reachable over the real network.
|
|
|
|
Open `https://localhost:8080` in a browser to see the same thing visually.
|
|
|
|
Optional but recommended — replace the initial password:
|
|
|
|
```sh
|
|
argocd account update-password
|
|
```
|
|
|
|
## 4. Hand the cluster to Git
|
|
|
|
[`app-of-apps/app-of-apps.yaml`](app-of-apps/app-of-apps.yaml) is the one
|
|
manifest in this whole repo you apply by hand — everything after it, Argo
|
|
CD applies for you. First, every Application manifest needs its own
|
|
`repoURL` pointed at your fork (they don't inherit it from each other):
|
|
|
|
```sh
|
|
grep -rl YOUR_GITHUB_USERNAME .
|
|
```
|
|
|
|
Edit `spec.source.repoURL` in each file that command finds, commit, and
|
|
push — the child Applications are read from Git, not your local disk, so
|
|
this has to land in your fork before the next step. Then:
|
|
|
|
```sh
|
|
kubectl apply -f argocd/app-of-apps/app-of-apps.yaml
|
|
```
|
|
|
|
Watch it take over:
|
|
|
|
```sh
|
|
argocd app get app-of-apps
|
|
argocd app list
|
|
```
|
|
|
|
You should see `app-of-apps` sync, then `demo` and `metallb` Applications
|
|
appear underneath it, then sync themselves. See
|
|
[`docs/04-app-of-apps.md`](../docs/04-app-of-apps.md) for what's happening
|
|
here and [`docs/checklist.md`](../docs/checklist.md) for the full guided
|
|
path.
|
|
|
|
## 5. Give the UI a real address (MetalLB)
|
|
|
|
Once `metallb` (above) is `Synced`/`Healthy` and you've configured its
|
|
address pool (see [`docs/05-metallb.md`](../docs/05-metallb.md)), you can
|
|
retire the port-forward from step 3 and give Argo CD's UI a permanent
|
|
address instead. This one change is applied directly, not through Git —
|
|
Argo CD's own install isn't managed by this repo's GitOps loop:
|
|
|
|
```sh
|
|
kubectl -n argocd patch svc argocd-server --type merge -p \
|
|
'{"spec":{"type":"LoadBalancer"},"metadata":{"annotations":{"metallb.universe.tf/loadBalancerIPs":"<ARGOCD_IP>"}}}'
|
|
```
|
|
|
|
```sh
|
|
kubectl -n argocd get svc argocd-server
|
|
```
|
|
|
|
Once `EXTERNAL-IP` shows your chosen address, `https://<that-address>`
|
|
works directly, from any machine on your network — no port-forward
|
|
required.
|