Kubernetes Engine Migration

Overview

• This guide provides the procedures and tasks for using Velero to migrate workloads (stateless, stateful) located in the Kubernetes Engine of SCP (Samsung Cloud Platform) to SCP (Samsung Cloud Platform) V2.
• Velero is an open-source tool used to back up and restore data across Kubernetes clusters or in cloud environments. * This guide provides a step-by-step explanation of how to migrate a Kubernetes cluster using Velero.

Constraints

• Supported Kubernetes versions: Velero only supports specific versions of Kubernetes. * Refer to the official documentation to check the compatible version.
• Resource limitation: For large clusters, backup and restore times may be longer.
• Network configuration: Communication between clusters must be possible.
• Storage support: Velero only supports specific storage plugins. * Make sure the storage provider you are using is compatible.

Pre-work

1. Install Velero CLI: Install on the Bastion Host

• Virtual server required for Velero CLI operations (OS: Ubuntu 24.04 / vCPU: 2 cores, Memory: 4 GB recommended)
• Download the Velero (tarball) appropriate for the work server OS.
• Extract the downloaded archive.

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

• Copy the extracted Velero binary file to the execution path.

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

2. Backup storage configuration

Create an object storage for storing Velero backup data.

• Create bucket

• object storage details > access control (SCP) or service resource allowance (SCP v2) register bastion host, worker node

• v1 → v2 or v1 ← v2 object storage bucket accessed using a VPC Endpoint, add a resource to allow private access > Add the VPC Endpoint in the VPC Endpoint

• Grant access to ports 8443 (SCP)/443 (SCP v2) in the security group: bastion host, worker Node

• Prepare the Object Storage Credentials file (authentication for using Object Storage for backup storage).

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

3. Velero server and component installation: Cluster installation

• Prepare the kubeconfig files for the Source and target kubenetes clusters.
• Image preparation

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

• Register the image in the 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 내용 확인

• Create helm installation reference file: verify image path, version, etc.

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

• Create an Image pull secret to use when pulling an Image registered in the Container Registry

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

• Create a Credential file for accessing Object Storage

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

• Helm installation

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  

• Download the Helm Chart file for installing the Velero server and components.

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

• Create a namespace for installing Velero on the Source and Target Kubernetes clusters.

kubectl create namespace velero

• Install Velero using a Helm Chart.

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

• You can also install the Velero server and components via the Velero CLI (optional).

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. Cluster preparation

• Check the status of the cluster to be migrated.
• Verify that the required resources (e.g., Pod, Service, PersistentVolume, etc.) are operating correctly.

5. Velero cluster deployment verification

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 Migration Procedure

1. Backup execution

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

Note

• Check backup results

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

2. Check backup data

• When you query the backup storage (ObjectStorage), the Kubernetes resources—including workloads that constitute the application—and the volume data area are stored encrypted and compressed. * In backups, subfolders are created per backup object, and Kubernetes resources are backed up. * And within kopia, volume data is backed up.

3. Restore execution

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

5. Restore result verification

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