Manually deploy gateway proxies

Use Istio Helm charts to configure and deploy an Istio control plane and gateways in each workload cluster. The deployments are created by using Helm to facilitate future version upgrades. For example, you can fork Istio's existing Helm chart to add it to your existing CI/CD workflow.

Review the following information about the Istio control plane and gateway setup in this guide:

If you also use Gloo Mesh Enterprise alongside Gloo Gateway, follow the steps to install Istio in the Gloo Mesh documentation instead. The Gloo Mesh guide shows you how to customize your service mesh installation, and install sidecars with your control plane and gateways.

Step 1: Set up tools

Set up the following tools and environment variables.

  1. Save the Istio version information as environment variables.

    • For REPO, use a Solo repo key that you can get by logging in to the Support Center and reviewing the Istio images built by Solo.io support article. If you do not have a Solo account or have trouble logging in, contact your account administrator. For more information, see Get the Solo distribution of Istio that you want to use.
    • For ISTIO_VERSION, save the Istio version that you want to use. To verify that the version is supported for the Kubernetes or OpenShift version of your cluster, see Supported versions.
      Istio 1.20 is supported only as patch version 1.20.1-patch1 and later. Do not use patch versions 1.20.0 and 1.20.1, which contain bugs that impact several Gloo Platform features that rely on Istio ServiceEntries.
    • For ISTIO_IMAGE, append the solo tag to the Istio version. The solo tag is required to use many enterprise features. You can optionally append other tags for the Solo distribution of Istio, as described in About the Solo distribution of Istio.
    • For REVISION, take the Istio version and replace the periods with hyphens. The revision label facilitates canary-based upgrades, which allow you to upgrade the version of the Istio control plane more easily, as documented in the Istio upgrade guide.
    export REPO=<repo-key>
    export ISTIO_VERSION=1.20.2
    export ISTIO_IMAGE=1.20.2-solo
    export REVISION=1-20
    
  2. Install istioctl, the Istio CLI tool.

    curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
    cd istio-$ISTIO_VERSION
    export PATH=$PWD/bin:$PATH
    
  3. Add and update the Helm repository for Istio.

    helm repo add istio https://istio-release.storage.googleapis.com/charts
    helm repo update
    

Step 2: Prepare the cluster environment

Prepare the cluster for Istio installation, including installing the Istio custom resource definitions (CRDs).

  1. Save the name and kubeconfig context of your cluster in the following environment variables. For multicluster setups, each time you repeat the steps in this guide, you change these variables to the next workload cluster's name and context.

    export CLUSTER_NAME=<remote-cluster>
    export CLUSTER_CONTEXT=<remote-cluster-context>
    
  2. Ensure that the Istio operator CRD (istiooperators.install.istio.io) is not managed by the Gloo Platform CRD Helm chart.

    kubectl get crds -A --context $CLUSTER_CONTEXT | grep istiooperators.install.istio.io
    
    • If the CRD does not exist on your cluster, you disabled it during the Gloo Gateway installation. Continue to the next step.
    • If the CRD exists on your cluster, follow these steps to remove the Istio operator CRD from the gloo-platform-crds Helm release:
      1. Update the Helm repository for Gloo Platform.
        helm repo add gloo-platform https://storage.googleapis.com/gloo-platform/helm-charts
        helm repo update
        
      2. Upgrade your gloo-platform-crds Helm release by including the --set installIstioOperator=false flag.
        helm upgrade gloo-platform-crds gloo-platform/gloo-platform-crds \
           --kube-context $CLUSTER_CONTEXT \
           --namespace=gloo-mesh \
           --set installIstioOperator=false
        
  3. Install the Istio CRDs.

    helm upgrade --install istio-base istio/base \
      -n istio-system \
      --version $ISTIO_VERSION \
      --kube-context $CLUSTER_CONTEXT \
      --create-namespace
    
  4. Create the istio-config namespace. This namespace serves as the administrative root namespace for Istio configuration.

    kubectl create namespace istio-config --context $CLUSTER_CONTEXT
    
  5. OpenShift only: Deploy the Istio CNI plug-in, and elevate the istio-system service account permissions. For more information about using Istio on OpenShift, see the Istio documentation for OpenShift installation.

    1. Install the CNI plug-in, which is required for using Istio in OpenShift.
      helm install istio-cni istio/cni \
      --namespace kube-system \
      --kube-context $CLUSTER_CONTEXT \
      --version $ISTIO_VERSION \
      --set cni.cniBinDir=/var/lib/cni/bin \
      --set cni.cniConfDir=/etc/cni/multus/net.d \
      --set cni.cniConfFileName="istio-cni.conf" \
      --set cni.chained=false \
      --set cni.privileged=true
      
    2. Elevate the permissions of the following service accounts. These permissions allow the Istio sidecars 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 --context $CLUSTER_CONTEXT
      oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-config --context $CLUSTER_CONTEXT
      oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-ingress --context $CLUSTER_CONTEXT
      oc adm policy add-scc-to-group anyuid system:serviceaccounts:istio-eastwest --context $CLUSTER_CONTEXT
      
    3. Create a NetworkAttachmentDefinition custom resource for the gloo-mesh-gateways project.
      cat <<EOF | oc create -n gloo-mesh-gateways --context $CLUSTER_CONTEXT -f -
      apiVersion: "k8s.cni.cncf.io/v1"
      kind: NetworkAttachmentDefinition
      metadata:
        name: istio-cni
      EOF
      

Step 3: Deploy the Istio control plane

Deploy an Istio control plane in your cluster. The provided Helm values files are configured with production-level settings; however, depending on your environment, you might need to edit settings to achieve specific Istio functionality.

  1. Prepare a Helm values file for the istiod control plane. You can further edit the file to provide your own details for production-level settings.

    1. Download an example file, istiod.yaml, and update the environment variables with the values that you previously set.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/manual-helm/istiod.yaml > istiod.yaml
      envsubst < istiod.yaml > istiod-values.yaml
      
    2. Optional: Trust domain validation is disabled by default in the profile that you downloaded in the previous step. If you have a multicluster setup and you want to enable trust domain validation, add all the clusters that are part of your setup in the meshConfig.trustDomainAliases field, excluding the cluster that you currently prepare for the istiod installation. For example, let's say you have 3 clusters that belong to your mesh: cluster1, cluster2, and cluster3. When you install istiod in cluster1, you set the following values for your trust domain:

            ...
            meshConfig:
              trustDomain: cluster1
              trustDomainAliases: ["cluster2","cluster3"]
            

      Then, when you move on to install istiod in cluster2, you set trustDomain: cluster2 and trustDomainAliases: ["cluster1","cluster3"]. You repeat this step for all the clusters that belong to your service mesh. Note that as you add or delete clusters from your service mesh, you must make sure that you update the trustDomainAliases field for all of the clusters.

  2. Create the istiod control plane in your cluster.

    helm upgrade --install istiod-$REVISION istio/istiod \
      --version $ISTIO_VERSION \
      --namespace istio-system \
      --kube-context $CLUSTER_CONTEXT \
      --wait \
      -f istiod-values.yaml
    
  3. After the installation is complete, verify that the Istio control plane pods are running.

    kubectl get pods -n istio-system --context $CLUSTER_CONTEXT
    

    Example output for 2 replicas:

    NAME                            READY   STATUS    RESTARTS   AGE
    istiod-1-20-7b96cb895-4nzv9     1/1     Running   0          30s
    istiod-1-20-7b96cb895-r7l8k     1/1     Running   0          30s
    

Step 4: Deploy the Istio ingress gateway

Deploy an Istio ingress gateway to allow incoming traffic requests to your Istio-managed apps.

  1. Prepare a Helm values file for the Istio ingress gateway. This sample command downloads an example file, ingress-gateway.yaml, and updates the environment variables with the values that you previously set. You can further edit the file to provide your own details for production-level settings.

    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/manual-helm/ingress-gateway.yaml > ingress-gateway.yaml
    envsubst < ingress-gateway.yaml > ingress-gateway-values.yaml
    
  2. Create the ingress gateway.

    helm upgrade --install istio-ingressgateway-$REVISION istio/gateway \
      --version $ISTIO_VERSION \
      --create-namespace \
      --namespace istio-ingress \
      --kube-context $CLUSTER_CONTEXT \
      --wait \
      -f ingress-gateway-values.yaml
    
  3. Verify that the ingress gateway pods are running and the load balancer service is assigned an external address.

    kubectl get pods -n istio-ingress --context $CLUSTER_CONTEXT
    kubectl get svc -n istio-ingress --context $CLUSTER_CONTEXT
    

    Example output:

    NAME                                         READY   STATUS    RESTARTS   AGE
    istio-ingressgateway-1-20-665d46686f-nhh52     1/1     Running   0          106s
    istio-ingressgateway-1-20-665d46686f-tlp5j     1/1     Running   0          2m1s
    NAME                               TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                                                      AGE
    istio-ingressgateway-1-20          LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP                                   2m2s
    

    AWS clusters only: For the Elastic Load Balancer (ELB) instance that is automatically created for you to back the ingress gateway service, verify that the health check shows a healthy state. Gloo Gateway configures the ingress gateway to listen on HTTPS port 15443. However, when the ELB is created, the first port that is defined in the Kubernetes service manifest is used to perform the health check. This port might be different from the port that Gloo Gateway configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.

  4. Optional for OpenShift: Expose the load balancer by using an OpenShift route.

    oc -n istio-ingress expose svc istio-ingressgateway-1-20 --port=http2 --context $CLUSTER_CONTEXT
    

Step 5 (multicluster setups): Deploy the Istio east-west gateway

If you have a multicluster Gloo Gateway setup, deploy an Istio east-west gateway into each cluster in addition to the ingress gateway. In Gloo Gateway, the east-west gateways allow the ingress gateway in one cluster to route incoming traffic requests to services in another cluster.

  1. Prepare a Helm values file for the Istio east-west gateway. This sample command downloads an example file, eastwest-gateway.yaml, and updates the environment variables with the values that you previously set. You can further edit the file to provide your own details for production-level settings.

    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/manual-helm/eastwest-gateway.yaml > eastwest-gateway.yaml
    envsubst < eastwest-gateway.yaml > eastwest-gateway-values.yaml
    
  2. Create the east-west gateway.

    helm upgrade --install istio-eastwestgateway-$REVISION istio/gateway \
      --version $ISTIO_VERSION \
      --create-namespace \
      --namespace istio-eastwest \
      --kube-context $CLUSTER_CONTEXT \
      --wait \
      -f eastwest-gateway-values.yaml
    
  3. Verify that the east-west gateway pods are running and the load balancer service is assigned an external address.

    kubectl get pods -n istio-eastwest --context $CLUSTER_CONTEXT
    kubectl get svc -n istio-eastwest --context $CLUSTER_CONTEXT
    

    Example output:

    NAME                                          READY   STATUS    RESTARTS   AGE
    istio-eastwestgateway-1-20-7f6f8f7fc7-ncrzq     1/1     Running   0          11s
    istio-eastwestgateway-1-20-7f6f8f7fc7-ncrzq     1/1     Running   0          48s
    NAME                               TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                                                      AGE
    istio-eastwestgateway-1-20         LoadBalancer   10.96.166.166   <externalip>  15021:32343/TCP,80:31685/TCP,443:30877/TCP,31400:31030/TCP,15443:31507/TCP,15012:30668/TCP,15017:30812/TCP   13s
    

    AWS clusters only: For the Elastic Load Balancer (ELB) instance that is automatically created for you to back the east-west gateway service, verify that the health check shows a healthy state. Gloo Gateway configures the east-west gateway to listen on HTTPS port 15443. However, when the ELB is created, the first port that is defined in the Kubernetes service manifest is used to perform the health check. This port might be different from the port that Gloo Gateway configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.

Step 6 (multicluster setups): Repeat steps 2 - 5

If you have a multicluster Gloo Gateway setup, repeat steps 2 - 5 for each workload cluster that you want to install Istio on. Remember to change the cluster name and context variables each time you repeat the steps.

export CLUSTER_NAME=<remote-cluster>
export CLUSTER_CONTEXT=<remote-cluster-context>

Next steps

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