On this page

Migrate to Gloo-managed service meshes

Switch from your existing Istio installations to Gloo-managed service meshes.

Overview

If you have existing Istio installations and want to switch to using the Gloo Operator for service mesh management, you can use one of the following guides:

Revisioned Helm: You installed Istio with Helm. To add namespaces to the service mesh, you used revision labels such as istio.io/rev=1-28.
Revisionless Helm: You installed Istio with Helm. To add namespaces to the service mesh, you used the sidecar injection label, istio-injection=enabled.
Istio lifecycle manager: You installed Istio and gateways by using Solo’s Istio lifecycle manager, such as by using the default settings in the getting started guides, the istioInstallations Helm settings in your Gloo Helm chart, or by directly creating IstioLifecycleManager and GatewayLifecycleManager custom resources.

info

The Gloo Operator uses the gloo revision by default to manage Istio installations in your cluster. This revision is used to facilitate initial migration to the Gloo Operator. However, after migration, in-place upgrades are recommended for further operator-managed changes. For more information, see the Gloo Operator upgrade guide.

Migrate from revisioned Helm installations

If you currently install Istio by using Helm and use revisions to manage your installations, you can migrate from your community Istio revision, such as 1-28, to the gloo revision. The Gloo Operator uses the gloo revision by default to manage Istio installations in your cluster.

Save your Istio installation values in environment variables.
1. If you do not already have a license, contact an account representative.
2. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table.
3. Save each value in an environment variable. If you prefer to specify license keys in a secret instead, see Licensing. Note that the Gloo Operator installs the Solo distribution of Istio by default for the version you specify, so neither the -solo image tag nor the repo URL are required.
```
     export SOLO_LICENSE_KEY=<license_key>
   export ISTIO_VERSION=1.28.1-patch0
     
```
4. Install or upgrade istioctl with the same version of Istio that you saved.
```
     curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
   cd istio-${ISTIO_VERSION}
   export PATH=$PWD/bin:$PATH
     
```

Install the Gloo Operator and deploy a managed istiod control plane.

Install the Gloo Operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (Gloo Platform APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.
```
  helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.4.2 \
  -n gloo-mesh \
  --create-namespace \
  --set manager.env.SOLO_ISTIO_LICENSE_KEY=${SOLO_LICENSE_KEY}
  
```

Verify that the operator pod is running.

  kubectl get pods -n gloo-mesh -l app.kubernetes.io/name=gloo-operator

Example output:

  gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s

Create a ServiceMeshController custom resource to configure an Istio installation. For more information about the configurable fields, see the installation guide.
```
  kubectl apply -n gloo-mesh -f -<<EOF
apiVersion: operator.gloo.solo.io/v1
kind: ServiceMeshController
metadata:
  name: managed-istio
  labels:
    app.kubernetes.io/name: managed-istio
spec:
  cluster: $CLUSTER_NAME
  dataplaneMode: Sidecar
  version: ${ISTIO_VERSION}
  # Uncomment if you installed the istio-cni
  # onConflict: Force
EOF
  
```
notifications
If you currently install the istio-cni plugin by using Helm, you must directly replace the CNI to avoid downtime by setting onConflict: Force.

If you set the installNamespace to a namespace other than gloo-system, gloo-mesh, or istio-system, you must include the --set manager.env.WATCH_NAMESPACES=<namespace> setting.

Verify that the ServiceMeshController is ready. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

  kubectl describe servicemeshcontroller -n gloo-mesh managed-istio

Example output:

  ...
Status:
  Conditions:
    Last Transition Time:  2024-12-27T20:47:01Z
    Message:               Manifests initialized
    Observed Generation:   1
    Reason:                ManifestsInitialized
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               CRDs installed
    Observed Generation:   1
    Reason:                CRDInstalled
    Status:                True
    Type:                  CRDInstalled
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  ControlPlaneDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  CNIDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  WebhookDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               All conditions are met
    Observed Generation:   1
    Reason:                SystemReady
    Status:                True
    Type:                  Ready
  Phase:                   SUCCEEDED
Events:                    <none>

Migrate your Istio-managed workloads to the managed gloo control plane.

Get the workload namespaces that you previously labeled with an Istio revision, such as 1-28 in the following example.
```
  kubectl get namespaces -l istio.io/rev=1-28
  
```
Overwrite the revision label for each of the workload namespaces with the gloo revision label.
```
  kubectl label namespace <namespace> istio.io/rev=gloo --overwrite
  
```
Restart the workloads in each labeled namespace so that they are managed by the Gloo Operator Istio installation.
- To restart all deployments in the namespace:
```
  kubectl rollout restart deployment -n <namespace>
  
```
- To restart individual deployments in the namespace, such as to test a small number of deployments or to stagger the restart process:
```
  kubectl rollout restart deployment <deployment> -n <namespace>
  
```

Verify that the workloads are successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the workload is now part of the Gloo-revisioned service mesh.

  istioctl proxy-status

Example output:

  NAME                                                              CLUSTER     ...     ISTIOD                         VERSION
details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo

Update any existing Istio ingress or egress gateways to the gloo revision.

Get the name and namespace of your gateway Helm release.
```
  helm ls -A
  
```

Get the current values for the gateway Helm release in your cluster.

  helm get values <gateway_release> -n <namespace> -o yaml > gateway.yaml

Upgrade your gateway Helm release.

  helm upgrade -i <gateway_release> istio/gateway \
  --version 1.28.1-patch0 \
  --namespace <namespace> \
  --set "revision=gloo" \
  -f gateway.yaml

Verify that the gateway is successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the gateway is now included in the Gloo-revisioned data plane.

  istioctl proxy-status | grep gateway

Example output:

  NAME                                                  CLUSTER    ...     ISTIOD                           VERSION
istio-ingressgateway-bdc4fd65f-ftmz9.istio-ingress    cluster1    ...     istiod-gloo-6495985689-rkwwd     1.28.1-patch0-solo

Verify that Istio still correctly routes traffic requests to apps in your mesh. For example, if you deployed the Bookinfo sample app, you can send a curl request to the product page.
```
  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage
  
```
Get the name and namespace of your previous istiod Helm release.
```
  helm ls -A
  
```

Uninstall the unmanaged control plane.

  helm uninstall <istiod_release> -n istio-system

Optional: If you previously installed the Istio CNI pods with a Helm chart, uninstall the release and delete the secret stored by Helm.
```
  helm uninstall <cni_release> -n istio-system
kubectl delete secret "sh.helm.release.v1.istio-cni.v1" -n istio-system
  
```

Send another request to your apps to verify that traffic is still flowing.

  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage

The migration of your service mesh is now complete!

Migrate from revisionless Helm installations

If you currently install Istio by using Helm and do not use revisions to manage your installations, such as by labeling namespaces with istio-injection: enabled, you can migrate the management of the MutatingWebhookConfiguration to the Gloo Operator. The Gloo Operator uses the gloo revision by default to manage Istio installations in your cluster.

Save your Istio installation values in environment variables.
1. If you do not already have a license, contact an account representative.
2. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table.
3. Save each value in an environment variable. If you prefer to specify license keys in a secret instead, see Licensing. Note that the Gloo Operator installs the Solo distribution of Istio by default for the version you specify, so neither the -solo image tag nor the repo URL are required.
```
     export SOLO_LICENSE_KEY=<license_key>
   export ISTIO_VERSION=1.28.1-patch0
     
```
4. Install or upgrade istioctl with the same version of Istio that you saved.
```
     curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
   cd istio-${ISTIO_VERSION}
   export PATH=$PWD/bin:$PATH
     
```

Install the Gloo Operator and deploy a managed istiod control plane.

Install the Gloo Operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (Gloo Platform APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.
```
  helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.4.2 \
  -n gloo-mesh \
  --create-namespace \
  --set manager.env.SOLO_ISTIO_LICENSE_KEY=${SOLO_LICENSE_KEY}
  
```

Verify that the operator pod is running.

  kubectl get pods -n gloo-mesh -l app.kubernetes.io/name=gloo-operator

Example output:

  gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s

Create a ServiceMeshController custom resource to configure an Istio installation. For more information about the configurable fields, see the installation guide.
```
  kubectl apply -n gloo-mesh -f -<<EOF
apiVersion: operator.gloo.solo.io/v1
kind: ServiceMeshController
metadata:
  name: managed-istio
  labels:
    app.kubernetes.io/name: managed-istio
spec:
  cluster: $CLUSTER_NAME
  dataplaneMode: Sidecar
  version: ${ISTIO_VERSION}
  # Uncomment if you installed the istio-cni
  # onConflict: Force
EOF
  
```
notifications
If you currently install the istio-cni plugin by using Helm, you must directly replace the CNI to avoid downtime by setting onConflict: Force.

If you set the installNamespace to a namespace other than gloo-system, gloo-mesh, or istio-system, you must include the --set manager.env.WATCH_NAMESPACES=<namespace> setting.

Describe the ServiceMeshController and note that it cannot take over the istio-injection: enabled label until the webhook is deleted.

  kubectl describe ServiceMeshController -n gloo-mesh managed-istio

Example output:

    - lastTransitionTime: "2024-12-12T19:41:52Z"
    message: MutatingWebhookConfiguration istio-sidecar-injector references default
      Istio revision istio-system/istiod; must be deleted before migration
    observedGeneration: 1
    reason: ErrorConflictDetected
    status: "False"
    type: WebhookDeployed

Delete the existing webhook.

  kubectl delete mutatingwebhookconfiguration istio-sidecar-injector -n istio-system

Verify that the ServiceMeshController is now healthy. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

  kubectl describe servicemeshcontroller -n gloo-mesh managed-istio

Example output:

  ...
Status:
  Conditions:
    Last Transition Time:  2024-12-27T20:47:01Z
    Message:               Manifests initialized
    Observed Generation:   1
    Reason:                ManifestsInitialized
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               CRDs installed
    Observed Generation:   1
    Reason:                CRDInstalled
    Status:                True
    Type:                  CRDInstalled
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  ControlPlaneDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  CNIDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  WebhookDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               All conditions are met
    Observed Generation:   1
    Reason:                SystemReady
    Status:                True
    Type:                  Ready
  Phase:                   SUCCEEDED
Events:                    <none>

Migrate your Istio-managed workloads to the managed control plane.

Get the workload namespaces that you previously included in the service mesh by using the istio-injection=enabled label.
```
  kubectl get namespaces -l istio-injection=enabled
  
```

Label each workload namespace with the gloo revision label.

  kubectl label namespace <namespace> istio.io/rev=gloo --overwrite

Restart your workloads so that they are managed by the Gloo Operator Istio installation.
- To restart all deployments in the namespace:
```
  kubectl rollout restart deployment -n <namespace>
  
```
- To restart individual deployments in the namespace, such as to test a small number of deployments or to stagger the restart process:
```
  kubectl rollout restart deployment <deployment> -n <namespace>
  
```

Verify that the workloads are successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the workload is now part of the Gloo-revisioned service mesh.

  istioctl proxy-status

Example output:

  NAME                                                              CLUSTER     ...     ISTIOD                         VERSION
details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo

Remove the istio-injection=enabled label from the workload namespaces.
```
  kubectl label ns <namespace> istio-injection-
  
```

Migrate any existing Istio ingress or egress gateways to the managed gloo control plane.

Get the deployment name of your gateway.

  kubectl get deploy -n <gateway_namespace>

Update each Istio gateway by restarting it.

  kubectl rollout restart deploy <gateway_name> -n <namespace>

Verify that the gateway is successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the gateway is now included in the Gloo-revisioned data plane.

  istioctl proxy-status | grep gateway

Example output:

  NAME                                                  CLUSTER    ...     ISTIOD                           VERSION
istio-ingressgateway-bdc4fd65f-ftmz9.istio-ingress    cluster1    ...     istiod-gloo-6495985689-rkwwd     1.28.1-patch0-solo

Verify that Istio still correctly routes traffic requests to apps in your mesh. For example, if you deployed the Bookinfo sample app, you can send a curl request to the product page.
```
  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage
  
```
Get the name and namespace of your previous istiod Helm release.
```
  helm ls -A
  
```

Uninstall the unmanaged control plane.

  helm uninstall <istiod_release> -n istio-system

Optional: If you previously installed the Istio CNI pods with a Helm chart, uninstall the release and delete the secret stored by Helm.
```
  helm uninstall <cni_release> -n istio-system
kubectl delete secret "sh.helm.release.v1.istio-cni.v1" -n istio-system
  
```

Send another request to your apps to verify that traffic is still flowing.

  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage

The migration of your service mesh is now complete!

Migrate from the Istio lifecycle manager

You might have previously installed Istio and gateways by using Solo’s Istio lifecycle manager, such as by using the default settings in the getting started guides, the istioInstallations Helm settings in your Gloo Helm chart, or by directly creating IstioLifecycleManager and GatewayLifecycleManager custom resources. You can migrate from the Istio revision that your lifecycle manager currently runs, such as 1-28, to the revision that the Gloo Operator uses by default to manage Istio installations in your cluster, gloo.

Single cluster

Save your Istio installation values in environment variables.
1. If you do not already have a license, contact an account representative.
2. Choose the version of Istio that you want to install or upgrade to by reviewing the supported versions table.
3. Save each value in an environment variable. If you prefer to specify license keys in a secret instead, see Licensing. Note that the Gloo Operator installs the Solo distribution of Istio by default for the version you specify, so neither the -solo image tag nor the repo URL are required.
```
     export SOLO_LICENSE_KEY=<license_key>
   export ISTIO_VERSION=1.28.1-patch0
     
```
4. Install or upgrade istioctl with the same version of Istio that you saved.
```
     curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
   cd istio-${ISTIO_VERSION}
   export PATH=$PWD/bin:$PATH
     
```

Install the Gloo Operator and deploy a managed istiod control plane.

Install the Gloo Operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (Gloo Platform APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.
```
  helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.4.2 \
  -n gloo-mesh \
  --create-namespace \
  --set manager.env.SOLO_ISTIO_LICENSE_KEY=${SOLO_LICENSE_KEY}
  
```

Verify that the operator pod is running.

  kubectl get pods -n gloo-mesh -l app.kubernetes.io/name=gloo-operator

Example output:

  gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s

Create a ServiceMeshController custom resource to configure an Istio installation. For more information about the configurable fields, see the installation guide.
```
  kubectl apply -n gloo-mesh -f -<<EOF
apiVersion: operator.gloo.solo.io/v1
kind: ServiceMeshController
metadata:
  name: managed-istio
  labels:
    app.kubernetes.io/name: managed-istio
spec:
  cluster: $CLUSTER_NAME
  dataplaneMode: Sidecar
  version: ${ISTIO_VERSION}
  # Uncomment if you installed the istio-cni
  # onConflict: Force
EOF
  
```
notifications
If you currently install the istio-cni plugin by using Helm, you must directly replace the CNI to avoid downtime by setting onConflict: Force.

If you set the installNamespace to a namespace other than gloo-system, gloo-mesh, or istio-system, you must include the --set manager.env.WATCH_NAMESPACES=<namespace> setting.

Verify that the ServiceMeshController is ready. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

  kubectl describe servicemeshcontroller -n gloo-mesh managed-istio

Example output:

  ...
Status:
  Conditions:
    Last Transition Time:  2024-12-27T20:47:01Z
    Message:               Manifests initialized
    Observed Generation:   1
    Reason:                ManifestsInitialized
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               CRDs installed
    Observed Generation:   1
    Reason:                CRDInstalled
    Status:                True
    Type:                  CRDInstalled
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  ControlPlaneDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  CNIDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  WebhookDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               All conditions are met
    Observed Generation:   1
    Reason:                SystemReady
    Status:                True
    Type:                  Ready
  Phase:                   SUCCEEDED
Events:                    <none>

Migrate your Istio-managed workloads to the managed gloo control plane.

Get the workload namespaces that you previously labeled with an Istio revision, such as 1-28 in the following example.
```
  kubectl get namespaces -l istio.io/rev=1-28
  
```
Overwrite the revision label for each of the workload namespaces with the gloo revision label.
```
  kubectl label namespace <namespace> istio.io/rev=gloo --overwrite
  
```
Restart the workloads in each labeled namespace so that they are managed by the Gloo Operator Istio installation.
- To restart all deployments in the namespace:
```
  kubectl rollout restart deployment -n <namespace>
  
```
- To restart individual deployments in the namespace, such as to test a small number of deployments or to stagger the restart process:
```
  kubectl rollout restart deployment <deployment> -n <namespace>
  
```

Verify that the workloads are successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the workload is now part of the Gloo-revisioned service mesh.

  istioctl proxy-status

Example output:

  NAME                                                              CLUSTER     ...     ISTIOD                         VERSION
details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo

For each gateway that the gateway lifecycle manager created, create Helm releases to deploy new Istio gateways to the gloo revision.
1. Create a new ingress gateway Helm release for the gloo control plane revision. Note that if you maintain your own services to expose gateways, you can disable the load balancer services that are defined by default in the gateway Helm release by including the --set service.type=None flag in this command. Then, you can switch from the old to the new gateways by updating the load balancer services to point to the new gateways.
```
  helm install istio-ingressgateway istio/gateway \
  --version ${ISTIO_VERSION} \
  --namespace istio-ingress \
  --set "revision=gloo"
  
```
2. Verify that the gateway is successfully deployed. In the output, the name of istiod includes the gloo revision, indicating that the gateway is included in the Gloo-revisioned data plane.
```
  istioctl proxy-status | grep gateway
  
```
  Example output:
```
  NAME                                                  CLUSTER    ...     ISTIOD                           VERSION
istio-ingressgateway-bdc4fd65f-ftmz9.istio-ingress    cluster1    ...     istiod-gloo-6495985689-rkwwd     1.28.1-patch0-solo
  
```
Verify that Istio now routes traffic requests to apps in your mesh through the new gateway that you deployed. For example, if you deployed the Bookinfo sample app, you can send a curl request to the product page.
```
  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage
  
```
Delete the GatewayLifecycleManager and IstioLifecycleManager managed installations. The steps vary based on whether you created the resources directly, or used the istioInstallations section of the gloo-platform Helm chart.
Lifecycle manager resources gloo-platform Helm chart
1. Delete the GatewayLifecycleManager resources for the gateways that you installed.
  kubectl delete GatewayLifecycleManager istio-eastwestgateway -n gloo-mesh kubectl delete GatewayLifecycleManager istio-ingressgateway -n gloo-mesh kubectl delete GatewayLifecycleManager istio-egressgateway -n gloo-mesh
2. Verify that the gateway resources are removed before you proceed to the next step.
  kubectl get all -n gloo-mesh-gateways
3. Delete the IstioLifecycleManager for the istiod control plane. Note that your resource might have a different name.
  kubectl delete IstioLifecycleManager istiod-control-plane -n gloo-mesh
1. Get the Helm values of your current Gloo Mesh (Gloo Platform APIs) installation.
  helm get values gloo-platform -o yaml -n gloo-mesh > gloo-single.yaml open gloo-single.yaml
2. In the values file, replace the istioInstallations section with the following, and save the file.
  istioInstallations: enabled: false
3. Upgrade your installation with your updated values file.
  helm upgrade gloo-platform gloo-platform/gloo-platform \ --namespace gloo-mesh \ -f gloo-single.yaml \ --version $GLOO_VERSION
Optional: If you previously installed the Istio CNI pods with a Helm chart, uninstall the release and delete the secret stored by Helm.
```
  helm uninstall <cni_release> -n istio-system
kubectl delete secret "sh.helm.release.v1.istio-cni.v1" -n istio-system
  
```

Send another request to your apps to verify that traffic is still flowing.

  kubectl port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage

The migration of your service mesh is now complete!

Multicluster

Save the kubeconfig context of a workload cluster in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s context.
```
  export CLUSTER_CONTEXT=<workload-cluster-context>
  
```
Set your Gloo Mesh (Gloo Platform APIs) license key as an environment variable. If you do not have one, contact an account representative. If you prefer to specify license keys in a secret instead, see Licensing. To check your license’s validity, you can run meshctl license check --key $(echo ${GLOO_MESH_LICENSE_KEY} | base64 -w0).
```
  export GLOO_MESH_LICENSE_KEY=<license_key>
  
```

Install the Gloo Operator and deploy a managed istiod control plane.

Install the Gloo Operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation. Note that if you already installed Gloo Mesh, you can optionally reference the secret that Gloo Mesh (Gloo Platform APIs) automatically creates for your license in the –set manager.env.SOLO_ISTIO_LICENSE_KEY_SECRET_REF=gloo-mesh/license-keys flag instead.
```
  helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.4.2 \
  -n gloo-mesh \
  --create-namespace \
  --set manager.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}
  
```

Verify that the operator pod is running.

  kubectl get pods -n gloo-mesh --context ${CLUSTER_CONTEXT} -l app.kubernetes.io/name=gloo-operator

Example output:

  gloo-operator-78d58d5c7b-lzbr5     1/1     Running   0          48s

Create a ServiceMeshController custom resource to configure an Istio installation. For more information about the configurable fields, see the installation guide.
notifications
If you currently install the istio-cni plugin by using Helm, you must directly replace the CNI to avoid downtime by setting onConflict: Force.
```
  kubectl --context ${CLUSTER_CONTEXT} apply -n gloo-mesh -f -<<EOF
apiVersion: operator.gloo.solo.io/v1
kind: ServiceMeshController
metadata:
  name: managed-istio
  labels:
    app.kubernetes.io/name: managed-istio
spec:
  cluster: $CLUSTER_NAME
  dataplaneMode: Sidecar
  version: 1.28.1-patch0
  # Uncomment if you installed the istio-cni
  # onConflict: Force
EOF
  
```
info
If you set the installNamespace to a namespace other than gloo-system, gloo-mesh, or istio-system, you must include the --set manager.env.WATCH_NAMESPACES=<namespace> setting.

Verify that the ServiceMeshController is ready. In the Status section of the output, make sure that all statuses are True, and that the phase is SUCCEEDED.

  kubectl --context ${CLUSTER_CONTEXT} describe servicemeshcontroller -n gloo-mesh managed-istio

Example output:

  ...
Status:
  Conditions:
    Last Transition Time:  2024-12-27T20:47:01Z
    Message:               Manifests initialized
    Observed Generation:   1
    Reason:                ManifestsInitialized
    Status:                True
    Type:                  Initialized
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               CRDs installed
    Observed Generation:   1
    Reason:                CRDInstalled
    Status:                True
    Type:                  CRDInstalled
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  ControlPlaneDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  CNIDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               Deployment succeeded
    Observed Generation:   1
    Reason:                DeploymentSucceeded
    Status:                True
    Type:                  WebhookDeployed
    Last Transition Time:  2024-12-27T20:47:02Z
    Message:               All conditions are met
    Observed Generation:   1
    Reason:                SystemReady
    Status:                True
    Type:                  Ready
  Phase:                   SUCCEEDED
Events:                    <none>

Migrate your Istio-managed workloads to the managed gloo control plane. The steps vary based on whether you labeld workload namespaces with revision labels, such as istio.io/rev=1-28, or with injection labels, such as istio-injection=enabled.

Get the workload namespaces that you previously labeled with an Istio revision, such as 1-28 in the following example.
```
  kubectl get namespaces -l istio.io/rev=1-28
  
```
Overwrite the revision label for each of the workload namespaces with the gloo revision label.
```
  kubectl label namespace <namespace> istio.io/rev=gloo --overwrite
  
```
Restart the workloads in each labeled namespace so that they are managed by the Gloo Operator Istio installation.
```
  kubectl --context ${CLUSTER_CONTEXT} rollout restart deployment -n <namespace> <deployment>
  
```

Verify that the workloads are successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the workload is now part of the Gloo-revisioned service mesh.

  istioctl --context ${CLUSTER_CONTEXT} proxy-status

Example output:

  NAME                                                              CLUSTER     ...     ISTIOD                         VERSION
details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo

Get the workload namespaces that you previously included in the service mesh by using the istio-injection=enabled label.
```
  kubectl get namespaces -l istio-injection=enabled
  
```

Label each workload namespace with the gloo revision label.

  kubectl label namespace <namespace> istio.io/rev=gloo --overwrite

Restart your workloads so that they are managed by the Gloo Operator Istio installation.
- To restart all deployments in the namespace:
```
  kubectl rollout restart deployment -n <namespace>
  
```
- To restart individual deployments in the namespace, such as to test a small number of deployments or to stagger the restart process:
```
  kubectl rollout restart deployment <deployment> -n <namespace>
  
```

Verify that the workloads are successfully migrated. In the output, the name of istiod includes the gloo revision, indicating that the workload is now part of the Gloo-revisioned service mesh.

  istioctl proxy-status

Example output:

  NAME                                                              CLUSTER     ...     ISTIOD                         VERSION
details-v1-7b6df9d8c8-s6kg5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
productpage-v1-bb494b7d7-xbtxr.bookinfo                           cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
ratings-v1-55b478cfb6-wv2m5.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v1-6dfcc9fc7d-7k6qh.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo
reviews-v2-7dddd799b5-m5n2z.bookinfo                              cluster1    ...     istiod-gloo-7c8f6fd4c4-m9k9t   1.28.1-patch0-solo

Remove the istio-injection=enabled label from the workload namespaces.
```
  kubectl label ns <namespace> istio-injection-
  
```

For each gateway that the gateway lifecycle manager created, create Helm releases to deploy new Istio gateways to the gloo revision.
1. Create a new east-west gateway Helm release for the gloo control plane revision. Note that if you maintain your own services to expose the gateways, you can disable the load balancer services that are defined by default in the gateway Helm release by including the --set service.type=None flag in this command. Then, you can switch from the old to the new gateways by updating the load balancer services to point to the new gateways.
```
  helm install istio-eastwestgateway istio/gateway \
  --kube-context ${CLUSTER_CONTEXT} \
  --version 1.28.1-patch0 \
  --namespace istio-eastwest \
  --create-namespace \
  --set "revision=gloo"
  
```
2. For ingress gateways: Create a new ingress gateway Helm release for the gloo control plane revision. Note that if you maintain your own services to expose the gateways, you can disable the load balancer services that are defined by default in the gateway Helm release by including the --set service.type=None flag in this command. Then, you can switch from the old to the new gateways by updating the load balancer services to point to the new gateways.
```
  helm install istio-ingressgateway istio/gateway \
  --kube-context ${CLUSTER_CONTEXT} \
  --version 1.28.1-patch0 \
  --namespace istio-ingress \
  --create-namespace \
  --set "revision=gloo"
  
```
3. Verify that the gateways are successfully deployed. In the output, the name of istiod includes the gloo revision, indicating that the gateways are included in the Gloo-revisioned data plane.
```
  istioctl --context ${CLUSTER_CONTEXT} proxy-status | grep gateway
  
```
  Example output:
```
  NAME                                                  CLUSTER    ...     ISTIOD                           VERSION
istio-eastwestgateway-bdc4fd65f-ftmz9.istio-eastwest  cluster1    ...     istiod-gloo-6495985689-rkwwd     1.28.1-patch0-solo
istio-ingressgateway-bdc4fd65f-ftmz9.istio-ingress    cluster1    ...     istiod-gloo-6495985689-rkwwd     1.28.1-patch0-solo
  
```
Verify that Istio now routes traffic requests to apps in your mesh through the new gateway that you deployed. For example, if you deployed the Bookinfo sample app, you can send a curl request to the product page.
```
  kubectl --context ${CLUSTER_CONTEXT} port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage
  
```
Optional: If you previously installed the Istio CNI pods with a Helm chart, uninstall the release and delete the secret stored by Helm.
```
  helm uninstall <cni_release> -n istio-system
kubectl delete secret "sh.helm.release.v1.istio-cni.v1" -n istio-system
  
```
If you have Istio installations in multiple clusters that the GatewayLifecycleManager and IstioLifecycleManager managed, be sure to repeat steps 1 - 6 in each cluster before you continue. The next step deletes the GatewayLifecycleManager and IstioLifecycleManager resources from the management cluster, which uninstalls the old Istio installations from every workload cluster in your multicluster setup. Be sure to reset the value of the $CLUSTER_CONTEXT environment variable to the next workload cluster’s context.

Delete the GatewayLifecycleManager and IstioLifecycleManager managed installations. The steps vary based on whether you created the resources directly, or used the istioInstallations section of the gloo-platform Helm chart.

Delete the GatewayLifecycleManager resources for the gateways that you installed.

  kubectl delete GatewayLifecycleManager istio-eastwestgateway -n gloo-mesh --context ${MGMT_CONTEXT}
kubectl delete GatewayLifecycleManager istio-ingressgateway -n gloo-mesh --context ${MGMT_CONTEXT}
kubectl delete GatewayLifecycleManager istio-egressgateway -n gloo-mesh --context ${MGMT_CONTEXT}

Verify that the gateway resources are removed from the workload clusters before you proceed to the next step.
```
  kubectl --context ${CLUSTER_CONTEXT} get all -n gloo-mesh-gateways
  
```
Delete the IstioLifecycleManager for the istiod control plane. Note that your resource might have a different name.
```
  kubectl --context ${MGMT_CONTEXT} delete IstioLifecycleManager istiod-control-plane -n gloo-mesh
  
```

Get the Helm values of your current Gloo Mesh (Gloo Platform APIs) installation.

  helm get values gloo-platform -o yaml -n gloo-mesh --kube-context ${MGMT_CONTEXT} > mgmt-plane.yaml
open mgmt-plane.yaml

In the values file, replace the istioInstallations section with the following, and save the file.
```
  
istioInstallations:
  enabled: false
  
```

Upgrade your installation with your updated values file.

  helm upgrade gloo-platform gloo-platform/gloo-platform \
--kube-context ${MGMT_CONTEXT} \
--namespace gloo-mesh \
-f mgmt-plane.yaml \
--version ${GLOO_VERSION}

Send another request to your apps to verify that traffic is still flowing.

  kubectl --context ${CLUSTER_CONTEXT} port-forward -n istio-ingress svc/istio-ingressgateway 8080:80
curl -v http://localhost:8080/productpage

The migration of your service mesh is now complete!

Launch the Gloo UI to review the Istio insights that were captured for your service mesh setup. Gloo Mesh (Gloo Platform APIs) comes with an insights engine that automatically analyzes your Istio setups for health issues. These issues are displayed in the UI along with recommendations to harden your Istio setups. The insights give you a checklist to address issues that might otherwise be hard to detect across your environment. For more information, see Insights.
Monitor and observe your Istio environment with Gloo Mesh (Gloo Platform APIs)’s built-in telemetry tools.
When it’s time to upgrade your service mesh, you can perform a safe in-place upgrade by using the Gloo Operator.

Migrate to Gloo-managed service meshes

Overview link

Migrate from revisioned Helm installations link

Migrate from revisionless Helm installations link

Migrate from the Istio lifecycle manager link

Single cluster link

Multicluster link

Next link

Overview

Migrate from revisioned Helm installations

Migrate from revisionless Helm installations

Migrate from the Istio lifecycle manager

Single cluster

Multicluster

Next