빠른 연결 구성

프리뷰 — 빠른 연결

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

앰비언트 네트워킹의 빠른 연결을 사용하면 애플리케이션에 인증 코드를 작성하거나 서비스 메시를 구성하지 않고도 소스 Cloud Run 서비스를 동일한 프로젝트 및 리전의 대상 Cloud Run 서비스에 연결할 수 있습니다.

Cloud Run 서비스가 다른 Identity and Access Management(IAM)로 보호되는 Cloud Run 서비스를 호출하는 경우 대상이 호출자의 ID와 권한을 확인할 수 있도록 요청에 OpenID Connect(OIDC) ID 토큰이 포함되어야 합니다. 빠른 연결이 없으면 애플리케이션에 서비스 간 인증 코드를 작성하여 메타데이터 서버에서 토큰을 가져와 연결하거나 가상 프라이빗 클라우드(VPC) 네트워크, 백엔드 서비스, 라우팅 규칙과 같은 Cloud Service Mesh 리소스를 구성해야 합니다. 빠른 연결은 이 인증 및 라우팅 작업을 완전 관리형 주변 사이드카 컨테이너로 오프로드하여 애플리케이션 코드의 이식성을 유지하고 비즈니스 로직에 집중할 수 있도록 합니다.

사용 사례

다음 시나리오에 빠른 연결을 사용할 수 있습니다.

• 애플리케이션 코드에서 서비스 간 인증 오프로드: 일반 HTTP를 통해 호출 Cloud Run 서비스를 IAM으로 보호되는 대상 Cloud Run 서비스에 연결합니다. 앰비언트 사이드카는 소스 서비스의 OIDC ID 토큰을 자동으로 가져와 삽입하고 HTTPS를 통해 요청을 암호화합니다.
• 커스텀 호스트 이름으로 도착 URL 추상화: 소스 애플리케이션이 대상의 결정론적 URL을 하드코딩하는 대신 http://my-backend과 같은 논리적 주소로 요청을 전송하도록 --matches-hostname 플래그를 사용하여 빠른 연결에서 커스텀 호스트 이름을 구성합니다. 대상 서비스가 변경되면 소스 애플리케이션 코드를 수정하거나 다시 배포하지 않고도 새 대상을 가리키도록 빠른 연결을 다시 만들 수 있습니다.
• 서비스 메시 없이 지점 간 서비스 호출 간소화: Cloud Service Mesh에 필요한 VPC 네트워크, 네트워크 엔드포인트 그룹, 백엔드 서비스, Cloud DNS 레코드를 프로비저닝하지 않고도 Cloud Run 서비스 간에 자동 사용자 인증 정보 삽입을 수행할 수 있습니다.

다음 표에서는 빠른 연결을 사용하지 않는 경우와 사용하는 경우의 인증된 서비스 간 통신을 설정하는 단계를 비교합니다.

단계	빠른 연결 없음	빠른 연결 사용
1. 대상 서비스 배포	IAM 인증이 필요한 대상 Cloud Run 서비스를 배포합니다(--no-allow-unauthenticated).	같습니다.
2. 호출자 권한 부여	대상 서비스에 대한 Cloud Run 호출자(roles/run.invoker) 역할을 소스 서비스의 서비스 계정에 부여합니다.	같습니다.
3. 아웃바운드 요청 구성	소스 애플리케이션에서 코드를 작성하여 도착 URL의 OIDC ID 토큰을 가져오고 HTTPS를 통해 Authorization: Bearer 헤더에 연결합니다.	소스 애플리케이션에서 인증 코드 없이 도착 URL 또는 커스텀 호스트 이름으로 일반 http:// 요청을 보냅니다.
4. 소스 서비스 배포	소스 Cloud Run 서비스를 배포합니다.	앰비언트 네트워킹이 사용 설정된 소스 Cloud Run 서비스를 배포한 후 배포된 소스 서비스와 대상 서비스 간에 빠른 연결을 만듭니다.

아키텍처

소스 Cloud Run 서비스에서 앰비언트 네트워킹을 사용 설정하고 빠른 연결을 만들면 Cloud Run은 각 컨테이너 인스턴스에서 애플리케이션 컨테이너와 함께 실행되는 완전 관리형 Envoy 사이드카 컨테이너를 구성합니다.

애플리케이션이 대상 서비스의 결정론적 URL 또는 빠른 연결에서 구성한 커스텀 호스트 이름으로 일반 HTTP 요청을 전송하면 앰비언트 사이드카 컨테이너가 자동으로 다음을 수행합니다.

1. 대상 서비스를 대상으로 하는 아웃바운드 HTTP 요청을 가로챕니다.
2. 소스 서비스의 서비스 계정에 대한 OIDC ID 토큰을 가져와 Authorization 헤더에 삽입합니다.
3. HTTPS(단방향 TLS)를 통해 요청을 암호화하고 호출자의 IAM 권한을 확인하는 대상 Cloud Run 서비스로 전달합니다.

그림 1. 앰비언트 사이드카 컨테이너는 소스 서비스의 아웃바운드 요청을 가로채고, OIDC ID 토큰을 삽입하고, HTTPS(단방향 TLS)를 통해 요청을 대상 서비스로 전달합니다.

네트워크 연결 및 데이터 영역

빠른 연결은 Ambient 사이드카에서 아웃바운드 요청 가로채기 및 사용자 인증 정보 삽입을 구성하지만 서비스 간의 기본 네트워크 경로를 대체하지는 않습니다. 소스 서비스가 대상 서비스의 인그레스 경로에 도달할 수 있는지 확인해야 합니다.

• 대상 인그레스가 모두로 설정됨: 소스 서비스에 VPC 네트워크 또는 아웃바운드 이그레스 구성이 필요하지 않습니다.
• 대상 인그레스가 내부 또는 내부 및 Cloud 부하 분산기로 설정됨: VPC 직접 연결 또는 비공개 Google 액세스가 사용 설정된 서버리스 VPC 액세스 커넥터를 사용하여 승인된 VPC 네트워크를 통해 소스 서비스에서 아웃바운드 트래픽을 라우팅해야 합니다. 자세한 내용은 다른 Cloud Run 서비스에서 요청 수신을 참조하세요.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Cloud Run, Network Services, Traffic Director API가 아직 사용 설정되지 않은 경우 사용 설정합니다.

   API 사용 설정에 필요한 역할

   API를 사용 설정하려면 serviceusage.services.enable 권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할(roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할(roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할 부여 방법 알아보기

   API 사용 설정

2. 동일한 프로젝트 및 리전에 기존 소스 Cloud Run 서비스와 기존 대상 Cloud Run 서비스가 있는지 확인합니다.
3. 소스 Cloud Run 서비스에서 global 범위를 사용하여 앰비언트 네트워킹이 사용 설정되어 있는지 확인합니다. 예를 들어 gcloud beta run services update SOURCE_SERVICE --ambient-networking --ambient-scope=global --region=REGION를 실행하고 먼저 서비스의 CPU 및 메모리 한도를 늘려야 합니다.

4. 앰비언트 네트워킹 사이드카 사용량에 대한 Cloud Run 가격 책정 페이지를 읽어보세요. 미리보기 중에는 주변 기능에 대한 결제가 시행되지 않습니다.

필요한 역할

빠른 연결을 구성하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 빠른 연결 구성: 프로젝트에 대한 Cloud Run 개발자(roles/run.developer) 및 서비스 계정 사용자(roles/iam.serviceAccountUser)
• 빠른 연결 리소스 관리: 프로젝트의 네트워크 서비스 관리자(roles/networkservices.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

소스 Cloud Run 서비스의 서비스 ID에도 프로젝트에 대한 다음 역할이 있어야 합니다.

• Traffic Director 클라이언트(roles/trafficdirector.client)
• Cloud Trace 에이전트(roles/cloudtrace.agent)

서비스 ID에 이러한 역할을 부여하려면 gcloud를 사용합니다.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:RUN_CLIENT_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/cloudtrace.agent"

다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• RUN_CLIENT_SA: 소스 Cloud Run 서비스에 연결된 서비스 계정의 이름입니다.

Cloud Run 서비스 ID에 이러한 역할이 없으면 Cloud Run 서비스가 배포되지만 앰비언트 네트워킹에 종속된 기능은 작동하지 않습니다. 이 동작은 필수 역할이 누락된 경우 Cloud Run 서비스가 배포되지 않는 Cloud Service Mesh와 다릅니다.

제한사항

빠른 연결에는 다음과 같은 제한사항이 적용됩니다.

• Cloud Run 서비스만 소스 및 대상 리소스로 지원됩니다. Cloud Run 작업, 작업자 풀, 인스턴스는 지원되지 않습니다.
• 프로젝트 간 및 리전 간 구성은 지원되지 않습니다. 소스 Cloud Run 서비스와 대상 Cloud Run 서비스는 동일한 프로젝트 및 리전에 있어야 합니다.
• 빠른 연결을 사용하려면 소스 서비스에 global 범위가 있는 앰비언트 네트워킹이 필요합니다. 소스 서비스에서 regional 범위를 사용하는 경우 빠른 연결이 생성되지만 트래픽이 라우팅되지 않습니다.
• 빠른 연결을 만들기 전에 소스 및 대상 Cloud Run 서비스를 만들어야 합니다. 순서가 맞지 않는 생성은 지원되지 않습니다. 대상 서비스를 삭제하면 빠른 연결을 삭제하거나 다시 만들 때까지 빠른 연결이 오래된 구성을 계속 표시하고 제공할 수 있습니다.
• 기존 빠른 연결의 소스 서비스, 대상 서비스 또는 커스텀 호스트 이름을 제자리에서 업데이트할 수 없습니다. gcloud beta network-services express-links update 명령어는 빠른 연결 설명만 업데이트합니다. 라우팅 구성을 변경하려면 빠른 연결을 삭제하고 다시 만듭니다.
• 커스텀 URL, 커스텀 도메인을 사용하거나 --matches-hostname 플래그를 사용하여 커스텀 호스트 이름을 구성하는 경우에도 대상 Cloud Run 서비스에 기본 run.app URL이 사용 설정되어 있어야 합니다.
• 대상 위치의 비결정적 URL로 전송된 요청은 가로채지 않으며 403 Forbidden 오류와 함께 실패합니다. 결합된 서비스 이름과 프로젝트 번호가 63자를 초과하여 대상 서비스에 결정론적 URL이 없는 경우 --matches-hostname를 지정해야 합니다. 그렇지 않으면 빠른 연결 만들기가 실패하고 Cloud Run Service name is too long 오류가 발생합니다.
• 빠른 연결의 전체 상태를 볼 때 대상 서비스 정보만 반환됩니다. 소스 Cloud Run 버전 및 협상된 인증에 대한 세부정보가 누락되거나 오래된 데이터가 표시될 수 있습니다. 이는 빠른 연결이 트래픽을 라우팅하거나 인증하는 방식에 영향을 미치지 않습니다.
• 에이전트 ID 및 mTLS 바인딩 토큰으로 구성된 소스 Cloud Run 서비스는 지원되지 않습니다.
• Cloud Run의 Agent Gateway 및 Secure Web Proxy를 통해 아웃바운드 트래픽을 라우팅하도록 구성된 소스 Cloud Run 서비스는 지원되지 않습니다. 빠른 연결에는 전역 앰비언트 네트워킹 범위가 필요하지만 Agent Gateway에는 리전 범위가 필요합니다.
• 소스 서비스의 아웃바운드 요청에 이미 Authorization 헤더가 포함되어 있으면 빠른 연결은 해당 헤더를 변경하지 않고 요청을 전달하며 토큰을 삽입하지 않습니다. X-Serverless-Authorization 헤더에 대한 자동 토큰 삽입은 지원되지 않습니다.
• Cloud Run 샌드박스 컨테이너에서 생성된 트래픽은 지원되지 않습니다.
• 빠른 연결을 사용하여 IAP(Identity-Aware Proxy)로 보호되는 대상 Cloud Run 서비스로 트래픽을 전달할 수 없습니다.
• 각 빠른 연결은 하나의 대상 Cloud Run 서비스를 지원하며 프로젝트당 최대 5,000개의 빠른 연결을 만들 수 있습니다.

빠른 연결 구성

Cloud Run 서비스를 연결하려면 소스 서비스와 대상 서비스를 지정하는 빠른 연결을 만든 다음 대상 서비스에 Cloud Run 호출자 역할을 부여합니다.

다른 Cloud Run 서비스에 연결

소스 Cloud Run 서비스를 대상 Cloud Run 서비스에 연결하려면 gcloud 또는 YAML을 사용하여 빠른 연결을 만듭니다.

gcloud

gcloud beta network-services express-links create 명령어를 사용하여 빠른 연결을 만듭니다.

gcloud beta network-services express-links create EXPRESS_LINK_NAME \
    --location=global \
    --source-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE \
    --destination-services=//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE

다음을 바꿉니다.

• EXPRESS_LINK_NAME: 빠른 연결의 이름입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• REGION: Cloud Run 서비스가 배포된 리전입니다.
• SOURCE_SERVICE: 소스 Cloud Run 서비스의 이름입니다.
• DESTINATION_SERVICE: 대상 Cloud Run 서비스의 이름입니다.

명령어가 완료된 후 라우팅 구성이 실행 중인 소스 서비스 인스턴스에 전파되는 데 최대 2분이 걸릴 수 있습니다.

기본적으로 빠른 연결은 비결정론적 URL이 아닌 대상 서비스의 결정론적 URL로 전송된 요청만 가로챕니다. 커스텀 호스트 이름을 사용하려면 --matches-hostname="HOSTNAME" 플래그에 스키마 없이 호스트 이름을 전달하고(예: --matches-hostname="DESTINATION_SERVICE") 소스 애플리케이션에서 http://HOSTNAME로 요청을 보냅니다. --matches-hostname를 지정하면 결정론적 URL에 추가하는 대신 대체합니다.

YAML

1. 구성 파일(예: express-link.yaml)을 만듭니다.

   name: "projects/PROJECT_ID/locations/global/expressLinks/EXPRESS_LINK_NAME"
   source:
     services:
       - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SOURCE_SERVICE"
   destination:
     services:
       - "//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/DESTINATION_SERVICE"

   다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
   • REGION: 서비스가 배포된 리전입니다.
   • EXPRESS_LINK_NAME: 빠른 연결의 이름입니다.
   • SOURCE_SERVICE: 소스 Cloud Run 서비스의 이름입니다.
   • DESTINATION_SERVICE: 대상 Cloud Run 서비스의 이름입니다.

2. gcloud beta network-services express-links import 명령어를 사용하여 YAML 파일을 가져옵니다.

   gcloud beta network-services express-links import EXPRESS_LINK_NAME \
       --location=global \
       --source=YAML_FILENAME.yaml

   다음을 바꿉니다.

   • EXPRESS_LINK_NAME: 빠른 연결의 이름입니다.
   • YAML_FILENAME: YAML 파일의 이름입니다.

대상 서비스에 호출자 권한 부여

소스 서비스가 IAM으로 보호되는 대상 서비스를 호출하도록 허용하려면 대상 Cloud Run 서비스의 소스 서비스 계정에 Cloud Run 호출자(roles/run.invoker) 역할을 부여합니다. 이는 데이터 영역에서 인증이 작동하는 데 필요합니다.

gcloud run services add-iam-policy-binding DESTINATION_SERVICE \
    --member="serviceAccount:SOURCE_SA@PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/run.invoker" \
    --region=REGION

다음을 바꿉니다.

• DESTINATION_SERVICE: 대상 Cloud Run 서비스의 이름입니다.
• SOURCE_SA: 소스 Cloud Run 서비스에 연결된 서비스 계정의 이름입니다.
• PROJECT_ID: Google Cloud 프로젝트 ID입니다.
• REGION: 대상 서비스가 배포된 리전입니다.

빠른 연결 상태 확인

빠른 연결의 기본 구성을 보려면 gcloud beta network-services express-links describe 명령어를 사용합니다.

gcloud beta network-services express-links describe EXPRESS_LINK_NAME \
    --location=global

connectionStatus(활성 경로 유형, 일치하는 호스트 이름, 소스 버전 URI) 및 cloudRunSourceInfo(구성된 인증 방법 및 VPC 네트워크)를 포함한 빠른 연결의 전체 상태를 보려면 리소스 이름에 ?view=EXPRESS_LINK_VIEW_FULL#를 포함합니다.

gcloud beta network-services express-links describe 'EXPRESS_LINK_NAME?view=EXPRESS_LINK_VIEW_FULL#' \
    --location=global

EXPRESS_LINK_NAME을 빠른 연결의 이름으로 바꿉니다. 전체 뷰를 쿼리할 때는 작은따옴표와 후행 # 문자를 유지합니다.

빠른 연결 삭제 또는 다시 만들기

빠른 연결을 삭제하고 소스 서비스에서 자동 사용자 인증 정보 삽입 및 트래픽 가로채기를 중지하려면 gcloud beta network-services express-links delete 명령어를 사용합니다.

gcloud beta network-services express-links delete EXPRESS_LINK_NAME \
    --location=global

EXPRESS_LINK_NAME을 빠른 연결의 이름으로 바꿉니다.

기존 빠른 연결을 다른 대상 서비스로 가리키거나 --matches-hostname 설정을 변경하려면 이전 명령어로 빠른 연결을 삭제한 후 업데이트된 구성으로 새 빠른 연결을 만듭니다.

다음 단계

• Cloud Run 서비스에 앰비언트 네트워킹을 구성하는 방법을 알아봅니다.
• Cloud Run의 Agent Gateway 알아보기
• Cloud Run의 서비스 간 인증 알아보기
• Cloud Run 서비스의 네트워크 엔드포인트 인그레스를 제한하는 방법을 알아보세요.