BackendConfig custom resource

Beta

This is a Beta release of BackendConfig Custom Resource. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

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

Overview

BackendConfig is a custom resource definition that is used by the Kubernetes Engine Ingress controller. Beginning with GKE version 1.10.5-gke.3, you can provide configuration for a Cloud load balancer by associating Service ports with BackendConfig objects.

You can use a BackendConfig to configure these features of HTTP(S) Load Balancing:

• Cloud CDN (Cloud CDN)
• Google Cloud Armor
• Cloud Identity-Aware Proxy (Cloud IAP)
• Timeout, Connection draining timeout, Session affinity

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/v1beta1
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:

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 beta.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 beta.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 will revoke 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/v1beta1
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 beta.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 beta.cloud.google.com/backend-config annotation.

Important: Do not delete a BackendConfig object before you remove its name from the beta.cloud.google.com/backend-config annotation and apply the updated Service manifest. If you do, the configuration will not get removed from the HTTP(S) Load Balancing backend service. Also, you will see errors as Kubernetes events on the Ingress object.

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, Cloud IAP, and Cloud CDN.

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

You must use kubectl 1.7 or later to interact with BackendConfig. That is, you must have a version ofkubectl that supports custom resources.

What's next

• Configuring Cloud CDN
• Configuring Google Cloud Armor
• Enabling Cloud IAP for Kubernetes Engine
• Configuring Timeout, Connection draining timeout, and Session affinity
• BackendConfig Reference
• Setting up HTTP Load Balancing with Ingress
• HTTP(S) Load Balancing Concepts

Reference

BackendConfig v1beta1 cloud.google.com

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 v1beta1 cloud.google.com

Fields
iap	IAPConfig Cloud IAP configuration for the associated HTTP(S) Load Balancing backend service. Note that Cloud 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. Note that Cloud 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.

BackendConfigList v1beta1 cloud.google.com

Fields
	metav1.TypeMeta API group, version, and kind.
metadata	metav1.ObjectMeta Standard object metadata.
items	BackendConfig array List of BackendConfig objects.

IAPConfig v1beta1 cloud.google.com

Fields
enabled	boolean Specifies whether Cloud IAP is enabled for the associated HTTP(S) Load Balancing backend service.
oauthclientCredentials	OAuthClientCredentials Client credentials, including OAuth client ID and secret.

OAuthClientCredentials v1beta1 cloud.google.com

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 v1beta1 cloud.google.com

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 v1beta1 cloud.google.com

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 v1beta1 cloud.google.com

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

ConnectionDraining v1beta1 cloud.google.com

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

SessionAffinity v1beta1 cloud.google.com

Fields
affinityType	string The type of session affinity. Possible values are "CLIENT_IP", "GENERATED_COOKIE", and "NONE". Default is "NONE".
affinityCookieTtlSec	int64 Time to live, in seconds, for an affinity cookie. You can set affinityCookieTtlSec even even if affinityType is not "GENERATED_COOKIE".