☰
Navigation :

Install managed gateway proxies

In Gloo Gateway 2.3 and later, you can easily manage and update gateway proxies in the gloo-platform Helm chart, instead of managing individual gateway lifecycle manager CRDs. If you installed Gloo Gateway by using the legacy gloo-mesh-enterpise, gloo-mesh-agent, and other included Helm charts, or if you used meshctl version 2.2 or earlier to install Gloo Gateway, migrate your legacy installation to the new gloo-platform Helm chart. Then, you can follow the steps in the gloo-platform upgrade guide to perform in-place and canary upgrades for the gateway proxy.

Streamline the gateway installation process by using the Gloo management plane to install Istio in your clusters, as part of the Istio lifecycle management. In Gloo Gateway, you install an Istio control plane and Istio gateways to allow incoming traffic to your cluster environment. If you use Gloo Mesh Enterprise, you can also add Istio sidecars to your workloads to create a managed service mesh.

By using a Gloo-managed installation, you no longer need to use istioctl to individually install the Istio control plane and gateways. Instead, you can supply IstioOperator configurations in your gloo-platform Helm chart. Gloo translates this configuration into an Istio control plane and gateway proxy in the cluster.

Before you begin

  1. Choose the Istio version you want to use for installation.

    To use the default supported version of Gloo Istio, set the REVISION environment variable to auto. This setting automatically uses the default supported Gloo Istio version for the image tag (such as 1.18.2-solo) and the revision (such as 1-18-2).

    export REVISION=auto

    Note that in future upgrades, the version set by the auto setting does not change unless you manually specify different values for the image tag, revision, and image repository.

    Save the Istio version information as environment variables.

    • For REPO, use a Gloo Istio repo key that you can get by logging in to the Support Center and reviewing the Istio images built by Solo.io support article. For more information, see Get the Gloo Istio version that you want to use.
    • For ISTIO_IMAGE, save the version that you downloaded, such as 1.18.2, and append the solo tag, which is required to use many enterprise features. You can optionally append other Gloo Istio tags, as described in About Gloo Istio. If you downloaded a different version than the following, make sure to specify that version instead. Note: The Istio lifecycle manager is supported only for Istio versions 1.15.4 or later.
    • For REVISION, take the Istio major and minor version numbers and replace the period with a hyphen, such as 1-18-2.
    export REPO=<repo-key>
export ISTIO_IMAGE=1.18.2-solo
export REVISION=1-18-2

    Istio version 1.17 does not support the Gloo legacy metrics pipeline. If you run the legacy metrics pipeline, before you upgrade or deploy gateway proxies with Istio 1.17, be sure that you set up the Gloo OpenTelemetry (OTel) pipeline instead in your new or existing Gloo Gateway installation.

  2. Review the following considerations.

    • Throughout this guide, you use example configuration files that have pre-filled values. You can update some of the values, but unexpected behaviors might occur. For example, if you change the default istio-ingressgateway name, you cannot also use Kubernetes horizontal pod autoscaling. For more information, see the Troubleshooting docs.
    • If your organization restricts elevated Kubernetes RBAC permissions for security reasons, you might need to install the Istio CNI plug-in. The OpenShift steps provide an example. For more information, see the Istio docs.

  3. Deploy managed Istio in a multicluster or single-cluster setup.

Manage Istio installations in a single-cluster setup

  1. Prepare an IstioLifecycleManager resource to manage istiod control planes.

    1. Download the example file. 
      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/single-cluster/gm-istiod.yaml > gm-istiod.yaml
      1. Elevate the permissions of the following service accounts that will be created. These permissions allow the gateways to make use of a user ID that is normally restricted by OpenShift. 
        oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-18-2
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways
      2. If you also use Gloo Mesh Enterprise, repeat the following steps for each project where you want to deploy workloads, in each registered cluster.
        1. Create a NetworkAttachmentDefinition custom resource. 
          cat <<EOF | oc -n <project> create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
        2. Elevate the permissions of the service account to allow the gateway to make use of a user ID that is normally restricted by OpenShift. 
          oc adm policy add-scc-to-group anyuid system:serviceaccounts:<project>
      3. Download the gm-istiod.yaml example file. 
        curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/single-cluster/gm-istiod-openshift.yaml > gm-istiod.yaml
    2. Update the example file with the environment variables that you previously set, and optionally further edit the file to provide your own details. Save the updated file as gm-istiod-values.yaml. For more information, see the API reference.
      • Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command. 
        envsubst < gm-istiod.yaml > gm-istiod-values.yaml
open gm-istiod-values.yaml
    3. Apply the IstioLifecycleManager resource to your management cluster. 
      kubectl apply -f gm-istiod-values.yaml

  2. Prepare a GatewayLifecycleManager custom resource to manage the ingress gateway proxies.

    1. Download the gm-ingress-gateway.yaml example file. 
      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/single-cluster/gm-ingress-gateway.yaml > gm-ingress-gateway.yaml
    2. Update the example file with the environment variables that you previously set, and optionally further edit the file to provide your own details. Save the updated file as gm-ingress-gateway-values.yaml. For more information, see the API reference.
      • Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command. 
        envsubst < gm-ingress-gateway.yaml > gm-ingress-gateway-values.yaml
open gm-ingress-gateway-values.yaml
    3. Apply the GatewayLifecycleManager resource to your management cluster. 
      kubectl apply -f gm-ingress-gateway-values.yaml

  3. Verify that the namespaces for your Istio installations are created.

    kubectl get ns

    For example, the gm-iop-1-18-2, gloo-mesh-gateways, and istio-system namespaces are created:

    NAME               STATUS   AGE
default            Active   56m
gloo-mesh          Active   36m
gm-iop-1-18-2        Active   91s
gloo-mesh-gateways Active   90s
istio-system       Active   91s
kube-node-lease    Active   57m
kube-public        Active   57m
kube-system        Active   57m

  4. In each namespace, verify that the Istio resources that you specified in your Istio operator configuration are successfully installing. For example, verify that the Istio control plane pods are running. 

    kubectl get all -n gm-iop-1-18-2

    Example output:

    NAME                                       READY   STATUS    RESTARTS   AGE
pod/istio-operator-1-18-2-678fd95cc6-ltbvl   1/1     Running   0          4m12s

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/istio-operator-1-18-2   ClusterIP   10.204.15.247   <none>        8383/TCP   4m12s

NAME                                  READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istio-operator-1-18-2   1/1     1            1           4m12s

NAME                                             DESIRED   CURRENT   READY   AGE
replicaset.apps/istio-operator-1-18-2-678fd95cc6   1         1         1       4m12s

    kubectl get all -n istio-system

    Example output:

    NAME                              READY   STATUS    RESTARTS   AGE
pod/istiod-1-18-2-b65676555-g2vmr   1/1     Running   0          8m57s

NAME                  TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                                 AGE
service/istiod-1-18-2   ClusterIP   10.204.6.56   <none>        15010/TCP,15012/TCP,443/TCP,15014/TCP   8m56s

NAME                          READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istiod-1-18-2   1/1     1            1           8m57s

NAME                                    DESIRED   CURRENT   READY   AGE
replicaset.apps/istiod-1-18-2-b65676555   1         1         1       8m57s

NAME                                              REFERENCE                     TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
horizontalpodautoscaler.autoscaling/istiod-1-18-2   Deployment/istiod-1-18-2   1%/80%    1         5         1          8m58s

    Note that the gateways might take a few minutes to be created.

    kubectl get all -n gloo-mesh-gateways

    Example output:

    NAME                                              READY   STATUS    RESTARTS   AGE
pod/istio-ingressgateway-1-18-2-77d5f76bc8-j6qkp    1/1     Running   0          2m18s

NAME                                      TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                                      AGE
service/istio-ingressgateway              LoadBalancer   10.44.4.140    34.150.235.221   15021:31321/TCP,80:32525/TCP,443:31826/TCP   2m16s

NAME                                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istio-ingressgateway-1-18-2    1/1     1            1           2m18s

NAME                                                    DESIRED   CURRENT   READY   AGE
replicaset.apps/istio-ingressgateway-1-18-2-77d5f76bc8    1         1         1       2m18s

NAME                                                             REFERENCE                                  TARGETS         MINPODS   MAXPODS   REPLICAS   AGE
horizontalpodautoscaler.autoscaling/istio-ingressgateway-1-18-2    Deployment/istio-ingressgateway-1-18-2    4%/80%          1         5         1          2m19s

Manage Istio installations in a multicluster setup

  1. Save the names of your clusters from your infrastructure provider as environment variables. If your clusters have different names, specify those names instead.

    export REMOTE_CLUSTER1=<cluster1>
export REMOTE_CLUSTER2=<cluster2>
...
  2. Save the kubeconfig contexts for your clusters as environment variables. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column. 
    export MGMT_CONTEXT=<management-cluster-context>
export REMOTE_CONTEXT1=<remote-cluster1-context>
export REMOTE_CONTEXT2=<remote-cluster2-context>
...

  3. Prepare an IstioLifecycleManager resource to manage istiod control planes.

    1. Download the example file. 
      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-istiod.yaml > gm-istiod.yaml
      1. Elevate the permissions of the following service accounts that will be created. These permissions allow the Istio sidecars to make use of a user ID that is normally restricted by OpenShift. For more information, see the Istio on OpenShift documentation. 
        oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system --context $REMOTE_CONTEXT1
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways --context $REMOTE_CONTEXT1
# Update revision as needed
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-18-2 --context $REMOTE_CONTEXT1

        oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-system --context $REMOTE_CONTEXT2
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways --context $REMOTE_CONTEXT2
# Update revision as needed
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-18-2 --context $REMOTE_CONTEXT2
      2. Create the gloo-mesh-gateways project, and create a NetworkAttachmentDefinition custom resource for the project. 
        kubectl create ns gloo-mesh-gateways --context $REMOTE_CONTEXT1
cat <<EOF | oc --context $REMOTE_CONTEXT1 -n gloo-mesh-gateways create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF

        kubectl create ns gloo-mesh-gateways --context $REMOTE_CONTEXT2
cat <<EOF | oc --context $REMOTE_CONTEXT2 -n gloo-mesh-gateways create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
      3. Download the gm-istiod.yaml example file. 
        curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-istiod-openshift.yaml > gm-istiod.yaml
    2. Update the example file with the environment variables that you previously set, and optionally further edit the file to provide your own details. Save the updated file as gm-istiod-values.yaml. For more information, see the API reference.
      • Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command. 
        envsubst < gm-istiod.yaml > gm-istiod-values.yaml
open gm-istiod-values.yaml
    3. Apply the IstioLifecycleManager resource to your management cluster. 
      kubectl apply -f gm-istiod-values.yaml --context $MGMT_CONTEXT

  4. Prepare a GatewayLifecycleManager custom resource to manage the ingress gateways.

    1. Download the gm-ingress-gateway.yaml example file. 
      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-ingress-gateway.yaml > gm-ingress-gateway.yaml
    2. Update the example file with the environment variables that you previously set, and optionally further edit the file to provide your own details. Save the updated file as gm-ingress-gateway-values.yaml. For more information, see the API reference.
      • Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command. 
        envsubst < gm-ingress-gateway.yaml > gm-ingress-gateway-values.yaml
open gm-ingress-gateway-values.yaml
    3. Apply the GatewayLifecycleManager resource to your management cluster. 
      kubectl apply -f gm-ingress-gateway-values.yaml --context $MGMT_CONTEXT

  5. Verify that the namespaces for your Istio installations are created in each workload cluster.

    kubectl get ns --context $REMOTE_CONTEXT1
kubectl get ns --context $REMOTE_CONTEXT2

    For example, the gm-iop-1-18-2, gloo-mesh-gateways, and istio-system namespaces are created:

    NAME               STATUS   AGE
default            Active   56m
gloo-mesh          Active   36m
gm-iop-1-18-2      Active   91s
gloo-mesh-gateways Active   90s
istio-system       Active   91s
kube-node-lease    Active   57m
kube-public        Active   57m
kube-system        Active   57m

  6. In each namespace, verify that the Istio resources that you specified in your Istio operator configuration are successfully installing. For example, verify that the Istio control plane pods are running. 

    kubectl get all -n gm-iop-1-18-2 --context $REMOTE_CONTEXT1

    Example output:

    NAME                                            READY   STATUS    RESTARTS   AGE
pod/istio-operator-1-18-2-678fd95cc6-ltbvl   1/1     Running   0          4m12s

NAME                               TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/istio-operator-1-18-2   ClusterIP   10.204.15.247   <none>        8383/TCP   4m12s

NAME                                       READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istio-operator-1-18-2   1/1     1            1           4m12s

NAME                                                  DESIRED   CURRENT   READY   AGE
replicaset.apps/istio-operator-1-18-2-678fd95cc6   1         1         1       4m12s

    kubectl get all -n istio-system --context $REMOTE_CONTEXT1

    Example output:

    NAME                                   READY   STATUS    RESTARTS   AGE
pod/istiod-1-18-2-b65676555-g2vmr   1/1     Running   0          8m57s

NAME                       TYPE        CLUSTER-IP    EXTERNAL-IP   PORT(S)                                 AGE
service/istiod-1-18-2   ClusterIP   10.204.6.56   <none>        15010/TCP,15012/TCP,443/TCP,15014/TCP   8m56s

NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istiod-1-18-2   1/1     1            1           8m57s

NAME                                         DESIRED   CURRENT   READY   AGE
replicaset.apps/istiod-1-18-2-b65676555   1         1         1       8m57s

NAME                                                   REFERENCE                     TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
horizontalpodautoscaler.autoscaling/istiod-1-18-2   Deployment/istiod-1-18-2   1%/80%    1         5         1          8m58s

    Note that the gateways might take a few minutes to be created.

    kubectl get all -n gloo-mesh-gateways --context $REMOTE_CONTEXT1

    Example output:

    NAME                                                   READY   STATUS    RESTARTS   AGE
pod/istio-ingressgateway-1-18-2-77d5f76bc8-j6qkp    1/1     Running   0          2m18s

NAME                                      TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                                      AGE
service/istio-ingressgateway              LoadBalancer   10.44.4.140    34.150.235.221   15021:31321/TCP,80:32525/TCP,443:31826/TCP   2m16s

NAME                                              READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/istio-ingressgateway-1-18-2    1/1     1            1           2m18s

NAME                                                         DESIRED   CURRENT   READY   AGE
replicaset.apps/istio-ingressgateway-1-18-2-77d5f76bc8    1         1         1       2m18s

NAME                                                                  REFERENCE                                    TARGETS         MINPODS   MAXPODS   REPLICAS   AGE
horizontalpodautoscaler.autoscaling/istio-ingressgateway-1-18-2    Deployment/istio-ingressgateway-1-18-2    4%/80%          1         5         1          2m19s

  7. Optional for OpenShift: Expose the gateways by using OpenShift routes.

    oc -n gloo-mesh-gateways expose svc istio-ingressgateway --port=http2 --context $REMOTE_CONTEXT1
oc -n gloo-mesh-gateways expose svc istio-ingressgateway --port=http2 --context $REMOTE_CONTEXT2

In multicluster setups, one Gloo Gateway for north-south traffic is deployed to each workload cluster. To learn about your gateway options, such as creating a global load balancer to route to each gateway IP address or registering each gateway IP address in one DNS entry, see the gateway deployment patterns page.

Next steps

Now that the gateway proxies are installed, check out the following resources to explore Gloo Gateway capabilities: