Configure Gateway resources using Policies


This page shows you how to configure the load balancer that GKE creates when you deploy a Gateway in a Google Kubernetes Engine (GKE) cluster.

When you deploy a Gateway in a GKE cluster, the GatewayClass configuration determines which load balancer GKE creates. This managed load balancer is pre-configured with default settings that you can modify using a Policy.

You can only attach Policies to Services or ServiceImports. After you apply or modify a Policy, you do not need to delete or recreate your Gateway, Route, or Service resources. When attaching Policies, the policy resource must be in the same namespace as the target Service or ServiceImport.

Before you begin

Before you start, make sure you have performed the following tasks:

  • Enable the Google Kubernetes Engine API.
  • Enable Google Kubernetes Engine API
  • If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI.
  • Deploy an internal or external Gateway.

Limitations

  • Gateway limitations apply.
  • You cannot use a FrontendConfig or a BackendConfig to configure a Gateway. You must use a Policy.
  • GCPBackendPolicy, HealthCheckPolicy, and GCPGatewayPolicy resources can only be attached to a v1 Service for single cluster Gateway. For multi-cluster Gateways, these resources can only be attached to a net.gke.io/v1 ServiceImport.
  • GCPBackendPolicy, HealthCheckPolicy, and GCPGatewayPolicy resources must exist in the same namespace as the target Service or ServiceImport resource.
  • When using a single cluster Gateway, GCPBackendPolicy, and HealthCheckPolicy resources must refer to a Service resource and GCPGatewayPolicy must refer to a Gateway. When using a multi-cluster Gateway, GCPBackendPolicy, and HealthCheckPolicy, resources must refer to a ServiceImport resource and GCPGatewayPolicy must refer to a Gateway.

Configure global access for your regional internal Gateway

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

To enable global access with your internal Gateway, attach a policy to the Gateway resource.

The following GCPGatewayPolicy manifest enables regional internal Gateway for global access:

apiVersion: networking.gke.io/v1
kind: GCPGatewayPolicy
metadata:
  name: my-gateway-policy
  namespace: default
spec:
  default:
    allowGlobalAccess: true
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: my-gateway

Configure SSL Policies to secure client-to-load-balancer traffic

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

To secure your client-to-load-balancer traffic, configure the SSL policy by adding the name of your policy to the GCPGatewayPolicy. By default, the Gateway does not have any SSL Policy defined and attached.

Make sure that you create an SSL policy prior to referencing the policy in your GCPGatewayPolicy.

The following GCPGatewayPolicy manifest specifies a security policy named gke-gateway-ssl-policy:

apiVersion: networking.gke.io/v1
kind: GCPGatewayPolicy
metadata:
  name: my-gateway-policy
  namespace: team1
spec:
  default:
    sslPolicy: gke-gateway-ssl-policy
  targetRef:
    group: gateway.networking.k8s.io
    kind: Gateway
    name: my-gateway

Configure backend service timeout

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

The following GCPBackendPolicy manifest specifies a backend service timeout period of 40 seconds. The timeoutSec field defaults to 30 seconds.

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    timeoutSec: 40
  targetRef:
    group: ""
    kind: Service
    name: lb-service

Configure session affinity

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

You can configure session affinity based on the following criteria:

  • Client IP address
  • Generated cookie

The following GCPBackendPolicy manifest specifies a session affinity based on the client IP address:

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    sessionAffinity:
      type: CLIENT_IP
  targetRef:
    group: ""
    kind: Service
    name: lb-service

The following GCPBackendPolicy manifest specifies a session affinity based on a generated cookie and configures the cookies TTL to 50 seconds:

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    sessionAffinity:
      type: GENERATED_COOKIE
      cookieTtlSec: 50
  targetRef:
    group: ""
    kind: Service
    name: lb-service

You can use the following options for sessionAffinity.type: CLIENT_IP, CLIENT_IP_PROTO, CLIENT_IP_PORT_PROTO, GENERATED_COOKIE, HEADER_FIELD, HTTP_COOKIE, NONE.

Configure connection draining timeout

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

You can configure connection draining timeout using GCPBackendPolicy. Connection draining timeout is the time, in seconds, to wait for connections to drain. The timeout duration can be from 0 to 3600 seconds. The default value is 0, which also disables connection draining.

The following GCPBackendPolicy manifest specifies a connection draining timeout of 60 seconds:

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    connectionDraining:
      drainingTimeoutSec: 60
  targetRef:
    group: ""
    kind: Service
    name: lb-service

For the specified duration of the timeout, GKE waits for existing requests to the removed backend to complete. The load balancer does not send new requests to the removed backend. After the timeout duration is reached, GKE closes all remaining connections to the backend.

Configure HTTP access logging

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

Gateway can log all HTTP requests from clients to Cloud Logging.

You can enable and disable access logging using GCPBackendPolicy. You can also configure the access logging sampling rate.

To configure access logging, use the logging field in your GCPBackendPolicy. If logging is omitted, access logging is disabled by default.

The following CPBackendPolicy manifest enables access logging and sets the sample rate to 50% of the HTTP requests for a given Service resource:

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    logging:
      enabled: true
      sampleRate: 500000
  targetRef:
    group: ""
    kind: Service
    name: lb-service

This manifest has the following fields:

  • enable: true: enables access logging. Logs are available in Logging.
  • sampleRate: 500000: specifies that 50% of packets are logged. You can use a value between 0 and 1,000,000. GKE converts this value to a floating point value in the range [0, 1] by dividing by 1,000,000. This field is only relevant if enable is set to true. sampleRate is an optional field, but if it's configured then enable: true must also be set. If enable is set to true and sampleRate is not provided then GKE sets enable to false.

Configure Google Cloud Armor security policy to secure your backend services

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

Configure the Google Cloud Armor security policy by adding the name of your security policy to the GCPBackendPolicy to secure your backend services. By default, the Gateway does not have any Google Cloud Armor security policy defined and attached.

Make sure that you create a Google Cloud Armor security policy prior to referencing the policy in your GCPBackendPolicy.

The following GCPBackendPolicy manifest specifies a security policy named example-security-policy:

apiVersion: networking.gke.io/v1
kind: GCPBackendPolicy
metadata:
  name: my-backend-policy
  namespace: lb-service-namespace
spec:
  default:
    securityPolicy: example-security-policy
  targetRef:
    group: ""
    kind: Service
    name: lb-service

Configure health checks

This section describes a functionality that is available on GKE clusters running version 1.24 or later.

You can use a HealthCheckPolicy to control the load balancer health check settings. Each type of health check (http, https, grpc, and http2) has a collection of parameters that can be defined and Google Cloud creates a unique health check for each backend service for each GKE Service.

The following HealthCheckPolicy manifest shows all the fields available when configuring a health check policy:

apiVersion: networking.gke.io/v1
kind: HealthCheckPolicy
metadata:
  name: lb-healthcheck
  namespace: lb-service-namespace
spec:
  default:
    checkIntervalSec: INTERVAL
    timeoutSec: TIMEOUT
    healthyThreshold: HEALTHY_THRESHOLD
    unhealthyThreshold: UNHEALTHY_THRESHOLD
    logConfig:
      enabled: ENABLED
    config:
      type: PROTOCOL
      httpHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      httpsHealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
      grpcHealthCheck:
        grpcServiceName: GRPC_SERVICE_NAME
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
      http2HealthCheck:
        portSpecification: PORT_SPECIFICATION
        port: PORT
        portName: PORT_NAME
        host: HOST
        requestPath: REQUEST_PATH
        response: RESPONSE
        proxyHeader: PROXY_HEADER
  targetRef:
    group: ""
    kind: Service
    name: lb-service

Replace the following:

  • INTERVAL: specifies the check-interval, in seconds, for each health check prober. This is the time from the start of one prober's check to the start of its next check. If you omit this parameter, the Google Cloud default is 5 seconds. For more information, see Multiple probes and frequency.
  • TIMEOUT: specifies the amount of time that Google Cloud waits for a response to a probe. The value of TIMEOUT must be less than or equal to the INTERVAL. Units are seconds. Each probe requires an HTTP 200 (OK) response code to be delivered before the probe timeout.
  • HEALTHY_THRESHOLD and UNHEALTHY_THRESHOLD: specifies the number of sequential connection attempts that must succeed or fail, for at least one prober, to change the health state from healthy to unhealthy or unhealthy to healthy. If you omit one of these parameters, the Google Cloud default is 2.
  • PROTOCOL: specifies a protocol used by probe systems for health checking. For more information, see Success criteria for HTTP, HTTPS, and HTTP/2 and Success criteria for gRPC. This parameter is required.
  • ENABLED: specifies if logging is enabled or disabled.
  • PORT_SPECIFICATION: specifies if the health check uses a fixed port (USE_FIXED_PORT), named port (USE_NAMED_PORT) or serving port (USE_SERVING_PORT). If not specified, the health check follows the behavior specified in the port and portName fields. If neither port or portName are specified, this field defaults to USE_SERVING_PORT.
  • PATH: specifies the request-path to which the probe system should connect for HTTP, HTTPS, or HTTP2 health checks. If you omit this parameter, the Google Cloud default is /.
  • PORT: A HealthCheckPolicy only supports specifying the load balancer health check port by using a port number. If you omit this parameter, the Google Cloud default is 80. Because the load balancer sends probes to the Pod's IP address directly, you should select a port matching a containerPort of a serving Pods, even if the containerPort is referenced by a targetPort of the Service. You are not limited to containerPorts referenced by a Service's targetPort.
  • PORT_NAME: specifies the port name as defined in InstanceGroup.NamedPort.name. If both port and portName are defined, Google Cloud considers the port value first.
  • HOST: the value of the host header in the health check request. This value uses the RFC 1123 definition of a hostname except numeric IP addresses are not allowed. If not specified or left empty, this value defaults to the IP address of the health check.
  • REQUEST_PATH: specifies the request path of the health check request. If not specified or left empty, defaults to /.
  • RESPONSE: specifies the bytes to match against the beginning of the response data. If not specified or left empty, GKE interprets any response as healthy. The response data can only be ASCII.
  • PROXY_HEADER: specifies the proxy header type. You can use NONE or PROXY_V1. Defaults to NONE.
  • GRPC_SERVICE_NAME: an optional name of the gRPC Service. Omit this field to specify all Services.

For more information about HealthCheckPolicy fields, see the healthChecks reference.

What's next