클러스터에서 TRAFFIC_DIRECTOR 컨트롤 플레인을 사용하는 경우 멀티 클러스터 보안 비밀은 지원되지 않습니다. 이 문서에서는 Istio 멀티 클러스터 보안 비밀 사용에서 multicluster_mode 사용으로 현대화하는 방법을 설명합니다.
Istio 보안 비밀과 선언적 API 개요
오픈소스 Istio 멀티 클러스터 엔드포인트 검색은 istioctl 또는 기타 도구를 사용하여 클러스터에 Kubernetes 보안 비밀을 만드는 방식으로 작동합니다. 이 보안 비밀을 사용하면 클러스터가 메시의 다른 클러스터로 트래픽 부하를 분산할 수 있습니다. 그러면 ISTIOD 컨트롤 플레인에서 이 보안 비밀을 읽고 다른 클러스터로 트래픽 라우팅을 시작합니다.
Cloud Service Mesh에는 Istio 보안 비밀을 직접 만드는 대신 멀티 클러스터 트래픽을 제어하는 선언적 API가 있습니다. 이 API는 Istio 보안 비밀을 구현 세부정보로 취급하며 Istio 보안 비밀을 수동으로 만드는 것보다 안정적입니다. 향후 Cloud Service Mesh 기능은 선언적 API에 종속되며 Istio 보안 비밀로 이러한 새 기능을 직접 사용할 수 없습니다. 선언적 API는 앞으로 지원되는 유일한 경로입니다.
Istio 보안 비밀을 사용하는 경우 선언적 API를 사용하는 것으로 최대한 빨리 마이그레이션하세요. multicluster_mode 설정은 각 클러스터가 메시의 다른 모든 클러스터로 트래픽을 전달하도록 지시합니다. 보안 비밀을 사용하면 더 유연하게 구성할 수 있으므로 각 클러스터에 대해 메시에서 트래픽을 전달할 다른 클러스터를 구성할 수 있습니다.
선언적 API와 Istio 보안 비밀의 지원되는 기능 간의 차이점의 전체 목록은 Istio API를 사용하는 지원 기능을 참고하세요.
Istio 보안 비밀에서 선언적 API로 마이그레이션
Fleet 기능 API를 사용하여 자동 관리를 통해 Cloud Service Mesh를 프로비저닝한 경우 이 안내를 따르지 않아도 됩니다.
이 단계는 asmcli --managed를 사용하여 온보딩한 경우에만 적용됩니다.
이 프로세스는 클러스터를 가리키는 보안 비밀을 변경합니다. 이 과정에서 엔드포인트가 삭제되었다가 다시 추가됩니다. 엔드포인트가 삭제되고 추가되는 사이에 트래픽이 다른 클러스터로 부하 분산되는 대신 잠시 로컬 라우팅으로 되돌아갑니다.
자세한 내용은 GitHub 문제를 참고하세요.
Istio 보안 비밀 사용에서 선언적 API로 전환하려면 다음 단계를 따르세요.
다음 단계를 동시에 또는 연속으로 실행합니다.
multicluster_mode=connected를 설정하여 멀티 클러스터 엔드포인트 검색을 사용 설정하려는 Fleet의 각 클러스터에 선언적 API를 사용 설정합니다. 클러스터를 검색할 수 없도록 하려면 multicluster_mode=disconnected를 명시적으로 설정해야 합니다.
클러스터에서 multicluster_mode=connected를 설정하면 각 클러스터에 multicluster_mode=connected가 설정된 다른 모든 클러스터에 대해 새 보안 비밀이 생성됩니다.
보안 비밀은 istio-system 네임스페이스에 배치되며 다음 형식입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Configuration updates for modernization\n=======================================\n\nThis document describes configuration updates you may need to make to your\nmanaged Cloud Service Mesh before modernizing your mesh to\nthe `TRAFFIC_DIRECTOR` control plane from the `ISTIOD` control plane.\n\nFor more information on the modernization workflow, see the\n[Managed control plane modernization](/service-mesh/v1.24/docs/modernization) page.\n\nMigrate from Istio secrets to multicluster_mode\n-----------------------------------------------\n\nMulti-cluster secrets are not supported when a cluster is using the\n`TRAFFIC_DIRECTOR` control plane. This document describes how you\ncan modernize from using Istio multi-cluster secrets to using `multicluster_mode`.\n\n### Istio secrets versus declarative API overview\n\n[Open source istio multi-cluster](https://istio.io/latest/docs/setup/install/multicluster/) endpoint discovery works by\nusing `istioctl` or other tools to create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) in a\ncluster. This secret allows a cluster to load balance traffic to another cluster\nin the mesh. The `ISTIOD` control plane then reads this\nsecret and begins routing traffic to that other cluster.\n\nCloud Service Mesh has a [declarative API](/service-mesh/v1.24/docs/operate-and-maintain/multi-cluster#endpoint-discovery-declarative-api)\nto control\nmulti-cluster traffic instead of directly creating Istio secrets. This API\ntreats Istio secrets as an implementation detail and is more reliable\nthan creating Istio secrets manually. Future Cloud Service Mesh features will\ndepend on the declarative API, and you won't be able to use those new\nfeatures with Istio secrets directly. The declarative API is the only\nsupported path forward.\n\nIf you are using Istio Secrets, migrate to using the declarative API as\nsoon as possible. Note that the `multicluster_mode` setting directs each cluster\nto direct traffic to every other cluster in the mesh. Using secrets allows a\nmore flexible configuration, letting you configure for each cluster which other\ncluster it should direct traffic to in the mesh.\nFor a full list of the differences between the supported\nfeatures of the declarative API and Istio secrets, see\n[Supported features using Istio APIs](/service-mesh/v1.24/docs/supported-features-managed#multi-cluster_deployment).\n| **Important:** With the declarative API, an entire cluster is opted into endpoint discovery at a time. This means that every cluster with \\`multicluster_mode=connected\\` will discover endpoints for every other cluster in the fleet that also has \\`multicluster_mode=connected\\`.\n\n### Migrate from Istio secrets to declarative API\n\nIf you provisioned Cloud Service Mesh using automatic management with the\n[fleet feature API](/service-mesh/v1.24/docs/onboarding/provision-control-plane), you don't\nneed to follow these instructions.\nThese steps only apply if you onboarded using `asmcli --managed`.\n\nNote, this process changes secrets that point to a cluster. During this process,\nthe endpoints are removed and then re-added. In between the endpoints\nbeing removed and added, the traffic will\nbriefly revert to routing locally instead of load balancing to other clusters.\nFor more information, see the\n[GitHub issue](https://github.com/istio/istio/issues/36365).\n\nTo move from using Istio secrets to the declarative API, follow these steps.\nExecute these steps at the same time or in close succession:\n\n1. Enable the declarative API for each cluster in the fleet where you want to\n enable multi cluster endpoint discovery by setting\n `multicluster_mode=connected`. Note that you need to explicitly set\n `multicluster_mode=disconnected` if you don't want the cluster to be\n discoverable.\n\n Use the following command to opt in a cluster for multi cluster endpoint\n discovery: \n\n kubectl patch configmap/asm-options -n istio-system --type merge -p '{\"data\":{\"multicluster_mode\":\"connected\"}}'\n\n Use the following command to opt a cluster out of endpoint discovery: \n\n kubectl patch configmap/asm-options -n istio-system --type merge -p '{\"data\":{\"multicluster_mode\":\"disconnected\"}}'\n\n2. Delete old secrets.\n\n After setting `multicluster_mode=connected` on your clusters, each\n cluster will have a new secret generated for every other cluster that also\n has `multicluster_mode=connected` set.\n The secret is placed in the istio-system namespace and have the following\n format: \n\n istio-remote-secret-projects-\u003cvar translate=\"no\"\u003ePROJECT_NAME\u003c/var\u003e-locations-\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e-memberships-\u003cvar translate=\"no\"\u003eMEMBERSHIPS\u003c/var\u003e\n\n Each secret will also have the label `istio.io/owned-by: mesh.googleapis.com` applied.\n\n Once the new secrets are created, you can delete any secrets manually\n created with `istioctl create-remote-secret`: \n\n kubectl delete secret \u003cvar translate=\"no\"\u003eSECRET_NAME\u003c/var\u003e -n istio-system\n\nOnce migrated, check your request metrics to make sure they're routed as\nexpected."]]
