Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Apps und Helm-Repos

Ziel: Gitea im local-Cluster als Container-Registry und Helm-Repo betreiben, dem Cluster werk die Registry über Rancher beibringen und notes als App aus dem eigenen Katalog installieren und aktualisieren. · Dauer: ca. 120 min · Voraussetzung: Tag 6

Briefing

  • Gitea ist ein schlanker Git-Server. Mit Packages ist es zugleich Registry für Container-Images und Repo für Helm-Charts. An Tag 8 dient es als Git-Server für Fleet.
  • Zertifikate kommen von einer eigenen Labor-CA in cert-manager. Jeder, der Gitea anspricht, muss dieser CA vertrauen: dein Mac, die Nodes, Rancher.
  • Die Nodes von werk bekommen Zugangsdaten und CA nicht von Hand, sondern über rkeConfig.registries im Cluster-Objekt. Rancher verteilt sie auf alle Nodes.
  • Ein ClusterRepo macht ein Helm-Repo in Rancher zum Katalog. Installiert wird als App: ein Helm-Release, das Rancher anzeigt und aktualisiert.
 Mac                         local-Cluster (VM rancher)          Cluster werk
 nerdctl push ──────────────► Gitea  gitea.<IP>.sslip.io
 curl (Chart) ──────────────►  ├ Container: lab/notes-*  ◄──pull── containerd
                               └ Helm: lab/notes 0.3.0   ◄──index── ClusterRepo lab
                              cert-manager: Labor-CA                 App notes

Drill 1: Speicher und eine Labor-CA

Gitea braucht ein Volume. Das local-Cluster ist ein frisches RKE2 ohne StorageClass; local-path hilft wie in „Kubernetes zum Anfassen”, Tag 12:

source ~/rancher-lab/setup/env.sh
mkdir -p "$LAB/tag07" && cd "$LAB/tag07"
cp "$LAB/code/tag07/"* .
export KUBECONFIG="$LAB/kube/rancher.yaml"
kubectl apply -f https://raw.githubusercontent.com/rancher/\
local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml > /dev/null
kubectl annotate sc local-path storageclass.kubernetes.io/is-default-class=true

Erwartet:

storageclass.storage.k8s.io/local-path annotated

Rancher hat seine eigene CA nur für sich. Für Gitea legst du mit cert-manager eine zweite an:

# tag07/lab-ca.yaml – Stand Ende Tag 7: eigene Labor-CA mit cert-manager
# 1. Selbstsigniert, nur um die CA zu erzeugen …
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}
---
# 2. … das CA-Zertifikat selbst (Secret lab-ca in cert-manager) …
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: lab-ca
  namespace: cert-manager
spec:
  isCA: true
  commonName: rancher-lab CA
  secretName: lab-ca
  duration: 8760h
  privateKey:
    algorithm: ECDSA
    size: 256
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer
---
# 3. … und der Issuer, der damit Zertifikate für Gitea und Co. ausstellt.
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: lab-ca
spec:
  ca:
    secretName: lab-ca
kubectl apply -f lab-ca.yaml
kubectl -n cert-manager wait certificate/lab-ca --for=condition=Ready --timeout=60s
kubectl get clusterissuer
kubectl -n cert-manager get secret lab-ca -o jsonpath='{.data.ca\.crt}' \
  | base64 -d > lab-ca.crt
openssl x509 -in lab-ca.crt -noout -subject -enddate

Erwartet (gekürzt, Namen, IPs und Zeiten weichen bei dir ab):

clusterissuer.cert-manager.io/selfsigned created
certificate.cert-manager.io/lab-ca created
clusterissuer.cert-manager.io/lab-ca created
certificate.cert-manager.io/lab-ca condition met
NAME         READY   AGE
lab-ca       True    1s
selfsigned   True    1s
subject=CN = rancher-lab CA
notAfter=Oct 31 14:42:10 2027 GMT

lab-ca.crt ist das öffentliche CA-Zertifikat. Es kommt heute noch an drei Stellen zum Einsatz.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Gitea

gitea-values.yaml hält Gitea klein: SQLite statt eigener Datenbank, kein Cache-Cluster, Packages an, Ingress über Traefik mit einem Zertifikat der Labor-CA:

# tag07/gitea-values.yaml (Ausschnitt) – Stand Ende Tag 7
gitea:
  admin:
    username: lab
    password: lab-gitea-pw-123
  config:
    database:
      DB_TYPE: sqlite3            # ein Pod, keine eigene Datenbank
    packages:
      ENABLED: true               # Container-Registry und Helm-Repo
postgresql-ha:
  enabled: false
valkey-cluster:
  enabled: false
ingress:
  enabled: true
  className: traefik
  annotations:
    cert-manager.io/cluster-issuer: lab-ca

Die vollständige Datei liegt im Begleitcode code/tag07/.

sed -i '' "s/RANCHER_IP/$RANCHER/g" gitea-values.yaml
helm repo add gitea-charts https://dl.gitea.com/charts/
helm install gitea gitea-charts/gitea --version 12.7.0 -n gitea --create-namespace \
  -f gitea-values.yaml --wait --timeout 10m | grep -E '^(NAME|STATUS):'
G="https://gitea.$RANCHER.sslip.io"
curl -s --cacert lab-ca.crt -u lab:lab-gitea-pw-123 "$G/api/v1/version"; echo

Erwartet:

"gitea-charts" has been added to your repositories
NAME: gitea
STATUS: deployed
{"version":"1.27.0"}

Nach knapp einer Minute läuft Gitea. Diesmal ohne -k: curl prüft das Zertifikat gegen lab-ca.crt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Images in die Registry

Rancher Desktop pusht die Images aus Tag 1. Der containerd darin kennt die Labor-CA nicht; für das Labor überspringt --insecure-registry die Prüfung beim Push:

R="gitea.$RANCHER.sslip.io"
echo lab-gitea-pw-123 | nerdctl login --insecure-registry -u lab --password-stdin "$R"
for s in api:0.2.0 web:0.1.0 worker:0.1.0; do
  nerdctl --namespace k8s.io tag "notes-${s%:*}:${s#*:}" "$R/lab/notes-${s%:*}:${s#*:}"
  nerdctl --namespace k8s.io push --insecure-registry "$R/lab/notes-${s%:*}:${s#*:}"
done
curl -s --cacert lab-ca.crt -u lab:lab-gitea-pw-123 \
  "$G/api/v1/packages/lab?type=container" | jq -r '.[].name' | sort -u

Erwartet (gekürzt):

Login Succeeded
…
notes-api
notes-web
notes-worker

Ein Container-Image heißt bei Gitea <host>/<besitzer>/<name>:<tag>; Besitzer ist der Benutzer lab.

Sicherheit: --insecure-registry gehört nur ins Labor. Für Produktion bekommt jeder Client die CA in seinen Vertrauensspeicher; die Nodes von werk machen das gleich richtig.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Das Chart ins Helm-Repo

Gitea nimmt Charts als .tgz per HTTP-Upload an:

helm package "$LAB/code/notes-chart/notes"
curl -s --cacert lab-ca.crt -u lab:lab-gitea-pw-123 -X POST \
  --upload-file notes-0.3.0.tgz -w '%{http_code}\n' \
  "$G/api/packages/lab/helm/api/charts"
helm repo add lab "$G/api/packages/lab/helm" --ca-file lab-ca.crt \
  --username lab --password lab-gitea-pw-123
helm search repo lab/notes

Erwartet:

Successfully packaged chart and saved it to: …/notes-0.3.0.tgz
201
"lab" has been added to your repositories
NAME        CHART VERSION   APP VERSION   DESCRIPTION
lab/notes   0.3.0           0.2.0         Die notes-Anwendung aus dem Trainings…

In Gitea siehst du beides unter dem Benutzer lab im Reiter Packages:

Gitea mit drei Container-Images und dem Helm-Chart

Fortschritt speichern? Kostenlos registrieren

Drill 5: werk lernt die Registry

Zuerst die Zugangsdaten als Secret im local-Cluster, im Namespace der Cluster:

# tag07/gitea-pull.yaml – Stand Ende Tag 7: Pull-Zugang der Nodes zu Gitea
apiVersion: v1
kind: Secret
metadata:
  name: gitea-pull
  namespace: fleet-default
type: rke.cattle.io/auth-config
stringData:
  username: lab
  password: lab-gitea-pw-123

Dann bekommt das Cluster-YAML aus Tag 5 einen neuen Abschnitt:

# tag07/cluster-werk.yaml (Ausschnitt) – Stand Ende Tag 7
    registries:              # neu an Tag 7: wird zu registries.yaml auf jedem Node
      configs:
        gitea.RANCHER_IP.sslip.io:
          authConfigSecretName: gitea-pull
          caBundle: CA_BUNDLE

caBundle erwartet die CA als base64-kodiertes PEM. Wende beides an und schau zu, wie Rancher die Nodes nacheinander anpasst:

kubectl apply -f gitea-pull.yaml
sed -i '' -e "s|RANCHER_IP|$RANCHER|" -e "s|CA_BUNDLE|$(base64 -i lab-ca.crt)|" \
  cluster-werk.yaml
kubectl apply -f cluster-werk.yaml
kubectl -n fleet-default wait clusters.provisioning.cattle.io/werk \
  --for=condition=Updated --timeout=600s
multipass exec werk2 -- sudo grep -o '"ca_file":"[^"]*"' \
  /etc/rancher/rke2/registries.yaml

Erwartet (gekürzt):

secret/gitea-pull created
cluster.provisioning.cattle.io/werk configured
cluster.provisioning.cattle.io/werk condition met
"ca_file":"/var/lib/rancher/rke2/etc/tls/registries/gitea.….sslip.io/ca.crt"

Nach anderthalb Minuten hat jeder Node seine registries.yaml, die CA liegt daneben, und RKE2 ist neu gestartet. Das ist dieselbe Datei wie in „Kubernetes zum Anfassen”, Tag 13. Dort hast du sie per Hand verteilt, hier macht das ein Plan (Tag 5).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Ein Katalog pro Cluster

# tag07/clusterrepo-lab.yaml – Stand Ende Tag 7: Gitea-Helm-Repo als Katalog
# Vorlage: RANCHER_IP und CA_BUNDLE (base64 der Labor-CA) ersetzt Drill 6 per sed.
apiVersion: v1
kind: Secret
metadata:
  name: gitea-helm
  namespace: cattle-system
type: kubernetes.io/basic-auth
stringData:
  username: lab
  password: lab-gitea-pw-123
---
apiVersion: catalog.cattle.io/v1
kind: ClusterRepo
metadata:
  name: lab
spec:
  url: https://gitea.RANCHER_IP.sslip.io/api/packages/lab/helm
  caBundle: CA_BUNDLE
  clientSecret:
    name: gitea-helm
    namespace: cattle-system

Zwei Stolpersteine, beide live gefunden:

  • Ein ClusterRepo gilt nur in dem Cluster, in dem es liegt. Für Apps in werk gehört es nach werk, nicht ins local-Cluster.
  • Hier erwartet caBundle die CA im DER-Format, base64-kodiert. PEM führt zu x509: malformed certificate.
DER=$(openssl x509 -in lab-ca.crt -outform der | base64)
sed -i '' -e "s|RANCHER_IP|$RANCHER|" -e "s|CA_BUNDLE|$DER|" clusterrepo-lab.yaml
export KUBECONFIG="$LAB/kube/werk.yaml"
kubectl apply -f clusterrepo-lab.yaml
kubectl wait clusterrepos.catalog.cattle.io/lab --for=condition=Downloaded \
  --timeout=120s
kubectl get clusterrepos.catalog.cattle.io

Erwartet (gekürzt):

secret/gitea-helm created
clusterrepo.catalog.cattle.io/lab created
clusterrepo.catalog.cattle.io/lab condition met
NAME                     HTTP URL                                    …   DOWNLOAD TIME
lab                      https://gitea.….sslip.io/api/packages/lab…  …   …T14:58:36Z
rancher-charts                                                       …   …T14:20:29Z
rancher-partner-charts                                               …   …T14:19:21Z

Unter Apps › Charts in werk findet die Suche jetzt notes aus dem Repo lab:

Der eigene Katalog in Rancher: notes aus dem Repo lab

Ein Klick zeigt die Chart-Seite mit Version und App-Version:

Chart-Seite von notes mit Version 0.3.0

Fortschritt speichern? Kostenlos registrieren

Drill 7: notes als App installieren

Auch werk hat keine StorageClass. Ohne sie bleibt db-0 auf Pending, und Helm bricht nach zehn Minuten ab. Also erst Speicher und Secrets, dann die App:

kubectl apply -f https://raw.githubusercontent.com/rancher/\
local-path-provisioner/v0.0.37/deploy/local-path-storage.yaml > /dev/null
kubectl annotate sc local-path storageclass.kubernetes.io/is-default-class=true
kubectl -n notes create secret generic notes-api --from-literal=api-key=lab-api-key-123
kubectl -n notes create secret generic notes-db --from-literal=password=lab-db-pw-123 \
  --from-literal=db-url='postgres://notes:lab-db-pw-123@db:5432/notes'
sed -i '' "s/RANCHER_IP/$RANCHER/g" values-werk.yaml
cat values-werk.yaml

Erwartet (gekürzt):

storageclass.storage.k8s.io/local-path annotated
secret/notes-api created
secret/notes-db created
# tag07/values-werk.yaml – Stand Ende Tag 7: notes auf werk, Images aus Gitea
api:
  image:
    repository: gitea.….sslip.io/lab/notes-api
…
gateway:
  enabled: false                   # werk hat Traefik aus RKE2, siehe ingress.yaml
networkPolicy:
  gatewayNamespace: kube-system    # dort läuft Traefik

In der Oberfläche klickst du auf der Chart-Seite Install, wählst den Namespace notes und fügst die Werte ein. Derselbe Aufruf geht an Ranchers API; so ist er wiederholbar:

H="Authorization: Bearer $(cat "$LAB/rancher-token")"
ID=$(kubectl --kubeconfig "$LAB/kube/rancher.yaml" -n fleet-default \
  get clusters.provisioning.cattle.io werk -o jsonpath='{.status.clusterName}')
V=$(yq -o=json values-werk.yaml)
API="https://rancher.$RANCHER.sslip.io/k8s/clusters/$ID/v1"
API+="/catalog.cattle.io.clusterrepos/lab"
curl -sk -X POST -H "$H" -H 'Content-Type: application/json' "$API?action=install" \
  -d "{\"charts\":[{\"chartName\":\"notes\",\"version\":\"0.3.0\",
       \"releaseName\":\"notes\",\"values\":$V}],\"namespace\":\"notes\",
       \"wait\":true,\"timeout\":\"600s\"}" \
  | jq -c '{operationName, operationNamespace}'

Erwartet:

{"operationName":"helm-operation-sgvx2","operationNamespace":"notes"}

yq (per Homebrew) wandelt die Values in JSON um. Rancher startet einen Pod helm-operation-…, der helm install ausführt. Nach gut einer Minute:

helm -n notes list
kubectl -n notes get pods -o wide
kubectl get operations.catalog.cattle.io -n notes \
  -o custom-columns=NAME:.metadata.name,CMD:.status.command[1]

Erwartet (gekürzt):

NAME    NAMESPACE   REVISION   UPDATED   STATUS     CHART         APP VERSION
notes   notes       1          2026-…    deployed   notes-0.3.0   0.2.0
NAME                      READY   STATUS      RESTARTS   AGE   …   NODE
api-74fbdd7f6b-66wrh      1/1     Running     3          55s   …   werk2
…
db-0                      1/1     Running     0          55s   …   werk3
migrate-q292f             0/1     Completed   0          12s   …   werk2
web-9695cdc87-b8jvn       1/1     Running     0          55s   …   werk3
…
NAME                   CMD
helm-operation-sgvx2   install

Unter Apps › Installed Apps steht notes als Deployed:

Installierte Apps in werk

Fortschritt speichern? Kostenlos registrieren

Drill 8: Von außen

werk hat wie k3s Traefik als Standard-Ingress. Die Ingress-Datei aus Tag 2 passt, nur mit der Adresse von werk1:

sed "s/WERK1_IP/$WERK1/" ingress.yaml | kubectl apply -f -
curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"text":"aus dem eigenen Katalog"}' "http://notes.$WERK1.sslip.io/api/notes"; echo
curl -s "http://notes.$WERK1.sslip.io/api/notes"; echo

Erwartet (gekürzt):

ingress.networking.k8s.io/web created
{"id":"c0c70ff3-…","text":"aus dem eigenen Katalog"}
[{"id":"c0c70ff3-…","text":"aus dem eigenen Katalog"}]

notes läuft jetzt auf zwei Clustern: auf k3s aus einem Image-Archiv, auf werk aus dem eigenen Katalog und der eigenen Registry.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

kubectl get clusterrepos.catalog.cattle.io lab

Erwartet: das Repo lab mit einer DOWNLOAD TIME.

NAME   HTTP URL                                         …   DOWNLOAD TIME
lab    https://gitea.….sslip.io/api/packages/lab/helm   …   2026-10-31T14:58:36Z
helm -n notes list

Erwartet: Release notes mit Chart notes-0.3.0, deployed.

NAME    NAMESPACE   REVISION   UPDATED   STATUS     CHART         APP VERSION
notes   notes       1          2026-…    deployed   notes-0.3.0   0.2.0
curl -s "http://notes.$WERK1.sslip.io/api/notes"; echo

Erwartet: die Notiz aus Drill 8.

[{"id":"c0c70ff3-…","text":"aus dem eigenen Katalog"}]

Challenge

Veröffentliche das Chart als Version 0.3.1, lass Rancher den Katalog neu laden und aktualisiere die App, ohne Werte zu verlieren. Woran erkennst du in der Oberfläche, dass ein Update bereitsteht?

Hinweis: Ein ClusterRepo lädt nur alle paar Stunden neu; spec.forceUpdate mit einem neuen Zeitstempel erzwingt es. Die API kennt neben install auch upgrade.

Lösung

cp -R "$LAB/code/notes-chart/notes" chart031
sed -i '' 's/^version: 0.3.0/version: 0.3.1/' chart031/Chart.yaml
helm package chart031
curl -s --cacert lab-ca.crt -u lab:lab-gitea-pw-123 -X POST \
  --upload-file notes-0.3.1.tgz -w '%{http_code}\n' \
  "$G/api/packages/lab/helm/api/charts"
kubectl patch clusterrepos.catalog.cattle.io lab --type merge \
  -p "{\"spec\":{\"forceUpdate\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}}"
curl -sk -X POST -H "$H" -H 'Content-Type: application/json' "$API?action=upgrade" \
  -d "{\"charts\":[{\"chartName\":\"notes\",\"version\":\"0.3.1\",
       \"releaseName\":\"notes\",\"values\":$V}],\"namespace\":\"notes\",
       \"wait\":true,\"timeout\":\"600s\"}" \
  | jq -c '{operationName}'
helm -n notes history notes

Erwartet (gekürzt, nach gut einer Minute):

Successfully packaged chart and saved it to: …/notes-0.3.1.tgz
201
clusterrepo.catalog.cattle.io/lab patched
{"operationName":"helm-operation-nd9xk"}
REVISION   UPDATED    STATUS       CHART         APP VERSION   DESCRIPTION
1          …          superseded   notes-0.3.0   0.2.0         Install complete
2          …          deployed     notes-0.3.1   0.2.0         Upgrade complete

Vor dem Upgrade zeigt Installed Apps in der Spalte Upgradable die neue Version:

Rancher meldet notes 0.3.1 als verfügbares Update

Die Werte gibst du beim Upgrade erneut mit; die Oberfläche übernimmt sie von selbst. Die Notiz bleibt, denn sie liegt in Postgres.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Registry: Statt Gitea steht meist Harbor oder die Registry der Git-Plattform bereit, mit Projekten, Scans und Replikation. rkeConfig.registries.mirrors leitet dazu Docker Hub über einen eigenen Spiegel um.
  • Kataloge zentral: Ein ClusterRepo pro Cluster lässt sich per Fleet (Tag 9) auf alle Cluster verteilen, statt es von Hand anzulegen.
  • OCI-Charts: Rancher kann Charts auch direkt aus OCI-Registries laden (oci://…); dann reicht eine einzige Registry für Images und Charts.
  • Vertrauen: Eine Unternehmens-CA kommt per Systemkonfiguration auf alle Rechner und Nodes. --insecure-registry und curl -k haben dort nichts verloren.
  • Apps oder GitOps: Klicken in Apps ist bequem, hinterlässt aber keinen Verlauf im Git. Ab Tag 8 kommen die Werte aus einem Repository.