By using Gloo-managed service meshes, you no longer need to manually install and manage the istiod control plane. Instead, you provide the Istio configuration in a Gloo custom resource (CR), and Gloo translates this configuration into managed istiod control plane and gateways in each workload cluster for you.

Before you begin

  1. Follow the get started or advanced installation guide to install the Gloo Mesh Enterprise components.

  2. Review the following considerations for using the Istio lifecycle manager.

    • 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 you plan to run multiple revisions of Istio in your cluster and use discoverySelectors in each revision to discover the resources in specific namespaces, enable the glooMgmtServer.extraEnvs.IGNORE_REVISIONS_FOR_VIRTUAL_DESTINATION_TRANSLATION environment variable on the Gloo management server. For more information, see Multiple Istio revisions in the same cluster.
    • 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. Review Supported versions to choose the Solo distribution of Istio that you want to use, and save the version information in the following environment variables.

    • REPO: The repo key for the Solo distribution of Istio that you can get by logging in to the Support Center and reviewing the Istio images built by Solo.io support article.
    • ISTIO_IMAGE: The version that you want to use with the solo tag, such as 1.22.5-patch0-solo. You can optionally append other tags of Solo distributions of Istio as needed.
    • REVISION: Take the Istio major and minor versions and replace the periods with hyphens, such as 1-22.

      export REPO=<repo-key>
export ISTIO_IMAGE=1.22.5-patch0-solo
export REVISION=1-22

Multicluster

Use Gloo Mesh Enterprise to deploy and manage Istio service meshes in each workload cluster.

istiod control planes

Prepare an IstioLifecycleManager CR to manage istiod control planes.

  1. Set the names of your clusters from your infrastructure provider. 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. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column. Note: Do not use context names with underscores. The generated certificate that connects workload clusters to the management cluster uses the context name as a SAN specification, and underscores in SAN are not FQDN compliant. You can rename a context by running kubectl config rename-context "<oldcontext>" <newcontext>.
      export MGMT_CONTEXT=<management-cluster-context>
export REMOTE_CONTEXT1=<remote-cluster1-context>
export REMOTE_CONTEXT2=<remote-cluster2-context>
...

  3. Download the example file, istiod.yaml, which contains a basic IstioLifecycleManager configuration for the control plane.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-istiod.yaml > istiod.yaml
    1. Elevate the permissions of the following service accounts that will be created. These permissions allow the Istio sidecarsgateways 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-22 --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-22 --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 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 > istiod.yaml

  4. Update the example file with the environment variables that you previously set. Save the updated file as istiod-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < istiod.yaml > istiod-values.yaml

  5. Verify that the configuration is correct. For example, in spec.installations.clusters, verify that entries exist for each workload cluster name. You can also further edit the file to provide your own details. For more information, see the API reference.

      open istiod-values.yaml

  6. Apply the IstioLifecycleManager CR to your management cluster.

      kubectl apply -f istiod-values.yaml --context $MGMT_CONTEXT

  7. In each workload cluster, verify that the Istio pods have a status of Running.

         kubectl get pods -n istio-system --context $REMOTE_CONTEXT1
   kubectl get pods -n istio-system --context $REMOTE_CONTEXT2

    Example output:

         NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-22-b65676555-g2vmr     1/1     Running   0          47s
   NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-22-7b96cb895-4nzv9     1/1     Running   0          43s

East-west gateways

Prepare a GatewayLifecycleManager custom resource to manage the east-west gateways.

  1. Download the example file, ew-gateway.yaml, which contains a basic GatewayLifecycleManager configuration for an east-west gateway.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-ew-gateway.yaml > ew-gateway.yaml

  2. Update the example file with the environment variables that you previously set. Save the updated file as ew-gateway-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < ew-gateway.yaml > ew-gateway-values.yaml

  3. Verify that the configuration is correct. You can also further edit the file to provide your own settings. For more information, see the API reference.

      open ew-gateway-values.yaml
    • For testing environments only, you can deploy a revisionless installation by removing the revision field.

  4. Apply the GatewayLifecycleManager CR to your management cluster.

      kubectl apply -f ew-gateway-values.yaml --context $MGMT_CONTEXT

  5. In each workload cluster, verify that the east-west gateway pod is running.

      kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                                    READY   STATUS    RESTARTS   AGE
istio-eastwestgateway-665d46686f-nhh52  1/1     Running   0          106s

  6. In each workload cluster, verify that the load balancer service has an external address.

      kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                         AGE
istio-eastwestgateway      LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP      2m2s

Optional: Ingress gateways

If you want to allow traffic from outside the cluster to enter your mesh, create a GatewayLifecycleManager resource to deploy and manage an ingress gateway. The ingress gateway allows you to specify basic routing rules for how to match and forward incoming traffic to a workload in the mesh. However, to also apply policies, such as rate limits, external authentication, or a Web Application Firewall to the gateway, you must have a Gloo Mesh Gateway license. For more information about Gloo Mesh Gateway, see the docs. If you want a service mesh-only environment without ingress, you can skip this step.

  1. Download the example file, ingress-gateway.yaml, which contains a basic GatewayLifecycleManager configuration for an ingress gateway.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-ingress-gateway.yaml > ingress-gateway.yaml

  2. Update the example file with the environment variables that you previously set. Save the updated file as ingress-gateway-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < ingress-gateway.yaml > ingress-gateway-values.yaml

  3. Verify that the configuration is correct. You can also further edit the file to provide your own settings. For more information, see the API reference.

      open ingress-gateway-values.yaml
    • You can add cloud provider-specific load balancer annotations to the istioOperatorSpec.components.ingressGateways.k8s section, such as the following AWS annotations:
                ...
          k8s:
            service:
              ...
            serviceAnnotations:
              service.beta.kubernetes.io/aws-load-balancer-backend-protocol: ssl
              service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
              service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
              service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
              service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:<cert>"
              service.beta.kubernetes.io/aws-load-balancer-type: external
      For testing environments only, you can deploy a revisionless installation by removing the gatewayRevision field.

  4. Apply the GatewayLifecycleManager CR to your management cluster.

      kubectl apply -f ingress-gateway-values.yaml --context $MGMT_CONTEXT

  5. In each workload cluster, verify that the ingress gateway pod is running.

      kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                                    READY   STATUS    RESTARTS   AGE
istio-ingressgateway-665d46686f-nhh52   1/1     Running   0          106s

  6. In each workload cluster, verify that the load balancer service has an external address.

      kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                         AGE
istio-ingressgateway       LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP      2m2s

  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

Optional: Egress gateways

Optional: Prepare a GatewayLifecycleManager CR to deploy and manage egress gateways. For more information, see Block egress traffic with an egress gateway.

  1. Download the example file, egress-gateway.yaml, which contains a basic GatewayLifecycleManager configuration for an egress gateway.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-egress-gateway.yaml > egress-gateway.yaml

  2. Update the example file with the environment variables that you previously set. Save the updated file as egress-gateway-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < egress-gateway.yaml > egress-gateway-values.yaml

  3. Verify that the configuration is correct. For example, in spec.installations.clusters, verify that entries exist for each workload cluster name. You can also further edit the file to provide your own settings. For more information, see the API reference.

      open egress-gateway-values.yaml

  4. Apply the GatewayLifecycleManager CR to your management cluster.

      kubectl apply -f egress-gateway-values.yaml --context $MGMT_CONTEXT

  5. In each workload cluster, verify that the egress gateway pods are running.

      kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                                    READY   STATUS    RESTARTS   AGE
istio-egressgateway-665d46686f-nhh52    1/1     Running   0          106s

  6. In each workload cluster, verify that the load balancer service has an external address.

      kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT2

    Example output for one cluster:

      NAME                       TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                         AGE
istio-egressgateway        LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP      2m2s

Add services to the mesh

Now that Istio is up and running, you can create service namespaces for your teams to run app workloads in. For any namespaces that you want to deploy apps to, be sure to follow these steps to include your services in the service mesh.

  1. Label the namespace with the Istio revision so that Istio sidecars deploy to your app pods.

      export REVISION=$(kubectl get pod -L app=istiod -n istio-system --context $REMOTE_CONTEXT -o jsonpath='{.items[0].metadata.labels.istio\.io/rev}')
kubectl label ns <namespace> istio.io/rev=$REVISION --overwrite --context $REMOTE_CONTEXT

  2. If you already deployed app pods to the namespace, restart the workloads so that sidecars are injected into the pods. For example, you might roll out a restart to each deployment by using a command similar to the following.

      kubectl rollout restart deployment -n <namespace> <deployment> --context $REMOTE_CONTEXT

Single cluster

Use Gloo Mesh Enterprise to install a managed service mesh that runs a hardened Solo distribution of Istio in your cluster.

istiod control plane

Prepare an IstioLifecycleManager CR to manage the istiod control plane.

  1. Save the name of your cluster as an environment variable.

      export CLUSTER_NAME=<cluster_name>

  2. Download the example file, istiod.yaml, which contains a basic IstioLifecycleManager configuration for the control plane.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/single-cluster/gm-istiod.yaml > istiod.yaml
    1. Elevate the permissions of the following service accounts that will be created. These permissions allow the Istio sidecarsgateways 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
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gloo-mesh-gateways
# Update revision as needed
oc adm policy add-scc-to-group anyuid system:serviceaccounts:gm-iop-1-22
    2. Elevate the permissions of the service account in each project where you want to deploy workloads. This permission allows 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:<project>
    3. Create the gloo-mesh-gateways project, and create a NetworkAttachmentDefinition custom resource for the project.
        kubectl create ns gloo-mesh-gateways
cat <<EOF | oc -n gloo-mesh-gateways create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
    4. Create a NetworkAttachmentDefinition custom resource for each project where you want to deploy workloads.
        cat <<EOF | oc -n <project> create -f -
apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: istio-cni
EOF
    5. 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-openshift.yaml > istiod.yaml

  3. Update the example file with the environment variables that you previously set. Save the updated file as istiod-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < istiod.yaml > istiod-values.yaml

  4. Verify that the configuration is correct. You can also further edit the file to provide your own details. For more information, see the API reference.

      open istiod-values.yaml

  5. Apply the IstioLifecycleManager CR to your cluster.

      kubectl apply -f istiod-values.yaml

  6. Verify that the istiod pod has a status of Running.

         kubectl get pods -n istio-system

    Example output:

         NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-22-b65676555-g2vmr     1/1     Running   0          47s

Optional: Ingress gateway

If you want to allow traffic from outside the cluster to enter your mesh, create a GatewayLifecycleManager resource to deploy and manage an ingress gateway. The ingress gateway allows you to specify basic routing rules for how to match and forward incoming traffic to a workload in the mesh. However, to also apply policies, such as rate limits, external authentication, or a Web Application Firewall to the gateway, you must have a Gloo Mesh Gateway license. For more information about Gloo Mesh Gateway, see the docs. If you want a service mesh-only environment without ingress, you can skip this step.

  1. Download the example file, ingress-gateway.yaml, which contains a basic GatewayLifecycleManager configuration for an ingress gateway.

      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 > ingress-gateway.yaml

  2. Update the example file with the environment variables that you previously set. Save the updated file as ingress-gateway-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < ingress-gateway.yaml > ingress-gateway-values.yaml

  3. Verify that the configuration is correct. You can also further edit the file to provide your own settings. For more information, see the API reference.

      open ingress-gateway-values.yaml
    • You can add cloud provider-specific load balancer annotations to the istioOperatorSpec.components.ingressGateways.k8s section, such as the following AWS annotations:
                ...
          k8s:
            service:
              ...
            serviceAnnotations:
              service.beta.kubernetes.io/aws-load-balancer-backend-protocol: ssl
              service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
              service.beta.kubernetes.io/aws-load-balancer-nlb-target-type: instance
              service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
              service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:<cert>"
              service.beta.kubernetes.io/aws-load-balancer-type: external
      For testing environments only, you can deploy a revisionless installation by removing the gatewayRevision field.

  4. Apply the GatewayLifecycleManager CR to your cluster.

      kubectl apply -f ingress-gateway-values.yaml

  5. Verify that the ingress gateway pod is running and that the load balancer service has an external address.

      kubectl get pods -n gloo-mesh-gateways
kubectl get svc -n gloo-mesh-gateways

    Example output:

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

  6. Optional for OpenShift: Expose the ingress gateway by using an OpenShift route.

      oc -n gloo-mesh-gateways expose svc istio-ingressgateway --port=http2

Optional: Egress gateway

Prepare a GatewayLifecycleManager resource to deploy and manage an egress gateway. For more information, see Block egress traffic with an egress gateway.

  1. Download the example file, egress-gateway.yaml, which contains a basic GatewayLifecycleManager configuration for an egress gateway.

      curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/single-cluster/gm-egress-gateway.yaml > egress-gateway.yaml

  2. Update the example file with the environment variables that you previously set. Save the updated file as egress-gateway-values.yaml.

    • For example, you can run a terminal command to substitute values:
        envsubst < egress-gateway.yaml > egress-gateway-values.yaml

  3. Verify that the configuration is correct. You can also further edit the file to replicate the settings in your existing Istio installation. For more information, see the API reference.

      open egress-gateway-values.yaml

  4. Apply the GatewayLifecycleManager resource to your cluster.

      kubectl apply -f egress-gateway-values.yaml

  5. In the gloo-mesh-gateways namespace, verify that the egress gateway pod for the new revision is running and that the load balancer service has an external address.

      kubectl get pods -n gloo-mesh-gateways
kubectl get svc -n gloo-mesh-gateways

    Example output for one cluster:

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

Add services to the mesh

Now that Istio is up and running, you can create service namespaces for your teams to run app workloads in. For any namespaces that you want to deploy apps to, be sure to follow these steps to include your services in the service mesh.

  1. Label the namespace with the Istio revision so that Istio sidecars deploy to your app pods.

      export REVISION=$(kubectl get pod -L app=istiod -n istio-system -o jsonpath='{.items[0].metadata.labels.istio\.io/rev}')
kubectl label ns <namespace> istio.io/rev=$REVISION --overwrite

  2. If you already deployed app pods to the namespace, restart the workloads so that sidecars are injected into the pods. For example, you might roll out a restart to each deployment by using a command similar to the following.

      kubectl rollout restart deployment -n <namespace> <deployment>

Next steps

Now that you have Gloo Mesh Enterprise and Istio up and running, check out some of the following resources to learn more about Gloo Mesh Enterprise and expand your service mesh capabilities.

Istio:

Help and support: