mmv1/products/networkservices/LbTrafficExtension.yaml

# Copyright 2024 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
name: 'LbTrafficExtension'
description: |
  LbTrafficExtension is a resource that lets the extension service modify the headers and payloads of both requests and responses without impacting the choice of backend services or any other security policies associated with the backend service.
references:
  guides:
    'Configure a traffic extension': 'https://cloud.google.com/service-extensions/docs/configure-callout#configure_a_traffic_extension'
  api: 'https://cloud.google.com/service-extensions/docs/reference/rest/v1beta1/projects.locations.lbTrafficExtensions'
docs:
base_url: 'projects/{{project}}/locations/{{location}}/lbTrafficExtensions'
self_link: 'projects/{{project}}/locations/{{location}}/lbTrafficExtensions/{{name}}'
create_url: 'projects/{{project}}/locations/{{location}}/lbTrafficExtensions?lbTrafficExtensionId={{name}}'
update_verb: 'PATCH'
update_mask: true
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
autogen_async: true
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: false
custom_code:
sweeper:
  url_substitutions:
    - region: "us-west1"
examples:
  - name: 'network_services_lb_traffic_extension_basic'
    primary_resource_id: 'default'
    vars:
      ilb_network_name: 'l7-ilb-network'
      proxy_subnet_name: 'l7-ilb-proxy-subnet'
      backend_subnet_name: 'l7-ilb-subnet'
      forwarding_rule_name: 'l7-ilb-forwarding-rule'
      target_http_proxy_name: 'l7-ilb-target-http-proxy'
      regional_url_map_name: 'l7-ilb-regional-url-map'
      backend_service_name: 'l7-ilb-backend-subnet'
      mig_template_name: 'l7-ilb-mig-template'
      hc_name: 'l7-ilb-hc'
      mig_name: 'l7-ilb-mig1'
      fw_allow_iap_hc_name: 'l7-ilb-fw-allow-iap-hc'
      fw_allow_ilb_to_backends_name: 'l7-ilb-fw-allow-ilb-to-backends'
      vm_test_name: 'l7-ilb-test-vm'
      lb_traffic_extension_name: 'l7-ilb-traffic-ext'
      callouts_instance_name: 'l7-ilb-callouts-ins'
      callouts_instance_group: 'l7-ilb-callouts-ins-group'
      callouts_hc_name: 'l7-ilb-callouts-hc'
      callouts_backend_name: 'l7-ilb-callouts-backend'
parameters:
  - name: 'location'
    type: String
    description: |
      The location of the traffic extension
    url_param_only: true
    required: true
    immutable: true
  - name: 'name'
    type: String
    description: |
      Name of the LbTrafficExtension resource in the following format: projects/{project}/locations/{location}/lbTrafficExtensions/{lbTrafficExtension}.
    url_param_only: true
    required: true
    immutable: true
properties:
  - name: 'description'
    type: String
    description: |
      A human-readable description of the resource.
  - name: 'labels'
    type: KeyValueLabels
    description: 'Set of labels associated with the LbTrafficExtension resource.'
  - name: 'forwardingRules'
    type: Array
    description: |
      A list of references to the forwarding rules to which this service extension is attached to.
      At least one forwarding rule is required. There can be only one LBTrafficExtension resource per forwarding rule.
    required: true
    diff_suppress_func: 'tpgresource.ProjectNumberDiffSuppress'
    item_type:
      type: String
  - name: 'extensionChains'
    type: Array
    description: |
      A set of ordered extension chains that contain the match conditions and extensions to execute.
      Match conditions for each extension chain are evaluated in sequence for a given request.
      The first extension chain that has a condition that matches the request is executed.
      Any subsequent extension chains do not execute. Limited to 5 extension chains per resource.
      Further information can be found at https://cloud.google.com/service-extensions/docs/reference/rest/v1/ExtensionChain
    required: true
    item_type:
      type: NestedObject
      properties:
        - name: 'name'
          type: String
          description: |
            The name for this extension chain. The name is logged as part of the HTTP request logs.
            The name must conform with RFC-1034, is restricted to lower-cased letters, numbers and hyphens,
            and can have a maximum length of 63 characters. Additionally, the first character must be a letter
            and the last a letter or a number.
          required: true
        - name: 'matchCondition'
          type: NestedObject
          description: |
             Conditions under which this chain is invoked for a request.
          required: true
          properties:
            - name: 'celExpression'
              type: String
              description: |
                A Common Expression Language (CEL) expression that is used to match requests for which the extension chain is executed.
              required: true
        - name: 'extensions'
          type: Array
          description: |
            A set of extensions to execute for the matching request.
            At least one extension is required. Up to 3 extensions can be defined for each extension chain for
            LbTrafficExtension resource. LbRouteExtension chains are limited to 1 extension per extension chain.
            Further documentation to be found at https://cloud.google.com/service-extensions/docs/reference/rest/v1/ExtensionChain#Extension
          required: true
          item_type:
            type: NestedObject
            properties:
              - name: 'name'
                type: String
                description: |
                  The name for this extension. The name is logged as part of the HTTP request logs.
                  The name must conform with RFC-1034, is restricted to lower-cased letters, numbers and hyphens,
                  and can have a maximum length of 63 characters. Additionally, the first character must be a letter
                  and the last a letter or a number.
                required: true
              - name: 'authority'
                type: String
                description: |
                  The :authority header in the gRPC request sent from Envoy to the extension service.
              - name: 'service'
                type: String
                description: |
                  The reference to the service that runs the extension. Must be a reference to a backend service
                required: true
                diff_suppress_func: 'tpgresource.ProjectNumberDiffSuppress'
              - name: 'timeout'
                type: String
                description: |
                  Specifies the timeout for each individual message on the stream. The timeout must be between 10-1000 milliseconds.
                  A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
                diff_suppress_func: 'tpgresource.DurationDiffSuppress'
              - name: 'failOpen'
                type: Boolean
                description: |
                   Determines how the proxy behaves if the call to the extension fails or times out.
                   When set to TRUE, request or response processing continues without error.
                   Any subsequent extensions in the extension chain are also executed.
                   When set to FALSE: * If response headers have not been delivered to the downstream client,
                   a generic 500 error is returned to the client. The error response can be tailored by
                   configuring a custom error response in the load balancer.
              - name: 'forwardHeaders'
                type: Array
                description: |
                  List of the HTTP headers to forward to the extension (from the client or backend).
                  If omitted, all headers are sent. Each element is a string indicating the header name.
                item_type:
                  type: String
              - name: 'supportedEvents'
                type: Array
                description: |
                  A set of events during request or response processing for which this extension is called.
                  This field is required for the LbTrafficExtension resource. It's not relevant for the LbRouteExtension
                  resource. Possible values:`EVENT_TYPE_UNSPECIFIED`, `REQUEST_HEADERS`, `REQUEST_BODY`, `RESPONSE_HEADERS`,
                  `RESPONSE_BODY`, `RESPONSE_BODY` and `RESPONSE_BODY`.
                item_type:
                  type: String
                min_size: 1
              - name: 'metadata'
                type: KeyValuePairs
                description: |
                  Metadata associated with the extension. This field is used to pass metadata to the extension service.
                  You can set up key value pairs for metadata as you like and need.
                  f.e. {"key": "value", "key2": "value2"}.

  - name: 'loadBalancingScheme'
    type: Enum
    description: |
      All backend services and forwarding rules referenced by this extension must share the same load balancing scheme.
      For more information, refer to [Choosing a load balancer](https://cloud.google.com/load-balancing/docs/backend-service) and
      [Supported application load balancers](https://cloud.google.com/service-extensions/docs/callouts-overview#supported-lbs).
    immutable: true
    enum_values:
      - 'INTERNAL_MANAGED'
      - 'EXTERNAL_MANAGED'