경로 확장 프로그램 구성

Service Extensions를 사용하면 지원되는 애플리케이션 부하 분산기가 플러그인을 사용하거나 백엔드 서비스에 콜아웃을 전송하여 처리 경로에 맞춤 처리를 삽입할 수 있습니다. 경로 확장 프로그램은 부하 분산기가 요청 헤더를 수신할 때 요청 처리 경로에서 실행되며 URL 맵을 평가하기 전에 실행됩니다. 이 페이지에서는 경로 확장 프로그램을 구성하는 방법을 설명합니다.

애플리케이션 부하 분산기 확장 프로그램에 대한 개요는 Cloud Load Balancing 확장 프로그램 개요를 참고하세요.

애플리케이션 부하 분산기의 경로 확장 프로그램은 다음 리소스를 가리킵니다.

  • 연결할 전달 규칙
  • 백엔드에서 ext_proc gRPC API를 실행하는 플러그인 또는 콜아웃 백엔드 서비스

경로 확장 프로그램은 관련 확장 프로그램 서비스를 체인으로 그룹화합니다. 동일한 확장 프로그램 체인에서 플러그인과 콜아웃을 모두 구성할 수 있습니다. 확장 프로그램 체인은 Common Expression Language (CEL) 일치 조건을 사용하여 처리할 트래픽을 선택합니다. 부하 분산기는 체인의 일치 조건에 대해 요청을 순차적으로 평가합니다. 요청이 체인에서 정의한 조건과 일치하면 체인의 모든 확장 프로그램이 요청에 대해 작동합니다. 하나의 체인만 지정된 요청과 일치합니다.

확장 프로그램은 연결할 부하 분산기 전달 규칙을 참조합니다. 리소스를 구성하면 부하 분산기가 일치하는 요청을 확장 프로그램 서비스로 전송하기 시작합니다.

애플리케이션 부하 분산기 확장 프로그램과 관련된 한도에 대한 자세한 내용은 할당량 및 한도 페이지를 참고하세요.

플러그인을 사용하여 구성

이 섹션에서는 경로가 /extensions와 일치할 때 :host 요청 헤더를 service-extensions.com로 재작성하는 플러그인을 사용하여 경로 확장 프로그램을 구성하는 방법을 예시를 통해 보여줍니다. 이전 호스트와 새로 구성된 호스트는 서로 다른 지역의 백엔드 서비스에 매핑되어 라우팅 동작을 보여줍니다.

특정 플러그인을 참조하는 모든 확장 프로그램 리소스는 동일한 유형이어야 합니다. 확장 프로그램의 부하 분산 스키마도 동일해야 합니다. Media CDN 확장 프로그램에서 이미 사용 중인 플러그인으로 Cloud Load Balancing 확장 프로그램을 구성할 수 없습니다.

시작하기 전에

  1. 맞춤 코드가 포함된 플러그인을 만듭니다.

  2. 경로 확장 플러그인을 지원하는 애플리케이션 부하 분산기를 만들고 구성합니다.

    다음 단계를 제외한 모든 단계는 VM 인스턴스 그룹 백엔드를 사용하여 리전 간 내부 애플리케이션 부하 분산기 설정 페이지의 안내를 따르세요.

    • 백엔드 서비스의 이름을 service-one로 지정합니다.
    • service-one를 A 리전의 가상 머신 (VM) 인스턴스로 지정합니다.
    • 기본적으로 gl7-gilb-url-map를 service-one로 지정

  3. 추가 백엔드 서비스 service-two를 설정하고 B 리전의 VM을 가리키도록 합니다.

  4. URL 맵에 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. URL 맵에 /extensions와 일치하는 항목이 없는지 확인합니다.

      curl FORWARDING_RULE_IP/extensions

      FORWARDING_RULE_IP를 전달 규칙의 IP 주소로 바꿉니다. IP 주소를 찾으려면 gcloud compute forwarding-rules describe 명령어를 사용합니다.

      출력은 URL 맵에 /extensions와 일치하는 항목이 없음을 나타냅니다. 출력은 다음과 비슷합니다.

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

  2. 경로 확장 프로그램을 구성합니다.

    콘솔

    1. Google Cloud 콘솔에서 서비스 확장 프로그램 페이지로 이동합니다.

      서비스 확장 프로그램으로 이동

    2. 확장 프로그램 만들기를 클릭합니다.

      마법사가 열려 초기 단계를 안내합니다.

    3. 제품에서 부하 분산을 선택합니다. 그런 다음 계속을 클릭합니다.

      지원되는 애플리케이션 부하 분산기 목록이 표시됩니다.

    4. 부하 분산기 유형으로 리전 간 내부 애플리케이션 부하 분산기를 선택합니다. 그런 다음 계속을 클릭합니다.

    5. 확장 프로그램 유형으로 라우팅 확장 프로그램을 선택한 다음 계속을 클릭합니다.

    6. 확장 프로그램 만들기 양식을 열려면 계속을 클릭합니다.

      확장 프로그램 만들기 양식에서 페이지 상단에 표시되는 이전 선택사항은 수정할 수 없습니다.

    7. 기본사항 섹션에서 다음을 수행합니다.

      1. 확장 프로그램의 고유한 이름을 지정합니다.

        이름은 소문자로 시작해야 합니다. 이어서 최대 62자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나서는 안 됩니다.

      2. 선택사항: 최대 1,024자를 사용하여 확장 프로그램에 관한 간단한 설명을 입력합니다.

      3. 선택사항: 라벨 섹션에서 라벨 추가를 클릭합니다. 그런 다음 표시되는 행에서 다음을 실행합니다.

        • 키에 키 이름을 입력합니다.
        • 값에 키 값을 입력합니다.

        키-값 쌍을 더 추가하려면 라벨 추가를 클릭합니다. 최대 64개의 키-값 쌍을 추가할 수 있습니다.

        라벨에 대한 자세한 내용은 프로젝트 라벨 만들기 및 업데이트를 참고하세요.

    8. 전달 규칙에서 확장 프로그램과 연결할 전달 규칙을 하나 이상 선택합니다(예: cr-ilb-forwarding-rule).

      이미 다른 확장 프로그램과 연결된 전달 규칙은 선택할 수 없으며 사용 중지된 것으로 표시됩니다.

    9. 확장 프로그램 체인의 경우 일치하는 요청에 실행할 확장 프로그램 체인을 하나 이상 추가합니다.

      확장 프로그램 체인을 추가하려면 다음 단계를 따른 후 완료를 클릭하세요.

      • 새 확장 프로그램 체인에 고유한 이름을 지정합니다.

        이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자 또는 숫자여야 합니다.

      • 확장 프로그램 체인이 실행되는 요청을 일치시키려면 일치 조건에 Common Expression Language(CEL) 표현식(예: request.path.startsWith("/extensions"))을 지정합니다.

        CEL 표현식에 대한 자세한 내용은 구문 도움말 보기를 클릭하거나 CEL 일치자 언어 참조를 참고하세요.

      • 일치하는 요청에 실행할 확장 프로그램을 추가합니다. 경로 확장 프로그램의 경우 하나의 확장 프로그램만 지정할 수 있습니다.

        확장 프로그램에서 다음을 수행한 후 완료를 클릭합니다.

        • 프로그래밍 가능 유형에서 플러그인을 선택합니다.

        • 확장 프로그램 이름에 고유한 이름을 지정합니다.

          이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자나 숫자여야 합니다.

        • 플러그인에서 동일한 제품 및 확장 프로그램 유형에 대해 서비스 확장 프로그램을 사용하여 생성된 플러그인을 선택합니다.

        • 헤더 전달에서 헤더 추가를 클릭한 다음 클라이언트 또는 백엔드에서 확장 프로그램으로 전달할 HTTP 헤더를 추가합니다. 헤더를 지정하지 않으면 모든 헤더가 전송됩니다.

        • 선택사항: 확장 프로그램이 시간 초과되거나 실패하고 요청 또는 응답 처리를 계속하려면 Fail open에 대해 Enabled를 선택합니다.

          기본적으로 Fail open 옵션은 선택되어 있지 않습니다. 이 경우 오류가 발생하면 요청 또는 응답 처리가 중지됩니다. 응답 헤더가 다운스트림 클라이언트에 전송되지 않으면 클라이언트에 일반 HTTP 500 상태 코드가 반환됩니다. 응답 헤더가 전송되면 클라이언트에 대한 HTTP 스트림이 재설정됩니다.

          보안 또는 무결성을 우선시하는 경우 장애 허용을 선택하지 않은 기본 옵션이 선호됩니다. 특히 중요하지 않은 작업에 대해 Fail open을 사용 설정하면 가용성의 우선순위를 지정할 때 도움이 됩니다.

    10. 확장 프로그램 만들기를 클릭합니다.

    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
EOF

      다음을 바꿉니다.

      • PROJECT_ID: 프로젝트 ID입니다.
      • REGION: 전달 규칙의 리전입니다. 값은 플러그인 위치에 지정된 값과 일치해야 합니다.
      • LOCATION: 플러그인의 위치(global 또는 리전)
      • WASM_PLUGIN: 플러그인의 ID 또는 정규화된 이름입니다.

    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-service 대신 l7-ilb-backend-service2로 흐릅니다.

  1. URL 맵에 /extensions와 일치하는 항목이 있는지 확인합니다.

    1. 클라이언트 VM에서 전달 규칙에 대해 다음 curl 명령어를 실행합니다.

      curl FORWARDING_RULE_IP/extensions

      FORWARDING_RULE_IP를 전달 규칙의 IP 주소로 바꿉니다. IP 주소를 찾으려면 gcloud compute forwarding-rules describe 명령어를 사용합니다.

      출력은 URL 맵에 /extensions와 일치하는 항목이 없음을 나타냅니다. 출력은 다음과 비슷합니다.

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

  2. 경로 확장 프로그램을 구성합니다.

    콘솔

    1. Google Cloud 콘솔에서 서비스 확장 프로그램 페이지로 이동합니다.

      서비스 확장 프로그램으로 이동

    2. 확장 프로그램 만들기를 클릭합니다.

      마법사가 열려 초기 단계를 안내합니다.

    3. 제품에서 부하 분산을 선택합니다. 그런 다음 계속을 클릭합니다.

      지원되는 애플리케이션 부하 분산기 목록이 표시됩니다.

    4. 부하 분산기 유형을 선택합니다. 리전 부하 분산기의 경우 리전도 지정합니다. 계속을 클릭합니다.

    5. 확장 프로그램 유형으로 라우팅 확장 프로그램을 선택한 다음 계속을 클릭합니다.

    6. 확장 프로그램 만들기 양식을 열려면 계속을 클릭합니다.

      확장 프로그램 만들기 양식에서 페이지 상단에 표시되는 이전 선택사항은 수정할 수 없습니다.

    7. 기본사항 섹션에서 다음을 수행합니다.

      1. 확장 프로그램의 고유한 이름을 지정합니다.

        이름은 소문자로 시작해야 합니다. 이어서 최대 62자(영문 기준)의 소문자, 숫자 또는 하이픈이 와야 하며 하이픈으로 끝나서는 안 됩니다.

      2. 선택사항: 최대 1,024자를 사용하여 확장 프로그램에 관한 간단한 설명을 입력합니다.

      3. 선택사항: 라벨 섹션에서 라벨 추가를 클릭합니다. 그런 다음 표시되는 행에서 다음을 실행합니다.

        • 키에 키 이름을 입력합니다.
        • 값에 키 값을 입력합니다.

        키-값 쌍을 더 추가하려면 라벨 추가를 클릭합니다. 최대 64개의 키-값 쌍을 추가할 수 있습니다.

        라벨에 대한 자세한 내용은 프로젝트 라벨 만들기 및 업데이트를 참고하세요.

    8. 전달 규칙에서 확장 프로그램과 연결할 전달 규칙을 하나 이상 선택합니다(예: l7-ilb-forwarding-rule).

      이미 다른 확장 프로그램과 연결된 전달 규칙은 선택할 수 없으며 사용 중지된 것으로 표시됩니다.

    9. 확장 프로그램 체인의 경우 일치하는 요청에 실행할 확장 프로그램 체인을 하나 이상 추가합니다.

      확장 프로그램 체인을 추가하려면 다음 단계를 따른 후 완료를 클릭하세요.

      • 새 확장 프로그램 체인에 고유한 이름을 지정합니다.

        이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자나 숫자여야 합니다.

      • 확장 프로그램 체인이 실행되는 요청을 일치시키려면 일치 조건에 Common Expression Language(CEL) 표현식(예: request.path.startsWith("/extensions"))을 지정합니다.

        CEL 표현식에 대한 자세한 내용은 구문 도움말 보기를 클릭하거나 CEL 일치자 언어 참조를 참고하세요.

      • 일치하는 요청에 실행할 확장 프로그램을 추가합니다. 경로 확장 프로그램의 경우 하나의 확장 프로그램만 지정할 수 있습니다.

        확장 프로그램에서 다음을 수행한 후 완료를 클릭합니다.

        • 프로그래밍 가능 유형에서 콜아웃을 선택합니다.

        • 확장 프로그램 이름에 고유한 이름을 지정합니다.

          이름은 RFC-1034를 준수해야 하며 소문자, 숫자, 하이픈만 사용해야 하고 최대 길이는 63자(영문 기준)입니다. 또한 첫 번째 문자는 문자여야 하고 마지막 문자는 문자나 숫자여야 합니다.

        • 권한에 부하 분산기에서 확장 프로그램 서비스로 전송된 gRPC 요청의 authority 헤더를 입력합니다.

        • 백엔드 서비스의 경우 콜아웃 백엔드 서비스 구성의 안내에 따라 만든 백엔드 서비스를 선택합니다.

        • 시간 제한의 경우 부하 분산기가 ext_proc 서비스의 응답을 기다리는 동안 스트림의 메시지가 시간 초과되는 10~1,000밀리초 사이의 값을 지정합니다.

        • 헤더 전달에서 헤더 추가를 클릭한 다음 클라이언트 또는 백엔드에서 확장 프로그램으로 전달할 HTTP 헤더를 추가합니다. 헤더를 지정하지 않으면 모든 헤더가 전송됩니다.

        • 선택사항: 확장 프로그램이 시간 초과되거나 실패하고 요청 또는 응답 처리를 계속하려면 Fail open에 대해 Enabled를 선택합니다. 체인의 후속 확장 프로그램도 실행됩니다.

          기본적으로 Fail open 옵션은 선택되어 있지 않습니다. 이 경우 오류가 발생하면 요청 또는 응답 처리가 중지됩니다. 응답 헤더가 다운스트림 클라이언트에 전송되지 않으면 클라이언트에 일반 HTTP 500 상태 코드가 반환됩니다. 응답 헤더가 전송되면 클라이언트에 대한 HTTP 스트림이 재설정됩니다.

          보안 또는 무결성을 우선시하는 경우 장애 허용을 선택하지 않은 기본 옵션이 선호됩니다. 특히 중요하지 않은 작업에 대해 Fail open을 사용 설정하면 가용성의 우선순위를 지정할 때 도움이 됩니다.

        • 메타데이터에서 메타데이터 추가를 클릭하고 제안된 대로 샘플 값을 지정합니다. 키에 key를 지정하고 값에 value를 지정합니다.

          메타데이터 추가를 클릭하여 다른 키-값 쌍을 추가합니다. 키에 fr를 지정하고 값에 forwarding_rule_id를 지정합니다.

          메타데이터 필드를 사용하면 부하 분산기에서 확장 프로그램 서버로 추가 정보를 전달할 수 있습니다. 메타데이터는 ProcessingRequest 메시지로 전송되고 protobuf.Struct로 인코딩됩니다. 지정된 전달 규칙 ID와 일치하는 메타데이터 내 텍스트는 클라이언트 요청과 연결된 전달 규칙의 정규화된 리소스 URL로 대체됩니다.

          메타데이터의 총 크기는 1KiB 미만이어야 합니다. 메타데이터의 총 키 수는 16개 미만이어야 합니다. 각 키의 길이는 64자(영문 기준) 미만이어야 합니다. 각 값의 길이는 1,024자(영문 기준) 미만이어야 합니다. 모든 값은 문자열이어야 합니다.

    10. 확장 프로그램 만들기를 클릭합니다.

    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"
EOF

      PROJECT_ID를 프로젝트 ID로 바꿉니다.

      확장 프로그램 구성의 metadata 필드를 사용하면 부하 분산기에서 확장 프로그램 서버로 추가 정보를 전달할 수 있습니다. 메타데이터는 ProcessingRequest 메시지로 전송되고 protobuf.Struct로 인코딩됩니다. 지정된 전달 규칙 ID와 일치하는 메타데이터 내의 텍스트는 클라이언트 요청과 연결된 전달 규칙의 정규화된 리소스 URL로 대체됩니다.

      metadata의 총 크기는 1KiB보다 작아야 합니다. 메타데이터의 총 키 수는 16개 미만이어야 합니다. 각 키의 길이는 64자(영문 기준) 미만이어야 합니다. 각 값의 길이는 1,024자(영문 기준) 미만이어야 합니다. 모든 값은 문자열이어야 합니다.

    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 접두사가 있는 요청만 타겟팅하는지 확인하려면 path 접두사 없이 curl 명령어를 반복합니다.

    curl FORWARDING_RULE_IP

    출력은 다음과 비슷합니다.

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

경로 확장 프로그램의 제한사항

  • 경로 확장 프로그램은 HTTP 본문 처리를 지원하지 않습니다.
  • 경로 확장 프로그램의 경우 확장 프로그램에서 클라이언트로 직접 응답하는 것은 지원되지 않습니다. 경로 확장 프로그램 서버가 직접 응답이 포함된 처리 응답으로 처리 요청에 응답하면 부하 분산기는 처리 응답을 무시합니다.

모든 확장 프로그램에 적용되는 제한사항은 확장 프로그램 제한사항을 참고하세요.

다음 단계