앰비언트 모드 활성화하기
앰비언트 모드 활성화하기 (Enable ambient mode)
앰비언트 모드를 한 번에 한 네임스페이스씩 활성화해요. 이렇게 하면 각 네임스페이스를 진행하기 전에 검증할 수 있고, 문제가 생기면 단일 네임스페이스를 되돌릴 수 있어요.
출처: Istio 문서
본문
네임스페이스 마이그레이션 (Migrating a namespace)
순서 요구사항 (Ordering requirements)
이 순서를 따르지 않으면 트래픽이 사이드카도 ztunnel도 아닌 곳에서 처리되어 워크로드에 장애가 생길 수 있어요.
1단계: 웨이포인트 활성화 (Step 1: Activate waypoints)
이전 단계에서 배포한 웨이포인트를 istio.io/use-waypoint 레이블을 추가해서 활성화해요.
전체 네임스페이스에 대한 웨이포인트를 활성화하려면:
$ kubectl label namespace <namespace> istio.io/use-waypoint=waypoint
특정 Service에 대해서만 웨이포인트를 활성화하려면:
$ kubectl label service <service-name> -n <namespace> istio.io/use-waypoint=waypoint
웨이포인트가 준비되었는지 확인하세요:
$ kubectl get gateway waypoint -n <namespace>
READY 열이 True를 보여야 해요.
2단계: 네임스페이스에 앰비언트 모드 활성화 (Step 2: Enable ambient mode for the namespace)
네임스페이스에 istio.io/dataplane-mode=ambient 레이블을 추가해요. 이는 CNI 플러그인에게 이 네임스페이스의 새 파드와 재시작된 파드가 사이드카 대신(또는 사이드카와 함께) ztunnel을 사용해야 한다고 알려줘요:
$ kubectl label namespace <namespace> istio.io/dataplane-mode=ambient
네임스페이스가 이제 앰비언트 메시에 등록되었는지 확인하세요:
$ istioctl ztunnel-config workloads -n istio-system | grep <namespace>
네임스페이스의 워크로드는 프로토콜로 HBONE이 표시된 채 나타나요. 이 시점에서 파드에는 여전히 사이드카가 있어요. 둘 다 가진 파드의 경우 사이드카가 ztunnel보다 우선해요.
3단계: 사이드카 주입 제거 (Step 3: Remove sidecar injection)
네임스페이스에서 사이드카 주입 레이블을 제거해요:
기본 주입 레이블을 사용한다면:
$ kubectl label namespace <namespace> istio-injection-
리비전 레이블을 사용한다면:
$ kubectl label namespace <namespace> istio.io/rev-
4단계: 파드 재시작 (Step 4: Restart pods)
네임스페이스의 워크로드를 재시작해요. 파드가 재시작되면 사이드카 컨테이너 없이 올라오고, 대신 ztunnel(그리고 구성했다면 웨이포인트)을 사용해요:
$ kubectl rollout restart deployment -n <namespace>
$ kubectl rollout status deployment -n <namespace>
5단계: 이전 사이드카 정책 제거 (Step 5: Remove old sidecar policies)
L7 규칙이 있는 워크로드 selector를 사용했던 AuthorizationPolicy 리소스를, targetRefs 기반 대응물로 교체되었으니 삭제해요:
$ kubectl delete authorizationpolicy <sidecar-policy-name> -n <namespace>
또한 HTTPRoute로 교체된 VirtualService와 DestinationRule 리소스도 제거해요:
$ kubectl delete virtualservice <name> -n <namespace>
$ kubectl delete destinationrule <name> -n <namespace>
L7 규칙이 없는 selector를 사용하는 L4 AuthorizationPolicy 리소스는 유지해도 안전해요. ztunnel이 그것을 올바르게 적용해요.
6단계: 검증 (Step 6: Validate)
파드가 사이드카 컨테이너 없이 실행 중인지 확인하세요:
$ kubectl get pods -n <namespace>
ztunnel이 워크로드를 관리하고 있는지 확인하세요:
$ istioctl ztunnel-config workloads -n istio-system | grep <namespace>
웨이포인트를 배포했다면, HTTPRoute와 AuthorizationPolicy 리소스가 정의하는 특정 동작(헤더 기반 라우팅, HTTP 메서드 제한 등)을 테스트해서 L7 정책과 라우팅 규칙이 적용되고 있는지 검증하세요.
각 네임스페이스에 대해 반복하기 (Repeat for each namespace)
마이그레이션하려는 각 네임스페이스에 대해 네임스페이스 마이그레이션 단계를 반복하세요. istio.io/dataplane-mode=ambient로 레이블되지 않은 네임스페이스는 계속 사이드카를 사용하며 영향을 받지 않아요.
롤백 (Rollback)
각 단계는 독립적으로 되돌릴 수 있어요. 진행한 정도에 맞는 롤백 절차를 사용하세요:
| 단계 | 롤백 작업 |
|---|---|
| 1단계 이후 (웨이포인트 활성화) | kubectl label namespace <ns> istio.io/use-waypoint- |
| 2단계 이후 (앰비언트 활성화) | kubectl label namespace <ns> istio.io/dataplane-mode- |
| 3단계 이후 (주입 제거) | 주입 레이블 다시 추가: kubectl label namespace <ns> istio-injection=enabled |
| 4단계 이후 (파드 재시작) | 주입 레이블 다시 추가 후, kubectl rollout restart deployment -n <ns> |
| 5단계 이후 (이전 정책 삭제) | kubectl apply -f istio-config-backup.yaml로 백업에서 복원 |
파드 재시작이 포함된 롤백 후에는 파드가 2/2 컨테이너(사이드카가 재주입되었음을 의미)를 보이는지 확인하고, 진행하기 전에 트래픽이 흐르는지 확인하세요.
마이그레이션 후 가시성 변경 사항 (Post-migration observability changes)
앰비언트 모드로 마이그레이션한 후 텔레메트리의 다음 변경 사항을 알아두세요:
메트릭 (Metrics): 사이드카 모드에서 메트릭은 reporter="source"와 reporter="destination"으로 보고돼요. 앰비언트 모드에서 ztunnel의 메트릭은 reporter="source"를 사용하고, 웨이포인트 프록시의 메트릭은 reporter="waypoint"를 사용해요. reporter 레이블에 의존하는 대시보드나 알림 규칙을 업데이트하세요.
메트릭 병합 (Metrics merging): 사이드카 모드에서 프록시 에이전트는 메트릭 병합을 지원하는데, 이는 표준 prometheus.io 어노테이션을 사용해 Istio와 애플리케이션 메트릭을 단일 스크레이프 대상으로 결합해요. 이 기능은 앰비언트 모드에서는 사용할 수 없어요. 마이그레이션 후에는 Istio 컴포넌트(ztunnel과 웨이포인트 파드)와 애플리케이션 파드를 별도 대상으로 스크레이프하도록 Prometheus를 구성해야 해요. 단일 병합 엔드포인트에 의존했던 PodMonitor나 ServiceMonitor 리소스를 업데이트하세요.
트레이싱 (Tracing): 사이드카 모드에서 각 홉은 두 개의 span(소스 사이드카 하나, 목적지 사이드카 하나)을 생성해요. 웨이포인트가 있는 앰비언트 모드에서는 웨이포인트당 하나의 span이 생성돼요. 이에 따라 트레이스 기반 SLO를 업데이트하세요.
istioctl proxy-status: 이 명령은 ztunnel 워크로드를 보여주지 않아요. 앰비언트 프록시 상태를 검사하려면 대신 istioctl ztunnel-config workloads를 사용하세요.
자세한 내용은 다음을 참조하세요: