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
- Identity-Aware Proxy (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 namedconfig-http
. - The
http2
port is associated with a BackendConfig namedconfig-http2
. - All other ports for the Service are associated with the default BackendConfig,
which is named
config-default
. So in this example, thehttp3
port is associated withconfig-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:
First remove the BackendConfig's name from the
beta.cloud.google.com/backend-config
annotation in the Service manifest.Apply the changed Service manifest to your cluster, for example, by using
kubectl apply
.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 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. That is,
you must have a version ofkubectl
that supports custom resources.
What's next
- Configuring Cloud CDN
- Configuring Google Cloud Armor
- Enabling 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 | |
---|---|
|
API group, version, and kind. |
metadata |
Standard object metadata. |
spec |
The desired behavior of the BackendConfig. |
status |
Most recently observed status of the BackendConfig. |
BackendConfigSpec v1beta1 cloud.google.com
Fields | |
---|---|
iap |
IAP configuration for the associated HTTP(S) Load Balancing backend service. Note that IAP and Cloud CDN cannot be enabled for the same HTTP(S) Load Balancing backend service. |
cdn |
Cloud CDN configuration for the associated HTTP(S) Load Balancing backend service. Note that IAP and Cloud CDN cannot be enabled for the same HTTP(S) Load Balancing backend :service. |
securityPolicy |
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 |
Connection draining configuration for the associated HTTP(S) Load Balancing backend service. |
sessionAffinity |
Session affinity configuration for the associated HTTP(S) Load Balancing backend service. |
BackendConfigList v1beta1 cloud.google.com
Fields | |
---|---|
|
API group, version, and kind. |
metadata |
Standard object metadata. |
items |
List of BackendConfig objects. |
IAPConfig v1beta1 cloud.google.com
Fields | |
---|---|
enabled |
Specifies whether IAP is enabled for the associated HTTP(S) Load Balancing backend service. |
oauthclientCredentials |
Client credentials, including OAuth client ID and secret. |
OAuthClientCredentials v1beta1 cloud.google.com
Fields | |
---|---|
secretName |
Name of the Secret that stores the OAuth client ID and secret. |
clientID |
Direct reference to the OAuth client ID. |
clientSecret |
Direct reference to the OAuth client secret. |
CDNConfig v1beta1 cloud.google.com
Fields | |
---|---|
enabled |
Specifies whether Cloud CDN is enabled for the associated HTTP(S) Load Balancing backend service. |
cachePolicy |
Cache key policy for the associated HTTP(S) Load Balancing backend service. |
CacheKeyPolicy v1beta1 cloud.google.com
Fields | |
---|---|
includeHost |
If true, request to different hosts are cached separately. |
includeProtocol |
If true, HTTP and HTTPS requests are cached separately. |
includeQueryString |
If |
queryStringBlacklist |
Names of query string parameters to exclude from cache keys. All
other parameters are included. Either specify
|
queryStringWhitelist |
Names of query string parameters to include in cache keys. All
other parameters are excluded. Either specify
|
SecurityPolicyConfig v1beta1 cloud.google.com
Fields | |
---|---|
name |
Name of the Google Cloud Armor security policy to be applied. |
ConnectionDraining v1beta1 cloud.google.com
Fields | |
---|---|
drainingTimeoutSec |
Time, in seconds, to wait for connections to drain. Default is 0 seconds. |
SessionAffinity v1beta1 cloud.google.com
Fields | |
---|---|
affinityType |
The type of session affinity. Possible values are "CLIENT_IP", "GENERATED_COOKIE", and "NONE". Default is "NONE". |
affinityCookieTtlSec |
Time to live, in seconds, for an affinity cookie. You can set
|