Build bis Rollout: S2I, ImageStream und Deployment

1 Die ganze Kette

Vier Übergaben verbinden Quelltext mit laufenden Pods. An jeder Übergabe entsteht ein anderer überprüfbarer Zustand.

Source-to-Image, kurz S2I, verbindet deinen Quelltext mit einem Builder-Image. Das Builder-Image kennt die Sprache und enthält Skripte zum Bauen und Starten. Der fertige Container enthält keine besondere S2I-Laufzeit.

2 Die Objekte einordnen

3 Cluster und APIs prüfen

Du brauchst einen angemeldeten Benutzer mit Recht auf ein eigenes Projekt. Die interne Registry muss verfügbar sein.

oc whoami
oc get co image-registry
oc get image.config.openshift.io cluster -o yaml
oc api-resources | Select-String -Pattern 'BuildConfig|ImageStream|Deployment'

oc whoami
oc get co image-registry
oc get image.config.openshift.io cluster -o yaml
oc api-resources | grep -E 'BuildConfig|ImageStream|Deployment'

4 Lokalen Quelltext anlegen

Die drei Dateien bilden eine HTTP-Anwendung ohne zusätzliche npm-Pakete. S2I erkennt package.json und startet später npm start.

New-Item -ItemType Directory -Force -Path .\s2i-src | Out-Null

@'
{"name":"s2i-rollout-lab","version":"1.0.0","scripts":{"start":"node server.js"}}
'@ | Set-Content -LiteralPath .\s2i-src\package.json -Encoding utf8

@'
const http = require("http");
const fs = require("fs");
const version = fs.readFileSync("version.txt", "utf8").trim();
const port = Number(process.env.PORT || 8080);

http.createServer((request, response) => {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end(`hello ${version}\n`);
}).listen(port, "0.0.0.0");
'@ | Set-Content -LiteralPath .\s2i-src\server.js -Encoding utf8

'v1' | Set-Content -LiteralPath .\s2i-src\version.txt -Encoding utf8
Get-ChildItem -LiteralPath .\s2i-src

mkdir -p ./s2i-src

cat > ./s2i-src/package.json <<'EOF'
{"name":"s2i-rollout-lab","version":"1.0.0","scripts":{"start":"node server.js"}}
EOF

cat > ./s2i-src/server.js <<'EOF'
const http = require("http");
const fs = require("fs");
const version = fs.readFileSync("version.txt", "utf8").trim();
const port = Number(process.env.PORT || 8080);

http.createServer((request, response) => {
  response.writeHead(200, {"Content-Type": "text/plain"});
  response.end(`hello ${version}\n`);
}).listen(port, "0.0.0.0");
EOF

printf 'v1\n' > ./s2i-src/version.txt
find ./s2i-src -maxdepth 1 -type f -print

s2i-src/package.json, s2i-src/server.js und s2i-src/version.txt legst du an. Das Verzeichnis ist als lokales Lab-Artefakt in .gitignore ausgeschlossen.

5 ImageStream und BuildConfig anwenden

Die Quelle ist vom Typ Binary. Sie wird beim Start des Builds übertragen und nicht dauerhaft in der BuildConfig gespeichert.

oc new-project build-rollout-lab

@'
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: hello-s2i
---
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: hello-s2i
spec:
  runPolicy: Serial
  source:
    type: Binary
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: registry.access.redhat.com/ubi9/nodejs-20:latest
  output:
    to:
      kind: ImageStreamTag
      name: hello-s2i:latest
'@ | oc apply -f -

oc new-project build-rollout-lab

oc apply -f - <<'EOF'
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: hello-s2i
---
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: hello-s2i
spec:
  runPolicy: Serial
  source:
    type: Binary
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: registry.access.redhat.com/ubi9/nodejs-20:latest
  output:
    to:
      kind: ImageStreamTag
      name: hello-s2i:latest
EOF

6 Den ersten S2I-Build verfolgen

oc start-build hello-s2i --from-dir .\s2i-src --follow
oc get build,pod,imagestream,imagestreamtag
oc describe build hello-s2i-1
oc get istag hello-s2i:latest -o jsonpath='{.image.dockerImageReference}{"\n"}'

oc start-build hello-s2i --from-dir ./s2i-src --follow
oc get build,pod,imagestream,imagestreamtag
oc describe build hello-s2i-1
oc get istag hello-s2i:latest -o jsonpath='{.image.dockerImageReference}{"\n"}'

Die Skripte assemble und run sind wichtige Bestandteile des Builder-Images. Du legst sie in diesem Lab nicht an. Ein Projekt könnte sie unter .s2i/bin/ bewusst überschreiben.

7 Deployment, Service und Route anlegen

Das Deployment startet zunächst aus dem internen Registry-Namen. Danach bindest du es ausdrücklich an den ImageStreamTag.

oc create deployment hello-s2i --image=image-registry.openshift-image-registry.svc:5000/build-rollout-lab/hello-s2i:latest
oc set triggers deployment/hello-s2i --from-image=hello-s2i:latest -c hello-s2i
oc expose deployment hello-s2i --port=8080
oc expose service hello-s2i
oc rollout status deployment/hello-s2i --timeout=120s
oc get deployment,replicaset,pod -o wide
oc get route hello-s2i

Das Deployment besitzt das ReplicaSet über ownerReferences. Das ReplicaSet besitzt wiederum die Pods. Der Wert pod-template-hash verbindet jeden Pod mit genau der Vorlagenversion, aus der er entstand.

oc get replicaset -l app=hello-s2i --sort-by=.metadata.creationTimestamp
oc get pod -l app=hello-s2i -o jsonpath='{range .items[*]}{.metadata.name}{" <- "}{.metadata.ownerReferences[0].kind}{"/"}{.metadata.ownerReferences[0].name}{"\n"}{end}'
oc get replicaset -l app=hello-s2i -o jsonpath='{range .items[*]}{.metadata.name}{" <- "}{.metadata.ownerReferences[0].kind}{"/"}{.metadata.ownerReferences[0].name}{"\n"}{end}'

8 Den Image-Trigger lesen

Bei einem Kubernetes-Deployment speichert OpenShift den Trigger in metadata.annotations. Er ist kein Feld der Kubernetes-Deployment-API.

oc set triggers deployment/hello-s2i
oc get deployment hello-s2i -o jsonpath='{.metadata.annotations.image\.openshift\.io/triggers}{"\n"}'
oc get deployment hello-s2i -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

Die Annotation nennt den beobachteten ImageStreamTag, den Container und den Pfad zum Image-Feld. Sobald sich der Digest des Tags ändert, schreibt OpenShift die neue aufgelöste Image-Referenz in spec.template. Kubernetes erkennt eine neue Pod-Vorlage und erzeugt das nächste ReplicaSet.

9 Einen automatischen Rollout beweisen

Terminal 1 beobachtet die Kette

oc get build,deployment,replicaset,pod --watch

Terminal 2 baut Version 2

$digestBefore = oc get istag hello-s2i:latest -o jsonpath='{.image.metadata.name}'
'v2' | Set-Content -LiteralPath .\s2i-src\version.txt -Encoding utf8
oc start-build hello-s2i --from-dir .\s2i-src --follow
oc rollout status deployment/hello-s2i --timeout=120s
$digestAfter = oc get istag hello-s2i:latest -o jsonpath='{.image.metadata.name}'
"Digest vorher: $digestBefore"
"Digest nachher: $digestAfter"
oc get replicaset -l app=hello-s2i --sort-by=.metadata.creationTimestamp
$hostName = oc get route hello-s2i -o jsonpath='{.spec.host}'
curl.exe "http://$hostName"

digest_before=$(oc get istag hello-s2i:latest -o jsonpath='{.image.metadata.name}')
printf 'v2\n' > ./s2i-src/version.txt
oc start-build hello-s2i --from-dir ./s2i-src --follow
oc rollout status deployment/hello-s2i --timeout=120s
digest_after=$(oc get istag hello-s2i:latest -o jsonpath='{.image.metadata.name}')
printf 'Digest vorher: %s\nDigest nachher: %s\n' "$digest_before" "$digest_after"
oc get replicaset -l app=hello-s2i --sort-by=.metadata.creationTimestamp
host_name=$(oc get route hello-s2i -o jsonpath='{.spec.host}')
curl "http://$host_name"

10 ConfigChange richtig einordnen

Ein Kubernetes-Deployment braucht keinen eigenen ConfigChange-Trigger. Jede Änderung an seiner Pod-Vorlage erzeugt von sich aus einen neuen Rollout.

oc set env deployment/hello-s2i LAB_CONFIG=v2
oc rollout status deployment/hello-s2i --timeout=120s
oc get replicaset -l app=hello-s2i --sort-by=.metadata.creationTimestamp
oc get deployment hello-s2i -o jsonpath='{.spec.template.spec.containers[0].env}{"\n"}'

oc set env ändert spec.template. Der Hash der Vorlage ändert sich und das Deployment erzeugt ein weiteres ReplicaSet. Genau das meint die ConfigChange-Wirkung bei einem Kubernetes-Deployment.

oc set triggers deployment/hello-s2i --from-image=hello-s2i:latest -c hello-s2i --remove
oc set triggers deployment/hello-s2i
oc get deployment hello-s2i -o jsonpath='{.metadata.annotations.image\.openshift\.io/triggers}{"\n"}'

11 Dateien, Ressourcen und Besitz

12 Fehler an der Übergabe eingrenzen

13 Lab vollständig aufräumen

oc delete project build-rollout-lab
Remove-Item -Recurse -LiteralPath .\s2i-src

oc delete project build-rollout-lab
rm -rf -- ./s2i-src

Das Projekt löscht die angelegten Ressourcen und die erzeugten Build- sowie Rollout-Objekte gemeinsam. Der Builder in der externen Registry und OpenShift-Systemkomponenten bleiben unverändert.

14 Lernkontrolle

• Ich kann erklären, welche Arbeit assemble und run übernehmen.
• Ich kann Tag und Digest unterscheiden und beide am ImageStreamTag finden.
• Ich kann die Besitzkette Deployment, ReplicaSet und Pod über ownerReferences belegen.
• Ich kann zeigen, wo OpenShift den Image-Trigger an einem Kubernetes-Deployment speichert.
• Ich kann erklären, warum eine Pod-Vorlagenänderung rollt, eine externe ConfigMap-Änderung allein aber nicht.
• Ich kann für Build- und Rolloutfehler die richtige Übergabe zuerst prüfen.