Deploy Gloo-managed service meshes
Use Gloo’s Istio Lifecycle Manager to install and manage Solo distributions of Istio service meshes in your clusters for you.
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.
Istio 1.22 is supported only as patch version 1.22.1-patch0
and later. Do not use patch versions 1.22.0 and 1.22.1, which contain bugs that impact several Gloo Mesh Enterprise routing features that rely on virtual destinations. Additionally, in Istio 1.22.0-1.22.3, the ISTIO_DELTA_XDS
environment variable must be set to false
. For more information, see this upstream Istio issue. Note that this issue is resolved in Istio 1.22.4.
Gloo Mesh Enterprise version 2.6 supports Istio version 1.21. However, a bug was identified when upgrading from Istio version 1.20 or lower to Istio version 1.21 and later while being on Gloo Mesh Enterprise version 2.6. This bug can lead to disabled JWT authentication and authorization policies that fail close, which means that the gateway rejects requests as unauthenticated on any route that is protected by a JWT policy. Note that this bug will be fixed in a future 2.6 patch release. Do not upgrade to Istio version 1.21 and later until this patch is available. For more information, see the release notes.
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 Mesh Enterprise features that rely on Istio ServiceEntries.
If you have multiple external services that use the same host and plan to use Istio 1.20, 1.21, or 1.22, you must use patch versions 1.20.7, 1.21.3, or 1.22.1-patch0 or later to ensure that the Istio service entry that is created for those external services is correct.
Before you begin
Follow the get started or advanced installation guide to install the Gloo Mesh Enterprise components.
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 theglooMgmtServer.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.
- 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
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 thesolo
tag, such as1.22.4-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 as1-22
.
For testing environments only, you can deploy a revisionless installation. Revisionless installations permit in-place upgrades, which are quicker than the canary-based upgrades that revisioned installations require. To omit a revision, do not set a revision environment variable. Then in the following sections, you edit the sampleIstioLifecycleManager
andGatewayLifecycleManager
files that you download to remove therevision
andgatewayRevision
fields. Note that if you deploy multiple Istio installations in the same cluster, only one installation can be revisionless.export REPO=<repo-key> export ISTIO_IMAGE=1.22.4-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.
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> ...
- Save the kubeconfig contexts for your clusters. Run
kubectl config get-contexts
, look for your cluster in theCLUSTER
column, and get the context name in theNAME
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 runningkubectl config rename-context "<oldcontext>" <newcontext>
.export MGMT_CONTEXT=<management-cluster-context> export REMOTE_CONTEXT1=<remote-cluster1-context> export REMOTE_CONTEXT2=<remote-cluster2-context> ...
Download the example file,
istiod.yaml
, which contains a basicIstioLifecycleManager
configuration for the control plane.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
- For example, you can run a terminal command to substitute values:
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
For testing environments only, you can deploy a revisionless installation by removing therevision
fields.Apply the
IstioLifecycleManager
CR to your management cluster.kubectl apply -f istiod-values.yaml --context $MGMT_CONTEXT
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.
Download the example file,
ew-gateway.yaml
, which contains a basicGatewayLifecycleManager
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
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
- For example, you can run a terminal command to substitute values:
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.
- For testing environments only, you can deploy a revisionless installation by removing the
Apply the
GatewayLifecycleManager
CR to your management cluster.kubectl apply -f ew-gateway-values.yaml --context $MGMT_CONTEXT
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
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
AWS clusters: 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 Mesh Core 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 configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.
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.
Download the example file,
ingress-gateway.yaml
, which contains a basicGatewayLifecycleManager
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
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
- For example, you can run a terminal command to substitute values:
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:For testing environments only, you can deploy a revisionless installation by removing the... 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
gatewayRevision
field.
- You can add cloud provider-specific load balancer annotations to the
Apply the
GatewayLifecycleManager
CR to your management cluster.kubectl apply -f ingress-gateway-values.yaml --context $MGMT_CONTEXT
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
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
AWS clusters: 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 Mesh Core 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 configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.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.
Download the example file,
egress-gateway.yaml
, which contains a basicGatewayLifecycleManager
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
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
- For example, you can run a terminal command to substitute values:
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
For testing environments only, you can deploy a revisionless installation by removing therevision
field.Apply the
GatewayLifecycleManager
CR to your management cluster.kubectl apply -f egress-gateway-values.yaml --context $MGMT_CONTEXT
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
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.
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
If you deployed revisionless installations in testing environments, you can instead label your workload namespaces withkubectl label ns
.istio-injection=enabled --context $REMOTE_CONTEXT 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.
Save the name of your cluster as an environment variable.
export CLUSTER_NAME=<cluster_name>
Download the example file,
istiod.yaml
, which contains a basicIstioLifecycleManager
configuration for the control plane.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
- For example, you can run a terminal command to substitute values:
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
For testing environments only, you can deploy a revisionless installation by removing therevision
field.Apply the
IstioLifecycleManager
CR to your cluster.kubectl apply -f istiod-values.yaml
Verify that the
istiod
pod has a status ofRunning
.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.
Download the example file,
ingress-gateway.yaml
, which contains a basicGatewayLifecycleManager
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
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
- For example, you can run a terminal command to substitute values:
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:For testing environments only, you can deploy a revisionless installation by removing the... 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
gatewayRevision
field.
- You can add cloud provider-specific load balancer annotations to the
Apply the
GatewayLifecycleManager
CR to your cluster.kubectl apply -f ingress-gateway-values.yaml
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
AWS clusters: 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 Mesh Core 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 configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.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.
Download the example file,
egress-gateway.yaml
, which contains a basicGatewayLifecycleManager
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
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
- For example, you can run a terminal command to substitute values:
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
For testing environments only, you can deploy a revisionless installation by removing therevision
field.Apply the
GatewayLifecycleManager
resource to your cluster.kubectl apply -f egress-gateway-values.yaml
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
AWS clusters: 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 Mesh Core 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 configures. For your ELB health check to pass, you might need to configure the load balancer to run the health check on port 15443.
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.
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
If you deployed revisionless installations in testing environments, you can instead label your workload namespaces withkubectl label ns
.istio-injection=enabled 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:
- Find out more about hardened Istio
n-4
version support built into Solo distributions of Istio. - Review how Gloo Mesh Enterprise custom resources are automatically translated into Istio resources.
- Monitor and observe your Istio environment with Gloo Mesh Enterprise’s built-in telemetry tools.
- When it’s time to upgrade Istio, use Gloo Mesh Enterprise to upgrade managed Istio installations.
Help and support:
- Talk to an expert to get advice or build out a proof of concept.
- Join the #gloo-mesh channel in the Solo.io community slack.
- Try out one of the Gloo workshops.