Google Distributed Cloud는 VMware vSphere 스토리지, Kubernetes 트리 내 볼륨 플러그인(또는 '드라이버), 컨테이너 스토리지 인터페이스(CSI) 드라이버를 통해 외부 블록 또는 파일 스토리지 시스템과 통합됩니다.
1.15에서는 기본적으로 Kubernetes CSI 마이그레이션 기능이 사용 설정되어 있으므로 트리 내 vSphere 볼륨 플러그인이 지원하는 PersistentVolume이 CSI 전용 환경에서 계속 작동합니다. CSI 마이그레이션 기능은 트리 내 플러그인 작업 호출을 CSI 드라이버로 리디렉션합니다. PersistentVolume 사양은 변경할 수 없으므로 트리 내 플러그인에서 계속 지원됩니다. 사용 가능한 기능은 트리 내 볼륨 플러그인과 동일합니다.
볼륨 확장 및 볼륨 스냅샷과 같은 전체 CSI 기능은 이러한 볼륨에 사용할 수 없습니다. 이러한 기능을 활용하려면 vSphere CSI 드라이버가 지원하는 PersistentVolume을 다시 만들어 스테이트풀(Stateful) 워크로드를 CSI로 완전히 마이그레이션해야 합니다. CSI 마이그레이션 도구를 사용하여 스테이트풀(Stateful) 워크로드를 CSI로 마이그레이션하고 CSI 전체 기능을 사용할 수 있습니다.
이 도구는 StatefulSet의 PersistentVolume 및 PersistentVolumeClaim을 CSI로 순차적으로 마이그레이션하는 방법을 제공하며 애플리케이션 다운타임을 포함하지 않습니다. 이 도구는 로컬 디렉터리에서 Kubernetes 리소스를 백업하고 마이그레이션하기 전에 ReclaimPolicy를 Retain으로 설정합니다. 따라서 데이터 손실이 발생하지 않습니다.
제한사항
자동화 도구는 완전히 지원되는 Google Distributed Cloud 버전에서만 지원됩니다.
StatefulSet에서만 작동합니다. 도구를 사용하여 프리플라이트 검사를 실행하면 도구를 사용하기 전에 몇 가지 안전 확인을 실행할 수 있습니다.
USER_CLUSTER_NAME: StatefulSet가 사용자 클러스터에서 실행 중인 경우 사용자 클러스터 이름을 제공하세요.
워크로드가 관리자 클러스터에서 실행 중이면 이 플래그를 건너뜁니다.
STS_NAME: StatefulSet의 이름
STS_NAMESPACE: StatefulSet의 네임스페이스
INTREE_STORAGECLASS: StatefulSet의 PersistentVolume을 지원하는 트리 내 StorageClass 이름
CSI_STORAGECLASS: 마이그레이션 후 StatefulSet의 PersistentVolume을 지원하는 CSI StorageClass 이름
다운로드
gs://gke-on-prem-release/statefulset-csi-migration-tool/v1.0/statefulset-csi-migration-tool에서 도구를 다운로드합니다.
이 도구는 프리뷰 상태입니다.
절차
이 섹션에서는 vSphere 트리 내 vCP 내부 프로비저닝 도구(kubernetes.io/vsphere-volume)에서 vSphere CSI 프로비저닝 도구(csi.vsphere.vmware.com)로 StatefulSet를 마이그레이션하는 데 필요한 단계를 제공합니다.
USER_CLUSTER_NAME: StatefulSet가 사용자 클러스터에서 실행 중인 경우 사용자 클러스터 이름을 제공하세요.
워크로드가 관리자 클러스터에서 실행 중이면 이 플래그를 건너뜁니다.
STS_NAME: StatefulSet의 이름
STS_NAMESPACE: StatefulSet의 네임스페이스
INTREE_STORAGECLASS: StatefulSet의 PersistentVolume을 지원하는 트리 내 StorageClass 이름
CSI_STORAGECLASS: 마이그레이션 후 StatefulSet의 PersistentVolume을 지원하는 CSI StorageClass 이름
WORKING_DIRECTORY: StatefulSet와 해당 포드, PersistentVolumeClaim, PersistentVolume의 Kubernetes 리소스 사양을 저장할 로컬 디렉터리. 디렉터리 이름은 각 StatefulSet마다 고유해야 합니다. 이 디렉터리는 비어 있거나 존재하지 않아야 합니다.
도구가 자동으로 만들 수 있도록 이 디렉터리를 만들지 않는 것이 좋습니다.
이 명령어는 다음 태스크를 수행합니다.
로컬 작업 디렉터리에서 StatefulSet와 PersistentVolume, PersistentVolumeClaim, 포드 복제본 사양과 같은 종속 항목을 백업합니다.
분리된 항목 삭제 정책으로 StatefulSet를 삭제합니다. 이 단계에서는 StatefulSet만 삭제하고 포드 복제본, PersistentVolume, PersistentVolumeClaim과 같은 종속 항목은 삭제하지 않습니다.
각 포드를 CSI 드라이버로 마이그레이션하고(옵션 1과 유사) 다음을 수행합니다.
a. PersistentVolume의 ReclaimPolicy 필드를 Retain으로 설정합니다.
b. 포드, PersistentVolume, PersistentVolumeClaim을 삭제합니다.
c. 기존 VMDK를 FCD로 변환합니다.
d. PersistentVolume, PersistentVolumeClaim, 포드를 다시 만듭니다.
StatefulSet를 다시 만들지만 사양의 PVCTemplate 필드는 CSI StorageClass를 가리킵니다. StatefulSet 컨트롤러는 분리된 복제본에 다시 매핑되어야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["This document explains how to use the StatefulSet CSI Migration Tool to\nmigrate stateful workloads from an in-tree vSphere volume plugin to the vSphere\nCSI Driver in Google Distributed Cloud.\n\nThe following list shows the launch stage for this tool per version:\n\n- v1.0: GA\n- v0.1: [Preview](/products#product-launch-stages)\n\nSupported Google Distributed Cloud versions: 1.30 - 1.28.\n\nOverview\n\nGoogle Distributed Cloud integrates with external block or file storage systems\nthrough VMware vSphere storage, Kubernetes in-tree volume plugins (or\n\"drivers\"), and Container Storage Interface (CSI) drivers.\n\nWith the Kubernetes CSI migration feature enabled by default in 1.15, a\nPersistentVolume backed by the in-tree vSphere volume plugin continues\nfunctioning in a CSI-only environment. The CSI migration feature redirects\nin-tree plugin operation calls to the CSI driver. Because the PersistentVolume\nspec is immutable, it is still backed by the in-tree plugin. The set of\navailable features is the same as for the in-tree volume plugin.\n\nThe full set of CSI features, like Volume Expansion and Volume Snapshot,\nisn't available for such volumes. To take advantage of these features,\nstateful workloads must be completely migrated to CSI by recreating the\nPersistentVolumes backed by the vSphere CSI Driver. You can use the\nCSI migration tool to migrate stateful workloads to CSI and use the full set of\nCSI features.\n\nThis tool provides a way to rolling migrate a StatefulSet's PersistentVolume and\nPersistentVolumeClaim to CSI and does not involve application downtime. This\ntooling takes the backup of Kubernetes resources in a local directory and sets\n`ReclaimPolicy` to `Retain` before migration. So there will be no data loss.\n\nLimitation\n\n- The automated tooling is only supported on Google Distributed Cloud versions that\n are [fully supported](/kubernetes-engine/distributed-cloud/vmware/docs/version-history).\n\n- It only works with StatefulSets. You can run preflight checks using\n the tool to run a few safety checks before using the tools.\n\n```\n./statefulset-csi-migration-tool preflight \\\n --kubeconfig ADMIN_KUBECONFIG \\\n --cluster-name USER_CLUSTER_NAME \\\n --sts-name STS_NAME \\\n --sts-namespace STS_NAMESPACE \\\n --intree-storageclass INTREE_STORAGECLASS \\\n --csi-storageclass CSI_STORAGECLASS\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e: the path of your admin cluster\n kubeconfig file.\n\n- \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e: If the StatefulSet is\n running on the user cluster, then provide the user cluster name.\n Skip this flag if the workload is running on the admin cluster.\n\n- \u003cvar translate=\"no\"\u003eSTS_NAME\u003c/var\u003e: name of the StatefulSet.\n\n- \u003cvar translate=\"no\"\u003eSTS_NAMESPACE\u003c/var\u003e: namespace of the StatefulSet.\n\n- \u003cvar translate=\"no\"\u003eINTREE_STORAGECLASS\u003c/var\u003e: the in-tree StorageClass\n name backing the StatefulSet's PersistentVolume.\n\n- \u003cvar translate=\"no\"\u003eCSI_STORAGECLASS\u003c/var\u003e: the CSI StorageClass\n name backing the StatefulSet's PersistentVolume after migration.\n\nDownload\n\nDownload the tool at\n`gs://gke-on-prem-release/statefulset-csi-migration-tool/v1.0/statefulset-csi-migration-tool`.\nNote this tool is in preview.\n\nProcedure\n\nThis section provides the steps needed for migrating StatefulSet from vSphere\nin-tree **vCP** internal provisioner (`kubernetes.io/vsphere-volume`) to vSphere\n**CSI** provisioner (`csi.vsphere.vmware.com`). \n\n```\n./statefulset-csi-migration-tool rolling-migration all \\\n --kubeconfig ADMIN_KUBECONFIG \\\n --cluster-name USER_CLUSTER_NAME \\\n --sts-name STS_NAME \\\n --sts-namespace STS_NAMESPACE \\\n --intree-storageclass INTREE_STORAGECLASS \\\n --csi-storageclass CSI_STORAGECLASS \\\n --working-directory WORKING_DIRECTORY\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eADMIN_KUBECONFIG\u003c/var\u003e: the path of your admin cluster\n kubeconfig file.\n\n- \u003cvar translate=\"no\"\u003eUSER_CLUSTER_NAME\u003c/var\u003e: If the StatefulSet is\n running on the user cluster, then provide the user cluster name.\n Skip this flag if the workload is running on the admin cluster.\n\n- \u003cvar translate=\"no\"\u003eSTS_NAME\u003c/var\u003e: name of the StatefulSet.\n\n- \u003cvar translate=\"no\"\u003eSTS_NAMESPACE\u003c/var\u003e: namespace of the StatefulSet.\n\n- \u003cvar translate=\"no\"\u003eINTREE_STORAGECLASS\u003c/var\u003e: the in-tree StorageClass\n name backing the StatefulSet's PersistentVolume.\n\n- \u003cvar translate=\"no\"\u003eCSI_STORAGECLASS\u003c/var\u003e: the CSI StorageClass\n name backing the StatefulSet's PersistentVolume after migration.\n\n- \u003cvar translate=\"no\"\u003eWORKING_DIRECTORY\u003c/var\u003e: the local directory to\n save the Kubernetes resource spec of StatefulSet and its Pod,\n PersistentVolumeClaim and PersistentVolume. The directory name must be\n unique for each StatefulSet. This directory should be empty or not exist.\n It is ideal to not create this directory so that the tooling can create\n one for you.\n\nThis command performs the following tasks:\n\n1. Takes a backup of the StatefulSet and its dependencies like PersistentVolume,\n PersistentVolumeClaim and Pod replica specs in the local working directory.\n\n2. Deletes the StatefulSet with orphan deletion policy. This step only deletes\n the StatefulSet but does not delete its dependencies like the Pod replicas,\n PersistentVolume and PersistentVolumeClaim.\n\n3. Migrates each Pod to CSI drivers (similar to Option 1), and does the\n following:\n\n a. Sets the PersistentVolume's ReclaimPolicy field as Retain.\n\n b. Deletes the Pod, PersistentVolume and PersistentVolumeClaim.\n\n c. Converts the existing VMDK to FCD.\n\n d. Creates the PersistentVolume, PersistentVolumeClaim and Pod again.\n4. Recreates the StatefulSet, but the PVCTemplate field in its spec points to\n the CSI StorageClass. The StatefulSet controller should map to the orphaned\n replicas again."]]
