Install Istio by using Gloo Mesh

Streamline the Istio installation process by using Gloo Mesh to install Istio in your workload clusters.

With a Gloo Mesh-managed installation, you no longer need to use istioctl to individually install Istio in each workload cluster. Instead, Gloo Mesh translates your IstioOperator configuration into Istio control planes and resources in your workload clusters for you. Gloo Mesh can currently manage the Istio installation for Istio version 1.8 or greater.

This feature does not currently support managing existing Istio installations. Until management of the full lifecycle of Istio is supported, do not use this feature in production.

Currently, versions 1.11 and earlier of Istio are supported for Gloo Mesh-managed Istio installations.

Before you begin

  1. Install Gloo Mesh Enterprise into a management cluster.
  2. Register each workload cluster with Gloo Mesh.

Step 1: Prepare the Istio operator

Prepare an IstioOperator resource that you want to use to configure your Istio installations. Note that you must configure any Istio gateways in a separate IstioOperator resource than the IstioOperator resource for the Istio control plane. Then, in the next section, you can specify the resources together in one IstioLifecycleManager resource for the installation.

  1. Prepare an IstioOperator resource for the Istio control plane. For example Istio install profiles, see Installing Istio. To ensure that the gateway components are not included in the IstioOperator for the control plane, set the profile value to minimal, and for each gateway set enabled to false (example).

    Keep in mind the following changes that Gloo Mesh applies to the Istio operator configuration when it is used:

    • Revision: A revision based on the specified Istio tag and hub is automatically generated for the Istio operator. For example, if you use version 1.11.6 of the Solo FIPs tag (tag: 1.11.6-solo-fips), a solo-1-11 revision is generated. Note that this generated revision overrides any revision that you specify in the IstioOperator file.
    • Namespace: If you do not specify a namespace, the root namespace for the installed Istio resources in workload clusters is set to istio-system. If istio-system does not already exist, it is created for you.
    • Cluster name values: In typical Istio operator configuration, you specify the name of the workload cluster in the meshConfig.proxyMetadata.GLOO_MESH_CLUSTER_NAME, values.global.network, and values.global.multiCluster.clusterName fields. With the Istio installer, you can leave these fields blank, because for each workload cluster, the installer automatically sets these fields to the cluster name that was specified during cluster registration.
    • Trust domain: By default, the trustDomain value is automatically set by the installer to the name of each workload cluster. To override the trustDomain for each cluster, you can instead specify the override value in the trustDomain field, and include the value in the list of cluster names when you create the installer resource in step 3. For example, if you specify trustDomain: cluster-1-trust-override in the Istio operator, you then specify the cluster name and the trust domain in the list of cluster names: cluster-1,cluster-1-trust-override. Additionally, because Gloo Mesh requires multiple trust domains for east-west routing, the PILOT_SKIP_VALIDATE_TRUST_DOMAIN field is set to "true" by default.
  2. Prepare an IstioOperator resource for the Istio ingress gateway. For example, this command downloads a sample file, ingress-gateway.yaml, which you can edit to provide your own details. Set the profile value to empty to ensure that the control plane is not installed.

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

    Keep in mind the following requirements:

    • If your IstioOperator installs the ingress gateway into a different namespace than the istiod control plane, you must complete the first step in [this section]( /gloo-mesh-enterprise/latest/setup/installation/istio/prod_istio/operator_deployment/#step-3-deploy-istio-ingress-gateway to copy the Istio revision configmap to that namespace.
    • All other changes listed in the previous step also apply to this IstioOperator.
  3. Optional: If you have a multicluster Gloo Mesh setup, prepare an IstioOperator resource for the Istio east-west gateway. For example, this command downloads a sample file, eastwest-gateway.yaml, which you can edit to provide your own details. Set the profile value to empty to ensure that the control plane is not installed.

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

    Keep in mind the following requirements:

    • If your IstioOperator installs the east-west gateway into a different namespace than the istiod control plane, you must complete the first step in [this section]( /gloo-mesh-enterprise/latest/setup/installation/istio/prod_istio/operator_deployment/#step-3-deploy-istio-ingress-gateway to copy the Istio revision configmap to that namespace.
    • All other changes listed in the first step also apply to this IstioOperator.

Step 2: Install the Istio operators with Gloo Mesh

  1. Get the names of the workload clusters that are registered with Gloo Mesh.

    kubectl get kubernetescluster -n gloo-mesh --context $MGMT_CONTEXT
    

    Example output:

    NAME           AGE
    cluster-1      27s
    cluster-2      23s
    
  2. Create the Gloo Mesh-managed installation resource in your management cluster by using the meshctl command or by creating and applying the IstioLifecycleManager resource.

    • meshctl installation: Specify the comma-separated list of registered cluster names and your Istio operator configuration in the following command. For more information, see the meshctl istio install reference documentation.
      meshctl istio install --kubecontext $MGMT_CONTEXT --clusters <cluster_list> --file <istio_operator_spec> --name <installation_name>
      

      Example command:

      meshctl istio install --kubecontext $MGMT_CONTEXT --clusters cluster-1,cluster-2 --file operator-1-11-6.yaml --name managed-installation
      
    • kubectl installation:
      1. Create an IstioLifecycleManager resource and save the file as managed-installation.yaml. Specify the registered cluster names in the spec.clusters section and your Istio operator configurations in the spec.installations section.
        apiVersion: admin.enterprise.mesh.gloo.solo.io/v1alpha1
        kind: IstioLifecycleManager
        metadata:
          name: managed-installation
          namespace: gloo-mesh
        spec:
          clusters:
            - name: cluster-1
            - name: cluster-2
          installations:
            - name: control-plane
              istioOperatorSpec:
                profile: minimal
                tag: 1.11.6
                namespace: istio-system
                [...]
            - name: ingress-gateway
              istioOperatorSpec:
                profile: empty
                tag: 1.11.6
                namespace: istio-system
                [...]
            - name: eastwest-gateway
              istioOperatorSpec:
                profile: empty
                tag: 1.11.6
                namespace: istio-system
                [...]
        
      2. Apply the IstioLifecycleManager resource to your management cluster.
        kubectl apply -f managed-installation.yaml --context $MGMT_CONTEXT
        

Step 3: Verify the Istio installation

  1. In each workload cluster, check the status of the IstioInstallationInstance, which is created with the same name and in the same namespace as the IstioLifecycleManager resource. The Istio installation instance contains the Istio operator configuration and information on the status of the installation.

    kubectl get IstioInstallationInstance -n gloo-mesh --context $REMOTE_CONTEXT1
    

    In this example output, the state of the installation is HEALTHY. If there are issues with your installation, the status includes additional details in the message. You can also inspect the logs of the controller and the operator that are listed in the status section.

    apiVersion: admin.agent.enterprise.mesh.gloo.solo.io/v1alpha1
    kind: IstioInstallationInstance
    metadata:
      name: managed-installation
      namespace: gloo-mesh
    spec:
      istioOperatorSpec:
        [...]
    status:
      state: HEALTHY
      generatedRevision: 1-11
      istioOperator:
        name: gloo-mesh-istio-operator-1-11
        namespace: istio-system-1-11
      istioOperatorController:
        name: istio-operator-1-11
        namespace: gloo-mesh-iop-1-11
    
  2. In each workload cluster, 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 pods -n istio-system --context $REMOTE_CONTEXT1
    

    Example output:

    NAME                                    READY   STATUS    RESTARTS   AGE
    istiod-7795ccf9dc-vr4cq                 1/1     Running   0          5d22h
    

Step 4: Expose Istio gateways

Expose the gateways in each cluster by creating load balancers. Note that load balancer services are not managed by the Gloo Mesh Istio installation and upgrade system.

  1. In each workload cluster, create a load balancer service to expose the ingress gateway. For example, this command downloads a sample file, ingress-gateway-lb.yaml, which you can edit to provide your own details. Note that load balancer services are not managed by the Gloo Mesh Istio installation and upgrade system.

    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/istio-install/1.11/ingress-gateway-lb.yaml > ingress-gateway-lb.yaml
    kubectl apply -f ingress-gateway-lb-values.yaml
    
  2. If you installed the east-west gateway, create a load balancer service to expose the east-west gateway in each workload cluster. For example, this command downloads a sample file, eastwest-gateway-lb.yaml, which you can edit to provide your own details. Note that load balancer services are not managed by the Gloo Mesh Istio installation and upgrade system.

    curl -0L https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/istio-install/1.11/eastwest-gateway-lb.yaml > eastwest-gateway-lb.yaml
    kubectl apply -f eastwest-gateway-lb-values.yaml
    

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.