設定 express link

預先發布版 - Express link

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

透過周邊網路上的 express link，您可以將來源 Cloud Run 服務連結至相同專案和區域中的目的地 Cloud Run 服務，不必在應用程式中編寫驗證程式碼，也不用設定服務網格。

當 Cloud Run 服務呼叫其他受 Identity and Access Management (IAM) 保護的 Cloud Run 服務時，要求必須包含 OpenID Connect (OIDC) ID 權杖，目的地才能驗證呼叫者的身分和權限。如果沒有 express link，您必須在應用程式中編寫服務對服務驗證程式碼，從中繼資料伺服器擷取並附加權杖，或設定 Cloud Service Mesh 資源，例如虛擬私有雲 (VPC) 網路、後端服務和路由規則。express link 會將這項驗證和轉送工作卸載至全代管的 ambient 邊車容器，讓應用程式程式碼保持可攜性，並專注於商業邏輯。

用途

express link 適用於下列情境：

• 從應用程式程式碼卸載服務對服務驗證：透過一般 HTTP，將呼叫 Cloud Run 服務連結至受 IAM 保護的目的地 Cloud Run 服務。Ambient sidecar 會自動擷取並插入來源服務的 OIDC ID 權杖，並透過 HTTPS 加密要求。
• 使用自訂主機名稱抽象化到達網頁網址：使用 --matches-hostname 旗標在 express link 設定自訂主機名稱，讓來源應用程式將要求傳送至邏輯位址 (例如 http://my-backend)，而不是硬式編碼目的地的確定性網址。如果目的地服務有所變更，您可以重新建立 express link，指向新的目的地，不必修改或重新部署來源應用程式程式碼。
• 簡化點對點服務呼叫，不需使用服務網格：在 Cloud Run 服務之間自動插入憑證，不需佈建 Cloud Service Mesh 所需的虛擬私有雲網路、網路端點群組、後端服務或 Cloud DNS 記錄。

下表比較有無 express link 時，設定已驗證服務對服務通訊的步驟：

步驟	不使用 express link	使用 express link
1. 部署目的地服務	部署目的地 Cloud Run 服務，並要求 IAM 驗證 (--no-allow-unauthenticated)。	相同。
2. 授予叫用者權限	將目的地服務的 Cloud Run 叫用者 (roles/run.invoker) 角色授予來源服務的服務帳戶。	相同。
3. 設定傳出要求	在來源應用程式中編寫程式碼，擷取到達網頁網址的 OIDC ID 權杖，並透過 HTTPS 將權杖附加至 Authorization: Bearer 標頭。	在來源應用程式中，將不含驗證碼的一般 http:// 要求傳送至到達網頁網址或自訂主機名稱。
4. 部署來源服務	部署來源 Cloud Run 服務。	部署來源 Cloud Run 服務，並啟用周邊網路，然後在部署的來源和目的地服務之間建立 express link。

架構

在來源 Cloud Run 服務上啟用周邊網路並建立 express link 時，Cloud Run 會設定全代管 Envoy 邊車容器，在每個容器執行個體中與應用程式容器一起執行。

當應用程式將純 HTTP 要求傳送至目的地服務的確定性網址，或您在 express link 設定的自訂主機名稱時，ambient 邊車容器會自動執行下列操作：

1. 攔截傳送至目標服務的傳出 HTTP 要求。
2. 擷取來源服務服務帳戶的 OIDC ID 權杖，並將其插入 Authorization 標頭。
3. 透過 HTTPS (單向 TLS) 加密要求，並將要求轉送至目的地 Cloud Run 服務，該服務會驗證呼叫者的 IAM 權限。

圖 1. ambient 邊車容器會攔截來源服務的傳出要求、插入 OIDC ID 權杖，並透過 HTTPS (單向 TLS) 將要求轉送至目的地服務。

網路連線和資料層

express link 會在 ambient sidecar 中設定傳出要求攔截和憑證插入，但不會取代服務之間的基礎網路路徑。您仍須確保來源服務可以連上目的地服務的輸入路徑：

• 目的地輸入設為「All」(全部)：來源服務不需要虛擬私有雲網路或輸出設定。
• 目的地輸入設為「Internal」(內部) 或「Internal and Cloud Load Balancers」(內部和 Cloud Load Balancer)：您必須使用直接虛擬私有雲輸出或無伺服器 VPC 存取連接器，並啟用私人 Google 存取權，透過授權的虛擬私有雲網路轉送來源服務的傳出流量。詳情請參閱「接收來自其他 Cloud Run 服務的要求」。

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $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 所需的角色

   如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (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 定價頁面，瞭解周邊網路 Sidecar 的用量。預先發布版期間，不會強制收取 Ambient 功能費用。

必要的角色

如要取得設定 express link 所需的權限，請要求管理員授予您下列 IAM 角色：

• 設定 express link：專案的 Cloud Run 開發人員 (roles/run.developer) 和服務帳戶使用者 (roles/iam.serviceAccountUser)
• 管理 express link 資源：專案的網路服務管理員 (roles/networkservices.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

來源 Cloud Run 服務的服務身分也必須具備專案的下列角色：

• Traffic Director 用戶端 (roles/trafficdirector.client)
• Cloud Trace 代理 (roles/cloudtrace.agent)

如要將這些角色授予服務身分，請使用 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 服務身分缺少這些角色，Cloud Run 服務仍會部署，但依賴周邊網路的功能將無法運作。這與 Cloud Service Mesh 的行為不同，後者在缺少必要角色時，會無法部署 Cloud Run 服務。

限制

express link 有下列限制：

• 僅支援 Cloud Run 服務做為來源和目的地資源。不支援 Cloud Run 工作、worker 集區和執行個體。
• 不支援跨專案和跨區域設定。來源 Cloud Run 服務和目的地 Cloud Run 服務必須位於相同專案和區域。
• Express link 必須在來源服務上啟用周邊網路，並設定 global 範圍。如果來源服務使用 regional 範圍，系統會成功建立 express link，但不會轉送流量。
• 您必須先建立來源和目的地 Cloud Run 服務，才能建立 express link。不支援不按順序建立。如果刪除目的地服務，express link 會繼續顯示並提供過時的設定，直到您刪除或重新建立 express link 為止。
• 您無法直接更新現有 express link 的來源服務、目的地服務或自訂主機名稱。gcloud beta network-services express-links update 指令只會更新 express link 說明。如要變更轉送設定，請刪除並重新建立 express link。
• 目的地 Cloud Run 服務必須啟用預設 run.app 網址，即使您使用自訂網址、自訂網域，或使用 --matches-hostname 旗標設定自訂主機名稱，也必須啟用。
• 傳送至目的地非確定性網址的要求不會遭到攔截，並會失敗並顯示 403 Forbidden 錯誤。如果目的地服務沒有確定性網址 (因為服務名稱和專案編號合計超過 63 個字元)，則必須指定 --matches-hostname，否則 express link 建立作業會失敗，並顯示 Cloud Run Service name is too long 錯誤。
• 查看 express link 的完整狀態時，系統只會傳回目的地服務資訊。來源 Cloud Run 修訂版本和協商驗證的詳細資料可能遺失或顯示過時資料。這不會影響 express link 轉送或驗證流量的方式。
• 不支援設定代理程式身分和 mTLS 繫結權杖的來源 Cloud Run 服務。
• 不支援設定為透過 Cloud Run 上的 Agent Gateway 和 Secure Web Proxy 轉送傳出流量的來源 Cloud Run 服務。Express Link 需要全域周邊網路範圍，Agent Gateway 則需要區域範圍。
• 如果來源服務的傳出要求已包含 Authorization 標頭，express link 會轉送該要求，並保留該標頭，不會插入權杖。不支援自動將權杖插入 X-Serverless-Authorization 標頭。
• 不支援 Cloud Run 沙箱容器產生的流量。
• 您無法使用 express link，將流量轉送至受 Identity-Aware Proxy 保護的目的地 Cloud Run 服務。
• 每個 express link 支援一個目的地 Cloud Run 服務，每項專案最多可建立 5,000 個 express link。

設定 express link

如要連結 Cloud Run 服務，請建立 express link，指定來源服務和目的地服務，然後在目的地服務上授予 Cloud Run 叫用者角色。

連線至其他 Cloud Run 服務

如要將來源 Cloud Run 服務連結至目的地 Cloud Run 服務，請使用 gcloud 或 YAML 建立 express link。

gcloud

使用 gcloud beta network-services express-links create 指令建立 express link：

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：express link 的名稱。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• REGION：部署 Cloud Run 服務的區域。
• SOURCE_SERVICE：來源 Cloud Run 服務的名稱。
• DESTINATION_SERVICE：目的地 Cloud Run 服務的名稱。

指令完成後，最多可能需要 2 分鐘，路由設定才會套用至執行中的來源服務執行個體。

根據預設，express link 只會攔截傳送至目的地服務確定性網址的要求，不會攔截傳送至非確定性網址的要求。如要使用自訂主機名稱，請在 --matches-hostname="HOSTNAME" 旗標中傳遞不含配置的主機名稱 (例如 --matches-hostname="DESTINATION_SERVICE")，並從來源應用程式傳送要求至 http://HOSTNAME。指定 --matches-hostname 會取代確定性網址，而不是新增。

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：express link 的名稱。
   • 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：express link 的名稱。
   • YAML_FILENAME：YAML 檔案的名稱。

授予叫用者目的地服務的權限

如要允許來源服務叫用受 IAM 保護的目的地服務，請將 Cloud Run 叫用者 (roles/run.invoker) 角色授予目的地 Cloud Run 服務上的來源服務帳戶。必須完成這項操作，驗證才能在資料層中運作。

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：部署目的地服務的區域。

驗證 express link 狀態

如要查看 express link 的基本設定，請使用 gcloud beta network-services express-links describe 指令：

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

如要查看 express link 的完整狀態，包括 connectionStatus (有效路徑類型、相符的主機名稱和來源修訂版本 URI) 和 cloudRunSourceInfo (設定的驗證方式和虛擬私有雲網路)，請在資源名稱中加入 ?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 替換為 express link 的名稱。查詢完整檢視表時，請保留單引號和結尾的 # 字元。

刪除或重新建立 express link

如要移除 express link，並停止從來源服務自動插入憑證和攔截流量，請使用 gcloud beta network-services express-links delete 指令：

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

將 EXPRESS_LINK_NAME 替換為 express link 的名稱。

如要將現有 express link 指向其他目的地服務，或變更 --matches-hostname 設定，請使用上述指令刪除 express link，然後以更新後的設定建立新的 express link。

後續步驟

• 瞭解如何為 Cloud Run 服務設定周邊網路。
• 瞭解 Cloud Run 上的 Agent Gateway。
• 瞭解 Cloud Run 的服務對服務驗證。
• 瞭解如何限制 Cloud Run 服務的網路端點輸入。