본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

업그레이드 노트

원문 보기 위키 갱신

업그레이드 전에 이 페이지를 꼭 훑어보세요. 여러분이 의존하고 있을 수 있는 동작을 바꾸는 변경 사항들을 정리하고, 누구에게 영향을 주는지, 그리고 무엇을 해야 하는지 설명해요. 별도 표기가 없다면 각 노트는 v3.33으로의 모든 업그레이드에 적용돼요.

출처: 문서

본문

Calico가 단일 이미지로 배포됨 (Calico ships as a single image)

Calico 이미지를 프라이빗 레지스트리로 미러링하거나, 이미지 이름 또는 다이제스트를 고정하거나, 특정 이미지를 스캔한다면 이 변경이 여러분에게 영향을 줘요.

이제 대부분의 컴포넌트가 하나의 calico/calico 이미지 안에서 배포돼요. 대체된 이미지들은 3.33에서는 아예 배포되지 않기 때문에, 업그레이드 후 미러나 고정된 참조로는 풀에 실패해요. 더 이상 배포되지 않는 13개 이미지는 다음과 같아요: calico/typha, calico/cni, calico/ctl, calico/apiserver, calico/kube-controllers, calico/goldmane, calico/dikastes, calico/csi, calico/node-driver-registrar, calico/pod2daemon-flexvol, calico/key-cert-provisioner, calico/flannel-migration-controller, calico/whisker-backend. calico/node, calico/whisker, calico/third-party-cni-plugins, Windows 이미지, Envoy 이미지, Istio 이미지는 계속 별도로 배포돼요.

  1. 업그레이드 전에 calico/calico를 여러분의 레지스트리로 미러링하세요.
  2. 대체된 이미지를 가리키던 이미지 고정 핀, 다이제스트, 스캐너 구성을 모두 업데이트하세요.
  3. Calico를 업그레이드하세요.

정책 규칙과 셀렉터 크기 제한 (Limits on policy rules and selectors)

Calico 네트워크 정책을 프로그램으로 생성하거나, 매우 큰 규칙 목록·주소 목록·셀렉터를 가진 정책을 쓴다면 이 변경이 여러분에게 영향을 줘요.

Calico 네트워크 정책 타입이 이제 CRD 스키마에서 크기 제한을 선언하고, Kubernetes API 서버가 모든 쓰기에 이를 강제해요.

필드 제한
ingress 규칙, egress 규칙 각각 1024개
selector, notSelector, namespaceSelector, serviceAccountSelector 1024자
nets, notNets 규칙당 256개 항목
ports, notPorts 규칙당 50개 항목
HTTP methods, paths 규칙당 20개 항목

데이터스토어에 이미 저장된 정책은 계속 동작하고, 제한을 넘는 필드를 건드리지 않는 업데이트는 여전히 허용돼요. Kubernetes가 CRD 검증을 래칫(ratchet) 방식으로 처리하기 때문이에요. 실패하는 것은 제한을 넘는 정책의 생성, 또는 제한을 넘는 필드의 업데이트예요. 이 제한은 CRD에 있기 때문에 etcdv3 데이터스토어에는 적용되지 않아요.

  1. 업그레이드 전에 기존 정책이 제한을 넘는지, 그리고 정책을 생성하는 도구가 제한을 넘는 정책을 만들 수 있는지 확인하세요.
  2. 제한을 넘는 정책은 분할하거나, 해당 필드를 좁히세요.
  3. Calico를 업그레이드하세요.

Calico Ingress Gateway 프록시의 네임스페이스 이동

WARNING: 업그레이드 시 게이트웨이 프록시가 네임스페이스를 이동하고, 병합된(merged) 게이트웨이는 더 이상 지원되지 않아요.

Calico Ingress Gateway를 사용한다면 이 변경이 여러분에게 영향을 줘요.

이제 각 게이트웨이의 프록시는 자신의 Gateway와 같은 네임스페이스에서 실행되고, 컨트롤러는 calico-system으로 이동해요. 기존 프록시들은 tigera-gateway 네임스페이스에서 벗어나기 때문에, tigera-gateway에 고정된 것들 — 네트워크 정책, 모니터링, 외부 DNS — 은 프록시와 더 이상 매칭되지 않아요. 병합된 게이트웨이(mergeGateways: true)는 더 이상 지원되지 않아서, 각 게이트웨이가 자체 로드밸런서를 갖게 돼요.

  1. 업그레이드 전에 글로벌 기본 deny 정책을 쓰고 있다면, 각 Gateway의 네임스페이스에 프록시 파드를 허용하는 네트워크 정책을 만들어서 프록시가 이동하자마자 시작할 수 있게 하세요. 정책 내용은 인그레스 게이트웨이 만들기를 참고하세요.
  2. Calico를 업그레이드하세요.
  3. 모니터링과 외부 DNS를 tigera-gateway에서 각 Gateway의 네임스페이스로 다시 연결하세요. 병합된 게이트웨이를 썼다면 게이트웨이마다 로드밸런서, DNS 레코드, 인증서를 하나씩 준비하세요.

Calico Ingress Gateway가 Gateway API v1.6으로 이동

Calico Ingress Gateway를 사용한다면 이 변경이 여러분에게 영향을 줘요.

번들된 Envoy Gateway가 v1.9.1로 이동하면서, 번들된 Gateway API CRD가 v1.5.1에서 v1.6.1로 올라가요. Gateway API v1.6은 HTTPRoute에서 sessionPersistence.idleTimeout을 제거했고, Envoy Gateway v1.9는 ClientTrafficPolicy의 빈 clientIPDetection을 거부해요. 둘 중 하나를 쓰는 매니페스트는 CRD가 업그레이드되는 순간 거부돼요.

  1. 업그레이드 전에 모든 HTTPRoute에서 sessionPersistence.idleTimeout을, ClientTrafficPolicy에서 빈 clientIPDetection을 제거하세요.

eBPF 데이터플레인에 커널 5.10 이상 필요

5.10보다 오래된 커널, 또는 BTF와 CO-RE 지원 없이 빌드된 커널에서 eBPF 데이터플레인을 실행한다면 이 변경이 여러분에게 영향을 줘요. Red Hat이 필요한 기능을 해당 빌드로 백포트했기 때문에 커널 4.18.0-305 이상의 Red Hat 8.4는 지원돼요.

오래된 커널을 위한 런타임 폴백 경로가 사라졌어요. 성능 저하로 버티는 대신, Calico는 이제 명확한 상태 메시지를 보고하고 지원되지 않는 노드에는 데이터플레인을 프로그래밍하지 않아요.

  1. 업그레이드 전에 eBPF 데이터플레인을 실행하는 모든 노드를 uname -r로 확인하고, ls /sys/kernel/btf/vmlinux로 BTF 지원을 확인하세요.
  2. 너무 오래된 노드는 업그레이드하거나 표준 데이터플레인으로 옮기세요.
  3. Calico를 업그레이드하세요.

지원 범위 안의 일부 커널에도 이 릴리스에서 알려진 문제가 있어요. 업그레이드를 계획하기 전에 릴리스 노트의 known issues를 확인하세요.

eBPF 프로그램이 기본으로 netkit을 통해 부착됨

eBPF 데이터플레인을 실행하고 3.32 이전으로 롤백할 가능성이 있다면 이 변경이 여러분에게 영향을 줘요.

BPFAttachType에 Netkit 값이 생겼고, 이 값이 이제 기본이에요. Felix는 워크로드 netkit 장치에는 netkit API로, 그 밖의 인터페이스에는 TCX로 BPF 프로그램을 부착해요. 3.33 이전 릴리스는 netkit 장치를 이해하지 못하기 때문에, 사전 준비 없이 롤백하면 그 장치들이 관리되지 않은 상태로 남아요.

  1. Calico를 업그레이드하세요.
  2. netkit 지원이 없는 릴리스로 롤백하기 전에 FelixConfiguration에서 BPFAttachType을 TCX 또는 TC로 설정하세요. 그러면 Felix가 기존 netkit 장치를 그 메커니즘으로 구동해요.

겹치는 IP 풀이 거부됨 (Overlapping IP pools are rejected)

두 IP 풀이라도 CIDR이 겹친다면 이 변경이 여러분에게 영향을 줘요.

이제 IP 풀을 만들거나 업데이트할 때 CIDR이 기존 풀과 겹치면 거부돼요. 이미 저장된 풀은 계속 동작하지만, 겹침이 해소되기 전에는 겹치는 풀을 편집할 수 없어요.

  1. 업그레이드 전에 나중에 풀을 편집할 계획이라면 지금 CIDR 겹침을 확인하세요.

Felix 메트릭 엔드포인트가 기본으로 클라이언트 인증서를 요구하지 않음

HTTPS로 Felix Prometheus 메트릭 엔드포인트를 제공하면서 prometheusMetricsCertFile과 prometheusMetricsKeyFile을 설정했고, prometheusMetricsClientAuth를 설정한 적이 없다면 이 변경이 여러분에게 영향을 줘요. 기본값인 일반 HTTP로 제공한다면 클라이언트 인증서는 애초에 관여하지 않았으니 아무것도 바뀌지 않아요.

기본값이 RequireAndVerifyClientCert에서 NoClientCert로 바뀌어요. 아무것도 실패하지 않고 스크랩도 깨지지 않아요. 다만 엔드포인트가 클라이언트 인증서를 더 이상 요구하지 않게 되어서, 기본으로 갖고 있던 보호 장치가 업그레이드 후 사라져요.

  1. 업그레이드 전에 그 보호에 의존한다면 FelixConfiguration에 prometheusMetricsClientAuth: RequireAndVerifyClientCert를 명시적으로 설정하세요.

FIPS 모드 제거 (FIPS mode is removed)

Installation에서 fipsMode: Enabled를 설정한다면 — operator 관리 클러스터가 -fips 이미지를 쓰는 방식이에요 — 이 변경이 여러분에게 영향을 줘요.

Calico는 더 이상 -fips 태그 이미지나 boringcrypto 바이너리를 배포하지 않고, FIPS 모드는 3.30에서 deprecated됐어요. fipsMode 필드는 Installation API에 여전히 존재하지만 deprecated이고, Enabled로 두면 업그레이드 후 설치가 degraded로 표시돼요.

  1. 업그레이드 전에 Installation에서 fipsMode를 제거하거나 Disabled로 설정하세요.
  2. 이미지 태그를 고정하는 곳이 있다면 -fips 변형에서 벗어나세요.

신규 설치가 네이티브 v3 CRD를 기본으로 사용

조치가 필요 없어요. 이 노트는 업그레이드가 클러스터를 바꾸기 때문이 아니라 기본값이 바뀌었기 때문에 존재해요.

업그레이드가 기존 클러스터를 aggregation API 서버와 네이티브 v3 CRD 사이에서 전환하는 일은 절대 없어요. operator는 이미 존재하는 CRD를 보고 모드를 선택해요. 바뀐 것은 완전히 새로운 설치의 기본값이고, 이제는 v3 CRD 모드예요. Kubernetes 1.35에서는 그 모드가 API 서버에서 MutatingAdmissionPolicy 기능 게이트가 켜져 있어야 하는데, 베타 API가 존재하지만 기본으로 켜져 있지는 않기 때문이에요. 1.36부터는 이 기능이 일반 공급되고 자동으로 켜져요.

  1. Calico를 업그레이드하세요. 클러스터는 이미 쓰던 메커니즘을 유지해요.
  2. 기존 클러스터를 의도적으로 네이티브 v3 CRD로 옮기려면 API 서버에서 네이티브 CRD로 마이그레이션을 따르세요. 유지보수 창을 계획하세요: 마이그레이션이 끝날 때까지 새 파드 스케줄링과 정책 변경이 막히고, 마지막 단계에는 IPAM 할당도 막혀요.

OpenStack이 타이머 기반 리싱크를 더 이상 수행하지 않음

Calico for OpenStack을 실행하면서 드리프트 복구를 주기적 리싱크에 의존했다면 이 변경이 여러분에게 영향을 줘요.

주기적 리싱크가 사라졌어요. resync_interval_secs와 resync_max_interval_secs는 이제 no-op이고, 기존 neutron.conf가 깨지지 않도록 유지될 뿐이에요. 드라이버는 Neutron 서버가 시작될 때 한 번 리싱크하고, 그 후에는 요청 시에 리싱크해요.

  1. Calico를 업그레이드하세요.
  2. 편할 때 neutron.conf에서 resync_interval_secs와 resync_max_interval_secs를 제거하세요.
  3. 패키지로 설치한다면 각 컨트롤 노드에 calico-resync 패키지를 설치하세요. 이 커맨드는 calico-control과 별도로 배포돼요.
  4. 즉시 재조정이 필요할 때 calico-resync를 실행하세요. 재조정을 완전히 수동으로 하려면 startup_resync = never로 설정하세요. Neutron과 etcd 사이의 리싱크를 참고하세요.

AdminNetworkPolicy와 BaselineAdminNetworkPolicy가 더 이상 강제되지 않음

3.31에서 업그레이드하면서 AdminNetworkPolicy 또는 BaselineAdminNetworkPolicy 리소스가 있다면 이 변경이 여러분에게 영향을 줘요. 이미 3.32라면 이미 일어난 일이에요.

3.32에서 이 둘의 지원이 제거되고 ClusterNetworkPolicy로 대체됐어요. Calico는 3.32부터 이 둘을 강제하지 않기 때문에 조용히 효력을 잃어요: 리소스는 클러스터에 남아 있고 아무것도 오류를 보고하지 않아요.

  1. 업그레이드 전에 각 AdminNetworkPolicy와 BaselineAdminNetworkPolicy를 동등한 ClusterNetworkPolicy로 교체하거나 제거하세요.

OpenStack 정책 이름이 etcd 데이터스토어에서 변경됨

3.31에서 업그레이드하면서 etcd 데이터스토어로 Calico for OpenStack을 실행한다면 이 변경이 여러분에게 영향을 줘요. 이미 3.32라면 이미 일어난 일이에요.

3.32에서 저장된 정책의 이름 규칙이 바뀌었어요: 기본 tier의 정책은 그냥 자기 이름으로 저장되는데, 3.29.4부터 3.31.x는 tier 접두어가 붙은 이름으로 저장했어요. Kubernetes 클러스터는 kube-controllers를 통해 자동으로 마이그레이션해요. OpenStack 클러스터는 kube-controllers를 실행하지 않기 때문에 마이그레이션을 수동으로 한 번 실행해야 해요.

  1. Calico를 업그레이드하세요.
  2. 정책 데이터 마이그레이션에 설명된 일회성 마이그레이션을 실행하세요.

더 알아보기 (Learn more)

이 문서의 각 항목은 "누구에게 영향을 주는지 → 무엇을 할지" 구조로 되어 있으니, 자신에게 해당하는 항목만 골라 체크리스트로 쓰면 돼요. 특히 이미지 미러링 환경은 단일 calico/calico 이미지 전환이 풀 실패로 바로 이어지니 가장 먼저 준비하세요. 커널 요구사항과 정책 크기 제한은 업그레이드 전 점검 목록에 넣어두면 안전해요.