Міграція обʼєктів Kubernetes за допомогою міграції версій сховища

Міграція обʼєктів Kubernetes за допомогою міграції версій сховища

СТАН ФУНКЦІОНАЛУ: Beta since Kubernetes v1.35; (стандартно вимкнено)
More information about this feature

To use this feature, you (or a cluster administrator) will need to enable the StorageVersionMigrator feature gate for all relevant components in your cluster.

See Enable Or Disable Feature Gates for more information.

Kubernetes покладається на активне переписування даних API для підтримки деяких операцій обслуговування, повʼязаних зі зберіганням у стані спокою. Два помітні приклади — версійна схема збережених ресурсів (тобто зміна бажаної схеми зберігання з v1 на v2 для певного ресурсу) та шифрування у стані спокою (тобто перезапис застарілих даних через зміну способу шифрування даних).

Виконання міграції версій сховища гарантує, що всі обʼєкти ресурсу перенесено із застарілої версії сховища. Вимога до виконання міграції сховища — ресурс повинен мати цілочисельну версію ресурсу. Усі ресурси Kubernetes і CRD гарантовано мають цю властивість, але міграція завершиться збоєм, якщо це не так, наприклад для агрегованих API.

Перш ніж ви розпочнете

Встановіть kubectl.

Вам треба мати кластер Kubernetes, а також інструмент командного рядка kubectl має бути налаштований для роботи з вашим кластером. Рекомендується виконувати ці настанови у кластері, що має щонайменше два вузли, які не виконують роль вузлів управління. Якщо у вас немає кластера, ви можете створити його, за допомогою minikube або використовувати одну з цих пісочниць:

Версія вашого Kubernetes сервера має бути не старішою ніж v1.30.

Для перевірки версії введіть kubectl version.

Функціональна можливість StorageVersionMigrator та REST API storagemigration.k8s.io/v1 стандартно увімкнені в усіх кластерах.

Повторне шифрування Secrets Kubernetes за допомогою міграції версій сховища

  • Спочатку налаштуйте постачальника KMS для шифрування даних у стані спокою в etcd за допомогою такої конфігурації шифрування.

    kind: EncryptionConfiguration
    apiVersion: apiserver.config.k8s.io/v1
    resources:
    - resources:
      - secrets
      providers:
      - aescbc:
          keys:
          - name: key1
            secret: c2VjcmV0IGlzIHNlY3VyZQ==
    

    Обовʼязково увімкніть автоматичне перезавантаження файлу конфігурації шифрування, встановивши --encryption-provider-config-automatic-reload у true.

  • Створіть Secret за допомогою kubectl.

    kubectl create secret generic my-secret --from-literal=key1=supersecret
    
  • Перевірте, що серіалізовані дані цього обʼєкта Secret починаються з k8s:enc:aescbc:v1:key1.

  • Оновіть файл конфігурації шифрування таким чином, щоб виконати ротацію ключа шифрування.

    kind: EncryptionConfiguration
    apiVersion: apiserver.config.k8s.io/v1
    resources:
    - resources:
      - secrets
      providers:
      - aescbc:
          keys:
          - name: key2
            secret: c2VjcmV0IGlzIHNlY3VyZSwgaXMgaXQ/
      - aescbc:
          keys:
          - name: key1
            secret: c2VjcmV0IGlzIHNlY3VyZQ==
    
  • Щоб забезпечити повторне шифрування раніше створеного Secret my-secret новим ключем key2, ви використаєте Storage Version Migration.

  • Створіть маніфест StorageVersionMigration з назвою migrate-secret.yaml з таким вмістом:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: secrets-migration
    spec:
      resource:
        group: ""
        resource: secrets
    

    Створіть обʼєкт за допомогою kubectl таким чином:

    kubectl apply -f migrate-secret.yaml
    
  • Стежте за міграцією Secrets, перевіряючи .status обʼєкта StorageVersionMigration. Успішна міграція повинна мати стан Succeeded зі значенням true. Отримайте обʼєкт StorageVersionMigration таким чином:

    kubectl wait --for=condition=Succeeded storageversionmigration.storagemigration.k8s.io/secrets-migration
    

    Вивід подібний до такого:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: secrets-migration
      uid: 628f6922-a9cb-4514-b076-12d3c178967c
      resourceVersion: "90"
      creationTimestamp: "2024-03-12T20:29:45Z"
    spec:
      resource:
        group: ""
        resource: secrets
    status:
      conditions:
      - type: Running
        status: "False"
        lastUpdateTime: "2024-03-12T20:29:46Z"
        reason: StorageVersionMigrationInProgress
      - type: Succeeded
        status: "True"
        lastUpdateTime: "2024-03-12T20:29:46Z"
        reason: StorageVersionMigrationSucceeded
      resourceVersion: "84"
    
  • Перевірте, що збережений Secret тепер починається з k8s:enc:aescbc:v1:key2.

Оновлення бажаної схеми зберігання CRD

Розгляньмо сценарій, у якому CustomResourceDefinition (CRD) створено для обслуговування власних ресурсів (CR) і встановлено як бажану схему зберігання. Коли настане час ввести v2 CRD, її можна додати лише для обслуговування за допомогою вебхука конвертації. Це забезпечує плавніший перехід, за якого користувачі можуть створювати CR за схемою v1 або v2, а вебхук виконує потрібну конвертацію схеми між ними. Перш ніж встановити v2 як бажану версію схеми зберігання, важливо переконатися, що всі наявні CR, збережені як v1, мігровано на v2. Цю міграцію можна виконати за допомогою Storage Version Migration, щоб перенести всі CR з v1 на v2.

  • Створіть маніфест для CRD з назвою test-crd.yaml з таким вмістом:

    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: selfierequests.example.com
    spec:
      group: example.com
      names:
        plural: selfierequests
        singular: selfierequest
        kind: SelfieRequest
        listKind: SelfieRequestList
      scope: Namespaced
      versions:
      - name: v1
        served: true
        storage: true
        schema:
          openAPIV3Schema:
            type: object
            properties:
              hostPort:
                type: string
      conversion:
        strategy: Webhook
        webhook:
          clientConfig:
            url: "https://127.0.0.1:9443/crdconvert"
            caBundle: <CABundle info>
        conversionReviewVersions:
        - v1
        - v2
    

    Збережена версія на цей момент має бути v1, переконайтеся в цьому, виконавши:

    kubectl get crd selfierequests.example.com -o jsonpath='{.spec.versions[?(@.storage==true)].name}'
    

    Створіть CRD за допомогою kubectl:

    kubectl apply -f test-crd.yaml
    
  • Створіть маніфест для прикладу testcrd. Назвіть маніфест cr1.yaml і використайте такий вміст:

    apiVersion: example.com/v1
    kind: SelfieRequest
    metadata:
      name: cr1
      namespace: default
    

    Створіть CR за допомогою kubectl:

    kubectl apply -f cr1.yaml
    
  • Перевірте, що CR записано і збережено як v1, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr1 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Оновіть CRD test-crd.yaml, щоб додати версію v2 для обслуговування й зберігання, а v1 залишити лише для обслуговування, таким чином:

    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: selfierequests.example.com
    spec:
      group: example.com
      names:
        plural: selfierequests
        singular: selfierequest
        kind: SelfieRequest
        listKind: SelfieRequestList
      scope: Namespaced
      versions:
        - name: v2
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                host:
                  type: string
                port:
                  type: string
        - name: v1
          served: true
          storage: false
          schema:
            openAPIV3Schema:
              type: object
              properties:
                hostPort:
                  type: string
      conversion:
        strategy: Webhook
        webhook:
          clientConfig:
            url: "https://127.0.0.1:9443/crdconvert"
            caBundle: <CABundle info>
          conversionReviewVersions:
            - v1
            - v2
    

    Збережена версія тепер має бути v2, переконайтеся в цьому:

    kubectl get crd selfierequests.example.com -o jsonpath='{.spec.versions[?(@.storage==true)].name}'
    

    Оновіть CRD за допомогою kubectl:

    kubectl apply -f test-crd.yaml
    
  • Створіть файл ресурсу CR з назвою cr2.yaml з таким вмістом:

    apiVersion: example.com/v2
    kind: SelfieRequest
    metadata:
      name: cr2
      namespace: default
    
  • Створіть CR за допомогою kubectl:

    kubectl apply -f cr2.yaml
    
  • Перевірте, що CR записано і збережено як v2, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr2 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Створіть маніфест StorageVersionMigration з назвою migrate-crd.yaml з таким вмістом:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: crdsvm
    spec:
      resource:
        group: example.com
        resource: selfierequests
    

    Створіть обʼєкт за допомогою kubectl таким чином:

    kubectl apply -f migrate-crd.yaml
    
  • Стежте за міграцією Secrets за допомогою статусу. Успішна міграція повинна мати стан Succeeded зі значенням "True" у полі статусу. Отримайте ресурс міграції таким чином:

    kubectl get storageversionmigration.storagemigration.k8s.io/crdsvm -o yaml
    

    Вивід подібний до такого:

    kind: StorageVersionMigration
    apiVersion: storagemigration.k8s.io/v1
    metadata:
      name: crdsvm
      uid: 13062fe4-32d7-47cc-9528-5067fa0c6ac8
      resourceVersion: "111"
      creationTimestamp: "2024-03-12T22:40:01Z"
    spec:
      resource:
        group: example.com
        resource: testcrds
    status:
      conditions:
        - type: Running
          status: "False"
          lastUpdateTime: "2024-03-12T22:40:03Z"
          reason: StorageVersionMigrationInProgress
        - type: Succeeded
          status: "True"
          lastUpdateTime: "2024-03-12T22:40:03Z"
          reason: StorageVersionMigrationSucceeded
      resourceVersion: "106"
    
  • Перевірте, що раніше створений cr1 тепер записано й збережено як v2, отримавши обʼєкт з etcd.

    ETCDCTL_API=3 etcdctl get /kubernetes.io/example.com/testcrds/default/cr1 [...] | hexdump -C
    

    де [...] містить додаткові аргументи для зʼєднання із сервером etcd.

  • Також перевірте, що статус збереженої версії CRD тепер лише v2:

    kubectl get crd testcrds.example.com -o yaml
    

    Вивід подібний до такого:

    kind: CustomResourceDefinition
    apiVersion: apiextensions.k8s.io/v1
    metadata:
      name: testcrds.example.com
    spec:
      group: example.com
      names:
        kind: TestCRD
        plural: testcrds
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: false
        - name: v2
          served: true
          storage: true
    status:
      acceptedNames:
        kind: TestCRD
        plural: testcrds
      conditions:
        - type: Established
          status: "True"
      storedVersions:
        - v2