Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 9: API-Versionen und Conversion

Ziel: Die StaticSite bekommt eine stabile Version v1 (Feld contentFrom heißt dort source), wird Storage-Version, und ein Conversion-Webhook übersetzt verlustfrei zwischen v1alpha1 und v1 – inklusive Migration der gespeicherten Objekte · Dauer: ca. 150 min · Voraussetzung: Tag 8

Briefing

  • Eine CRD kann mehrere Versionen ausliefern (served), aber nur in einer speichern (storage). Alles andere wird beim Lesen und Schreiben konvertiert.
  • Ohne Webhook (strategy: None) tauscht der API-Server nur apiVersion aus – umbenannte Felder gehen dabei verloren.
  • Hub & Spoke: Eine Version ist der Hub (Hub()), jede andere Spoke mit ConvertTo/ConvertFrom. Bei n Versionen brauchst du n-1 Paare, nicht n².
  • status.storedVersions merkt sich jede Version, die je in etcd lag. Eine alte Version entfernst du erst nach der Migration.
kubectl get ...v1alpha1...           kubectl get ...v1...
        |                                   |
   v1alpha1 (Spoke)  <-- ConvertFrom --  v1 (Hub, storage)  <--> etcd
                     --- ConvertTo  -->
             POST /convert  (Conversion-Webhook im Operator)

Drill 1: Version v1 anlegen

source ~/op-lab/env.sh
cp -r ~/op-lab/tag08-site-operator ~/op-lab/tag09-site-operator
cd ~/op-lab/tag09-site-operator
kubebuilder create api --group web --version v1 --kind StaticSite \
  --resource --controller=false

Erwartet (gekürzt):

Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests

Kubebuilder hat api/v1/ angelegt und in cmd/main.go webv1.AddToScheme ergänzt. --controller=false: Es bleibt ein Controller – er arbeitet ab Drill 5 mit v1.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die v1-Typen

v1 ist v1alpha1 mit einem umbenannten Feld und dem Marker storageversion. Statt 100 Zeilen abzutippen, leitest du die Datei ab und lässt dir den Unterschied zeigen – genau dieser Diff ist deine API-Änderung:

sed -e 's/^package v1alpha1/package v1/' \
    -e 's/ExactlyOneOf=content;contentFrom/ExactlyOneOf=content;source/' \
    -e 's/ContentFrom \*ContentSource/Source *ContentSource/' \
    -e 's/json:"contentFrom,omitempty"/json:"source,omitempty"/' \
    -e 's/zu contentFrom)/zu source)/; s|// contentFrom verweist|// source verweist|' \
    -e 's|^// +kubebuilder:subresource:status|&\n// +kubebuilder:storageversion|' \
    api/v1alpha1/staticsite_types.go > api/v1/staticsite_types.go
sed 's/^package v1alpha1/package v1/' api/v1alpha1/conditions.go > api/v1/conditions.go
gofmt -l api/
diff api/v1alpha1/staticsite_types.go api/v1/staticsite_types.go

Erwartet:

1c1
< package v1alpha1
---
> package v1
24c24
< // +kubebuilder:validation:ExactlyOneOf=content;contentFrom
---
> // +kubebuilder:validation:ExactlyOneOf=content;source
26c26
<   // content ist der HTML-Inhalt der Seite (alternativ zu contentFrom).
---
>   // content ist der HTML-Inhalt der Seite (alternativ zu source).
31c31
<   // contentFrom verweist auf eine vorhandene ConfigMap (alternativ zu content).
---
>   // source verweist auf eine vorhandene ConfigMap (alternativ zu content).
33c33
<   ContentFrom *ContentSource `json:"contentFrom,omitempty"`
---
>   Source *ContentSource `json:"source,omitempty"`
77a78
> // +kubebuilder:storageversion

Die alte Version bekommt einen Deprecation-Hinweis. In api/v1alpha1/staticsite_types.go direkt unter // +kubebuilder:subresource:status:

// +kubebuilder:deprecatedversion:warning="v1alpha1 ist veraltet, nutze v1"
make manifests generate
grep -E '^    (name|served|storage|deprecat)' \
  config/crd/bases/web.lab.example_staticsites.yaml

Erwartet (gekürzt):

    name: v1
    served: true
    storage: true
    deprecated: true
    deprecationWarning: v1alpha1 ist veraltet, nutze v1
    name: v1alpha1
    served: true
    storage: false

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ohne Conversion geht etwas verloren

Simuliere einen Cluster, in dem schon StaticSites von gestern liegen. Terminal 1 mit der CRD von Tag 8:

source ~/op-lab/env.sh
envtest-up --crds ~/op-lab/tag08-site-operator/config/crd/bases

Terminal 2: zwei Altobjekte anlegen, dann die neue CRD einspielen – noch ohne Webhook:

kubectl apply -f lab/demo.yaml -f lab/extern.yaml
kubectl replace -f config/crd/bases/
kubectl get crd staticsites.web.lab.example \
  -o jsonpath='{.status.storedVersions}{"\n"}'
kubectl get staticsites.v1.web.lab.example extern -o jsonpath='{.spec}{"\n"}'

Erwartet:

staticsite.web.lab.example/demo created
staticsite.web.lab.example/extern created
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example replaced
["v1alpha1","v1"]
{"image":"nginxinc/nginx-unprivileged:1.31-alpine","path":"/","replicas":1}

extern zeigt als v1 gelesen keine Quelle mehr: contentFrom ist im v1-Schema unbekannt und wird weggeschnitten (Pruning). Noch steht es in etcd – aber der erste Schreibzugriff über v1 würde es endgültig löschen. Genau dafür gibt es den Conversion-Webhook.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Hub und Spoke

kubebuilder create webhook --group web --version v1 --kind StaticSite \
  --conversion --spoke v1alpha1
cat api/v1/staticsite_conversion.go | grep -v '^//' | grep .

Erwartet (gekürzt):

package v1
func (*StaticSite) Hub() {}

Der Hub ist fertig. Kubebuilder hat außerdem internal/webhook/v1/ (Webhook-Server für /convert), den Aufruf in cmd/main.go und den Patch config/crd/patches/webhook_in_staticsites.yaml (Strategie Webhook) angelegt. Die eigentliche Arbeit steckt im Spoke:

cat > api/v1alpha1/staticsite_conversion.go <<'EOF'
package v1alpha1

import (
    "sigs.k8s.io/controller-runtime/pkg/conversion"

    webv1 "example.com/site-operator/api/v1"
)

// ConvertTo wandelt diese Spoke-Version (v1alpha1) in den Hub (v1).
func (src *StaticSite) ConvertTo(dstRaw conversion.Hub) error {
    dst := dstRaw.(*webv1.StaticSite)
    dst.ObjectMeta = src.ObjectMeta
    dst.Spec = webv1.StaticSiteSpec{
        Content:  src.Spec.Content,
        Replicas: src.Spec.Replicas,
        Image:    src.Spec.Image,
        Path:     src.Spec.Path,
    }
    if from := src.Spec.ContentFrom; from != nil { // contentFrom -> source
        dst.Spec.Source = &webv1.ContentSource{}
        if from.ConfigMapRef != nil {
            dst.Spec.Source.ConfigMapRef = &webv1.ConfigMapReference{
                Name: from.ConfigMapRef.Name}
        }
    }
    dst.Status = webv1.StaticSiteStatus(src.Status) // identische Felder
    return nil
}

// ConvertFrom wandelt den Hub (v1) zurück in v1alpha1.
func (dst *StaticSite) ConvertFrom(srcRaw conversion.Hub) error {
    src := srcRaw.(*webv1.StaticSite)
    dst.ObjectMeta = src.ObjectMeta
    dst.Spec = StaticSiteSpec{
        Content:  src.Spec.Content,
        Replicas: src.Spec.Replicas,
        Image:    src.Spec.Image,
        Path:     src.Spec.Path,
    }
    if s := src.Spec.Source; s != nil { // source -> contentFrom
        dst.Spec.ContentFrom = &ContentSource{}
        if s.ConfigMapRef != nil {
            dst.Spec.ContentFrom.ConfigMapRef = &ConfigMapReference{
                Name: s.ConfigMapRef.Name}
        }
    }
    dst.Status = StaticSiteStatus(src.Status)
    return nil
}
EOF

webv1.StaticSiteStatus(src.Status) ist eine Go-Typkonvertierung: Sie klappt, solange beide Structs exakt dieselben Felder haben – ändert sich der Status in einer Version, meldet der Compiler das sofort.

Der wichtigste Test für jede Conversion ist der Round-Trip Spoke → Hub → Spoke:

cat > api/v1alpha1/staticsite_conversion_test.go <<'EOF'
package v1alpha1

import (
    "testing"

    "k8s.io/apimachinery/pkg/api/equality"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"

    webv1 "example.com/site-operator/api/v1"
)

// Spoke -> Hub -> Spoke muss verlustfrei sein, sonst verliert jedes
// Lesen über die andere Version Daten.
func TestRoundTrip(t *testing.T) {
    ref := &ConfigMapReference{Name: "html"}
    tests := map[string]StaticSiteSpec{
        "content":      {Content: "<h1>Hallo</h1>", Replicas: 2, Path: "/docs/"},
        "contentFrom":  {ContentFrom: &ContentSource{ConfigMapRef: ref}},
        "leere Quelle": {ContentFrom: &ContentSource{}},
    }
    for name, spec := range tests {
        t.Run(name, func(t *testing.T) {
            in := &StaticSite{ObjectMeta: metav1.ObjectMeta{Name: "rt"}, Spec: spec}
            in.Status.URL = "http://rt.default.svc"
            hub := &webv1.StaticSite{}
            if err := in.ConvertTo(hub); err != nil {
                t.Fatal(err)
            }
            out := &StaticSite{}
            if err := out.ConvertFrom(hub); err != nil {
                t.Fatal(err)
            }
            if !equality.Semantic.DeepEqual(in, out) {
                t.Errorf("Round-Trip verändert:\n in %+v\nout %+v", in.Spec, out.Spec)
            }
        })
    }
}
EOF
go test ./api/... -run RoundTrip -v 2>&1 | grep -E '^(---|    ---|ok)'

Erwartet:

--- PASS: TestRoundTrip (0.00s)
    --- PASS: TestRoundTrip/content (0.00s)
    --- PASS: TestRoundTrip/contentFrom (0.00s)
    --- PASS: TestRoundTrip/leere_Quelle (0.00s)
ok      example.com/site-operator/api/v1alpha1  0.153s

Warum der Fall „leere Quelle”? Die naheliegende Kurzform if from != nil && from.ConfigMapRef != nil macht aus contentFrom: {} beim Rückweg nil:

--- FAIL: TestRoundTrip (0.00s)
    --- FAIL: TestRoundTrip/leere_Quelle (0.00s)
        staticsite_conversion_test.go:34: Round-Trip verändert:
             in {Content: ContentFrom:0x5482827ac3b8 Replicas:0 Image: Path:}
            out {Content: ContentFrom:<nil> Replicas:0 Image: Path:}

Solche Kleinigkeiten führen im Cluster zu Endlos-Diffs bei GitOps-Tools.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Der Controller arbeitet mit dem Hub

Der Operator soll nur noch eine Version kennen: die Storage-Version v1. Alte Clients dürfen weiter v1alpha1 schicken – der API-Server konvertiert, bevor dein Informer das Objekt sieht.

OLD='webv1alpha1 "example.com/site-operator/api/v1alpha1"'
NEW='webv1 "example.com/site-operator/api/v1"'
sed -i '' -e "s#$OLD#$NEW#" \
  -e 's/webv1alpha1\./webv1./g; s/ContentFrom/Source/g' \
  -e 's/spec\.contentFrom\./spec.source./g; s/contentFrom/source/g' \
  internal/controller/*.go
grep -l 'v1alpha1' internal/controller/*.go
go vet ./... && go test ./internal/controller/ -count=1 2>&1 | tail -1

Erwartet:

ok      example.com/site-operator/internal/controller   13.032s

grep -l findet nichts mehr: Controller, Status, Finalizer und alle Controller-Tests (inklusive der CEL-Tabelle von Tag 8) sprechen jetzt v1. Die Admission-Webhooks aus Tag 8 bleiben auf v1alpha1 – der API-Server konvertiert auch für sie (matchPolicy: Equivalent).

Achtung: sed -i '' ist die macOS-Syntax. Unter Linux heißt es sed -i ohne die leeren Anführungszeichen.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Conversion in envtest

Envtest richtet den Conversion-Webhook selbst ein – aber nur für Typen, die im Scheme als konvertierbar erkennbar sind, also wenn beide Versionen registriert sind. Und weil alle Webhook-Konfigurationen aus config/webhook/ geladen werden, müssen in jeder Suite auch alle Handler laufen.

In internal/webhook/v1/webhook_suite_test.go (Imports webv1alpha1 ".../api/v1alpha1" und webhookv1alpha1 ".../internal/webhook/v1alpha1" ergänzen):

    err = webv1.AddToScheme(scheme.Scheme)
    Expect(err).NotTo(HaveOccurred())
    Expect(webv1alpha1.AddToScheme(scheme.Scheme)).To(Succeed())
    // ...
    err = SetupStaticSiteWebhookWithManager(mgr)
    Expect(err).NotTo(HaveOccurred())
    Expect(webhookv1alpha1.SetupStaticSiteWebhookWithManager(mgr)).To(Succeed())

Spiegelbildlich in internal/webhook/v1alpha1/webhook_suite_test.go (Imports webv1 ".../api/v1" und webhookv1 ".../internal/webhook/v1"):

    Expect(webv1.AddToScheme(scheme.Scheme)).To(Succeed())
    // ...
    Expect(webhookv1.SetupStaticSiteWebhookWithManager(mgr)).To(Succeed())

Drei Specs: beide Richtungen und die Deprecation-Warnung.

cat > internal/webhook/v1/staticsite_webhook_test.go <<'EOF'
package v1

import (
    "context"

    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
    "k8s.io/client-go/rest"
    "sigs.k8s.io/controller-runtime/pkg/client"

    webv1 "example.com/site-operator/api/v1"
    webv1alpha1 "example.com/site-operator/api/v1alpha1"
)

var _ = Describe("Conversion im API-Server", func() {
    meta := func(name string) metav1.ObjectMeta {
        return metav1.ObjectMeta{Name: name, Namespace: "default"}
    }

    It("liest ein v1alpha1-Objekt als v1", func() {
        old := &webv1alpha1.StaticSite{ObjectMeta: meta("alt"),
            Spec: webv1alpha1.StaticSiteSpec{ContentFrom: &webv1alpha1.ContentSource{
                ConfigMapRef: &webv1alpha1.ConfigMapReference{Name: "html"}}}}
        Expect(k8sClient.Create(ctx, old)).To(Succeed())

        hub := &webv1.StaticSite{}
        Expect(k8sClient.Get(ctx, client.ObjectKeyFromObject(old), hub)).To(Succeed())
        Expect(hub.Spec.Source.ConfigMapRef.Name).To(Equal("html"))
    })

    It("liest ein v1-Objekt als v1alpha1", func() {
        neu := &webv1.StaticSite{ObjectMeta: meta("neu"),
            Spec: webv1.StaticSiteSpec{Source: &webv1.ContentSource{
                ConfigMapRef: &webv1.ConfigMapReference{Name: "html"}}}}
        Expect(k8sClient.Create(ctx, neu)).To(Succeed())

        spoke := &webv1alpha1.StaticSite{}
        Expect(k8sClient.Get(ctx, client.ObjectKeyFromObject(neu), spoke)).
            To(Succeed())
        Expect(spoke.Spec.ContentFrom.ConfigMapRef.Name).To(Equal("html"))
        Expect(spoke.Spec.Path).To(Equal("/")) // Default aus dem v1-Schema
    })

    It("warnt bei Nutzung von v1alpha1", func() {
        var got warnings
        cfgW := rest.CopyConfig(cfg)
        cfgW.WarningHandlerWithContext = &got
        c, err := client.New(cfgW, client.Options{Scheme: k8sClient.Scheme()})
        Expect(err).NotTo(HaveOccurred())
        Expect(c.Get(ctx, client.ObjectKey{Namespace: "default", Name: "neu"},
            &webv1alpha1.StaticSite{})).To(Succeed())
        Expect(got).To(ContainElement("v1alpha1 ist veraltet, nutze v1"))
    })
})

// warnings sammelt Warning-Header des API-Servers.
type warnings []string

func (w *warnings) HandleWarningHeaderWithContext(_ context.Context, _ int,
    _ string, text string) {
    *w = append(*w, text)
}
EOF
go test ./internal/webhook/... -count=1 -v -ginkgo.no-color \
  2>&1 | grep -E '^(Ran|SUCCESS|FAIL|ok)'

Erwartet:

Ran 3 of 3 Specs in 5.315 seconds
SUCCESS! -- 3 Passed | 0 Failed | 0 Pending | 0 Skipped
ok      example.com/site-operator/internal/webhook/v1   5.687s
Ran 7 of 7 Specs in 5.006 seconds
SUCCESS! -- 7 Passed | 0 Failed | 0 Pending | 0 Skipped
ok      example.com/site-operator/internal/webhook/v1alpha1 5.690s

Der zweite Spec zeigt nebenbei: Das Default path: / kommt aus dem v1-Schema und überlebt den Weg zurück nach v1alpha1.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Live – Webhook einschalten und migrieren

Zurück zu den Altobjekten aus Drill 3 (Terminal 1 läuft noch). Im Cluster würde kustomize den Patch aus config/crd/patches/ anwenden und cert-manager das CA-Bundle eintragen. Gegen envtest-up machst du beides von Hand – mit dem Lab-Zertifikat aus Tag 8 (lab/certs kam mit cp -r mit):

kubectl apply -f lab/webhooks-local.yaml
CA=$(base64 < lab/certs/tls.crt | tr -d '\n')
kubectl patch crd staticsites.web.lab.example --type=merge -p '{"spec":{"conversion":{
  "strategy":"Webhook","webhook":{"conversionReviewVersions":["v1"],
  "clientConfig":{"url":"https://127.0.0.1:9443/convert","caBundle":"'"$CA"'"}}}}}'

Erwartet (gekürzt):

customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example patched

Terminal 3: Operator starten – er bedient jetzt auch /convert:

cd ~/op-lab/tag09-site-operator
go run ./cmd/main.go -health-probe-bind-address=0 --webhook-cert-path=lab/certs \
  2>&1 | tee run.log

Terminal 2: dasselbe Objekt in beiden Versionen lesen:

kubectl get staticsites.v1.web.lab.example extern -o jsonpath='{.spec.source}{"\n"}'
kubectl get staticsites.v1alpha1.web.lab.example extern \
  -o jsonpath='{.spec.contentFrom}{"\n"}'
kubectl get site

Erwartet:

{"configMapRef":{"name":"extern-html"}}
Warning: v1alpha1 ist veraltet, nutze v1
{"configMapRef":{"name":"extern-html"}}
NAME     READY   AVAILABLE   URL                         AGE
demo             False       http://demo.default.svc     11m
extern           False       http://extern.default.svc   11m

Die Quelle ist wieder da – sie lag die ganze Zeit als v1alpha1 in etcd, der Webhook übersetzt beim Lesen. Jetzt die Storage-Migration: Jedes Objekt einmal lesen und unverändert zurückschreiben, dann liegt es als v1 in etcd. Erst danach darf v1alpha1 aus storedVersions verschwinden:

kubectl get staticsites.v1.web.lab.example -A -o json | kubectl replace -f -
kubectl patch crd staticsites.web.lab.example --subresource=status --type=merge \
  -p '{"status":{"storedVersions":["v1"]}}'
kubectl get crd staticsites.web.lab.example \
  -o jsonpath='{.status.storedVersions}{"\n"}'

Erwartet:

staticsite.web.lab.example/demo replaced
Warning: ConfigMap extern-html fehlt (noch)
staticsite.web.lab.example/extern replaced
customresourcedefinition.apiextensions.k8s.io/staticsites.web.lab.example patched
["v1"]

Die Warnung stammt aus deinem Validating-Webhook von Tag 8 – auch ein replace ist ein Update und läuft durch die ganze Admission-Kette.

Achtung: Reihenfolge ist alles. storedVersions zu kürzen, bevor alle Objekte umgeschrieben sind, lässt Objekte zurück, die keiner mehr lesen kann, sobald v1alpha1 aus der CRD entfernt wird.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/op-lab/tag09-site-operator
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
CRD=config/crd/bases/web.lab.example_staticsites.yaml
go test ./... -count=1 2>&1 | grep -q FAIL && nok "Tests" || ok "Tests grün"
grep -A1 'name: v1$' -m1 $CRD >/dev/null && grep -q 'storage: true' $CRD \
  && ok "v1 in der CRD" || nok "v1 fehlt"
grep -q 'func (\*StaticSite) Hub()' api/v1/staticsite_conversion.go \
  && ok "v1 ist Hub" || nok "Hub fehlt"
kubectl get staticsites.v1.web.lab.example extern -o jsonpath='{.spec.source}' \
  | grep -q extern-html && ok "Conversion live" || nok "Conversion (Operator?)"
kubectl get crd staticsites.web.lab.example -o jsonpath='{.status.storedVersions}' \
  | grep -qx '\["v1"\]' && ok "Migration abgeschlossen" || nok "storedVersions"

Erwartet:

✔ Tests grün
✔ v1 in der CRD
✔ v1 ist Hub
✔ Conversion live
✔ Migration abgeschlossen

Danach Operator und envtest-up beenden.

Challenge

v1 bekommt ein neues, optionales Feld spec.title (max. 200 Zeichen), das v1alpha1 nicht kennt. Sorge dafür, dass ein Titel den Weg Hub → Spoke → Hub übersteht, und beweise es mit einem Test.

Hinweis: Was der Spoke nicht als Feld kennt, parkt er in einer Annotation (web.lab.example/v1-title) – und ConvertTo holt es zurück und entfernt die Annotation wieder.

Lösung

In api/v1/staticsite_types.go am Ende von StaticSiteSpec:

    // title ist der Seitentitel (neu in v1).
    // +kubebuilder:validation:MaxLength=200
    // +optional
    Title string `json:"title,omitempty"`

In api/v1alpha1/staticsite_conversion.go (Import "maps"): eine Konstante und je ein Block am Ende von ConvertTo und ConvertFrom:

// titleAnnotation parkt v1-Felder, die v1alpha1 nicht kennt.
const titleAnnotation = "web.lab.example/v1-title"

    // ConvertTo, vor return nil:
    if t, ok := src.Annotations[titleAnnotation]; ok { // v1-Feld zurückholen
        dst.Spec.Title = t
        dst.Annotations = maps.Clone(src.Annotations)
        delete(dst.Annotations, titleAnnotation)
    }

    // ConvertFrom, vor return nil:
    if src.Spec.Title != "" { // v1alpha1 kennt title nicht: parken
        dst.Annotations = maps.Clone(src.Annotations)
        if dst.Annotations == nil {
            dst.Annotations = map[string]string{}
        }
        dst.Annotations[titleAnnotation] = src.Spec.Title
    }

maps.Clone ist wichtig: dst.ObjectMeta = src.ObjectMeta teilt sich die Map mit dem Quellobjekt – ohne Kopie würdest du das Hub-Objekt nebenbei verändern.

cat >> api/v1alpha1/staticsite_conversion_test.go <<'EOF'

// Hub -> Spoke -> Hub: Das neue Feld title überlebt in einer Annotation.
func TestRoundTripHub(t *testing.T) {
    in := &webv1.StaticSite{ObjectMeta: metav1.ObjectMeta{Name: "rt"},
        Spec: webv1.StaticSiteSpec{Content: "<h1>x</h1>", Title: "Willkommen"}}
    spoke := &StaticSite{}
    if err := spoke.ConvertFrom(in); err != nil {
        t.Fatal(err)
    }
    out := &webv1.StaticSite{}
    if err := spoke.ConvertTo(out); err != nil {
        t.Fatal(err)
    }
    if !equality.Semantic.DeepEqual(in, out) {
        t.Errorf("Round-Trip verändert:\n in %+v\nout %+v", in, out)
    }
    if in.Annotations != nil {
        t.Errorf("Hub-Objekt verändert: %v", in.Annotations)
    }
}
EOF
make manifests generate
go test ./api/... -run RoundTrip -v 2>&1 | grep -E '^(---|ok)'

Erwartet:

--- PASS: TestRoundTrip (0.00s)
--- PASS: TestRoundTripHub (0.00s)
ok      example.com/site-operator/api/v1alpha1  0.163s

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Versionen sind Versprechen: v1alpha1 darf brechen, v1 nicht. Neue Felder in v1 nur optional, Umbenennungen nur über eine neue Version mit Conversion.
  • Der Conversion-Webhook liegt im Lesepfad jedes Zugriffs auf ältere Versionen – auch für kubectl get und für andere Controller. Er braucht HA (≥ 2 Replicas, PDB) wie ein Admission-Webhook, sonst ist die ganze API der CRD weg.
  • Migration im Cluster: wie in Drill 7, bei vielen Objekten paginiert – oder mit dem kube-storage-version-migrator. Erst danach storedVersions kürzen, dann served: false, erst im nächsten Release die alte Version entfernen.
  • Helm, Argo CD und Flux kennen die alte Version weiter, wenn Manifeste sie noch enthalten: Charts und Repos vor dem Abschalten umstellen (die Deprecation-Warnung hilft beim Finden).
  • Round-Trip-Tests für jede Spoke-Version in die CI; fuzzing-basierte Tests (k8s.io/apimachinery/pkg/api/apitesting/roundtrip) finden verlorene Felder systematisch.