pulumi-gcp-kotlin/com.pulumi.gcp.compute.kotlin/BackendService

BackendService

class BackendService : KotlinCustomResource

A Backend Service defines a group of virtual machines that will serve traffic for load balancing. This resource is a global backend service, appropriate for external load balancing or self-managed internal load balancing. For managed internal load balancing, use a regional backend service instead. Currently self-managed internal load balancing is only available in beta. To get more information about BackendService, see:

API documentation
How-to Guides

Official Documentation

Warning: All arguments including iap.oauth2_client_secret and iap.oauth2_client_secret_sha256 will be stored in the raw state as plain-text.

Example Usage

Backend Service Basic

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HttpHealthCheck;
import com.pulumi.gcp.compute.HttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var defaultHttpHealthCheck = new HttpHealthCheck("defaultHttpHealthCheck", HttpHealthCheckArgs.builder()
            .requestPath("/")
            .checkIntervalSec(1)
            .timeoutSec(1)
            .build());
        var defaultBackendService = new BackendService("defaultBackendService", BackendServiceArgs.builder()
            .healthChecks(defaultHttpHealthCheck.id())
            .build());
    }
}

Backend Service Cache Simple

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HttpHealthCheck;
import com.pulumi.gcp.compute.HttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var defaultHttpHealthCheck = new HttpHealthCheck("defaultHttpHealthCheck", HttpHealthCheckArgs.builder()
            .requestPath("/")
            .checkIntervalSec(1)
            .timeoutSec(1)
            .build());
        var defaultBackendService = new BackendService("defaultBackendService", BackendServiceArgs.builder()
            .healthChecks(defaultHttpHealthCheck.id())
            .enableCdn(true)
            .cdnPolicy(BackendServiceCdnPolicyArgs.builder()
                .signedUrlCacheMaxAgeSec(7200)
                .build())
            .build());
    }
}

Backend Service Cache Include Http Headers

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyCacheKeyPolicyArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var default_ = new BackendService("default", BackendServiceArgs.builder()
            .cdnPolicy(BackendServiceCdnPolicyArgs.builder()
                .cacheKeyPolicy(BackendServiceCdnPolicyCacheKeyPolicyArgs.builder()
                    .includeHost(true)
                    .includeHttpHeaders("X-My-Header-Field")
                    .includeProtocol(true)
                    .includeQueryString(true)
                    .build())
                .cacheMode("USE_ORIGIN_HEADERS")
                .build())
            .enableCdn(true)
            .build());
    }
}

Backend Service Cache Include Named Cookies

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyCacheKeyPolicyArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var default_ = new BackendService("default", BackendServiceArgs.builder()
            .cdnPolicy(BackendServiceCdnPolicyArgs.builder()
                .cacheKeyPolicy(BackendServiceCdnPolicyCacheKeyPolicyArgs.builder()
                    .includeHost(true)
                    .includeNamedCookies(
                        "__next_preview_data",
                        "__prerender_bypass")
                    .includeProtocol(true)
                    .includeQueryString(true)
                    .build())
                .cacheMode("CACHE_ALL_STATIC")
                .clientTtl(7200)
                .defaultTtl(3600)
                .maxTtl(10800)
                .build())
            .enableCdn(true)
            .build());
    }
}

Backend Service Cache

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HttpHealthCheck;
import com.pulumi.gcp.compute.HttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var defaultHttpHealthCheck = new HttpHealthCheck("defaultHttpHealthCheck", HttpHealthCheckArgs.builder()
            .requestPath("/")
            .checkIntervalSec(1)
            .timeoutSec(1)
            .build());
        var defaultBackendService = new BackendService("defaultBackendService", BackendServiceArgs.builder()
            .healthChecks(defaultHttpHealthCheck.id())
            .enableCdn(true)
            .cdnPolicy(BackendServiceCdnPolicyArgs.builder()
                .cacheMode("CACHE_ALL_STATIC")
                .defaultTtl(3600)
                .clientTtl(7200)
                .maxTtl(10800)
                .negativeCaching(true)
                .signedUrlCacheMaxAgeSec(7200)
                .build())
            .build());
    }
}

Backend Service Cache Bypass Cache On Request Headers

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HttpHealthCheck;
import com.pulumi.gcp.compute.HttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCdnPolicyArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var defaultHttpHealthCheck = new HttpHealthCheck("defaultHttpHealthCheck", HttpHealthCheckArgs.builder()
            .requestPath("/")
            .checkIntervalSec(1)
            .timeoutSec(1)
            .build());
        var defaultBackendService = new BackendService("defaultBackendService", BackendServiceArgs.builder()
            .healthChecks(defaultHttpHealthCheck.id())
            .enableCdn(true)
            .cdnPolicy(BackendServiceCdnPolicyArgs.builder()
                .cacheMode("CACHE_ALL_STATIC")
                .defaultTtl(3600)
                .clientTtl(7200)
                .maxTtl(10800)
                .negativeCaching(true)
                .signedUrlCacheMaxAgeSec(7200)
                .bypassCacheOnRequestHeaders(
                    BackendServiceCdnPolicyBypassCacheOnRequestHeaderArgs.builder()
                        .headerName("Authorization")
                        .build(),
                    BackendServiceCdnPolicyBypassCacheOnRequestHeaderArgs.builder()
                        .headerName("Proxy-Authorization")
                        .build())
                .build())
            .build());
    }
}

Backend Service Traffic Director Round Robin

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HealthCheck;
import com.pulumi.gcp.compute.HealthCheckArgs;
import com.pulumi.gcp.compute.inputs.HealthCheckHttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.resources.CustomResourceOptions;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var healthCheck = new HealthCheck("healthCheck", HealthCheckArgs.builder()
            .httpHealthCheck(HealthCheckHttpHealthCheckArgs.builder()
                .port(80)
                .build())
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
        var default_ = new BackendService("default", BackendServiceArgs.builder()
            .healthChecks(healthCheck.id())
            .loadBalancingScheme("INTERNAL_SELF_MANAGED")
            .localityLbPolicy("ROUND_ROBIN")
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
    }
}

Backend Service Traffic Director Ring Hash

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HealthCheck;
import com.pulumi.gcp.compute.HealthCheckArgs;
import com.pulumi.gcp.compute.inputs.HealthCheckHttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceCircuitBreakersArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceConsistentHashArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceConsistentHashHttpCookieArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceConsistentHashHttpCookieTtlArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceOutlierDetectionArgs;
import com.pulumi.resources.CustomResourceOptions;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var healthCheck = new HealthCheck("healthCheck", HealthCheckArgs.builder()
            .httpHealthCheck(HealthCheckHttpHealthCheckArgs.builder()
                .port(80)
                .build())
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
        var default_ = new BackendService("default", BackendServiceArgs.builder()
            .healthChecks(healthCheck.id())
            .loadBalancingScheme("INTERNAL_SELF_MANAGED")
            .localityLbPolicy("RING_HASH")
            .sessionAffinity("HTTP_COOKIE")
            .circuitBreakers(BackendServiceCircuitBreakersArgs.builder()
                .maxConnections(10)
                .build())
            .consistentHash(BackendServiceConsistentHashArgs.builder()
                .httpCookie(BackendServiceConsistentHashHttpCookieArgs.builder()
                    .ttl(BackendServiceConsistentHashHttpCookieTtlArgs.builder()
                        .seconds(11)
                        .nanos(1111)
                        .build())
                    .name("mycookie")
                    .build())
                .build())
            .outlierDetection(BackendServiceOutlierDetectionArgs.builder()
                .consecutiveErrors(2)
                .build())
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
    }
}

Backend Service Network Endpoint

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.GlobalNetworkEndpointGroup;
import com.pulumi.gcp.compute.GlobalNetworkEndpointGroupArgs;
import com.pulumi.gcp.compute.GlobalNetworkEndpoint;
import com.pulumi.gcp.compute.GlobalNetworkEndpointArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import com.pulumi.gcp.compute.inputs.BackendServiceBackendArgs;
import com.pulumi.resources.CustomResourceOptions;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var externalProxy = new GlobalNetworkEndpointGroup("externalProxy", GlobalNetworkEndpointGroupArgs.builder()
            .networkEndpointType("INTERNET_FQDN_PORT")
            .defaultPort("443")
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
        var proxy = new GlobalNetworkEndpoint("proxy", GlobalNetworkEndpointArgs.builder()
            .globalNetworkEndpointGroup(externalProxy.id())
            .fqdn("test.example.com")
            .port(externalProxy.defaultPort())
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
        var default_ = new BackendService("default", BackendServiceArgs.builder()
            .enableCdn(true)
            .timeoutSec(10)
            .connectionDrainingTimeoutSec(10)
            .customRequestHeaders(proxy.fqdn().applyValue(fqdn -> String.format("host: %s", fqdn)))
            .customResponseHeaders("X-Cache-Hit: {cdn_cache_status}")
            .backends(BackendServiceBackendArgs.builder()
                .group(externalProxy.id())
                .build())
            .build(), CustomResourceOptions.builder()
                .provider(google_beta)
                .build());
    }
}

Backend Service External Managed

package generated_program;
import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import com.pulumi.gcp.compute.HealthCheck;
import com.pulumi.gcp.compute.HealthCheckArgs;
import com.pulumi.gcp.compute.inputs.HealthCheckHttpHealthCheckArgs;
import com.pulumi.gcp.compute.BackendService;
import com.pulumi.gcp.compute.BackendServiceArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;
public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }
    public static void stack(Context ctx) {
        var defaultHealthCheck = new HealthCheck("defaultHealthCheck", HealthCheckArgs.builder()
            .httpHealthCheck(HealthCheckHttpHealthCheckArgs.builder()
                .port(80)
                .build())
            .build());
        var defaultBackendService = new BackendService("defaultBackendService", BackendServiceArgs.builder()
            .healthChecks(defaultHealthCheck.id())
            .loadBalancingScheme("EXTERNAL_MANAGED")
            .build());
    }
}

Import

BackendService can be imported using any of these accepted formats

$ pulumi import gcp:compute/backendService:BackendService default projects/{{project}}/global/backendServices/{{name}}

$ pulumi import gcp:compute/backendService:BackendService default {{project}}/{{name}}

$ pulumi import gcp:compute/backendService:BackendService default {{name}}

Properties

affinityCookieTtlSec

val affinityCookieTtlSec: Output<Int>?

Lifetime of cookies in seconds if session_affinity is GENERATED_COOKIE. If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value for TTL is one day. When the load balancing scheme is INTERNAL, this field is not used.

backends

val backends: Output<List<BackendServiceBackend>>?

The set of backends that serve this BackendService. Structure is documented below.

cdnPolicy

val cdnPolicy: Output<BackendServiceCdnPolicy>

Cloud CDN configuration for this BackendService. Structure is documented below.

circuitBreakers

val circuitBreakers: Output<BackendServiceCircuitBreakers>?

Settings controlling the volume of connections to a backend service. This field is applicable only when the load_balancing_scheme is set to INTERNAL_SELF_MANAGED. Structure is documented below.

compressionMode

val compressionMode: Output<String>?

Compress text responses using Brotli or gzip compression, based on the client's Accept-Encoding header. Possible values are: AUTOMATIC, DISABLED.

connectionDrainingTimeoutSec

val connectionDrainingTimeoutSec: Output<Int>?

Time for which instance will be drained (not accept new connections, but still work to finish started).

consistentHash

val consistentHash: Output<BackendServiceConsistentHash>?

Consistent Hash-based load balancing can be used to provide soft session affinity based on HTTP headers, cookies or other properties. This load balancing policy is applicable only for HTTP connections. The affinity to a particular destination host will be lost when one or more hosts are added/removed from the destination service. This field specifies parameters that control consistent hashing. This field only applies if the load_balancing_scheme is set to INTERNAL_SELF_MANAGED. This field is only applicable when locality_lb_policy is set to MAGLEV or RING_HASH. Structure is documented below.

creationTimestamp

val creationTimestamp: Output<String>

Creation timestamp in RFC3339 text format.

customRequestHeaders

val customRequestHeaders: Output<List<String>>?

Headers that the HTTP/S load balancer should add to proxied requests.

customResponseHeaders

val customResponseHeaders: Output<List<String>>?

Headers that the HTTP/S load balancer should add to proxied responses.

description

val description: Output<String>?

An optional description of this resource.

edgeSecurityPolicy

val edgeSecurityPolicy: Output<String>?

The resource URL for the edge security policy associated with this backend service.

enableCdn

val enableCdn: Output<Boolean>?

If true, enable Cloud CDN for this BackendService.

fingerprint

val fingerprint: Output<String>

Fingerprint of this resource. A hash of the contents stored in this object. This field is used in optimistic locking.

generatedId

val generatedId: Output<Int>

The unique identifier for the resource. This identifier is defined by the server.

healthChecks

val healthChecks: Output<String>?

The set of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified. A health check must be specified unless the backend service uses an internet or serverless NEG as a backend. For internal load balancing, a URL to a HealthCheck resource must be specified instead.

iap

val iap: Output<BackendServiceIap>?

Settings for enabling Cloud Identity Aware Proxy Structure is documented below.

val id: Output<String>

loadBalancingScheme

val loadBalancingScheme: Output<String>?

Indicates whether the backend service will be used with internal or external load balancing. A backend service created for one type of load balancing cannot be used with the other. For more information, refer to Choosing a load balancer. Default value is EXTERNAL. Possible values are: EXTERNAL, INTERNAL_SELF_MANAGED, INTERNAL_MANAGED, EXTERNAL_MANAGED.

localityLbPolicies

val localityLbPolicies: Output<List<BackendServiceLocalityLbPolicy>>?

A list of locality load balancing policies to be used in order of preference. Either the policy or the customPolicy field should be set. Overrides any value set in the localityLbPolicy field. localityLbPolicies is only supported when the BackendService is referenced by a URL Map that is referenced by a target gRPC proxy that has the validateForProxyless field set to true. Structure is documented below.

localityLbPolicy

val localityLbPolicy: Output<String>?

The load balancing algorithm used within the scope of the locality. The possible values are:

logConfig

val logConfig: Output<BackendServiceLogConfig>

This field denotes the logging options for the load balancer traffic served by this backend service. If logging is enabled, logs will be exported to Stackdriver. Structure is documented below.

name

val name: Output<String>

Name of the resource. Provided by the client when the resource is created. The name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression a-z? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.

outlierDetection

val outlierDetection: Output<BackendServiceOutlierDetection>?

Settings controlling eviction of unhealthy hosts from the load balancing pool. This field is applicable only when the load_balancing_scheme is set to INTERNAL_SELF_MANAGED. Structure is documented below.

portName

val portName: Output<String>

Name of backend port. The same name should appear in the instance groups referenced by this service. Required when the load balancing scheme is EXTERNAL.

project

val project: Output<String>

The ID of the project in which the resource belongs. If it is not provided, the provider project is used.

protocol

val protocol: Output<String>

The protocol this BackendService uses to communicate with backends. The default is HTTP. NOTE: HTTP2 is only valid for beta HTTP/2 load balancer types and may result in errors if used with the GA API. NOTE: With protocol “UNSPECIFIED”, the backend service can be used by Layer 4 Internal Load Balancing or Network Load Balancing with TCP/UDP/L3_DEFAULT Forwarding Rule protocol. Possible values are: HTTP, HTTPS, HTTP2, TCP, SSL, GRPC, UNSPECIFIED.

pulumiChildResources

val pulumiChildResources: Set<KotlinResource>

pulumiResourceName

val pulumiResourceName: String

pulumiResourceType

val pulumiResourceType: String

securityPolicy

val securityPolicy: Output<String>?

The security policy associated with this backend service.

securitySettings

val securitySettings: Output<BackendServiceSecuritySettings>?

The security settings that apply to this backend service. This field is applicable to either a regional backend service with the service_protocol set to HTTP, HTTPS, or HTTP2, and load_balancing_scheme set to INTERNAL_MANAGED; or a global backend service with the load_balancing_scheme set to INTERNAL_SELF_MANAGED. Structure is documented below.

selfLink

val selfLink: Output<String>

The URI of the created resource.

sessionAffinity

val sessionAffinity: Output<String>

Type of session affinity to use. The default is NONE. Session affinity is not applicable if the protocol is UDP. Possible values are: NONE, CLIENT_IP, CLIENT_IP_PORT_PROTO, CLIENT_IP_PROTO, GENERATED_COOKIE, HEADER_FIELD, HTTP_COOKIE.

timeoutSec

val timeoutSec: Output<Int>

How many seconds to wait for the backend before considering it a failed request. Default is 30 seconds. Valid range is 1, 86400.

urn

val urn: Output<String>