BackendConfig custom resource

This page provides an overview of the BackendConfig custom resource and explains how it is used to configure Ingress in Google Kubernetes Engine (GKE). This page also provides reference material for the BackendConfig type and related types.

Overview

BackendConfig is a custom resource definition (CRD) that is used by the GKE Ingress controller. Beginning with GKE version 1.10.5-gke.3, you can provide configuration for an external HTTP(S) load balancer by associating Service ports with BackendConfig objects. Beginning with GKE version 1.16.4-gke.20, you can also use BackendConfig with an internal HTTP(S) load balancer.

The following table summarizes the features supported in the BackendConfig CRD for the External and Internal Ingress type. The BackendConfig feature reference section below describes the configuration and parameters of each feature.

BackendConfig feature support
Feature Ingress for External HTTP(S) Ingress for Internal HTTP(S) BackendConfig API version
Cloud CDN X v1, v1beta1
Identity-Aware Proxy (IAP) X v1, v1beta1
Google Cloud Armor security policy X v1, v1beta1
Timeout X X v1, v1beta1
HTTP access logging X X v1
Connection draining timeout X v1, v1beta1
Session Affinity X X v1, v1beta1
User-defined request headers X v1, v1beta1

To learn more about the basic concepts of HTTP(S) load balancing in Google Cloud, see HTTP(S) load balancing.

Example manifest

Here's an example of a manifest for a BackendConfig. The manifest specifies a Cloud CDN cache policy and declares that Cloud CDN should be enabled:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backend-config
spec:
  cdn:
    enabled: true
    cachePolicy:
      includeHost: true
      includeProtocol: true
      includeQueryString: false

Associating a Service port with a BackendConfig

In GKE, when you create a Kubernetes Ingress object, the GKE Ingress controller creates and configures an HTTP(S) load balancer for you. Your Ingress has rules, each of which references a port in a Kubernetes Service object. If a port of a Service is referenced by an Ingress, the port is associated with an HTTP(S) Load Balancing backend service.

If a Service port is referenced by an Ingress, and if the Service port is associated with a BackendConfig, then the HTTP(S) load balancing backend service takes part of its configuration from the BackendConfig.

Here is a Kubernetes Service manifest that has three ports:

For GKE Versions 1.16.8-gke.3+

    apiVersion: v1
    kind: Service
    metadata:
      annotations:
        cloud.google.com/backend-config:
          '{"ports": {"http":"config-http", "http2" :"config-http2"}, "default": "config-default"}'
      name: my-service
    spec:
      type: NodePort
      ports:
      - name: http
        protocol: TCP
        port: 80
        targetPort: 8080
      - name: http2
        protocol: TCP
        port: 443
        targetPort: 8080
      - name: http3
        protocol: TCP
        port: 49152
        targetPort: 49152
    ...
  

For GKE Versions below 1.16.8-gke.3

    apiVersion: v1
    kind: Service
    metadata:
      annotations:
        beta.cloud.google.com/backend-config:
          '{"ports": {"http":"config-http", "http2" :"config-http2"}, "default": "config-default"}'
      name: my-service
    spec:
      type: NodePort
      ports:
      - name: http
        protocol: TCP
        port: 80
        targetPort: 8080
      - name: http2
        protocol: TCP
        port: 443
        targetPort: 8080
      - name: http3
        protocol: TCP
        port: 49152
        targetPort: 49152
    ...
  

The cloud.google.com/backend-config annotation specifies a mapping between ports and BackendConfig objects. In the preceding manifest:

  • The http port is associated with a BackendConfig named config-http.
  • The http2 port is associated with a BackendConfig named config-http2.
  • All other ports for the Service are associated with the default BackendConfig, which is named config-default. So in this example, the http3 port is associated with config-default.

In the cloud.google.com/backend-config annotation, you must specify a ports field, a default field, or both.

Revoking the configuration specified in a BackendConfig

Neither removing the BackendConfig annotation from a Service nor deleting the BackendConfig object revokes the previously specified configuration in a BackendConfig. This is because the Ingress controller only reconciles configuration specified in the BackendConfig.

Therefore, you must explicitly disable the configuration in the BackendConfig to revoke the setup that is no longer needed. Here is an example of disabling the configuration:

apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: my-backend-config
spec:
  cdn:
    enabled: false
  securityPolicy:
    name: ""

Deleting a BackendConfig

To delete a BackedConfig, follow these steps:

  1. First remove the BackendConfig's name from the cloud.google.com/backend-config annotation in the Service manifest.

  2. Apply the changed Service manifest to your cluster, for example, by using kubectl apply.

  3. At this point, you can delete the BackendConfig. Note that you don't have to delete the BackendConfig. What's important is that you delete its name from the cloud.google.com/backend-config annotation.

Limitations

BackendConfigs have the following limitations:

  • One (Service, port) pair can consume only one BackendConfig, even if multiple Ingress objects reference the (Service, port). This means all Ingress objects that reference the same (Service, port) must use the same configuration for Google Cloud Armor, IAP, and Cloud CDN.

  • IAP and Cloud CDN cannot be enabled for the same HTTP(S) Load Balancing backend service. This means that you cannot configure both IAP and Cloud CDN in the same BackendConfig.

  • You must use kubectl 1.7 or later to interact with BackendConfig.

BackendConfig feature reference

BackendConfig

Fields

metav1.TypeMeta

API group, version, and kind.

metadata

metav1.ObjectMeta

Standard object metadata.

spec

BackendConfigSpec

The desired behavior of the BackendConfig.

status

BackendConfigStatus

Most recently observed status of the BackendConfig.

BackendConfigSpec

Fields
iap

IAPConfig

IAP configuration for the associated HTTP(S) Load Balancing backend service. IAP and Cloud CDN cannot be enabled for the same HTTP(S) Load Balancing backend service.

cdn

CDNConfig

Cloud CDN configuration for the associated HTTP(S) Load Balancing backend service. IAP and Cloud CDN cannot be enabled for the same HTTP(S) Load Balancing backend :service.

securityPolicy

SecurityPolicyConfig

Google Cloud Armor configuration for the associated HTTP(S) Load Balancing backend service.

timeoutSec int64

Request/response timeout in seconds. Default is 30 seconds..

connectionDraining

ConnectionDrainingConfig

Connection draining configuration for the associated HTTP(S) Load Balancing backend service.

sessionAffinity

SessionAffinityConfig

Session affinity configuration for the associated HTTP(S) Load Balancing backend service.

customRequestHeaders

CustomRequestHeadersConfig

User-defined request headers configuration for the associated HTTP(S) Load Balancing backend service.

logging

LogConfig

Logging configuration for the associated HTTP(S) Load Balancing backend service.

BackendConfigList

Fields

metav1.TypeMeta

API group, version, and kind.

metadata

metav1.ObjectMeta

Standard object metadata.

items

BackendConfig array

List of BackendConfig objects.

IAPConfig

Fields
enabled

boolean

Specifies whether IAP is enabled for the associated HTTP(S) Load Balancing backend service.

oauthclientCredentials

OAuthClientCredentials

Client credentials, including OAuth client ID and secret.

OAuthClientCredentials

Fields
secretName

string

Name of the Secret that stores the OAuth client ID and secret.

clientID

string

Direct reference to the OAuth client ID.

clientSecret

string

Direct reference to the OAuth client secret.

CDNConfig

Fields
enabled

boolean

Specifies whether Cloud CDN is enabled for the associated HTTP(S) Load Balancing backend service.

cachePolicy

CacheKeyPolicy

Cache key policy for the associated HTTP(S) Load Balancing backend service.

CacheKeyPolicy

Fields
includeHost

boolean

If true, request to different hosts are cached separately.

includeProtocol

boolean

If true, HTTP and HTTPS requests are cached separately.

includeQueryString

boolean

If includeQueryString is true, query string parameters are included in the cache key according to queryStringBlacklist and queryStringWhitelist. If neither is set, the entire query string is included. If includeQueryString is false, the entire query string is excluded from the cache key.

queryStringBlacklist

string array

Names of query string parameters to exclude from cache keys. All other parameters are included. Either specify queryStringBlacklist or queryStringWhitelist, but not both.

queryStringWhitelist

string array

Names of query string parameters to include in cache keys. All other parameters are excluded. Either specify queryStringBlacklist or queryStringWhitelist, but not both.

SecurityPolicyConfig

Fields
name

string

Name of the Google Cloud Armor security policy to be applied.

LogConfig

Also see how to configure access logging for Ingress.

Fields
enable

boolean

If true, access logging will be enabled for this Ingress and logs will be available in Cloud Logging.

If false, access logging will be disabled for this Ingress.

If logging is omitted, access logging will take the default behavior which is dependent on the GKE version.

sampleRate

int64

A value from 0.0 through 1.0, where 0.0 means no packets are logged and 1.0 means 100% of packets are logged. This field is only relevant if enable is set to true.

GKE Version Support
  • logging is supported in GKE versions 1.16.8-gke.10 and up. Prior to 1.16.8-gke.10 access logging is not directly configurable through Ingress
  • In GKE versions prior to 1.18 access logging defaults to on
  • In GKE 1.18 and later access logging defaults to off and requires logging to enable

ConnectionDraining

Fields
drainingTimeoutSec

int64

Time, in seconds, to wait for connections to drain. Default is 0 seconds.

SessionAffinity

Fields
affinityType

string

The type of session affinity. Possible values are "CLIENT_IP", "GENERATED_COOKIE", and "NONE". Default is "NONE".

affinityCookieTtlSec

int64

TTL, in seconds, for an affinity cookie. You can set affinityCookieTtlSec even if affinityType is not "GENERATED_COOKIE".

CustomRequestHeadersConfig

Fields
headers

string

Additional headers that the load balancer adds to the request. You specify each header as a header-name:header-value string.

What's next