This page describes parameters for the Service manifests which control LoadBalancerService behavior and configuration. Before reading this page, ensure that you'refamiliar withGoogle Kubernetes Engine (GKE) LoadBalancer Serviceconcepts.

Important: LoadBalancer Services rely on specific finalizers (prefixed withnetworking.gke.io) and debug annotations (prefixed withservice.kubernetes.io). Don't manually edit or remove these finalizers orannotations. Modifying or removing these objects can cause unexpected behavioror disruptions.

Service parameters

GKE supports the following parameters for LoadBalancer Services.

Parameter	Service field and description	Internal	External	Version Support
Internal passthrough Network Load Balancer	networking.gke.io/load-balancer-type: "Internal" Instructs GKE to create an internal passthrough Network Load Balancer. The load balancer usesGCE_VM_IP NEG backends if the Service manifest is applied to a cluster with GKE subsetting enabled. The load balancer uses instance group backends if the Service manifest is applied to a cluster that doesn't have GKE subsetting enabled. For more information, see Node grouping.			All supported versions.
Backend service-based external passthrough Network Load Balancer	cloud.google.com/l4-rbs: "enabled" Instructs GKE to create a backend service-based external passthrough Network Load Balancer. The load balancer usesGCE_VM_IP NEG backends if the Service manifest is applied to a cluster running GKE version 1.32.2-gke.1652000 or later. The load balancer uses instance group backends if the Service manifest is applied to a cluster running an earlier supported GKE version. For more information, see Node grouping.			GKE 1.25.5
Weighted Load Balancing	networking.gke.io/weighted-load-balancing: "pods-per-node" Allows nodes that have more serving Pods to receive a larger proportion of new connections compared to nodes that have fewer serving Pods.			GKE 1.31.0+
Internal Traffic Policy	spec.internalTrafficPolicy When set toLocal, GKE only routes packets from client Pods on a node to serving Pods on the same node. When set toCluster, GKE routes packets from client Pods on a node to serving Pods on any node. For more details, see Service Internal Traffic Policy. This parameter is not supported in clusters running GKE Dataplane V2.			GKE 1.22+
External Traffic Policy	spec.externalTrafficPolicy Controls which node VMs pass load balancer health checks and how packets are routed to ready and serving Pods in the cluster. Also controls how nodes are grouped intoGCE_VM_IP NEGs whenGKE subsetting is enabled. For details, see LoadBalancer Service concepts.			GKE 1.14+ (1.23.4-gke.400+ for Windows node pool).
Zonal affinity (Preview)	spec.trafficDistribution Enables zonal affinity for internal LoadBalancer Services. Zonal affinity controls the zone to which the internal passthrough Network Load Balancer routes incoming traffic for compatible clients when a zonal match is possible. To use zonal affinity, you must enable GKE subsetting. For more information, see Zonal affinity and traffic distribution.			GKE 1.33.3-gke.1392000 or later.
Health check port	spec.healthCheckNodePort Deploys a load balancer health check for LoadBalancer Services. This parameter is only valid ifspec.externalTrafficPolicy is set toLocal.			All supported versions.
Firewall rules and source IP address allowlist	spec.loadBalancerSourceRanges Configures optional firewall rules in GKE and in the VPC network to only allow certain source ranges.kube-proxy also configuresiptables rules to match the specified source ranges.			All supported versions.
Static IP addresses	spec.loadBalancerIP (IPv4 only) networking.gke.io/load-balancer-ip-addresses Specifies a static IPv4 address, static IPv6 address range, or both, that are assigned to the forwarding rules of the load balancer. SeeConsiderations for sharing a common IP address for important configuration requirements and implementation details.			spec.loadBalancerIP: All supported versions. networking.gke.io/load-balancer-ip-addresses: GKE 1.29 and later. SeeStatic IP address parameters for additional cluster configuration or annotation requirements.
Network Service Tiers	cloud.google.com/network-tier Specifies whichNetwork Service Tiers GKE uses for the external forwarding rule and IP address. The annotation valid values areStandard andPremium (default).			GKE 1.19 and later.
Custom subnet	networking.gke.io/internal-load-balancer-subnet networking.gke.io/load-balancer-subnet		(only applies to IPv6)	networking.gke.io/internal-load-balancer-subnet: All supported versions networking.gke.io/load-balancer-subnet: GKE 1.29 and later. SeeCustom subnet annotations for additional requirements.
Global access	networking.gke.io/internal-load-balancer-allow-global-access: "true" Enables the IP address of the forwarding rule to be accessible by clients in any region of the VPC network or a connected network.			Preview in GKE 1.16+. Generally available in GKE 1.17.9-gke.600+.
All ports	GKE automatically configures the forwarding rule to use all ports if more than five (up to 100) unique ports are specified inspec.ports[].port.			GKE version 1.18.19-gke.1400 or later
ipFamilyPolicy	spec.ipFamilyPolicy Defines how GKE allocates IP addresses to a Service. You can define thespec.ipFamilyPolicy asSingleStack,PreferDualStack, orRequireDualStack. To learn more, see IPv4/IPv6 dual-stack Services.			GKE clusters in version 1.29 or later support dual-stack network for LoadBalancer Services.
ipFamilies (Optional)	spec.ipFamilies Defines the IP address family to allocate either single-stack or dual-stack Services. Use any of the following values: IPv4 for single-stack IPv4 Service only. IPv6 for IPv6 Service only. IPv4,IPv6 for dual-stack Service where the primary IP address of the Service is IPv4. IPv6,IPv4 for dual-stack Service where the primary IP address of the Service is IPv6.			GKE clusters in version 1.29 or later support dual-stack network for LoadBalancer Services.

Health check port

As described inLoad balancer health checks,GKE always deploys a load balancer health check when it createsan external passthrough Network Load Balancer or internal passthrough Network Load Balancer.

Whether you can set uphealthCheckNodePort parameter or not depends on thefollowingexternalTrafficPolicy configuration:

externalTrafficPolicy	Health check port
Cluster	You cannot usespec.healthCheckNodePort.
Local	You can select a custom port by using thespec.healthCheckNodePort. If unspecified, the Kubernetes control plane assigns a health check port from the node port range. Note: Either thekube-proxy (legacy Dataplane) orcilium-agent (GKE Dataplane V2) responds to packets sent to the health check node port. Health checks for LoadBalancer Services cannot be answered by serving Pods.

Warning: Don't customize the external passthrough Network Load Balancer or internal passthrough Network Load Balancer by modifyingits health check resource outside of GKE.GKE does not offer any other customization parametersfor load balancer health checks created for LoadBalancer Services.

Firewall rules and source IP address allowlist

Unless you've configured a cluster toskip creating VPC firewallrules for LoadBalancerServices,GKE creates an ingress allowVPC firewall rulefor each Service.

Each automatically created firewall rule has the following characteristics:

• The firewall rule's direction is ingress, and its action is allow. Theimplied deny ingress firewallrules in Google Cloudmean that GKE uses an allowlist model when creating ingressfirewall rules.
• GKE sets the firewall rule's protocol and destination port tothose specified in the Service'sspec.ports[] list.
• GKE configures firewall rules for LoadBalancer Services byexplicitly setting thedestinationparameter to thevirtual IP address of the LoadBalancer (the load balancer's forwarding rule).
• GKE sets thetargetparameter of the firewall rule toinclude all nodes of the cluster.
• If the Service includesspec.loadBalancerSourceRanges[],GKE sets the firewall rule'ssourceparameter to the IPaddresses in that list. Additionally, GKE configures routesand rules within the node operating system to limit the source IP addressesfor load-balanced traffic, usingkube-proxy andiptables (LegacyDataplane) orcilium-agent and eBPF rules (GKE Dataplane V2). If theService does not includeloadBalancerSourceRanges[], GKEsets the firewall rule's source parameter to all IP addresses(0.0.0.0/0).

Static IP addresses

You cancreate a static IPaddress and configureGKE to assign that static address to the load balancer'sforwarding rule. Using a static IP address ensures that the load balancer's IPaddress remains the same even if you make changes to the LoadBalancer Service.Without a static IP address, GKE might assign a different IPaddress to the load balancer forwarding rule when you update a LoadBalancerService. The forwarding rule IP address isnot the same as the Service'sspec.clusterIP address. The ClusterIP address for a Service never changes whenyou update a LoadBalancer Service.

Static IP address parameters

To instruct a LoadBalancer Service to use a static IP address, use either thespec.loadBalancerIP parameter or thenetworking.gke.io/load-balancer-ip-addresses annotation. In GKEversion 1.29 and later, the annotation takes precedence overspec.loadBalancerIP if the Service manifest contains both the parameter andthe annotation.

Parameter or annotation and value	Requirements and capabilities
spec.loadBalancerIP: IPv4_ADDRESS	You can specify a static internal IPv4 address for an IPv4-only Internal LoadBalancer Service. You can specify a static external IPv4 address for an IPv4-only External LoadBalancer Service. The parameter works with all supported GKE versions.
networking.gke.io/load-balancer-ip-addresses: IP_ADDRESS_RESOURCE_NAME For single-stack LoadBalancer Services, set the value of the annotation to the IPv4 or IPv6 address resourcename, not the IP address itself. For dual-stack LoadBalancer Services, set the value of the annotation to the static IPv4 address resource name and the static IPv6 address range resource name separated by a comma.	You can specify static IPv4 address, static IPv6 address range, or both for IPv4-only, IPv6-only, and dual-stack Internal and External LoadBalancer Services. The annotation requires GKE 1.29 or later and the following additional requirements: To use this annotation with an Internal LoadBalancer Service, you must create the Internal LoadBalancer Service in a cluster after enabling GKE subsetting. To use this annotation with an External LoadBalancer Service, you must include thecloud.google.com/l4-rbs: "enabled" annotation in the Service manifest when you create the External LoadBalancer Service.

Considerations for sharing a common IP address

Two or more LoadBalancer Services can reference the same static IP address ifthe forwarding rule for each load balancer uses a unique combination of IPaddress, protocol, port specification, and Network Service Tiers specification,as indicated in the table in this section. Additionally:

• Static IPv6 addresses are actually/96 IPv6 address ranges, butGKE only configures nodes to accept packets on the first IPv6address (/128) in the/96 range.

• For two or more Internal LoadBalancer Services to use the same internal IPv4address or internal IPv6 address range, the static IP address must be createdwith theSHARED_LOADBALANCER_VIP purpose.

	Internal LoadBalancer Service	External LoadBalancer Service
Port specification	Forwarding rules for internal passthrough Network Load Balancers support up to five individual port numbers, or they can be configured to use all ports. When an Internal LoadBalancer Service has more than fivespec.ports[] specified, GKE configures the forwarding rule for the internal passthrough Network Load Balancer to use all ports. Forwarding rules with the same IP address and protocol cannot have overlapping ports. This means you cannot create multiple Internal LoadBalancer Services that share the same IP address, protocol, and port(s). For example: If you create an Internal LoadBalancer Service using TCP port 80, you cannot create another Service using TCP ports 80, 81, and 90 because port 80 overlaps. If an Internal LoadBalancer Service uses TCP ports 80, 8080, and 90, you cannot create another Service using TCP on all ports, as this would also result in overlapping ports For more information, see: internal passthrough Network Load Balancer forwarding rules that use a common IP address.	GKE creates a target pool based external passthrough Network Load Balancer if the LoadBalancer Service manifestlacks thecloud.google.com/l4-rbs: "enabled" annotation. Forwarding rules for target pool based external passthrough Network Load Balancers must usecontiguous port ranges. The contiguous port range includes all ports the Service needs, but the range might also include additional ports not used by the Service. For example, an External LoadBalancer Service powered by a target pool based external passthrough Network Load Balancer which specifies ports 80 and 443 in its Service manifest uses a load balancer forwarding rule with aport range of 80-443. This port range prevents other External LoadBalancer Services from using any of the ports 80, 443, and any of the numbers between 80 and 443. GKE creates a backend service-based external passthrough Network Load Balancer if the LoadBalancer Service manifestincludes thecloud.google.com/l4-rbs: "enabled" annotation. Forwarding rules for backend service-based external passthrough Network Load Balancers support up to five discrete port numbers or acontiguous port range.
Network Service Tiers	Not configurable—internal addresses are always Premium tier.	Configurable for static regional external IPv4 addresses. Static regional external IPv6 address ranges can only be created in the Premium tier. The Network Service Tiers specification of the static external IP address must match either: The tier specified in the LoadBalancer Service manifest'scloud.google.com/network-tier annotation, if that annotation is present in the manifest, or The project's default tier, if thecloud.google.com/network-tier annotation is absent from the LoadBalancer Service manifest. The project's default tier is Premium, unless you have configured it differently.

IP address reservation

GKE doesn't reserve the static IP addresses configured usingspec.loadBalancerIP ornetworking.gke.io/load-balancer-ip-addresses annotation.This means that the IP address you assign to your Servicecan be released when the Service is deleted.

To keep the IP address reserved, you must manually create an addressresource in your project. The static IP address must have the following attributes:

• Be regional only.
• Be in the same region as the cluster.
• Be in the sameNetwork Service Tiersas the LoadBalancer Service.
• Have a name which does doesn't use the LoadBalancer name, prefixes likek8s-, or theservice's UUID.

If you don't reserve the address yourself, the project logs can contain entriesabout address resources created and shortly removed. This is a part of normalservice provisioning and should be expected.

LoadBalancer subnet

You can configure an Internal LoadBalancer Service to use an ephemeral or staticIPv4 address, IPv6 address range, or both, in a custom subnet located in thesame region and VPC network as the cluster. Use a custom subnetfor an Internal LoadBalancer Service to:

• Group internal passthrough Network Load Balancers created by Internal LoadBalancer Services from two ormore GKE clusters in the same VPC network andregion.
• Create Internal LoadBalancer Services whose internal passthrough Network Load Balancers have IPv4addresses separate from the cluster's node IPv4 addresses.
• In a dual-stack cluster, create Internal LoadBalancer Services whoseinternal passthrough Network Load Balancers have IPv6 address ranges separate from the cluster's node andPod IPv6 addresses. A custom LoadBalancer subnet is mandatory to supportInternal LoadBalancer Services if the cluster's subnet has anexternal IPv6address range.

You can configure an External LoadBalancer Service to use an ephemeral or staticIPv6 address range in a custom subnet located in the same region andVPC network as the cluster. Use a custom subnet to createExternal LoadBalancer Services whose external passthrough Network Load Balancers have IPv6 address rangesseparate from the cluster's node and Pod IPv6 addresses. A custom LoadBalancersubnet is mandatory to support External LoadBalancer Services in a dual-stackcluster because the cluster's subnet has aninternal IPv6 addressrange.

Note: The custom subnet annotation has no effect on the selection of theexternal IPv4 address for an External LoadBalancer Service because IPv4addresses for external passthrough Network Load Balancers are not sourced from subnet ranges of aVPC network.

Custom subnet annotations

Use one of the following annotations to instruct a LoadBalancer Service to usean ephemeral or static IP address in a custom subnet. If a LoadBalancer Servicemanifest includes both annotations, thenetworking.gke.io/load-balancer-subnetannotation takes precedence provided that its annotation requirements are met.

Annotation and value	Requirements and capabilities
networking.gke.io/internal-load-balancer-subnet: SUBNET_RESOURCE_NAME	You can only use the annotation to specify a custom subnet for an IPv4-only Internal LoadBalancer Service. The annotation works with all supported GKE versions.
networking.gke.io/load-balancer-subnet: SUBNET_RESOURCE_NAME	You can specify a custom subnet for an IPv4-only, IPv6-only, or dual-stack Internal LoadBalancer Service. You can specify a custom subnet for an IPv6-only or dual-stack External LoadBalancer Service. The annotation requires GKE 1.29 or later and the following additional requirements: To use this annotation to specify a custom subnet for an Internal LoadBalancer Service, you must create the Internal LoadBalancer Service in a cluster after enabling GKE subsetting. To use this annotation to specify a custom subnet for an External LoadBalancer Service, you must include thecloud.google.com/l4-rbs: "enabled" annotation in the Service manifest when you create the External LoadBalancer Service.

Subnet and IPv4 address for an Internal LoadBalancer Service

The following table describes valid subnet specification and IPv4 addresscombinations for an IPv4-only or dual-stack Internal LoadBalancer Service.

	Static IPv4 address For IPv4-only, can be specified using eitherStatic IP address parameter. For dual-stack, must be specified using thenetworking.gke.io/load-balancer-ip-addresses annotation.	Ephemeral IPv4 address
Custom subnet Must be in the same VPC network and region as the cluster. For IPv4-only, can be specified using either of theCustom subnet annotations. For dual-stack, must be specified using thenetworking.gke.io/load-balancer-subnet annotation.	Custom subnet and static IPv4 address: The static internal IPv4 address must have been created in the custom subnet's primary IPv4 address range.	Custom subnet and ephemeral IPv4 address: GKE uses an unallocated internal IPv4 address in the custom subnet primary IPv4 address range.
Cluster subnet	Cluster subnet and static IPv4 address: The static internal IPv4 address must have been created in the cluster subnet's primary IPv4 address range.	Cluster subnet and ephemeral IPv4 address: GKE uses an unallocated internal IPv4 address in the cluster subnet primary IPv4 address range.

Subnet and IPv6 address range for an Internal LoadBalancer Service

The following table describes valid subnet specification and IPv6 address rangecombinations for an IPv6-only or dual-stack Internal LoadBalancer Service. Eventhough the internal passthrough Network Load Balancer IPv6 forwarding rule uses an internal/96 IPv6address range, GKE only configures nodes to accept packets whosedestinations match the first IPv6 address (/128) of the forwarding rule's/96 range.

	Static IPv6 address range Must be specified using thenetworking.gke.io/load-balancer-ip-addresses annotation	Ephemeral IPv6 address range
Custom dual-stack subnet Must be in the same VPC network and region as the cluster. Must have an internal IPv6 address range (access typeINTERNAL). Must be specified using thenetworking.gke.io/load-balancer-subnet annotation.	Custom subnet and static IPv6 address range: The static internal/96 IPv6 address range must have been created in the custom subnet's internal/64 IPv6 address range.	Custom subnet and ephemeral IPv6 address range: GKE uses an unallocated internal/96 IPv6 address range from the custom subnet's internal/64 IPv6 address range.
Cluster dual-stack subnet Must have an internal IPv6 address range (access typeINTERNAL).	Cluster subnet and static IPv6 address range: The static internal/96 IPv6 address range must have been created in the cluster subnet's internal/64 IPv6 address range.	Cluster subnet and ephemeral IPv6 address range: GKE uses an unallocated internal/96 IPv6 address range from the cluster subnet's internal/64 IPv6 address range.

Subnet and IPv4 address for an External LoadBalancer Service

For IPv4-only and dual-stack External LoadBalancer Services, the external IPv4address—whether astatic external IPv4 address or an ephemeral external IPv4address—doesn't come from a subnet.

Subnet and IPv6 address range for an External LoadBalancer Service

The following table describes valid subnet specification and IPv6 address rangecombinations for an IPv6-only or dual-stack External LoadBalancer Service. Eventhough the external passthrough Network Load Balancer IPv6 forwarding rule uses an external/96 IPv6address range, GKE only configures nodes to accept packets whosedestinations match the first IPv6 address (/128) of the forwarding rule's/96 range.

	Static IPv6 address range Must be specified using thenetworking.gke.io/load-balancer-ip-addresses annotation	Ephemeral IPv6 address range
Custom dual-stack subnet Must be in the same VPC network and region as the cluster. Must have an external IPv6 address range (access typeEXTERNAL). Must be specified using thenetworking.gke.io/load-balancer-subnet annotation.	Custom subnet and static IPv6 address range: The static external/96 IPv6 address range must have been created in the custom subnet's external/64 IPv6 address range. Static external IPv6 address ranges can only be created in Premium tier.	Custom subnet and ephemeral IPv6 address range: GKE uses an unallocated external/96 IPv6 address range from the custom subnet's external/64 IPv6 address range.
Cluster dual-stack subnet Must have an external IPv6 address range (access typeEXTERNAL).	Cluster subnet and static IPv6 address range: The static external/96 IPv6 address range must have been created in the cluster subnet's external/64 IPv6 address range. Static external IPv6 address ranges can only be created in Premium tier.	Cluster subnet and ephemeral IPv6 address range: GKE uses an unallocated external/96 IPv6 address range from the cluster subnet's external/64 IPv6 address range.

Global access

When thenetworking.gke.io/internal-load-balancer-allow-global-accessannotation isfalse or unspecified for an Internal LoadBalancer Service,GKE creates an internal passthrough Network Load Balancer whose forwarding rule hasglobal access disabled. When global access is disabled, clients that need toaccess the load balancer must be located in the same region andVPC network, or a network connected to the cluster'sVPC network.

When thenetworking.gke.io/internal-load-balancer-allow-global-accessannotation istrue for an Internal LoadBalancer Service, GKEenables the global access option on the internal passthrough Network Load Balancer's forwarding rule.Clients located in any region of the VPC network or a networkconnected to the cluster's VPC network can access the loadbalancer.

Note: If you use aninternal load balancer withPrivate Service Connect,you might face an error when you enable global access on the Service. Tomitigate this issue, follow the steps outlined inError enabling globalaccess.

For more information about how global access applies to clients in a connectednetwork, see:

• Client access in the internal passthrough Network Load Balancerdocumentation
• Internal passthrough Network Load Balancers and connected networks

All ports forwarding rules

Forwarding rules for internal passthrough Network Load Balancers support five unique port numbers or allports.

In GKE, anInternal LoadBalancer Service can only support up to 100 ports in the Service'sspec.ports[].port. If an Internal LoadBalancer Service defines up to five ports, the forwarding rule will include those specific ports. However, if the Service specifies more than five ports, the forwarding rule will automatically be configured to match all ports. When configuring a forwarding rule to useall ports, GKE only creates ingress allow firewall rules for thespecific ports configured inspec.ports[].port on the Service.

For more information about internal passthrough Network Load Balancer forwarding rules and valid portspecifications, seeForwarding rules and portspecifications.

IPv4/IPv6 dual-stack LoadBalancer Service

You can create an Internal or External LoadBalancer Service that can be single-stack (IPv4 only or IPv6 only) or dual-stack. Single-stack LoadBalancer Services create a single forwarding rule with either an IPv4 address or an IPv6 address. Dual-stack LoadBalancer Services create two forwarding rules: one with an IPv4 address, and another with an IPv6 address.To create a IPv4/IPv6 dual-stack LoadBalancer Service, deploy it on aIPv4/IPv6 dual-stack cluster and complete any of the following depending on the type of load balancer you use:

• For Internal LoadBalancer Services, you must have GKE subsetting enabled. For moreinformation see, enablingInternal load balancer subsetting.
• For External LoadBalancer Services, you must use a backend service-based external passthrough Network Load Balancer.For more information, seebackend service-based external Network Load Balancer.

For eachService, you can defineipFamilyPolicy andipFamilies specs. To learn more,seeIPv4/IPv6 dual-stack.

Restrictions of dual-stack LoadBalancer Services

• LoadBalancer Services with IPv6 addresses are only supported on clusters withstack typeipv4-ipv6. For more information, learn how toUse a dual-stack IP address for a VPC-native cluster.

• LoadBalancer Services created with a single-stack address cannot be upgradedto dual-stack Services.

• LoadBalancer Services created with a dual-stack addresses can be changed tosingle stack according to the following conditions:

  • A Service with ipFamilies["IPv4","IPv6"] can be changed to a Service withipFamiliesIPv4 but notIPv6.
  • A Service with ipFamilies["IPv6","IPv4"] can be changed to a Service withipFamiliesIPv6 but notIPv4.

What's next

• Learn aboutLoadBalancer Services.
• Learn how to set up aninternal load balancer.
• Read an overview ofIngress for Application Load Balancers.
• Learn how to usestandalone NEGs.
• Learn more aboutVPC firewall rules.