Kubernetes 存储版本迁移功能详解与实践指南

Kubernetes 存储版本迁移功能详解与实践指南

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website

概述

在 Kubernetes 集群的生命周期中，随着系统演进和功能增强，我们经常需要对存储在 etcd 中的 API 对象进行格式转换或重新加密。存储版本迁移（Storage Version Migration）是 Kubernetes 提供的一项重要功能，它允许管理员在不中断服务的情况下，安全地将现有资源对象从旧版本迁移到新版本。

核心概念解析

存储版本迁移的应用场景

1. 加密密钥轮换：当需要更新静态数据加密密钥时，可以安全地将现有数据重新加密
2. API 版本升级：当自定义资源定义(CRD)的存储模式发生变化时，迁移现有资源到新版本
3. 数据结构变更：当资源的数据结构发生重大变化时，确保现有数据与新结构兼容

工作原理

存储版本迁移通过创建 StorageVersionMigration 资源来触发迁移过程。API 服务器会：

1. 识别需要迁移的资源对象
2. 从存储中读取旧版本数据
3. 转换为新版本格式
4. 将新版本数据写回存储
5. 更新迁移状态

整个过程是原子性的，确保数据一致性。

实践指南

准备工作

1. 确保集群版本 >= 1.30
2. 启用相关特性门控：

   --feature-gates=StorageVersionMigrator=true,InformerResourceVersion=true
   

3. 启用存储版本迁移 API：

   --runtime-config=storagemigration.k8s.io/v1alpha1=true
   

场景一：Secret 重新加密

初始配置

1. 创建加密配置文件 encryption-config.yaml：

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

2. 创建测试 Secret：

   kubectl create secret generic my-secret --from-literal=key1=supersecret
   

密钥轮换

1. 更新加密配置，添加新密钥 key2：

   providers:
     - aescbc:
         keys:
           - name: key2
             secret: c2VjcmV0IGlzIHNlY3VyZSwgaXMgaXQ/
           - name: key1
             secret: c2VjcmV0IGlzIHNlY3VyZQ==
   

2. 创建迁移任务：

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

3. 应用迁移：

   kubectl apply -f migrate-secret.yaml
   

4. 监控迁移状态：

   kubectl get storageversionmigration secrets-migration -o yaml
   

场景二：CRD 存储版本升级

初始配置

1. 创建 v1 版本的 CRD：

   apiVersion: apiextensions.k8s.io/v1
   kind: CustomResourceDefinition
   metadata:
     name: selfierequests.stable.example.com
   spec:
     versions:
       - name: v1
         served: true
         storage: true
     conversion:
       strategy: Webhook
       webhook:
         clientConfig:
           url: https://127.0.0.1:9443/crdconvert
   

2. 创建测试 CR：

   kubectl apply -f cr1.yaml
   

版本升级

1. 更新 CRD 添加 v2 版本：

   versions:
     - name: v2
       served: true
       storage: true
     - name: v1
       served: true
       storage: false
   

2. 创建迁移任务：

   kind: StorageVersionMigration
   apiVersion: storagemigration.k8s.io/v1alpha1
   metadata:
     name: crdsvm
   spec:
     resource:
       group: stable.example.com
       version: v1
       resource: SelfieRequest
   

3. 应用并监控迁移：

   kubectl apply -f migrate-crd.yaml
   kubectl get storageversionmigration crdsvm -o yaml
   

最佳实践

1. 备份数据：在执行迁移前，确保对 etcd 数据进行完整备份
2. 分阶段迁移：对于大型集群，考虑按命名空间分批迁移
3. 监控验证：密切监控迁移状态，验证数据完整性
4. 回滚计划：准备详细的回滚方案，应对迁移失败情况
5. 非高峰期操作：选择业务低峰期执行迁移操作

常见问题排查

1. 迁移卡住：

   • 检查 API 服务器日志
   • 验证转换 webhook 是否可用
   • 检查资源配额限制

2. 数据不一致：

   • 比较迁移前后数据校验和
   • 验证 webhook 转换逻辑

3. 性能问题：

   • 考虑限流迁移速率
   • 增加 API 服务器资源

存储版本迁移是 Kubernetes 集群维护中的高级操作，合理使用可以显著提高集群的可维护性和安全性。通过本文的实践指南，管理员可以系统地规划和执行存储版本迁移任务。

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website