IP 매스커레이드는 다대일 IP 주소 변환을 수행하는 데 사용되는 네트워크 주소 변환(NAT)의 일종입니다. 이를 통해 여러 클라이언트가 단일 IP 주소에서 대상에 액세스할 수 있게 해줍니다.
Cloud Composer는 GKE에서 워크로드를 실행합니다. 올바른 함수를 위해 노드(VM)뿐만 아니라 GKE 포드와 서비스의 IP 범위가 필요합니다. Airflow DAG 및 태스크가 다른 서비스와 통신하는 경우 포드 IP를 사용하며 이러한 포드 IP 범위는 태스크가 상호작용하는 모든 대상과 라우팅할 수 있어야 합니다.
IP 매스커레이드 에이전트를 사용할 경우 포드 IP 주소를 노드 IP 주소로 변환할 수 있으므로, Airflow DAG 및 태스크에서 타겟팅된 대상과 서비스가 포드 IP 주소 대신 노드 IP 주소에서만 패킷을 수신하도록 할 수 있습니다. 이 방식은 노드 IP 주소에서만 패킷을 수신할 것으로 예상되거나 포드 IP 범위를 클러스터 외부에서 라우팅할 수 없는 환경에서 유용합니다.
또한 IP 매스커레이드 에이전트를 사용하여 네트워킹 구성에 네트워크 범위를 저장할 수 있습니다. 예를 들어 환경 클러스터 내부의 포드에 별도의 네트워크 범위를 사용하고 이 트래픽을 노드 IP 주소 범위에서 발생하는 것으로 매스커레이드할 수 있습니다. 이러한 방식으로 환경 클러스터의 포드에 다른 범위의 IP 주소를 사용하여 IP 주소 공간을 범위 하나에 저장합니다.
예를 들면 다음과 같습니다.
VM에 10.0.0.0/8 범위를 사용하며 이 범위만 방화벽 규칙에서 허용합니다.
네트워크 범위를 저장하려면 환경 클러스터의 포드에 다른 범위(예: 192.168.0.0/16)를 사용합니다.
포드(Airflow 작업자)에서 모든 서비스에 연결할 수 있으려면 IP 매스커레이딩이 필요합니다. 그렇지 않으면 서비스가 방화벽 규칙으로 인해 192.168.0.0/16에서 트래픽을 수신하고 삭제합니다. IP 매스커레이드 에이전트가 사용 설정 및 구성되면 서비스는 10.0.0.0/8에서 요청을 받고 수락합니다.
시작하기 전에
Google Cloud 콘솔에서는 IP 매스커레이드 에이전트를 사용 설정할 수 없습니다.
이 기능을 사용하려면 GKE 1.22.7 이상 버전을 사용하여 환경을 만들어야 합니다.
GKE가 1.22.7 이상 버전으로 업그레이드되더라도 이전 GKE 버전에서 생성된 환경에서는 IP 매스커레이드 에이전트를 사용할 수 없습니다.
IP 매스커레이드 에이전트를 사용 설정하면 기본 GKE의 EgressNatPolicy가 Cloud Composer의 정의로 대체됩니다. IP 마스커레이드 에이전트가 사용 설정되지 않으면 발신 트래픽이 마스커레이드되지 않으며 기본 GKE의 EgressNatPolicy를 사용합니다.
// POST https://composer.googleapis.com/v1/{parent=projects/*/locations/*}/environments{"name":"projects/example-project/locations/us-central1/environments/example-environment","config":{"softwareConfig":{"imageVersion":"composer-2.13.9-airflow-2.10.5"},"nodeConfig":{"enableIpMasqAgent":true}}}
Terraform
환경을 만들 때 node_config 블록의 enable_ip_masq_agent 필드에서 IP 매스커레이드 에이전트를 사용 설정합니다.
[[["이해하기 쉬움","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-26(UTC)"],[[["\u003cp\u003eThe IP Masquerade agent in Cloud Composer allows multiple clients to access a destination from a single IP address, translating Pod IP addresses to node IP addresses.\u003c/p\u003e\n"],["\u003cp\u003eEnabling the IP Masquerade agent is recommended to manage IP address shortages and ensure that services only receive packets from node IP addresses, which is useful when Pod IP ranges are not routable outside of the cluster.\u003c/p\u003e\n"],["\u003cp\u003eYou can only enable the IP Masquerade agent during the creation of a new environment with GKE version 1.22.7 or later, and it cannot be enabled for existing environments.\u003c/p\u003e\n"],["\u003cp\u003eThe IP Masquerade agent can be enabled via the \u003ccode\u003egcloud\u003c/code\u003e command-line tool, the API, or Terraform, using specific configurations for each method, but not through the Google Cloud console.\u003c/p\u003e\n"],["\u003cp\u003eWhen configuring the IP Masquerade agent, non-masquerade destinations must at least include the cluster's node and Pod IP address ranges due to Cloud Composer enabling intranode visibility.\u003c/p\u003e\n"]]],[],null,["\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\n[Cloud Composer 3](/composer/docs/composer-3/change-networking-type#comparison \"View this page for Cloud Composer 3\") \\| **Cloud Composer 2** \\| [Cloud Composer 1](/composer/docs/composer-1/enable-ip-masquerade-agent \"View this page for Cloud Composer 1\")\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\nThis page describes how to enable the IP Masquerade agent for your environment.\n| **Important:** Consider using the IP Masquerade agent if your project is impacted by the shortage of IP addresses. By enabling the IP Masquerade agent, you can use your environment's cluster IP addresses to communicate with external services.\n\nAbout the IP Masquerade agent in Cloud Composer\n\nCloud Composer supports\nthe [IP Masquerade agent](/kubernetes-engine/docs/how-to/ip-masquerade-agent) for your environments.\n\n*IP masquerading* is a form of network address translation (NAT) used to\nperform many-to-one IP address translations. This allows multiple clients to\naccess a destination from a single IP address.\n\nCloud Composer runs your workloads on GKE. For\ncorrect function, it requires IP ranges for nodes (VMs) as well as\nGKE Pods and Services. When Airflow DAGs and tasks\ncommunicate with other services, they use Pod IPs and these Pod IP ranges need\nto be routable to and from any destinations that the tasks interact with.\n\nWith the IP Masquerade agent, you have the option to translate Pod IP\naddresses to node IP addresses, so that destinations and services targeted\nfrom Airflow DAGs and tasks only receive packets from node IP addresses\ninstead of Pod IP addresses. This is useful in environments that expect to\nonly receive packets from node IP addresses or where Pod IP ranges are not\nroutable outside of the cluster.\n\nIn addition, you can use the IP Masquerade agent to save network ranges in\nyour networking configuration. For example, you can use a separate network\nrange for Pods inside your environment's cluster and masquerade this traffic\nas coming from the node IP address range. In this way, you save IP address\nspace in one range by using IP addresses from a different range for Pods in\nyour environment's cluster.\n\nFor example:\n\n1. You use the `10.0.0.0/8` range for VMs and only this range is allowed by\n your firewall rules.\n\n2. To save network ranges, you use a different range (for example,\n `192.168.0.0/16`) for Pods in your environment's cluster.\n\n3. To be able to connect to any service from a Pod (Airflow worker), IP\n masquerading is needed; otherwise the service receives traffic from\n `192.168.0.0/16` and drops it because of a firewall rule. With the IP\n Masquerade agent enabled and configured, the service gets requests from\n `10.0.0.0/8`, which are accepted.\n\nBefore you begin\n\n- It is not possible to enable the IP Masquerade agent in Google Cloud console.\n\n- To use this feature, you must create an environment with GKE\n 1.22.7 or later version.\n\n- The IP Masquerade agent is not available for environments that were created\n in earlier GKE versions, even if GKE was\n upgraded to 1.22.7 and later versions.\n\n- If you enable the IP Masquerade agent, the default\n [GKE's EgressNatPolicy](/kubernetes-engine/docs/how-to/egress-nat-policy-ip-masq-autopilot) will be\n replaced with Cloud Composer's definition. If the IP Masquerade\n agent is not enabled, the outgoing traffic won't be masqueraded and will\n use the default GKE's EgressNatPolicy.\n\nEnable the IP Masquerade agent for an existing environment\n\nIt is not possible to enable the IP Masquerade agent for an existing\nenvironment.\n\nEnable the IP Masquerade agent when creating an environment\n\nYou can enable the IP Masquerade agent when you create an environment.\n\nFor more information about creating Cloud Composer environments,\nsee [Create environment](/composer/docs/composer-2/create-environments). \n\nConsole\n\nIt is not possible to enable the IP Masquerade agent in Google Cloud console.\n\ngcloud\n\nWhen you create an environment, the `--enable-ip-masq-agent` argument\nenables the IP Masqerade agent. \n\n gcloud composer environments create \u003cvar translate=\"no\"\u003eENVIRONMENT_NAME\u003c/var\u003e \\\n --location \u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e \\\n --image-version composer-2.14.1-airflow-2.10.5 \\\n --enable-ip-masq-agent\n\nReplace:\n\n- `ENVIRONMENT_NAME` with the name of the environment.\n- `LOCATION` with the region where the environment is located.\n\nExample: \n\n gcloud composer environments create example-environment \\\n --location us-central1 \\\n --image-version composer-2.14.1-airflow-2.10.5 \\\n --enable-ip-masq-agent\n\nAPI\n\nConstruct an [`environments.create`](/composer/docs/reference/rest/v1/projects.locations.environments/create) API request.\nSpecify the configuration in the [`Environment`](/composer/docs/reference/rest/v1/projects.locations.environments#Environment)\nresource. \n\n {\n \"name\": \"projects/\u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e/locations/\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e/environments/\u003cvar translate=\"no\"\u003eENVIRONMENT_NAME\u003c/var\u003e\",\n \"config\": {\n \"softwareConfig\": {\n \"imageVersion\": \"composer-2.14.1-airflow-2.10.5\"\n },\n \"nodeConfig\": {\n \"enableIpMasqAgent\": true\n }\n }\n }\n\nReplace:\n\n- `PROJECT_ID` with the [Project ID](/resource-manager/docs/creating-managing-projects).\n- `LOCATION` with the region where the environment is located.\n- `ENVIRONMENT_NAME` with the environment name.\n\nExample: \n\n // POST https://composer.googleapis.com/v1/{parent=projects/*/locations/*}/environments\n\n {\n \"name\": \"projects/example-project/locations/us-central1/environments/example-environment\",\n \"config\": {\n \"softwareConfig\": {\n \"imageVersion\": \"composer-2.14.1-airflow-2.10.5\"\n },\n \"nodeConfig\": {\n \"enableIpMasqAgent\": true\n }\n }\n }\n\nTerraform\n\nWhen you create an environment, the `enable_ip_masq_agent`\nfield in the `node_config` block enables the IP Masqerade agent. \n\n resource \"google_composer_environment\" \"example_environment\" {\n provider = google-beta\n name = \"\u003cvar translate=\"no\"\u003eENVIRONMENT_NAME\u003c/var\u003e\"\n region = \"\u003cvar translate=\"no\"\u003eLOCATION\u003c/var\u003e\"\n\n config {\n software_config {\n image_version = \"composer-2.14.1-airflow-2.10.5\"\n }\n node_config {\n enable_ip_masq_agent = true\n }\n }\n\nReplace:\n\n- `ENVIRONMENT_NAME` with the name of the environment.\n- `LOCATION` with the region where the environment is located.\n\nExample: \n\n resource \"google_composer_environment\" \"example_environment\" {\n provider = google-beta\n name = \"example-environment\"\n region = \"us-central1\"\n\n config {\n software_config {\n image_version = \"composer-2.14.1-airflow-2.10.5\"\n }\n node_config {\n enable_ip_masq_agent = true\n }\n }\n }\n\nConfigure the IP Masquerade agent **Caution:** Cloud Composer enables [intranode visibility](/kubernetes-engine/docs/how-to/intranode-visibility) on GKE clusters. Therefore, non-masquerade destinations must at least include the cluster's node and Pod IP address range(s).\n\nFor more information about using and configuring the IP Masquerade agent in\nCloud Composer 2, see\n[Use Egress NAT Policy to configure IP masquerade in Autopilot clusters](/kubernetes-engine/docs/how-to/egress-nat-policy-ip-masq-autopilot).\n\n\nWhat's next\n\n- [Create an environment](/composer/docs/composer-2/create-environments)\n- [Configure Shared VPC networking](/composer/docs/composer-2/configure-shared-vpc)\n- [Configure Private IP networking](/composer/docs/composer-2/configure-private-ip)"]]
