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. 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:

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.

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

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

Cloud Armor 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 Cloud Armor security policy to be applied.

Was this page helpful? Let us know how we did:

Send feedback about...

Kubernetes Engine