設定路徑擴充功能

Service Extensions 可讓支援的應用程式負載平衡器使用外掛程式，或向後端服務傳送呼叫，在處理路徑中插入自訂處理程序。負載平衡器收到要求標頭時，會在要求處理路徑中執行路徑擴充功能，然後評估網址對應。本頁說明如何設定路徑擴充功能。

如要瞭解應用程式負載平衡器擴充功能，請參閱「Cloud Load Balancing 擴充功能總覽」。

應用程式負載平衡器的路由擴充功能會指向下列資源：

  • 要附加的轉送規則
  • 外掛程式或呼叫後端服務，其後端會執行 ext_proc gRPC API

路線擴充功能會將相關的擴充服務分組為鏈結。您可以在同一個擴充功能鏈結中設定外掛程式和附註。擴充功能鏈會使用一般運算語言 (CEL) 比對條件，選取要處理的流量。負載平衡器會依序評估要求是否符合鏈結的相符條件。如果要求符合鏈結定義的條件，鏈結中的所有擴充功能都會對要求採取行動。只有一個鏈結符合特定要求。

擴充功能會參照要附加的負載平衡器轉送規則。設定資源後，負載平衡器就會開始將相符要求傳送至擴充功能服務。

如要瞭解應用程式負載平衡器擴充功能相關限制，請參閱「配額與限制」頁面。

使用外掛程式設定

本節將以範例說明如何使用外掛程式設定路由擴充功能，在路徑符合 /extensions 時，將 :host 要求標頭重新編寫為 service-extensions.com。先前的主機和新設定的主機對應至不同區域的後端服務，這會顯示轉送行為。

參照特定外掛程式的所有擴充功能資源都必須屬於相同類型。 擴充功能也必須採用相同的負載平衡配置。您無法使用 Media CDN 擴充功能中已使用的外掛程式，設定 Cloud Load Balancing 擴充功能。

事前準備

  1. 建立外掛程式，其中包含自訂程式碼。

  2. 建立及設定支援路徑擴充功能外掛程式的應用程式負載平衡器。

    請按照「設定具有 VM 執行個體群組後端的跨區域內部應用程式負載平衡器」頁面的指示完成所有步驟，但下列步驟除外：

    • 將後端服務命名為 service-one。
    • 將 service-one 指向區域 A 中的虛擬機器 (VM) 執行個體。
    • 預設會指向 service-one。gl7-gilb-url-map

  3. 設定額外的後端服務 service-two，並將其指向 B 區域中的 VM。

  4. 在網址對應中，新增指向 service-two 的路徑比對器。使用 gcloud compute url-maps add-path-matcher 指令，並搭配下列範例值：

      gcloud compute url-maps add-path-matcher gl7-gilb-url-map \
      --path-matcher-name=rewrite-host \
      --default-service=service-two \
      --new-hosts=service-extensions.com \
      --location=global

  5. 設定將測試要求傳送至服務的方式 (例如執行 curl)。如果您使用內部負載平衡器，請建立用戶端 VM 以進行測試。

使用外掛程式設定路徑擴充功能

  1. 檢查擴充功能設定前的行為。

    1. 確認沒有明確路徑的要求會前往 A 區域：

      curl FORWARDING_RULE_IP

      將 FORWARDING_RULE_IP 替換為轉送規則的 IP 位址。如要找出 IP 位址，請使用 gcloud compute forwarding-rules describe 指令。

      輸出內容會與下列內容相似，並指出網頁是從 region A 中的 VM 提供服務：

      Page served from region-A-vm

    2. 確認網址對應中沒有 /extensions 的相符項目：

      curl FORWARDING_RULE_IP/extensions

      將 FORWARDING_RULE_IP 替換為轉送規則的 IP 位址。如要找出 IP 位址，請使用 gcloud compute forwarding-rules describe 指令。

      輸出內容表示網址對應中沒有與 /extensions 相符的項目。輸出結果會與下列內容相似：

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. 設定路徑擴充功能。

    控制台

    1. 前往 Google Cloud 控制台的「Service Extensions」頁面。

      前往 Service Extensions

    2. 按一下「建立擴充功能」。

      精靈會開啟，引導您完成一些初始步驟。

    3. 選取「負載平衡」產品。然後按一下「繼續」。

      系統會顯示支援的應用程式負載平衡器清單。

    4. 選取跨區域內部應用程式負載平衡器做為負載平衡器類型。 然後按一下「繼續」。

    5. 在「擴充功能類型」中選取「路線擴充功能」，然後按一下「繼續」。

    6. 如要開啟「建立擴充功能」表單，請按一下「繼續」。

      在「建立擴充功能」表單中，請注意頁面頂端顯示的先前選取項目無法編輯。

    7. 在「Basics」(基本) 部分，執行下列操作：

      1. 為擴充功能指定不重複的名稱。

        名稱開頭必須為小寫英文字母，後方最多可接 62 個小寫字母、數字或連字號，但結尾不得為連字號。

      2. 選用：輸入擴充功能的簡短說明，最多 1,024 個字元。

    8. 選用：在「標籤」部分中，按一下「新增標籤」。接著，在顯示的資料列中執行下列操作：

      • 在「Key」中輸入金鑰名稱。
      • 在「值」中輸入索引鍵的值。

      如要新增更多鍵/值組合，請按一下「新增標籤」。最多可新增 64 個鍵/值組合。

      如要進一步瞭解標籤，請參閱「建立及更新專案標籤」。

    9. 在「Forwarding rules」(轉送規則)，選取要與擴充功能建立關聯的一或多個轉送規則，例如 cr-ilb-forwarding-rule。

      無法選取已與其他擴充功能建立關聯的轉送規則，且這些規則會顯示為已停用。

    10. 如要為「擴充功能」新增擴充功能，以便在要求相符時執行，請按照下列步驟操作：

      • 如要比對執行擴充功能鏈的請求，請在「比對條件」Match condition中指定一般運算語言 (CEL) 運算式，例如 request.path.startsWith("/extensions")。

        如要進一步瞭解 CEL 運算式，請按一下「取得語法說明」，或參閱 CEL 比對器語言參考資料。

      • 在「Programmability type」(可程式化類型) 中，選取「Plugins」(外掛程式)。

      • 在「外掛程式」部分，選取使用服務擴充功能建立的外掛程式，且產品和擴充功能類型相同。

      • 在「轉送屬性」部分，選取要由擴充功能轉送的屬性。詳情請參閱「支援的屬性」。

      • 在「Forward headers」(轉送標頭) 部分，按一下「Add header」(新增標頭)，然後新增要轉送至擴充功能的 HTTP 標頭 (來自用戶端或後端)。如果未指定標頭，系統會傳送所有標頭。

      • 選用：如果擴充功能逾時或失敗，但您希望繼續處理要求或回覆，請選取「啟用」，啟用「失敗時開啟」。

        根據預設，系統不會選取「Fail open」(失敗時開放) 選項。在本例中，發生錯誤時，要求或回應處理作業會停止。如果回應標頭尚未傳送至下游用戶端，系統會傳回一般 HTTP 500 狀態碼給用戶端。如果已傳送回應標頭，系統會重設用戶端的 HTTP 串流。

        如果安全或完整性是首要考量，建議將「Fail open」預設選項保持為未選取狀態。啟用「Fail open」(特別是非重要作業) 有助於優先考量可用性。

      如要指定多個擴充功能或擴充功能鏈，而非單一擴充功能，請按一下表單結尾的「切換至進階模式」按鈕，然後指定所需擴充功能和鏈。擴充功能會按照列出的順序執行。

      為每個擴充功能和擴充功能鏈結指定不重複的名稱。名稱必須符合 RFC-1034 規定，只能使用小寫英文字母、數字和連字號，且長度不得超過 63 個字元。此外，第一個字元必須是英文字母，最後一個字元必須是英文字母或數字。

    11. 按一下「建立擴充功能」。

    gcloud

    1. 在 YAML 檔案中定義外掛程式，並將其與全域轉送規則建立關聯，例如 cr-ilb-forwarding-rule。

      cat >route-plugin.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/forwardingRules/cr-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext1'
        service: projects/PROJECT_ID/locations/LOCATION/wasmPlugins/WASM_PLUGIN
        failOpen: false
        supportedEvents:
        - REQUEST_HEADERS
        forwardAttributes:
        - request.host
        - request.path
EOF

      更改下列內容：

      • PROJECT_ID：專案 ID。
      • REGION：轉送規則的區域。這個值必須與外掛程式位置指定的值相符。
      • LOCATION：外掛程式的位置，可為 global 或區域。
      • WASM_PLUGIN：外掛程式的 ID 或完整名稱。

      如要進一步瞭解 YAML 檔案中的欄位，請參閱 API 說明文件中的「ExtensionChain」。如要瞭解支援的屬性，請參閱「支援的屬性」。

    2. 匯入路徑擴充功能。使用 gcloud service-extensions lb-route-extensions import 指令和下列範例值。

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route-plugin.yaml \
    --location=global

    建立路徑擴充功能後，新外掛程式需要一段時間才能發布至所有地點。外掛程式不會同時傳送至所有地點，因此時間可能因地點而異。

  3. 如要確認路徑擴充功能是否正常運作，請使用相同的 curl 指令：

    curl FORWARDING_RULE_IP/extensions

    輸出內容會與下列內容相似，並指出網頁是從 region B 中的 VM 提供服務：

    Page served from region-B-vm

    如要確認外掛程式只會針對具有 /extension 路徑前置字串的要求執行，請重複執行 curl 指令，但不要指定路徑。

    curl FORWARDING_RULE_IP

    輸出結果會與下列內容相似：

    Page served from region-A-vm

使用摘要設定

本節說明如何使用標註設定路徑擴充功能。

事前準備

按照「設定呼叫外送後端服務」一文中的說明，建立必要資源。

使用摘要設定路線擴充功能

以下範例說明如何設定路由擴充功能，在路徑符合 /extensions 時呼叫。callout-vm 中的路徑呼叫伺服器會將 Host 標頭變更為 service-extensions.com，將路徑設為 /，然後將指令傳送至負載平衡器，重新計算路徑。流量會流向 l7-ilb-backend-service2，而不是 l7-ilb-backend-service。

  1. 檢查網址對應中是否有 /extensions 的相符項目。

    1. 在用戶端 VM 中，對轉送規則執行下列 curl 指令：

      curl FORWARDING_RULE_IP/extensions

      將 FORWARDING_RULE_IP 替換為轉送規則的 IP 位址。如要找出 IP 位址，請使用 gcloud compute forwarding-rules describe 指令。

      輸出內容表示網址對應中沒有與 /extensions 相符的項目。輸出結果會與下列內容相似：

      <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>404 Not Found</title>
</head><body>
...

  2. 設定路徑擴充功能。

    控制台

    1. 前往 Google Cloud 控制台的「Service Extensions」頁面。

      前往 Service Extensions

    2. 按一下「建立擴充功能」。

      精靈會開啟，引導您完成一些初始步驟。

    3. 選取「負載平衡」產品。然後按一下「繼續」。

      系統會顯示支援的應用程式負載平衡器清單。

    4. 選取負載平衡器類型。如果是區域性負載平衡器，請一併指定區域。按一下「繼續」。

    5. 在「擴充功能類型」中選取「路線擴充功能」，然後按一下「繼續」。

    6. 如要開啟「建立擴充功能」表單，請按一下「繼續」。

      在「建立擴充功能」表單中，請注意頁面頂端顯示的先前選取項目無法編輯。

    7. 在「Basics」(基本) 部分，執行下列操作：

      1. 為擴充功能指定不重複的名稱。

        名稱開頭必須為小寫英文字母，後方最多可接 62 個小寫字母、數字或連字號，但結尾不得為連字號。

      2. 選用：輸入擴充功能的簡短說明，最多 1,024 個字元。

    8. 選用：在「標籤」部分中，按一下「新增標籤」。接著，在顯示的資料列中執行下列操作：

      • 在「Key」中輸入金鑰名稱。
      • 在「值」中輸入索引鍵的值。

      如要新增更多鍵/值組合，請按一下「新增標籤」。最多可新增 64 個鍵/值組合。

      如要進一步瞭解標籤，請參閱「建立及更新專案標籤」。

    9. 在「Forwarding rules」(轉送規則)，選取要與擴充功能建立關聯的一或多個轉送規則，例如 l7-ilb-forwarding-rule。

      無法選取已與其他擴充功能建立關聯的轉送規則，且這些規則會顯示為已停用。

    10. 如要為「擴充功能」新增擴充功能，以便在要求相符時執行，請按照下列步驟操作：

      • 如要比對執行擴充功能鏈的請求，請在「比對條件」Match condition中指定一般運算語言 (CEL) 運算式，例如 request.path.startsWith("/extensions")。

        如要進一步瞭解 CEL 運算式，請按一下「取得語法說明」，或參閱 CEL 比對器語言參考資料。

      • 在「可程式化類型」部分，選取「Callouts」。

        • 在「擴充功能名稱」部分指定專屬名稱。

          名稱必須符合 RFC-1034 規定，只能使用小寫英文字母、數字和連字號，且長度上限為 63 個字元。此外，第一個字元必須是英文字母，最後一個字元則須為英文字母或數字。

        • 在「Authority」中，輸入從負載平衡器傳送至擴充功能服務的 gRPC 要求中的 authority 標頭。

        • 在「後端服務」中，選取按照「設定呼叫外送後端服務」一文中的操作說明建立的後端服務。

        • 「逾時」值須介於 10 到 1000 毫秒之間，如果負載平衡器仍在等待 ext_proc 服務的回應，串流上的訊息就會逾時。

        • 在「轉送屬性」部分，選取要由擴充功能轉送的屬性。詳情請參閱「支援的屬性」。

        • 在「Forward headers」(轉送標頭) 部分，按一下「Add header」(新增標頭)，然後新增要轉送至擴充功能的 HTTP 標頭 (來自用戶端或後端)。如果未指定標頭，系統會傳送所有標頭。

        • 選用：如果擴充功能逾時或失敗，但您希望繼續處理要求或回覆，請選取「啟用」，啟用「失敗時開放」。鏈結中的後續擴充功能也會執行。

        根據預設，系統不會選取「Fail open」(失敗時開放) 選項。在本例中，發生錯誤時，要求或回應處理作業會停止。如果回應標頭尚未傳送至下游用戶端，系統會傳回一般 HTTP 500 狀態碼給用戶端。如果已傳送回應標頭，系統會重設用戶端的 HTTP 串流。

        如果安全或完整性是首要考量，建議將「Fail open」預設選項保持為未選取狀態。啟用「Fail open」(特別是非重要作業) 有助於優先考量可用性。

      • 在「中繼資料」部分，點選「新增中繼資料」，並按照建議指定範例值。將「Key」(索引鍵) 指定為 key，並將「Value」(值) 指定為 value。

        按一下「新增中繼資料」，新增其他鍵/值組合。將「Key」(索引鍵) 指定為 fr，並將「Value」(值) 指定為 forwarding_rule_id。

        您可以使用「中繼資料」欄位，將任何額外資訊從負載平衡器傳遞至擴充功能伺服器。中繼資料會以 ProcessingRequest 訊息傳送，並編碼為 protobuf.Struct。中繼資料中與指定轉送規則 ID 相符的任何文字，都會替換為與用戶端要求相關聯的轉送規則完整資源網址。

        中繼資料總大小不得超過 1 KiB。 中繼資料中的鍵總數不得超過 16 個。 每個鍵的長度不得超過 64 個半形字元。每個值的長度不得超過 1024 個字元。所有值都必須是字串。

      如要指定多個擴充功能或擴充功能鏈，而非單一擴充功能，請按一下表單結尾的「切換至進階模式」按鈕，然後指定所需擴充功能和鏈。擴充功能會按照列出的順序執行。

      為每個擴充功能和擴充功能鏈結指定不重複的名稱。名稱必須符合 RFC-1034 規定，只能使用小寫英文字母、數字和連字號，且長度不得超過 63 個字元。此外，第一個字元必須是英文字母，最後一個字元必須是英文字母或數字。

    11. 按一下「建立擴充功能」。

    gcloud

    1. 在 YAML 檔案中定義附註，並將其與轉送規則建立關聯。使用提供的樣本值。

      cat >route.yaml <<EOF
    name: route-ext
    forwardingRules:
    - https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/forwardingRules/l7-ilb-forwarding-rule
    loadBalancingScheme: INTERNAL_MANAGED
    extensionChains:
    - name: "chain1"
      matchCondition:
        celExpression: 'request.path.startsWith("/extensions")'
      extensions:
      - name: 'ext11'
        authority: ext11.com
        service: https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/us-west1/backendServices/l7-ilb-callout-service
        failOpen: false
        timeout: 0.1s
        metadata:
          "key": "value"
          "fr": "forwarding_rule_id"
        forwardAttributes:
        - request.host
        - request.path
EOF

      將 PROJECT_ID 替換為專案 ID。

      擴充功能設定中的 metadata 欄位可讓您將任何額外資訊從負載平衡器傳遞至擴充功能伺服器。中繼資料會以 ProcessingRequest 訊息傳送，並編碼為 protobuf.Struct。中繼資料中與指定轉送規則 ID 相符的任何文字，都會替換為與用戶端要求相關聯的轉送規則完整資源網址。

      metadata 的總大小不得超過 1 KiB。 中繼資料中的鍵總數不得超過 16 個。 每個鍵的長度不得超過 64 個半形字元。每個值的長度不得超過 1024 個字元。所有值都必須是字串。

      如要進一步瞭解 YAML 檔案中的欄位，請參閱 API 說明文件中的「ExtensionChain」。如要瞭解支援的屬性，請參閱「支援的屬性」。

    2. 匯入路徑擴充功能。使用 gcloud service-extensions lb-route-extensions import 指令，並搭配下列範例值。

      gcloud service-extensions lb-route-extensions import route-ext \
    --source=route.yaml \
    --location=us-west1

  3. 確認路徑擴充功能是否正常運作。使用相同的 curl 指令：

    curl FORWARDING_RULE_IP/extensions

    輸出內容指出，即使原始要求不相符，流量仍與虛擬主機 service-extensions.com 相符，並抵達 l7-ilb-backend-service2 服務。輸出結果會與下列內容相似：

    Page served from second backend service

    如要驗證呼叫僅指定具有 /extension 前置字串的要求，請重複執行 curl 指令，但不要加上 path 前置字串。

    curl FORWARDING_RULE_IP

    輸出結果會與下列內容相似：

    Page served from: l7-ilb-backend-example-1c7t

路線擴充功能的限制

  • 路由擴充功能不支援 HTTP 主體處理。
  • 路由擴充功能不支援從擴充功能直接回應用戶端。如果路徑擴充功能伺服器以包含直接回應的處理回應，回覆處理要求，負載平衡器會忽略該處理回應。

如要瞭解所有擴充功能適用的限制，請參閱「擴充功能限制」。

後續步驟