This page shows you how to configure anexternal Application Load Balancer by creating aKubernetes Ingress object.

Before reading this page, ensure that you're familiar withGKE networking concepts.

Before you begin

Before you start, make sure that you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task,install and theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

• Ensure that you have an existing Autopilot or Standardcluster. To create a new cluster, seeCreate an Autopilot cluster.

Enable theHttpLoadBalancing add-on

Your cluster must have theHttpLoadBalancing add-on enabled. This add-on isenabled by default. In Autopilot clusters, you can't disable thisadd-on.

You can enable theHttpLoadBalancing add-on using the Google Cloud console or theGoogle Cloud CLI.

gcloudcontainerclustersupdateCLUSTER_NAME--update-addons=HttpLoadBalancing=ENABLED

Create a static IP address

An external Application Load Balancer provides one stable IP address that you can useto route requests to one or more Services. If you want a permanent IP address,you must reserve aglobal static external IP addressbefore you create an Ingress.

If you modify an existing Ingress to use a static IP address instead of anephemeral IP address, GKE might change the IP address of theload balancer when GKE re-creates the forwarding rule of the loadbalancer.

Create an external Application Load Balancer

In this exercise, you configure an external Application Load Balancer to route requests todifferent Services depending on the URL path.

To follow step-by-step guidance for this task directly in the Google Cloud console, clickGuide me:

Guide me

Create Deployments and Services

Create two Deployments with Services namedhello-world-1 andhello-world-2:

1. Save the following manifest ashello-world-deployment-1.yaml:

   apiVersion:apps/v1kind:Deploymentmetadata:name:hello-world-deployment-1spec:selector:matchLabels:greeting:helloversion:onereplicas:3template:metadata:labels:greeting:helloversion:onespec:containers:-name:hello-app-1image:"us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0"env:-name:"PORT"value:"50000"

   This manifest describes a sample Deployment with three replicas.

2. Apply the manifest to the cluster:

   kubectlapply-fhello-world-deployment-1.yaml

3. Save the following manifest ashello-world-service-1.yaml:

   apiVersion:v1kind:Servicemetadata:name:hello-world-1spec:type:NodePortselector:greeting:helloversion:oneports:-protocol:TCPport:60000targetPort:50000

   This manifest describes a Service with the following properties:

   • Any Pod that has both thegreeting: hello label and theversion: one label is a member of the Service.
   • GKE forwards requests sent to the Service on TCP port 60000to one of the member Pods on TCP port 50000.
   • The Service type isNodePort, which is required unlessyou're usingcontainer native load balancing.If using container-native load balancing, there is no restriction on typeof service. Recommend to usetype: ClusterIP.

4. Apply the manifest to the cluster:

   kubectlapply-fhello-world-service-1.yaml

5. Save the following manifest ashello-world-deployment-2.yaml:

   apiVersion:apps/v1kind:Deploymentmetadata:name:hello-world-deployment-2spec:selector:matchLabels:greeting:helloversion:tworeplicas:3template:metadata:labels:greeting:helloversion:twospec:containers:-name:hello-app-2image:"us-docker.pkg.dev/google-samples/containers/gke/hello-app:2.0"env:-name:"PORT"value:"8080"

   This manifest describes a sample Deployment with three replicas.

6. Apply the manifest to the cluster:

   kubectlapply-fhello-world-deployment-2.yaml

7. Save the following manifest ashello-world-service-2.yaml:

   apiVersion:v1kind:Servicemetadata:name:hello-world-2spec:type:NodePortselector:greeting:helloversion:twoports:-protocol:TCPport:80targetPort:8080

   This manifest describes a Service with the following properties:

   • Any Pod that has both thegreeting: hello label and theversion: two label is a member of the Service.
   • GKE forwards requests sent to the Service on TCP port 80to one of the member Pods on TCP port 8080.

8. Apply the manifest to the cluster:

   kubectlapply-fhello-world-service-2.yaml

Create an Ingress

Create an Ingress that specifies rules for routing requests depending on the URLpath in the request. When you create the Ingress, the GKE Ingresscontroller creates and configures an external Application Load Balancer.

1. Save the following manifest asmy-ingress.yaml:

   apiVersion:networking.k8s.io/v1kind:Ingressmetadata:name:my-ingressannotations:# If the class annotation is not specified it defaults to "gce".kubernetes.io/ingress.class:"gce"spec:rules:-http:paths:-path:/*pathType:ImplementationSpecificbackend:service:name:hello-world-1port:number:60000-path:/v2pathType:ImplementationSpecificbackend:service:name:hello-world-2port:number:80

   This manifest describes an Ingress with the following properties:

   • There are two GKE Ingress classes. To specify an Ingress class,you must use thekubernetes.io/ingress.class annotation. You cannot specifya GKE Ingress usingspec.ingressClassName.

   • Thegce class deploys anexternal Application Load Balancer.

   • Thegce-internal class deploys aninternal Application Load Balancer.

   • When you deploy an Ingress resource without the annotationsspec.ingressClassName andkubernetes.io/ingress.class, GKEcreates an external Application Load Balancer. This is the same behavior thatoccurs if you specify thekubernetes.io/ingress.class: gce annotation.For moreinformation, seeGKE Ingress controller behavior.

   • GKE creates aGoogle Cloud backend Servicefor eachbackend.service. Each of the backend servicescorresponds to a Kubernetes Service, and each backend service must reference aGoogle Cloud health check.This health check isdifferent from a Kubernetes liveness or readiness probebecause the health check is implemented outside of the cluster. To learn more, seeHealth checks

   • When a client sends a request to the load balancer with URL path/,GKE forwards the request to thehello-world-1 Service onport 60000. When a client sends a request to the load balancer using URLpath/v2, GKE forwards the request to thehello-world-2Service on port 80. For more information about thepath andpathTypeproperties, seeURL Paths.

2. Apply the manifest to the cluster:

   kubectlapply-fmy-ingress.yaml

Test the external Application Load Balancer

Wait about five minutes for the load balancer to be configured, then test theexternal Application Load Balancer:

1. View the Ingress:

   kubectlgetingressmy-ingress--outputyaml

   The output shows the IP address of the external Application Load Balancer:

   status:  loadBalancer:    ingress:    - ip: 203.0.113.1

2. Test the/ path:

   curlLOAD_BALANCER_IP_ADDRESS/

   ReplaceLOAD_BALANCER_IP_ADDRESS with the external IPaddress of the load balancer.

   The output is similar to the following:

   Hello, world!Version: 1.0.0Hostname: ...

   If the output includes a 404 error, wait a few minutes.

3. Test the/v2 path:

   curlload-balancer-ip/v2

   The output is similar to the following:

   Hello, world!Version: 2.0.0Hostname: ...

How Ingress for external load balancing works

An external Application Load Balancer acts as a proxy between your clients and yourapplication. If you want to accept HTTPS requests from your clients, the loadbalancer must have a certificate so it can prove its identity to your clients.The load balancer must also have a private key to complete the HTTPS handshake.For more information, see:

• Setting up HTTPS (TLS) between client and load balancer.
• Using multiple SSL certificates in HTTPS Load Balancing with Ingress.

URL Paths

The only supported wildcard character for thepath field of an Ingressis the* character. The* character must follow a forward slash (/) andmust be the last character in the pattern. For example,/*,/foo/*, and/foo/bar/* are valid patterns, but*,/foo/bar*, and/foo/*/bar are not.

A more specific pattern takes precedence over a less specific pattern. If youhave both/foo/* and/foo/bar/*, then/foo/bar/bat is taken to match/foo/bar/*. For more information about path limitations and pattern matching,see theURL Maps documentation.

For GKE clusters running versions earlier than 1.21.3-gke.1600,the only supported value for thepathType field isImplementationSpecific.For clusters running version 1.21.3-gke.1600 or later,Prefix andExactvalues are also supported forpathType.

Disabling HTTP

If you want all traffic between the client and the load balancer to useHTTPS, you can disable HTTP. For more information, seeDisabling HTTP.

HTTPS between load balancer and application

If your application, running in a GKE Pod, is capable of receivingHTTPS requests, you can configure the load balancer to use HTTPS when it forwardsrequests to your application. For more information, seeHTTPS (TLS) between load balancer and your application.

HTTP/2 between client and load balancer

Clients can use HTTP/2 to send requests to the load balancer. No configurationis required.

HTTP/2 between load balancer and application

If your application, running in a GKE Pod, is capable of receivingHTTP/2 requests, you can configure the load balancer to use HTTP/2 when it forwardsrequests to your application. For more information, seeHTTP/2 for load balancing with Ingress.

Network endpoint groups

If your cluster supportsContainer-native load balancing,it is recommended to use network endpoint groups (NEGs). For GKEclusters 1.17 and later andunder certain conditions,container-native load balancing is default and does not require an explicitcloud.google.com/neg: '{"ingress": true}' Service annotation.

Shared VPC

If the GKE cluster in which you are deploying the Ingress resources is in a service project,and you want the GKE control plane to manage the firewall resources in your host project,then the service project's GKE service account must be granted the appropriate IAM permissions in the host projectas perManaging firewall resources for clusters with Shared VPC.This lets the Ingress controller create firewall rules to allow both ingress traffic and traffic for Google Cloud health checks.

The following is an example of an event that might be present in the Ingress resource logs. This error occurs when the Ingress controller is unable to createa firewall rule to allow ingress traffic for Google Cloud health checks if the permissions are not configured correctly.

Firewall change required by security admin: `gcloud compute firewall-rules update <RULE_NAME> --description "GCE L7 firewall rule" --allow tcp:<PORT> --source-ranges 130.211.0.0/22,35.191.0.0/16 --target-tags <TARGET_TAG> --project <HOST_PROJECT>

If you prefer tomanually provision firewall rules from the host project, then you can mute thefirewallXPNError eventsby adding thenetworking.gke.io/suppress-firewall-xpn-error: "true" annotation to the Ingress resource.

Summary of external Ingress annotations

Ingress annotations

Service annotations related to Ingress

What's next

• Read a conceptual overview ofIngress for external Application Load Balancers inGKE.

• Perform the tutorial onSetting up an external Application Load Balancer with Ingress.

• Read a conceptual overview ofServices inGKE.

• Implement abasic external Ingress.