Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 14: Flux trifft kro

Ziel: kro per Flux installieren, eine eigene Plattform-API aus Git ausrollen und ein Team diese API über sein Artefakt nutzen lassen, alles unter dem Lockdown aus Tag 12. · Dauer: ca. 60 min · Voraussetzung: Tag 12, hilfreich: „kro zum Anfassen“

Briefing

  • kro (Kube Resource Orchestrator) baut aus einer ResourceGraphDefinition (RGD) eine eigene Kubernetes-API. Ein Team legt dann nur noch ein kleines Objekt NotesApp an, und kro erzeugt daraus Secret, Deployment und Service.
  • Mit Flux ergibt sich eine klare Arbeitsteilung in drei Schichten, jede mit eigener Kustomization:
Schicht Wer Was Kustomization
Werkzeug Plattform kro selbst, als HelmRelease kro
API Plattform die RGD notesapp kro-apis (nach kro)
Nutzung Team Objekte NotesApp im eigenen Namespace apps in team-blau
  • Die Reihenfolge ist zwingend: Ohne kro keine RGD, ohne RGD keine Art NotesApp. Das regelt dependsOn.
 kro (HelmRelease, als helm-controller)
   └─► kro-apis (RGD notesapp)          ── dependsOn kro
         └─► CRD notesapps.lab.example.com
               └─► team-blau/apps: NotesApp blau ──► kro ──► Secret, Deployment, Service :30094

Drill 1: kro als HelmRelease

kro veröffentlicht sein Chart als OCI-Artefakt in der Registry von Kubernetes:

cd ~/flux-lab/fleet
mkdir -p infrastructure/kro
cd infrastructure/kro
flux create source oci kro --url=oci://registry.k8s.io/kro/charts/kro --tag=0.10.0 \
  --interval=1h \
  --layer-selector=application/vnd.cncf.helm.chart.content.v1.tar+gzip:copy \
  --export > source.yaml
flux create helmrelease kro --chart-ref=OCIRepository/kro.flux-system \
  --target-namespace=kro-system --create-target-namespace --release-name=kro \
  --interval=1h --export > release.yaml
cat > kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - source.yaml
  - release.yaml
EOF
cd ~/flux-lab/fleet
flux create kustomization kro --source=GitRepository/flux-system \
  --path=./infrastructure/kro --prune=true --interval=1h --wait=true --timeout=5m \
  --export > clusters/lab/kro.yaml
git add -A
git commit -m "kro per Flux"
git push
flux reconcile kustomization flux-system --with-source
flux get kustomization kro

Erwartet:

✔ applied revision main@sha1:ff7d5fd12178daf3933781c61ba135f7d6a3d3e5
✗ Kustomization object 'kro' not found in "flux-system" namespace

Erinnerst du dich an den Merksatz aus Tag 12? Seit clusters/lab eine eigene kustomization.yaml hat, wendet Flux nur an, was dort unter resources steht:

sed -i 's/  - echo.yaml/  - echo.yaml\n  - kro.yaml/' clusters/lab/kustomization.yaml
git commit -am "kro.yaml eintragen"
git push
flux reconcile kustomization flux-system --with-source

Eine halbe Minute später:

flux get helmreleases -n flux-system

Erwartet (gekürzt):

NAME    REVISION            SUSPENDED   READY   MESSAGE
kro     0.10.0+56561368ed4c False       False   Could not determine release state: failed to retrieve last release from storage: query: failed to query with labels: secrets is forbidden: User "system:serviceaccount:flux-system:default" cannot list resource "secrets" in API group "" in the namespace "kro-system"

Der zweite Stolperstein, ebenfalls aus Tag 12: Ohne serviceAccountName läuft der HelmRelease als flux-system:default und darf nichts. kro installiert CRDs und ClusterRoles, also braucht es Rechte im ganzen Cluster. Für die Plattform selbst ist der ServiceAccount des helm-controllers die richtige Wahl:

sed -i 's/^  releaseName: kro/  releaseName: kro\n  serviceAccountName: helm-controller/' \
  infrastructure/kro/release.yaml
git commit -am "kro: als helm-controller installieren"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization kro
flux get helmreleases -n flux-system
kubectl -n kro-system get pods

Erwartet (gekürzt):

NAME    REVISION            SUSPENDED   READY   MESSAGE
kro     0.10.0+56561368ed4c False       True    Helm install succeeded for release kro-system/kro.v1 with chart [email protected]+56561368ed4c
NAME                   READY   STATUS    RESTARTS   AGE
kro-65dc768bf8-b49w2   1/1     Running   0          26s

Dass HelmRelease und Quelle in flux-system liegen, ist Absicht: Werkzeuge der Plattform gehören der Plattform. Teams sehen sie nicht und können sie nicht ändern.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die API

Die RGD ist die aus Tag 4 von „kro zum Anfassen“, mit notes-api 0.7.1 als Standard. Sie nimmt vier Felder entgegen und erzeugt drei Objekte:

mkdir -p infrastructure/kro-apis
cat > infrastructure/kro-apis/notesapp-rgd.yaml <<'EOF'
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
  name: notesapp
spec:
  schema:
    apiVersion: v1alpha1
    kind: NotesApp
    group: lab.example.com
    spec:
      image: string | default="ghcr.io/thomaszachmann/notes-api:0.7.1"
      replicas: integer | default=1 minimum=1 maximum=5
      apiKey: string | required=true minLength=12
      nodePort: integer | required=true minimum=30000 maximum=32767
  resources:
    - id: secret
      template:
        apiVersion: v1
        kind: Secret
        metadata:
          name: ${schema.metadata.name}-api
        stringData:
          apiKey: ${schema.spec.apiKey}
    - id: deployment
      template:
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: ${schema.metadata.name}
        spec:
          replicas: ${schema.spec.replicas}
          selector:
            matchLabels:
              app: ${schema.metadata.name}
          template:
            metadata:
              labels:
                app: ${schema.metadata.name}
            spec:
              containers:
                - name: api
                  image: ${schema.spec.image}
                  ports:
                    - containerPort: 8080
                  env:
                    - name: NOTES_API_KEY
                      valueFrom:
                        secretKeyRef:
                          name: ${secret.metadata.name}
                          key: apiKey
    - id: service
      template:
        apiVersion: v1
        kind: Service
        metadata:
          name: ${schema.metadata.name}
        spec:
          type: NodePort
          selector: ${deployment.spec.selector.matchLabels}
          ports:
            - port: 80
              targetPort: 8080
              nodePort: ${schema.spec.nodePort}
EOF

${…} sind hier CEL-Ausdrücke für kro, keine Variablen für Flux. Die Kustomization kro-apis hat kein postBuild, also lässt Flux sie in Ruhe.

flux create kustomization kro-apis --source=GitRepository/flux-system \
  --path=./infrastructure/kro-apis --prune=true --interval=1h --wait=true \
  --depends-on=kro --export > clusters/lab/kro-apis.yaml
sed -i 's/  - kro.yaml/  - kro.yaml\n  - kro-apis.yaml/' clusters/lab/kustomization.yaml
git add -A
git commit -m "kro: API NotesApp"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization kro-apis
kubectl get rgd
kubectl api-resources | grep notesapp

Erwartet (gekürzt):

NAME       APIVERSION   KIND       STATE    READY   AGE
notesapp   v1alpha1     NotesApp   Active   True    6s
notesapps                 lab.example.com/v1alpha1   true   NotesApp

wait: true klappt auch für die RGD: Flux wertet die Condition Ready aus, die kro an jede RGD schreibt. kro-apis ist erst bereit, wenn die neue API wirklich da ist.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Das Team nutzt die API

Team blau braucht dafür keine neuen Rechte. Die RoleBinding aus Tag 12 gibt ihm alle Rechte in seinem Namespace, auch für neue Arten wie NotesApp.

cd ~/flux-lab/team-blau
cat > notesapp.yaml <<'EOF'
apiVersion: lab.example.com/v1alpha1
kind: NotesApp
metadata:
  name: blau
spec:
  apiKey: blau-key-123456
  nodePort: 30094
EOF
flux push artifact oci://localhost:30500/team-blau/apps:1.4.0 --path=. \
  --source=local --revision=1.4.0 --insecure-registry
flux reconcile source oci apps -n team-blau
flux reconcile kustomization apps -n team-blau

Erwartet (gekürzt):

...
✔ applied revision 1.4.0@sha256:02794bc2822ff0525301233da417fdb5600eb8d10dca06a463cdaa72d501dc7d
kubectl -n team-blau get notesapp
kubectl -n team-blau get deploy
curl -s localhost:30094/version; echo

Erwartet (gekürzt):

NAME   STATE    READY   AGE
blau   ACTIVE   True    19s
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
blau    1/1     1            1           19s
notes   1/1     1            1           16m
0.7.1

Sechs Zeilen YAML statt sechzig. Wer was verwaltet, zeigt flux tree:

flux tree kustomization apps -n team-blau

Erwartet:

Kustomization/team-blau/apps
├── Secret/team-blau/notes-api
├── Service/team-blau/notes
├── Deployment/team-blau/notes
└── NotesApp/team-blau/blau

Flux verwaltet die NotesApp, nicht das Deployment blau. Das gehört kro. Ändert jemand das Deployment von Hand, dreht kro es zurück. Ändert jemand die NotesApp von Hand, dreht Flux sie zurück. Zwei Controller, zwei Ebenen, keine Überschneidung.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

flux get kustomizations kro kro-apis

Erwartet: beide READY True.

kubectl get rgd notesapp -o jsonpath='{.status.state}{"\n"}'

Erwartet: Active.

curl -s localhost:30094/version; echo

Erwartet: 0.7.1.

Challenge

Der Cluster brennt ab, und du baust ihn mit flux bootstrap neu auf. Alle Kustomizations starten gleichzeitig. Was passiert mit team-blau/apps, solange kro und die RGD noch nicht da sind? Sorg dafür, dass die Mandanten erst nach der API kommen.

Hinweis: team-blau/apps darf wegen --no-cross-namespace-refs nicht von einer Kustomization in flux-system abhängen. Aber eine Kustomization in flux-system legt die Mandanten erst an.

Lösung

Ohne Vorkehrung scheitert team-blau/apps zunächst, weil der API-Server die Art NotesApp noch nicht kennt. Flux versucht es wieder, und irgendwann klappt es. Sauberer ist es, die Mandanten erst anzulegen, wenn die API steht:

cd ~/flux-lab/fleet
flux create kustomization tenants --source=GitRepository/flux-system \
  --path=./tenants --prune=true --interval=10m --depends-on=kro-apis \
  --export > clusters/lab/tenants.yaml
git commit -am "tenants erst nach kro-apis"
git push
flux reconcile kustomization flux-system --with-source
flux reconcile kustomization tenants
flux get kustomization tenants

Erwartet (gekürzt):

NAME    REVISION            SUSPENDED   READY   MESSAGE
tenants main@sha1:3f7e48a1  False       True    Applied revision: main@sha1:3f7e48a1

Die Kette ist jetzt kro → kro-apis → tenants → Namespaces und Kustomizations der Teams. Auf einem frischen Cluster entsteht ein Team erst, wenn seine Werkzeuge da sind.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • APIs versionieren: Eine RGD ist eine öffentliche Schnittstelle. Änderungen am Schema laufen durch Review, und kro sperrt Änderungen, die bestehende Instanzen brechen würden (siehe „kro zum Anfassen“, Tag 11).
  • Viele Cluster, eine API: Die RGDs liegen in infrastructure/kro-apis und gelten für jeden Cluster, dessen Ordner unter clusters/ darauf zeigt. Eine neue Version der API ist ein Commit, und alle Cluster ziehen nach.
  • Alternativen: Crossplane-Compositions oder eigene Operatoren füllen dieselbe Rolle. An der Arbeitsteilung mit Flux ändert das nichts: Flux bringt Werkzeug, API und Nutzung in der richtigen Reihenfolge in den Cluster.