Install Istio by using the Istio Lifecycle Manager
Streamline the Istio installation process by using Gloo Mesh to install Istio in your workload clusters, as part of the Istio lifecycle management.
With a Gloo Mesh-managed installation, you no longer need to use istioctl
to individually install Istio in each workload cluster. Instead, you can supply IstioOperator
configurations in a IstioLifecycleManager
resource to your management cluster. Gloo Mesh translates this resource into Istio control planes, gateways, and related resources in your registered workload clusters for you.
Before you begin
-
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 context name is used as a SAN specification in the generated certificate that connects workload clusters to the management cluster, 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> ...
-
Choose the Istio version you want to use for installation.
To use the default supported version of Gloo Istio, set the
REVISION
environment variable toauto
. This setting automatically uses the default supported Gloo Istio version for the image tag (such as1.17.2-solo
) and the revision (such as1-17-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.17.2, and append thesolo
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 as1-17-2
.
export REPO=<repo-key> export ISTIO_IMAGE=1.17.2-solo export REVISION=1-17-2
Istio version 1.17 does not support the Gloo legacy metrics pipeline. If you run the legacy metrics pipeline, before you upgrade or install Istio with version 1.17, be sure that you set up the Gloo OpenTelemetry (OTel) pipeline instead in your new or existing Gloo Mesh installation.
- For
-
Deploy managed Istio in a multicluster or single-cluster setup.
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.
Manage Istio installations in a multicluster setup
-
Prepare an
IstioLifecycleManager
resource to manageistiod
control planes.- 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
- 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-17-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-17-2 --context $REMOTE_CONTEXT2
- 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> --context $REMOTE_CONTEXT1 oc adm policy add-scc-to-group anyuid system:serviceaccounts:<project> --context $REMOTE_CONTEXT2
- 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
- In each workload cluster, create a NetworkAttachmentDefinition custom resource for each project where you want to deploy workloads.
cat <<EOF | oc --context $REMOTE_CONTEXT1 -n <project> create -f - apiVersion: "k8s.cni.cncf.io/v1" kind: NetworkAttachmentDefinition metadata: name: istio-cni EOF
cat <<EOF | oc --context $REMOTE_CONTEXT2 -n <project> create -f - apiVersion: "k8s.cni.cncf.io/v1" kind: NetworkAttachmentDefinition metadata: name: istio-cni EOF
- 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
- 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.
- 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
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
- Apply the
IstioLifecycleManager
resource to your management cluster.kubectl apply -f gm-istiod-values.yaml --context $MGMT_CONTEXT
- Download the example file.
-
Prepare a
GatewayLifecycleManager
custom resource to manage the east-west gateways.-
Download the
gm-ew-gateway.yaml
example file.curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/gloo-mesh/istio-install/gm-managed/gm-ew-gateway.yaml > gm-ew-gateway.yaml
-
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-ew-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-ew-gateway.yaml > gm-ew-gateway-values.yaml open gm-ew-gateway-values.yaml
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
-
Apply the
GatewayLifecycleManager
resource to your management cluster.kubectl apply -f gm-ew-gateway-values.yaml --context $MGMT_CONTEXT
-
-
Optional: If you have a Gloo Gateway license, prepare a
GatewayLifecycleManager
custom resource to manage the ingress gateways.- 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
- 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
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
- Apply the
GatewayLifecycleManager
resource to your management cluster.kubectl apply -f gm-ingress-gateway-values.yaml --context $MGMT_CONTEXT
- Download the
-
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-17-2
,gloo-mesh-gateways
, andistio-system
namespaces are created:NAME STATUS AGE default Active 56m gloo-mesh Active 36m gm-iop-1-17-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
-
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-17-2 --context $REMOTE_CONTEXT1
Example output:
NAME READY STATUS RESTARTS AGE pod/istio-operator-1-17-2-678fd95cc6-ltbvl 1/1 Running 0 4m12s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/istio-operator-1-17-2 ClusterIP 10.204.15.247 <none> 8383/TCP 4m12s NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/istio-operator-1-17-2 1/1 1 1 4m12s NAME DESIRED CURRENT READY AGE replicaset.apps/istio-operator-1-17-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-17-2-b65676555-g2vmr 1/1 Running 0 8m57s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/istiod-1-17-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-17-2 1/1 1 1 8m57s NAME DESIRED CURRENT READY AGE replicaset.apps/istiod-1-17-2-b65676555 1 1 1 8m57s NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE horizontalpodautoscaler.autoscaling/istiod-1-17-2 Deployment/istiod-1-17-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-eastwestgateway-1-17-2-66f464ff44-qlhfk 1/1 Running 0 2m6s pod/istio-ingressgateway-1-17-2-77d5f76bc8-j6qkp 1/1 Running 0 2m18s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/istio-eastwestgateway LoadBalancer 10.204.4.172 34.86.225.164 15021:30889/TCP,15443:32489/TCP 2m5s 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-eastwestgateway-1-17-2 1/1 1 1 2m6s deployment.apps/istio-ingressgateway-1-17-2 1/1 1 1 2m18s NAME DESIRED CURRENT READY AGE replicaset.apps/istio-eastwestgateway-1-17-2-66f464ff44 1 1 1 2m6s replicaset.apps/istio-ingressgateway-1-17-2-77d5f76bc8 1 1 1 2m18s NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE horizontalpodautoscaler.autoscaling/istio-eastwestgateway-1-17-2 Deployment/istio-eastwestgateway-1-17-2 <unknown>/80% 1 5 0 2m7s horizontalpodautoscaler.autoscaling/istio-ingressgateway-1-17-2 Deployment/istio-ingressgateway-1-17-2 4%/80% 1 5 1 2m19s
-
Optional for OpenShift: Expose the gateways by using OpenShift routes.
oc -n gloo-mesh-gateways expose svc istio-eastwestgateway --port=http2 --context $REMOTE_CONTEXT1 oc -n gloo-mesh-gateways expose svc istio-eastwestgateway --port=http2 --context $REMOTE_CONTEXT2
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
-
Now that Istio is up and running, you can create service namespaces for your teams to run app workloads in. For example, you might start out with the Bookinfo sample application.
- For any workload namespace, be sure to label the namespace with the revision so that Istio sidecars are deployed to your app pods.
kubectl label ns <namespace> istio.io/rev=$REVISION --overwrite --context $REMOTE_CONTEXT
- OpenShift only: Follow these additional steps for each workload project. For more information, see the Istio on OpenShift documentation.
- Create a NetworkAttachmentDefinition custom resource.
cat <<EOF | oc --context $REMOTE_CONTEXT -n <project> create -f - apiVersion: "k8s.cni.cncf.io/v1" kind: NetworkAttachmentDefinition metadata: name: istio-cni EOF
- 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> --context $REMOTE_CONTEXT
- Create a NetworkAttachmentDefinition custom resource.
- For any workload namespace, be sure to label the namespace with the revision so that Istio sidecars are deployed to your app pods.
Manage Istio installations in a single-cluster setup
-
Prepare an
IstioLifecycleManager
resource to manageistiod
control planes.- 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
- 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. 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-17-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>
- 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
- 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
- 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
- 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. For more information, see the Istio on OpenShift documentation.
- 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
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
- Apply the
IstioLifecycleManager
resource to your cluster.kubectl apply -f gm-istiod-values.yaml
- Download the example file.
-
Optional: If you have a Gloo Gateway license, prepare a
GatewayLifecycleManager
custom resource to manage the ingress gateways.- 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
- 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
- Tip: Instead of updating the file manually, try running a terminal command to substitute values, such as the following command.
- Apply the
GatewayLifecycleManager
resource to your management cluster.kubectl apply -f gm-ingress-gateway-values.yaml
- Download the
-
Verify that the namespaces for your Istio installations are created.
kubectl get ns
For example, the
gm-iop-1-17-2
,gloo-mesh-gateways
, andistio-system
namespaces are created:NAME STATUS AGE default Active 56m gloo-mesh Active 36m gm-iop-1-17-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
-
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-17-2
Example output:
NAME READY STATUS RESTARTS AGE pod/istio-operator-1-17-2-678fd95cc6-ltbvl 1/1 Running 0 4m12s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/istio-operator-1-17-2 ClusterIP 10.204.15.247 <none> 8383/TCP 4m12s NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/istio-operator-1-17-2 1/1 1 1 4m12s NAME DESIRED CURRENT READY AGE replicaset.apps/istio-operator-1-17-2-678fd95cc6 1 1 1 4m12s
kubectl get all -n istio-system
Example output:
NAME READY STATUS RESTARTS AGE pod/istiod-1-17-2-b65676555-g2vmr 1/1 Running 0 8m57s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/istiod-1-17-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-17-2 1/1 1 1 8m57s NAME DESIRED CURRENT READY AGE replicaset.apps/istiod-1-17-2-b65676555 1 1 1 8m57s NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE horizontalpodautoscaler.autoscaling/istiod-1-17-2 Deployment/istiod-1-17-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-17-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-17-2 1/1 1 1 2m18s NAME DESIRED CURRENT READY AGE replicaset.apps/istio-ingressgateway-1-17-2-77d5f76bc8 1 1 1 2m18s NAME REFERENCE TARGETS MINPODS MAXPODS REPLICAS AGE horizontalpodautoscaler.autoscaling/istio-ingressgateway-1-17-2 Deployment/istio-ingressgateway-1-17-2 4%/80% 1 5 1 2m19s
-
Optional for OpenShift: Expose the ingress gateway by using an OpenShift route.
oc -n gloo-mesh-gateways expose svc istio-ingressgateway --port=http2
-
Now that Istio is up and running, you can create service namespaces for your teams to run app workloads in. For example, you might start out with the Bookinfo sample application.
- For any workload namespace, be sure to label the namespace with the revision so that Istio sidecars are deployed to your app pods.
kubectl label ns <namespace> istio.io/rev=$REVISION --overwrite
- OpenShift only: Follow these additional steps for each workload project.
- 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
- Elevate the permissions of the service account to allow the gateway 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:<project>
- Create a NetworkAttachmentDefinition custom resource.
- For any workload namespace, be sure to label the namespace with the revision so that Istio sidecars are deployed to your app pods.
Next steps
Now that you have Gloo Mesh Enterprise and Istio installed, you can use Gloo Mesh to manage your Istio service mesh resources. You don't need to directly configure any Istio resources going forward.
- When it's time to upgrade Istio, you can use Gloo Mesh to upgrade Gloo Mesh-managed Istio installations.
- Review how Gloo Mesh custom resources are automatically translated into Istio resources.
- Configure workspaces to create boundaries for your teams’ resources.
- Try out the Policies for steps to secure, observe, and control network traffic.