이 문서에서는 Cloud Service Mesh를 사용하여 사이드카 프록시 삽입을 구성하여 네트워크 보안, 안정성, 관측 가능성을 개선하는 방법을 설명합니다. 이러한 기능이 애플리케이션의 기본 컨테이너에서 추상화되고 동일한 포드에서 별도의 컨테이너로 제공되는 프로세스 외부의 공통 프록시로 구현됩니다. 여기서는 서비스 메시에 참여하도록 프로덕션 애플리케이션을 재설계하지 않아도 Cloud Service Mesh의 기능을 제공합니다.
Cloud Service Mesh가 워크로드의 pod에 구성한 네임스페이스 라벨을 감지하면 자동 사이드카 프록시 삽입(자동 삽입)이 발생합니다. 프록시는 워크로드에 대한 모든 인바운드 및 아웃바운드 트래픽을 가로채고 Cloud Service Mesh와 통신합니다.
이 태스크에 필요한 권한
이 페이지에서 태스크를 수행하려면 roles/container.clusterAdmin 이상의 역할이 있어야 합니다. 이 역할에 포함된 권한에 대한 자세한 내용은 Google Kubernetes Engine 역할을 참조하세요.
자동 사이드카 삽입 사용 설정
권장되는 사이드카 프록시 삽입 방법은 pod의 Kubernetes 구성을 수동으로 업데이트할 수 있도록 웹훅 기반 자동 사이드카 인젝터를 사용하는 것입니다.
자동 삽입을 사용 설정하려면 네임스페이스에 기본 삽입 라벨을 지정하거나(기본 태그가 설정되어 있는 경우), 버전 라벨을 네임스페이스에 지정합니다.
추가하는 라벨은 관리형 Cloud Service Mesh를 배포했는지(Fleet API 또는 asmcli 사용) 또는 클러스터 내 컨트롤 플레인을 설치했는지 여부에 따라 다릅니다. 라벨은 사이드카 인젝터 웹훅에서 삽입된 사이드카를 특정 제어 영역 버전과 연결하는 데 사용됩니다.
자동 삽입을 사용 설정하려면 다음을 실행하세요.
클러스터 내
다음 명령어를 사용하여 istiod에서 버전 라벨을 찾습니다.
kubectl -n istio-system get pods -l app=istiod --show-labels
출력에서 "istio-injection not found" 메시지는 무시해도 됩니다. 즉, 네임스페이스에 이전에 istio-injection 라벨이 사용되지 않았으며, Cloud Service Mesh를 새로 설치하거나 새로 배포해야 합니다. 네임스페이스에 istio-injection 및 버전 라벨이 모두 포함된 경우 자동 삽입 동작이 정의되지 않으므로 Cloud Service Mesh 문서의 모든 kubectl label 명령어가 명시적으로 하나만 설정되었는지 확인합니다.
다음 섹션의 단계를 사용하여 영향을 받는 pod를 다시 시작합니다.
관리형 서비스 메시
다음 명령어를 사용하여 사용 가능한 출시 채널을 찾습니다.
kubectl -n istio-system get controlplanerevision
출력은 다음과 비슷합니다.
NAME AGE
asm-managed 6d7h
출력에서 Cloud Service Mesh 버전에 사용 가능한 출시 채널에 해당하는 REVISION 라벨인 NAME 열 아래의 값을 선택합니다. 이 라벨을 네임스페이스에 적용하고 istio-injection 라벨(있는 경우)을 삭제합니다.
다음 명령어에서 REVISION을 위에서 확인된 버전 라벨로 바꾸고 NAMESPACE를 자동 삽입을 사용 설정하려는 네임스페이스 이름으로 바꿉니다.
출력에서 "istio-injection not found" 메시지는 무시해도 됩니다. 즉, 네임스페이스에 이전에 istio-injection 라벨이 사용되지 않았으며, Cloud Service Mesh를 새로 설치하거나 새로 배포해야 합니다. 네임스페이스에 istio-injection 및 버전 라벨이 모두 포함된 경우 자동 삽입 동작이 정의되지 않으므로 Cloud Service Mesh 문서의 모든 kubectl label 명령어가 명시적으로 하나만 설정되었는지 확인합니다.
[[["이해하기 쉬움","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-08-20(UTC)"],[],[],null,["# Inject sidecar proxies with Cloud Service Mesh\n==============================================\n\nThis document covers how to configure sidecar proxy injection with Cloud Service Mesh\nto enhance network security, reliability, and observability. These functions are\nabstracted away from the application's primary container and implemented in a\ncommon out-of-process proxy (the sidecar), delivered as a separate container in\nthe same Pod. This provides the\n[Cloud Service Mesh's features](/service-mesh/v1.19/docs/overview) without redesigning your\nproduction applications to participate in a service mesh.\n\nAutomatic sidecar proxy injection (auto-injection) occurs when Cloud Service Mesh\ndetects a namespace label you configure for the workload's Pod. The proxy\nintercepts all inbound and outbound traffic to the workloads and communicates\nwith Cloud Service Mesh.\n\n#### Permissions required for these tasks\n\n\nTo perform the tasks on this page, you must have the\n`roles/container.clusterAdmin` or a higher role. See\n[Google Kubernetes Engine roles](/iam/docs/understanding-roles#container) for\ndetails on the permissions included in this role.\n\nEnabling automatic sidecar injection\n------------------------------------\n\nThe recommended way to inject sidecar proxies is to use the webhooks-based\nautomatic sidecar injector, although you can manually update your Pods'\nKubernetes configuration.\n\nTo enable auto-injection, you label your namespaces with the\n*[default injection labels](https://istio.io/latest/docs/setup/upgrade/canary/#default-tag)*\nif the default tag is set up, or with the\n[revision label](/service-mesh/v1.19/docs/revisions-overview) to your namespace.\nThe label that you add also depends on whether you deployed\nmanaged Cloud Service Mesh (with the\n[fleet API](/service-mesh/v1.19/docs/managed/provision-managed-anthos-service-mesh) or with\n[`asmcli`](/service-mesh/v1.19/docs/managed/provision-managed-anthos-service-mesh-asmcli)), or\ninstalled the in-cluster control plane. The label is used by the sidecar\ninjector webhook to associate injected sidecars with a particular control plane\nrevision.\n\nTo enable auto-injection: \n\n### In-cluster\n\n1. Use the following command to locate the revision label on `istiod`:\n\n kubectl -n istio-system get pods -l app=istiod --show-labels\n\n The output looks similar to the following: \n\n ```bash\n NAME READY STATUS RESTARTS AGE LABELS\n istiod-asm-11910-9-5788d57586-bljj4 1/1 Running 0 23h app=istiod,istio.io/rev=asm-11910-9,istio=istiod,pod-template-hash=5788d57586\n istiod-asm-11910-9-5788d57586-vsklm 1/1 Running 1 23h app=istiod,istio.io/rev=asm-11910-9,istio=istiod,pod-template-hash=5788d57586\n ```\n\n In the output, under the `LABELS` column, note the value of the `istiod`\n revision label, which follows the prefix `istio.io/rev=`. In this\n example, the value is `asm-11910-9`.\n\n\n | **Note:** You can substitute `istio.io/rev` with the `istio-injection=enabled` label if the [default tag](https://istio.io/latest/docs/setup/upgrade/canary/#default-tag) is configured. Verify the default tag exists by running ` istioctl tag list` with the `istioctl` from \u003cvar translate=\"no\"\u003eOUTPUT_DIR\u003c/var\u003e.\n\n \u003cbr /\u003e\n\n2. Apply the revision label to namespaces and remove the istio-injection label\n (if it exists). In the following command, \u003cvar translate=\"no\"\u003eNAMESPACE\u003c/var\u003e is\n the name of the namespace where you want to enable auto-injection, and\n \u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e is the revision label you noted in the\n previous step.\n\n kubectl label namespace \u003cvar translate=\"no\"\u003eNAMESPACE\u003c/var\u003e istio-injection- istio.io/rev=\u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e --overwrite\n\n\n You can ignore the message `\"istio-injection not found\"` in the\n output. That means that the namespace didn't previously have the\n `istio-injection` label, which you should expect in new\n installations of Cloud Service Mesh or new deployments. Because auto-injection\n behavior is undefined when a namespace has both the `istio-injection`\n and the revision label, all `kubectl label` commands in the\n Cloud Service Mesh documentation explicitly ensure that only one is set.\n3. Restart the affected pods, using the steps in the next section.\n\n### Managed service mesh\n\n1. Use the following command to locate the available release channels:\n\n kubectl -n istio-system get controlplanerevision\n\n The output is similar to the following: \n\n NAME AGE\n asm-managed 6d7h\n\n In the output, select the value under the `NAME` column is the\n \u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e label that corresponds to the available\n [release channel](/service-mesh/v1.19/docs/managed/select-a-release-channel#anthos_service_mesh_versions_per_channel)\n for the Cloud Service Mesh version. Apply this label to your namespaces, and\n remove the `istio-injection` label (if it exists).\n In the following command, replace \u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e with the\n revision label you noted above, and replace\n \u003cvar translate=\"no\"\u003eNAMESPACE\u003c/var\u003e` ` with the name of the namespace where you\n want to enable auto-injection: \n\n kubectl label namespace \u003cvar translate=\"no\"\u003eNAMESPACE\u003c/var\u003e istio-injection- istio.io/rev=\u003cvar translate=\"no\"\u003eREVISION\u003c/var\u003e --overwrite\n\n\n You can ignore the message `\"istio-injection not found\"` in the\n output. That means that the namespace didn't previously have the\n `istio-injection` label, which you should expect in new\n installations of Cloud Service Mesh or new deployments. Because auto-injection\n behavior is undefined when a namespace has both the `istio-injection`\n and the revision label, all `kubectl label` commands in the\n Cloud Service Mesh documentation explicitly ensure that only one is set.\n2. Restart the affected pods, using the steps in the next section.\n\n3. If you also deployed the optional\n [Google-managed data plane](/service-mesh/v1.19/docs/managed/provision-managed-anthos-service-mesh#managed-data-plane),\n annotate the `demo` namespace as follows:\n\n kubectl annotate --overwrite namespace \u003cvar translate=\"no\"\u003eYOUR_NAMESPACE\u003c/var\u003e \\\n mesh.cloud.google.com/proxy='{\"managed\":\"true\"}'\n\n### Restart Pods to update sidecar proxies\n\n| **Warning:** Unless you have a load balancer or router setup for [blue-green deployments](https://martinfowler.com/bliki/BlueGreenDeployment.html), make sure you test restarting Pods in a staging environment to verify that your services can handle any potential traffic interruption.\n\nWith automatic sidecar injection, you can update the sidecars for existing Pods\nwith a Pod restart:\n\nHow you restart Pods depends on if they were created as part of a\n[Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).\n\n1. If you used a Deployment, restart the Deployment, which restarts all Pods\n with sidecars:\n\n ```\n kubectl rollout restart deployment -n YOUR_NAMESPACE\n ```\n\n If you didn't use a Deployment, delete the Pods, and they are automatically\n recreated with sidecars: \n\n ```\n kubectl delete pod -n YOUR_NAMESPACE --all\n ```\n2. Check that all the Pods in the namespace have sidecars injected:\n\n ```\n kubectl get pod -n YOUR_NAMESPACE\n ```\n\n In the following example output from the previous command, notice that the\n `READY` column indicates there are two containers for each of your\n workloads: the primary container and the container for the sidecar proxy. \n\n ```\n NAME READY STATUS RESTARTS AGE\n YOUR_WORKLOAD 2/2 Running 0 20s\n ...\n ```\n\nWhat's next\n-----------\n\nLearn more about:\n\n- [Cloud Service Mesh control plane revisions](/service-mesh/v1.19/docs/revisions-overview)\n- [Deploying workloads](/kubernetes-engine/docs/how-to/deploying-workloads-overview)\n- [Customizing injection](https://istio.io/latest/docs/setup/additional-setup/sidecar-injection/#customizing-injection)"]]
