Installing and upgrading gateways with Istio APIs

Cloud Service Mesh gives you the option to deploy and managegateways as part ofyour service mesh. A gateway describes a load balancer that operates at the edgeof the mesh and receives incoming or outgoing HTTP/TCP connections. Gateways areprimarily used to manage ingress traffic, but you can also configure gateways tomanage other types of traffic.

• Egress gateways: An egress gateway lets you configure a dedicated exit nodefor traffic leaving the mesh, letting you limit which services can or shouldaccess external networks, or to enable secure control of egress traffic to addsecurity to your mesh, for example.

• Ingress gateways: An ingress gateway lets you configure a dedicated entrancenode to receive incoming HTTP/TCP connections.

• East-west gateways: A proxy foreast-west traffic to allow service workloads to communicate across cluster boundaries ina multi-primary mesh on different networks. By default, this gateway will bepublic on the Internet.

This page describes best practices for deploying and upgrading the gatewayproxies as well as examples of configuring your ownistio-ingressgateway andistio-egressgateway gateway proxies.

You can deploy gateways in different ways and you can use more thanone topology within the same cluster. Refer toGateway deployment topologies in the Istio documentation to learn more about these topologies.

Best practices for deploying gateways

The best practices for deploying gateways depend on whether you are using themanaged data plane or theunmanaged data plane.

Best practices for managed data plane

• Enable themanaged data plane.
• Add amanaged revision label to anamespace.
• Deploy and manage the control plane and gateways separately.
• As a security best practice, deploy gateways ina different namespace from the control plane.
• Useautomatic sidecar injection(auto-injection) to inject the proxy configuration for the gateways similarto how you would inject the sidecar proxies for your services.

These best practices:

• Ensure your managed gateways are automatically kept up-to-date with the latestenhancements and security updates.
• Offloads management and maintenance of gateway instances to Cloud Service Meshmanaged data plane.

Best practices for unmanaged data plane

• Deploy and manage the control plane and gateways separately.
• As a security best practice, deploy gateways ina different namespace from the control plane.
• Useautomatic sidecar injection(auto-injection) to inject the proxy configuration for the gateways similarto how you would inject the sidecar proxies for your services.

These best practices:

• Let your namespace administrators manage gateways without needingelevated privileges to your entire cluster.
• Let your administrators use the same deployment tooling or mechanismthat they use to manage Kubernetes applications to deploy and managegateways.
• Give administrators full control over the gateway Deployment, and alsosimplify operations. When a new upgrade is available or a configurationhas changed, administrators update gateway Pods by restarting them. Thismakes the experience of operating a gateway Deployment the same asoperating sidecar proxies for your services.

Deploy sample gateway

To support users with existing deployment tools, Cloud Service Mesh supports thesame ways to deploy a gateway asIstio:IstioOperator, Helm, and Kubernetes YAML. Each method produces the sameresult. Although you can choose the method you are most familiar with, werecommend that you use the Kubernetes YAML method because it is easier to modifyand you can store hydrated manifests in source control.

The following steps show how to deploy a sample gateway.

1. Create a namespace for the gateway if you don't already have one.ReplaceGATEWAY_NAMESPACE with the name of yournamespace.

   kubectlcreatenamespaceGATEWAY_NAMESPACE

2. Enable the namespace for injection. The steps depend on yourcontrol plane implementation.

   Managed (TD)

   1. Apply the default injection label to the namespace:

   kubectllabelnamespaceGATEWAY_NAMESPACE\istio.io/rev-istio-injection=enabled--overwrite

   Managed (Istiod)

   Recommended: Run the following command to apply the default injection label to the namespace:

   kubectllabelnamespaceGATEWAY_NAMESPACE\istio.io/rev-istio-injection=enabled--overwrite

   If you are an existing user with the Managed Istiod control plane:We recommend that you use default injection, but revision-based injection issupported. Use the following instructions:

   1. Run the following command to locate the available release channels:

      kubectl-nistio-systemgetcontrolplanerevision

      The output is similar to the following:

      NAME                AGEasm-managed-rapid   6d7h

      NOTE: If two control plane revisions appear in the list above, remove one. Having multiple control plane channels in the cluster is not supported.

      In the output, the value under theNAME column is the revision label that corresponds to the availablerelease channel for the Cloud Service Mesh version.

   2. Apply the revision label to the namespace:

      kubectllabelnamespaceGATEWAY_NAMESPACE\istio-injection-istio.io/rev=REVISION_LABEL--overwrite

   In-cluster

   Recommended: Run the following command to apply the default injection label to the namespace:

   kubectllabelnamespaceGATEWAY_NAMESPACE\istio.io/rev-istio-injection=enabled--overwrite

   We recommend that you use default injection, but revision-based injection is supported:Use the following instructions:

   1. Use the following command to locate the revision label onistiod:

      kubectlgetdeploy-nistio-system-lapp=istiod-o\jsonpath={.items[*].metadata.labels.'istio\.io\/rev'}'{"\n"}'

   2. Apply the revision label to the namespace. In the following command,REVISION_LABEL is the value of theistiod revisionlabel that you noted in the previous step.

      kubectllabelnamespaceGATEWAY_NAMESPACE\istio-injection-istio.io/rev=REVISION_LABEL--overwrite

3. Copy the configuration files for the sample gateways from theanthos-service-mesh repository.

4. Change your directory to thesamples directory. To ensure you are in thecorrect directory, run thels command to list the directory contents andthen confirm there is agateways directory (which you will access in thenext step) and anonline-boutique directory.

5. Deploy an ingress or egress gateway. These are located in thesamples/gateways/ directory as is, or modify it as needed.

   Ingress

   kubectlapply-nGATEWAY_NAMESPACE-fsamples/gateways/istio-ingressgateway

   Egress

   kubectlapply-nGATEWAY_NAMESPACE-fsamples/gateways/istio-egressgateway

6. After you create the deployment, verify that the new services are workingcorrectly:

   kubectlgetpod,service-nGATEWAY_NAMESPACE

   Verify that the output is similar to the following:

   NAME                                      READY   STATUS    RESTARTS   AGEpod/istio-ingressgateway-856b7c77-bdb77   1/1     Running   0          3sNAME                           TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)        AGEservice/istio-ingressgateway   LoadBalancer   10.24.5.129    34.82.157.6      80:31904/TCP   3s

Manage gateway resources like any other Kubernetes application. The samples intheanthos-service-mesh-packages repository are meant for guidance and aquickstart. Customize them according to your needs.

Gateway selectors

You apply aGateway configuration to theistio-ingressgateway andistio-egressgateway proxies tomanage inbound and outbound traffic for your mesh, letting you specify whichtraffic you want to enter or leave the mesh. The labels on a gatewaydeployment's Pods are used by Gateway configuration resources, so it's importantthat your Gateway selector matches these labels.

For example, in the preceding deployments, theistio=ingressgateway label is seton the gateway Pods. To apply a Gateway configuration to these deployments, youneed to select the same label:

apiVersion:networking.istio.io/v1beta1kind:Gatewaymetadata:name:gatewayspec:selector:istio:ingressgateway...

For an example of a Gateway configuration and Virtual Service,seefrontend.yaml in the Online Boutique sample application.

Upgrade gateways

In-place upgrades

For most use cases, you should upgrade your gateways following the in-placeupgrade pattern. Because gateways utilize Pod injection, new gateway Pods thatare created will automatically be injected with the latest configuration, whichincludes the version.

If you would like to change the control plane revision in use by the gateway,you can set theistio.io/rev label on the gateway Deployment, which will alsotrigger a rolling restart.

Managed control plane

Since Google manages the control plane upgrades for the managed control plane,you can simply restart the gateway Deployment and the new pods willautomatically be injected with the latest configuration and version.

kubectl rollout restart deployment istio-ingressgateway \  -nGATEWAY_NAMESPACE

In-cluster control plane

To apply the same pattern to your gateways when you have the in-cluster controlplane, you will need to change the control plane revision in use by the gateway.Set theistio.io/rev label on the gateway Deployment which will trigger arolling restart. The steps required depend on whether you need to update therevision label on namespace and/or the gateway pod.

• If you labeled the namespace for injection, set theistio.io/rev label onthe namespace to the new revision value:

    kubectl label namespaceGATEWAY_NAMESPACE \    istio-injection- istio.io/rev=REVISION \    --overwrite

• If you enabled injection only for the gateway pod, set theistio.io/revlabel on the Deployment to the new revision value like the followingKubernetes YAML file:

  cat <<EOF > gateway-deployment.yamlapiVersion: apps/v1kind: Deploymentmetadata:  name: istio-ingressgateway  namespace:GATEWAY_NAMESPACEspec:  selector:    matchLabels:      istio: ingressgateway  template:    metadata:      annotations:        # This is required to tell Cloud Service Mesh to inject the gateway with the        # required configuration.        inject.istio.io/templates: gateway      labels:        istio: ingressgateway        istio.io/rev:REVISION    spec:      containers:- name: istio-proxy        image: auto # The image will automatically update each time the pod starts.EOFkubectl apply -f gateway-deployment.yaml

  Note: If theimage does not automatically update with the actualCloud Service Mesh proxy image, then the container will not be found and an errorwill occur. SeeTroubleshoot gateways for nextsteps.

Canary upgrades (advanced)

If you are using the in-cluster control plane and would like to more slowlycontrol the rollout of a new control plane revision, you can follow the canaryupgrade pattern. You can run multiple versions of a gateway Deployment andensure everything works as expected with a subset of your traffic. For example,if you want to roll out a new revision, canary, create a copy of your gatewayDeployment with theistio.io/rev=REVISION label set to thenew revision and a new name, for exampleistio-ingressgateway-canary:

apiVersion:apps/v1kind:Deploymentmetadata:name:istio-ingressgateway-canarynamespace:GATEWAY_NAMESPACEspec:selector:matchLabels:istio:ingressgatewaytemplate:metadata:annotations:inject.istio.io/templates:gatewaylabels:istio:ingressgatewayistio.io/rev:REVISION# Set to the control plane revision you want to deployspec:containers:-name:istio-proxyimage:auto

When this Deployment is created, you will then have two versions of thegateway, both selected by the same Service:

kubectl get endpoints -o"custom-columns=NAME:.metadata.name,PODS:.subsets[*].addresses[*].targetRef.name"

NAME                   PODSistio-ingressgateway   istio-ingressgateway-788854c955-8gv96,istio-ingressgateway-canary-b78944cbd-mq2qf

kubectl delete deploy/istio-ingressgateway -nGATEWAY_NAMESPACE

kubectl delete deploy/istio-ingressgateway-canary -nGATEWAY_NAMESPACE

Refer toSet up TLS termination in ingress gateway document for more details.

Configure gateway minimum TLS version

For Cloud Service Mesh, the default minimum TLS version for gateway servers is 1.2.You can configure the minimum TLS version using theminProtocolVersion field.For more information, seeServerTLSSettings.

Unsupported features

If you haveTRAFFIC_DIRECTORcontrol plane implementation thenthe following fields or values in Gateway are not supported:

• ServerTLSSettings.TLSmode withAUTO_PASSTHROUGH value
• ServerTLSSettings.verifyCertificateSpki
• ServerTLSSettings.verifyCertificateHash

Troubleshoot gateways

Failed to update gateway image fromauto

When you deploy or upgrade a gateway, Cloud Service Mesh insertsauto as aplaceholder in theimage field. After the call to a mutating webhook,Cloud Service Mesh automatically replaces this placeholder with the actualCloud Service Mesh proxy image. If the call to the mutating webhook fails, theautoplaceholder remains, and the container is not found. This is typicallycaused by an incorrect namespace label. Ensure that you configured the correctnamespace and then deploy or upgrade the gateway again.