Kubernetes Engine Migration

개요

• SCP(Samsung Cloud Platform) 의 Kubernetes Engine 에 위치한 Workload(Stateless, Stateful)를 SCP(Samsung Cloud Platform) V2로 이전하기 위한 Velero 사용에 대한 절차와 작업을 안내합니다.
• Velero는 Kubernetes 클러스터 간 또는 클라우드 환경에서 데이터를 백업하고 복원하는 데 사용되는 오픈소스 도구입니다. 이 가이드는 Velero를 사용하여 Kubernetes 클러스터를 마이그레이션하는 방법을 단계별로 설명합니다.

제약사항

• 지원되는 Kubernetes 버전: Velero는 특정 버전의 Kubernetes만 지원합니다. 공식 문서를 참고하여 호환 가능한 버전을 확인하세요.
• 리소스 제한: 대규모 클러스터의 경우, 백업 및 복원 시간이 길어질 수 있습니다.
• 네트워크 설정: 클러스터 간 통신이 가능해야 합니다.
• 스토리지 지원: Velero는 특정 스토리지 플러그인만 지원합니다. 사용 중인 스토리지 제공업체가 호환되는지 확인하세요.

사전작업

1. Velero CLI 설치: Bastion Host에 설치

• Velero CLI 작업을 위한 Virtual Server(OS:Ubuntu 24.04 / vCPU:2Cores, Memory: 4GB 권고) 필요
• 작업 서버 OS에 적합한 Velero(tarball)를 다운로드 합니다.
• 다운로드한 압축파일을 해제 합니다.

wget https://github.com/vmware-tanzu/velero/releases/download/v1.16.2/velero-v1.16.2-linux-amd64.tar.gz
tar -xvzf velero-v1.16.2-linux-amd64.tar.gz

• 추출된 Velero 바이너리 파일을 실행경로로 복사합니다.

chmod +x velero
mv velero /usr/local/bin

2. 백업 스토리지 설정

Velero backup 데이터 저장용 object storage를 생성합니다.

• bucket 생성

• object storage 상세 > 접근제어(SCP) 또는 서비스 자원 허용(SCP v2)에서 bastion host, worker node 등록

• v1 → v2 또는 v1 ← v2 object storage bucket을 VPC Endpoint를 활용하여 접속할 경우, 프라이빗 접근 허용 리소스 추가 > VPC Endpoint에서 해당 VPC Endpoint를 추가

• security group에 8443(SCP)/443(SCP v2) port 접근 권한 부여: bastion host, worker Node

• Object Storage Credentials (백업 저장소 용 Object Storage 사용을 위한 인증)파일을 준비 합니다.

cat << EOF > credentials-velero
[default] 
aws_access_key_id=xxxx 
aws_secret_access_key=xxxxx
EOF

3. Velero 서버 및 컴포넌트 설치: Cluster 설치

• Source와 target kubenetes Cluster의 kubeconfig 파일 준비 합니다.
• Image 준비

velero/velero-plugin-for-aws:v1.12.1
velero/velero:v1.16.1
velero/velero-restore-helper:v1.15.2
bitnamilegacy/kubectl :1.30.6 
quay.io/skopeo/stable:v1.19.0
alpine:3.22

• Image를 container registry에 등록

docker pull <image명>:<tag명>
skopeo copy docker-daemon:velero/velero:v1.16.1 docker://<registry 주소>/<repository 명>/velero/velero:v1.16.1 --authfile ~/auth.json
* auth.json은 skopeo 내용 확인

• helm 설치 참조 파일 작성: Image 경로 및 버전 등 확인 필요

REGISTRY=<scr registry>
REPOSITORY=<repository> # SCP v2에는 적용
REGION=<object storage region, kr-west1>
BUCKET=<object storage bucket name>
OBS_ENDPOINT=<object storage access endpoint, do not include protocol scheme like https://>
OBS_VPC_ENDPOINT_IP=<object storage vpc endpoint ip, only assign v1 environment> 

cat << EOF > values-additional.yaml
image:
  repository: $REGISTRY/$REPOSITORY/velero/velero
  tag: v1.16.1

$(if [[ -n $OBS_VPC_ENDPOINT_IP ]]; then
  cat <<INNER
hostAliases:
- ip: $OBS_VPC_ENDPOINT_IP
  hostnames:
  - $OBS_ENDPOINT

nodeAgent:
  hostAliases:
  - ip: $OBS_VPC_ENDPOINT_IP
    hostnames:
    - $OBS_ENDPOINT
INNER
fi)

initContainers:
  - name: velero-plugin-for-aws
    image: $REGISTRY/$REPOSITORY/velero/velero-plugin-for-aws:v1.12.1
    volumeMounts:
      - mountPath: /target
        name: plugins

kubectl:
  image:
    repository: $REGISTRY/$REPOSITORY/bitnamilegacy/kubectl
    tag: 1.30.6

configuration:
  backupStorageLocation:
  - name: default
    provider: aws
    bucket: $BUCKET
    config:
      region: $REGION
      s3ForcePathStyle: true
      s3Url: https://$OBS_ENDPOINT
      checksumAlgorithm: ""
  defaultVolumesToFsBackup: true
  features: EnableAPIGroupVersions

serviceAccount:
  server:
    imagePullSecrets:
      - <secret 명>

snapshotsEnabled: false
deployNodeAgent: true

configMaps:
  fs-restore-action-config:
  labels:
    velero.io/plugin-config: ""
    velero.io/pod-volume-restore: RestoreItemAction
  data:
    image: $REGISTRY/$REPOSITORY/velero/velero-restore-helper:v1.15.2
EOF

• Container Registry에 등록된 Image를 가져올 때 사용할 Image pull secret 생성

kubectl create namespace velero
kubectl create secret generic <secret명> \
 --from-file=.dockerconfigjson=$HOME/auth.json \
 --type=kubernetes.io/dockerconfigjson -n velero

• Object Storage 접속을 위한 Credential 파일을 생성

cat << EOF > credentials-velero
[default]
aws_access_key_id=<accesskey>
aws_secret_access_key=<secretkey>
EOF

• Helm 설치

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
helm version  

• Velero 서버 및 컴포넌트 설치를 위한 Helm Chart 파일을 다운로드 합니다.

helm repo add vmware-tanzu https://vmware-tanzu.github.io/helm-charts/
helm repo update
helm pull vmware-tanzu/velero --untar

• Source 와 Target Kubernetes 클러스터에 Velero 설치를 위한 namespace를 생성합니다.

kubectl create namespace velero

• Helm Chart를 통해 Velero를 설치 합니다.

helm install velero -n velero velero \
 --set-file credentials.secretContents.cloud=credentials-velero \
 -f values-additional.yaml

• Velero Cli를 통해 Velero 서버 및 컴포넌트를 설치할 수도 있습니다(선택사항).

velero install \
--provider aws \
--plugins <Registry 주소>/velero/velero-plugin-for-aws:v1.10.0 \
--bucket <object storage bucket name> \
--secret-file ./credentials-velero \
--backup-location-config region=<object storage region>,s3ForcePathStyle="true",s3Url=https://<object storage endpoint> \
--use-volume-snapshots=false \
--use-node-agent \
--features=EnableAPIGroupVersions \
--default-volumes-to-fs-backup
--kubeconfig=kubeconfig

4. 클러스터 준비

• 마이그레이션할 클러스터의 상태를 확인합니다.
• 필요한 리소스(예: Pod, Service, PersistentVolume 등)가 정상적으로 동작하는지 검증합니다.

5. Velero cluster 배포 확인

kubectl get backupstoragelocation default -n velero -o yaml 
NAME      PROVIDER   BUCKET/PREFIX   PHASE         LAST VALIDATED                  ACCESS MODE   DEFAULT
default   aws        v2migs          Available     2025-08-12 12:45:41 +0900 KST   ReadWrite     true
* PHASE가 available 상태여야 함

Kubernetes 마이그레이션 절차

1. Backup 실행

velero backup create mlops --include-namespaces mynamespace --selector helm.sh/chart=mariadb-1.7.1-0

Note

• Backup 결과 확인

kubectl get backups -A
kubectl describe backups -n velero
velero backup describe mydb --details

2. Backup 데이터 확인

• 백업 저장소(ObjectStorage)를 조회하면, Application형상이 되는 Workload들을 포함한 Kubernetes Resource들과, 볼륨데이터영역이 암호화 및 압축되어 저장됩니다. backups안에는 백업객체 단위로 하위폴더를 생성하고, kubernetes resource들이 백업됩니다. 그리고 kopia안에는 볼륨데이터들이 백업 저장됩니다.

3. Restore 실행

velero restore create mlops  --from-backup mlops   --parallel-files-download 4
* --parallel-files-download옵션으로 다운로드를 병렬로 설정

5. Restore 결과 확인

kubectl get pod,svc,deploy,cm,sa,secret,pvc -n mynamespace -l helm.sh/chart=mariadb-1.7.1-0