워크로드 클러스터 업그레이드

이 항목에서는 TKG(Tanzu Kubernetes Grid) 워크로드 클러스터를 업그레이드하는 방법을 설명합니다. 독립형 관리 클러스터가 있는 TKG의 경우 먼저 워크로드 클러스터를 관리하는 관리 클러스터를 업그레이드해야 합니다.

중요

  • vSphere 8에서 Supervisor와 함께 배포한 워크로드 클러스터를 업그레이드하려면, Tanzu CLI를 사용하여 TKG 2.3 워크로드 클러스터 생성 및 관리에서 Supervisor가 배포한 클러스터 업그레이드(vSphere 8만 해당)를 참조하십시오.
  • 로컬에 저장된 VM 템플릿을 사용하는 Edge 워크로드 클러스터를 업그레이드하려면 로컬 VM 템플릿으로 Edge 클러스터 업그레이드를 참조하십시오.
  • 사용자 지정 클러스터 매니페스트에서 생성한 워크로드 클러스터를 업그레이드하려면 사용자 지정 클러스터 업그레이드를 참조하십시오.
  • 독립형 관리 클러스터와 워크로드 클러스터는 클라이언트 인증서를 사용하여 클라이언트를 인증합니다. 이러한 인증서는 1년 동안 유효합니다. 갱신하려면 클러스터를 일년에 한 번 이상 업그레이드합니다.

사전 요구 사항

인프라 사전 요구 사항

중요

Tanzu Kubernetes Grid v2.4.x는 AWS 및 Azure에서 기존 TKG 워크로드 클러스터 업그레이드를 지원하는 마지막 TKG 버전입니다. AWS 및 Azure에서 TKG 워크로드 클러스터를 업그레이드하는 기능은 Tanzu Kubernetes Grid v2.5 릴리스에서 제거됩니다.

지금부터는 VMware Tanzu Mission Control을 사용하여 네이티브 AWS EKS 및 Azure AKS 클러스터를 생성하는 것이 좋습니다. 그러나 AWS 및 Azure에서 기존 TKG 워크로드 클러스터를 업그레이드하는 것은 TKG v2.4.x 등 모든 TKG 릴리스에 대해 완전히 지원됩니다.

자세한 내용은 VMware Tanzu Kubernetes Grid v2.4 Release Notes에서 AWS 및 Azure에서 TKG 관리 및 워크로드 클러스터의 사용 중단을 참조하십시오.

vSphere
vSphere에서 실행되는 클러스터를 업그레이드하는 경우 클러스터를 Tanzu Kubernetes Grid 버전의 기본값이 아닌 Kubernetes 버전으로 업그레이드하려면 먼저 vSphere에서 적절한 기본 이미지 템플릿 OVA를 VM 템플릿으로 사용할 수 있어야 합니다. OVA 파일을 vSphere 가져오는 방법에 대한 자세한 내용은 클러스터 업그레이드 준비vSphere 탭을 참조하십시오.
AWS
AWS(Amazon Web Services)에서 실행되는 클러스터를 업그레이드하는 경우 지원되는 Kubernetes 버전을 포함하는 Amazon Linux 2 Amazon Machine Images(AMI)를 지원되는 모든 AWS 지역에서 모든 AWS 사용자가 공개적으로 사용할 수 있습니다. Tanzu Kubernetes Grid는 업그레이드할 때 지정한 Kubernetes 버전에 적합한 AMI를 자동으로 사용합니다.
Azure
Azure에서 실행되는 클러스터를 업그레이드하는 경우 클러스터 업그레이드 준비Azure 탭에 있는 단계를 완료했는지 확인합니다.


절차

업그레이드 프로세스는 워크로드 클러스터의 모든 제어부 및 Worker 노드에서 Kubernetes 버전을 업그레이드합니다.

  1. 사용 가능한 관리 클러스터의 대화형 목록을 보고 업그레이드할 클러스터를 관리하는 관리 클러스터를 선택하려면 tanzu context use 명령을 실행합니다.

    tanzu context use
    
  2. 워크로드 클러스터를 나열하려면 다음을 실행합니다.

    tanzu cluster list --include-management-cluster -A
    

    --include-management-cluster -A 옵션이 있는 tanzu cluster list 명령은 관리 클러스터에서 실행 중인 Kubernetes의 버전과 관리하는 모든 클러스터를 보여 줍니다. 이 예에서는 관리 클러스터가 이미 v1.26.8로 업그레이드되었지만 워크로드 클러스터가 이전 버전의 Kubernetes를 실행하고 있음을 확인할 수 있습니다.

    NAME                 NAMESPACE   STATUS    CONTROLPLANE  WORKERS  KUBERNETES         ROLES       PLAN  TKR
    k8s-1-24-14-cluster  default     running   1/1           1/1      v1.24.14+vmware.1  <none>      dev   v1.24.14---vmware.1-tkg.1
    k8s-1-25-10-cluster  default     running   1/1           1/1      1.25.10+vmware.1   <none>      dev   1.25.10---vmware.1-tkg.1
    mgmt-cluster         tkg-system  running   1/1           1/1      v1.26.8+vmware.1   management  dev   v1.26.8---vmware.1-tkg.1
    
  3. 관리 클러스터에서 사용할 수 있는 Kubernetes 버전을 검색하려면 tanzu kubernetes-release get 명령을 실행합니다.

    tanzu kubernetes-release get
    

    출력에는 클러스터를 배포하는 데 사용할 수 있는 모든 Kubernetes 버전이 다음 내용과 함께 나열됩니다.

    • COMPATIBLE: 현재 관리 클러스터는 이 Tanzu Kubernetes 릴리스(tkr)를 사용하여 워크로드 클러스터를 배포할 수 있습니다.
    • UPDATES AVAILABLE: 이 tkr은 Kubernetes 버전 라인에서 가장 최신이 아닙니다. 이 tkr 버전을 실행하는 모든 워크로드 클러스터를 최신 버전으로 업그레이드할 수 있습니다.

    예:

    NAME                              VERSION                         COMPATIBLE  ACTIVE  UPDATES AVAILABLE
    v1.24.17---vmware.1-tiny.2-tkg.1  v1.24.17+vmware.1-tiny.2-tkg.1  True        True
    v1.24.17---vmware.2-tkg.1         v1.24.17+vmware.2-tkg.1         True        True
    v1.25.13---vmware.1-tiny.2-tkg.1  v1.25.13+vmware.1-tiny.2-tkg.1  True        True
    v1.25.13---vmware.2-tkg.1         v1.25.13+vmware.2-tkg.1         True        True
    v1.26.8---vmware.1-tiny.2-tkg.1   v1.26.8+vmware.1-tiny.2-tkg.1   True        True
    v1.26.8---vmware.2-tkg.1          v1.26.8+vmware.2-tkg.1          True        True
    
  4. 이전 tkr 버전을 실행하는 워크로드 클러스터를 업그레이드할 수 있는 최신 tkr 버전을 검색하려면 tanzu kubernetes-release available-upgrades get 명령을 실행하고 현재 실행 중인 tkr 버전을 지정합니다.

    tanzu kubernetes-release available-upgrades get v1.25.10---vmware.2-tkg.1
    

    이 명령은 지정된 버전을 실행하는 클러스터를 업그레이드할 수 있는 사용 가능한 모든 Kubernetes 버전을 나열합니다.

    tanzu cluster available-upgrades get 명령에서 클러스터 이름을 지정하여 특정 워크로드 클러스터에 사용할 수 있는 tkr 버전을 검색할 수도 있습니다.

    tanzu cluster available-upgrades get k8s-1-24-14-cluster
    

    이 명령은 지정된 클러스터와 호환되는 모든 Kubernetes 버전을 나열합니다.

    tkr 버전을 업그레이드할 때 부 버전을 건너뛸 수 없습니다. 예를 들어 클러스터를 v1.24.x에서 v1.25.x로 직접 업그레이드할 수 없습니다. 클러스터를 v1.26.x로 업그레이드하기 전에 v1.24.x 클러스터를 v1.25.x로 업그레이드해야 합니다.

  5. (Azure) Azure에서 클러스터가 실행 중인 경우 클러스터를 업그레이드하기 전에 AZURE_CLIENT_SECRET 환경 변수를 설정합니다.

    export AZURE_CLIENT_SECRET=YOUR-AZURE-CLIENT-SECRET
    
  6. (vSphere) 노드 IPAM을 사용하는 클러스터는 업그레이드하기 전에 해당 IP 풀에 할당되지 않은 IP 주소가 하나 이상 필요합니다.

    1. 클러스터가 노드 IPAM을 사용하는지 확인하려면 클러스터 개체의 spec.topology.variables network 설정에서 addressesFromPools을 찾습니다.

      kubectl -n NAMESPACE get cluster CLUSTER-NAME -o json | jq '.spec.topology.variables[] | select(.name=="network")'
      

      여기서 CLUSTER-NAMENAMESPACE는 워크로드 클러스터의 이름과 관리 클러스터 네임스페이스입니다. 예:

      kubectl -n default get cluster my-work-cluster -o json | jq '.spec.topology.variables[] | select(.name=="network")'
      {
        "name": "network",
        "value": {
          "addressesFromPools": [
            {
              "apiGroup": "ipam.cluster.x-k8s.io",
              "kind": "InClusterIPPool",
              "name": "mgmt-cluster-nimbus"
            }
          ],
          "ipv6Primary": false
        }
      } 
      
    2. 클러스터의 IP 풀에 사용되지 않은 주소가 있는지 확인하려면 풀의 총 수를 현재 할당된 수와 비교하고 다음 명령을 통해 출력으로 비교합니다.

      kubectl -n NAMESPACE get ipaddress | grep POOL-NAME | wc -l
      
  7. tanzu cluster upgrade CLUSTER-NAME 명령을 실행하고 y를 입력하여 확인합니다. 확인 단계를 건너뛰려면 --yes 옵션을 지정합니다.

    클러스터를 이 Tanzu Kubernetes Grid 릴리스의 Kubernetes 기본 버전으로 업그레이드하려면 옵션 없이 tanzu cluster upgrade 명령을 실행합니다. 이 릴리스에서 기본 버전은 v1.26.8입니다. 예:

    tanzu cluster upgrade k8s-1-25-7-cluster
    

    클러스터가 default 네임스페이스에서 실행되고 있지 않으면 --namespace 옵션을 지정합니다.

    tanzu cluster upgrade CLUSTER-NAME --namespace NAMESPACE-NAME
    

    업그레이드가 완료되기 전에 시간이 초과되면 tanzu cluster upgrade를 다시 실행하고 기본값인 30분보다 큰 --timeout 옵션을 지정합니다.

    tanzu cluster upgrade CLUSTER-NAME --timeout 45m0s
    
    중요

    Azure에서의 작업은 다른 플랫폼보다 오래 걸리는 경우가 있습니다. Azure에서 클러스터를 업그레이드하는 경우 오류를 방지하기 위해 --timeout 옵션을 정기적으로 설정합니다.

    IaaS 계정의 여러 기본 VM 이미지가 업그레이드하려는 동일한 버전의 Kubernetes를 가지고 있는 경우, 업그레이드할 OS 선택에 설명된 대로 --os-name 및 기타 옵션을 포함하여 대상 OS를 지정할 수 있습니다.

    tanzu cluster upgrade CLUSTER-NAME --os-name ubuntu
    

    vSphere에서 --vsphere-vm-template-name 옵션을 사용하여 업그레이드할 OVA 템플릿 선택에 설명된 대로 클러스터 노드에 대해 대상 OVA 템플릿을 지정할 수 있습니다.

    tanzu cluster upgrade CLUSTER-NAME --vsphere-vm-template-name "/dc0/vm/tanzu/ubuntu-2004-kube-v1.29.9-vmware.1"
    

    tkr의 부 버전을 건너뛸 수 없기 때문에 기본 버전보다 2개 이상의 부 버전인 클러스터를 업그레이드하면 업그레이드 명령이 실패합니다. 예를 들어 v1.24.x에서 v1.26.x로 직접 업그레이드할 수 없습니다. 클러스터를 이 Tanzu Kubernetes Grid 릴리스의 기본 버전이 아닌 Kubernetes 버전으로 업그레이드하려면 위의 tanzu kubernetes-release get으로 나열된 대로 선택한 버전의 NAME이 있는 --tkr 옵션을 지정합니다. 예를 들어, 클러스터 k8s-1-24-14-cluster를 v1.24.14에서 v1.25.13으로 업그레이드.

    tanzu cluster upgrade k8s-1-24-14-cluster --tkr v1.25.13---vmware.1-tkg.1
    
  8. 업그레이드가 완료되면 tanzu cluster list 명령을 실행하여 워크로드 클러스터가 업그레이드되었는지 확인합니다.

    tanzu cluster list --include-management-cluster -A
    
  9. 관리자 kubeconfig를 다시 생성합니다.

    tanzu cluster kubeconfig get CLUSTER-NAME --admin
    

    여기서 CLUSTER-NAME은 워크로드 클러스터의 이름입니다.

    중요

    업그레이드 후 kubeconfig를 갱신하지 않으면 클러스터가 만료되면 액세스할 수 없습니다.

  10. LDAP 또는 OIDC ID 제공자를 사용하는 경우 kubectl을 사용하여 클러스터에 인증할 수 있는지 확인합니다. 예:

    kubectl get pods -A --kubeconfig my-cluster-credentials
    
  11. 워크로드 클러스터에서 실행 중인 Contour, Fluent Bit 또는 Prometheus와 같은 CLI 관리 패키지를 업그레이드합니다. CLI 관리 패키지 업그레이드에 대한 자세한 내용은 패키지 업데이트를 참조하십시오.

    중요

    워크로드 클러스터에 Prometheus를 설치하고 워크로드 클러스터를 Kubernetes v1.25로 업그레이드하는 경우 Prometheus를 적어도 버전 2.37.0+vmware.3-tkg.1로 업그레이드해야 합니다. 이전 버전의 Prometheus 패키지(예: 버전 2.37.0+vmware.1-tkg.1)는 Kubernetes 1.25와 호환되지 않습니다.

로컬 VM 템플릿을 사용하여 Edge 클러스터 업그레이드

tanzu cluster upgrade 명령을 사용하여 위의 로컬 VM 템플릿 지정에 설명된 대로 로컬 VM 템플릿을 사용하여 엣지 워크로드 클러스터의 Kubernetes 버전을 업그레이드할 수 없습니다.

대신 다음과 같이 Edge 워크로드 클러스터의 Kubernetes 버전을 업그레이드합니다.

  1. 새 VM 템플릿을 로컬 vCenter 업로드하고 인벤토리 경로(예: /dc0/vm/ubuntu-2004-kube-v1.26.8+vmware.1-tkg.1)를 기록합니다.

  2. 업그레이드할 Cluster 개체의 매니페스트를 편집합니다.

    kubectl edit cluster CLUSTER-NAME
    

    여기서 CLUSTER-NAME은 클러스터의 이름입니다.

  3. spec.topology 아래에서 다음을 업데이트합니다.

    • 새 Kubernetes 버전을 반영하도록 version을 설정합니다.
    • 클러스터 전체 또는 개별 시스템 배포에서 업데이트할 모든 vcenter.template 값을 새 로컬 템플릿의 인벤토리 경로로 설정합니다.
  4. 저장한 후 종료하여 새 Cluster 개체 설정을 적용합니다.

후속 작업

이제 Tanzu CLI를 계속 사용하여 클러스터를 관리할 수 있습니다. 자세한 내용은 Tanzu CLI를 사용하여 TKG 2.3 워크로드 클러스터 생성 및 관리를 참조하십시오.

check-circle-line exclamation-circle-line close-line
Scroll to top icon