Install a managed ambient mesh with the Gloo Operator

Overview link

By using the Gloo Operator to manage your service mesh, you no longer need to manually install and manage the istiod control plane. Instead, you provide minimal Istio configuration to the operator in a ServiceMeshController custom resource, and the operator translates this configuration into a managed istiod control plane in your cluster for you. The operator reduces both the amount of configuration required to deploy Istio, and the overhead required to manage the lifecycle of Istio resources in your cluster.

For more information about the components that are installed in these steps, see the ambient components overview.

Considerations link

Before you install an ambient mesh, review the following considerations and requirements.

Version requirements

• In Gloo Mesh version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (1.22.3-solo).
• If you plan to later link meshes for a multicluster ambient mesh setup: In Gloo Mesh version 2.7 and later, multicluster setups require version 1.24.3 or later.
• 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.

Single-cluster and multicluster meshes

This guide shows you how to install an ambient mesh in one cluster. If you later decide to to upgrade to a multicluster mesh with an Enterprise level license, you can link your existing ambient meshes across clusters.

Alternatively, if you prefer to start with a multicluster mesh immediately, check out Install and connect new ambient meshes in the multicluster guide instead.

Revision and canary upgrade limitations

The upgrade guides in this documentation show you how to perform in-place upgrades for your Istio components, which is the recommended upgrade strategy.

Set up tools link

1. If you do not already have a license, decide the level of licensed features that you want, and contact an account representative to obtain the license.

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 key are required.

     export GLOO_MESH_LICENSE_KEY=<license_key>
   export ISTIO_VERSION=1.25.2
     

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 ambient components link

1. 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 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.2.3 \
     -n gloo-mesh \
     --create-namespace \
     --set manager.env.SOLO_ISTIO_LICENSE_KEY=${GLOO_MESH_LICENSE_KEY}
     

2. 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
     

3. Create a ServiceMeshController custom resource to configure an Istio installation. For a description of each configurable field, see the ServiceMeshController reference. If you need to set more advanced Istio configuration, you can also create a gloo-extensions-config configmap.

     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:
     dataplaneMode: Ambient
     installNamespace: istio-system
     version: ${ISTIO_VERSION}
   EOF
     

   info

   Note that the operator detects your cloud provider and cluster platform, and configures the necessary settings required for that platform for you. For example, if you create an ambient mesh in an OpenShift cluster, no OpenShift-specific settings are required in the ServiceMeshController, because the operator automatically sets the appropriate settings for OpenShift and your specific cloud provider accordingly.
   
   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.

4. 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>
     

5. Verify that the istiod control plane, Istio CNI, and ztunnel pods are running.

     kubectl get pods -n istio-system
     

   Example output:

     NAME                          READY   STATUS    RESTARTS   AGE
   istio-cni-node-6s5nk          1/1     Running   0          2m53s
   istio-cni-node-blpz4          1/1     Running   0          2m53s
   istiod-gloo-bb86b959f-msrg7   1/1     Running   0          2m45s
   istiod-gloo-bb86b959f-w29cm   1/1     Running   0          3m
   ztunnel-mx8nw                 1/1     Running   0          2m52s
   ztunnel-w8r6c                 1/1     Running   0          2m52s
     

6. Apply the CRDs for the Kubernetes Gateway API to your cluster, which are required to create components such as waypoint proxies for L7 traffic policies, gateways with the Gateway resource, and more.

     kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.2.1/standard-install.yaml
     

Next link

• Add apps to the ambient mesh.
• Link meshes together to create a multicluster mesh.

ServiceMeshController reference link

Review the following configurable fields for the ServiceMeshController custom resource.

Advanced settings configuration link

You can set advanced Istio configuation by creating a configmap. For example, you might need to specify settings for istiod such as discovery selectors, pod and service annotations, affinities, tolerations, or node selectors.

The following gloo-extensions-config example configmap sets all possible fields for demonstration purposes.

  apiVersion: v1
kind: ConfigMap
metadata:
  name: gloo-extensions-config
  namespace: gloo-mesh
data:
  stable: |
    serviceMeshController:
      istiod:
        discoverySelectors:
          - matchLabels:
              foo: bar
        topology:
          affinity:
            podAntiAffinity:
              preferredDuringSchedulingIgnoredDuringExecution:
              - podAffinityTerm:
                  labelSelector:
                    matchExpressions:
                    - key: foo
                      operator: In
                      values:
                      - bar
                  topologyKey: foo.io/bar
                weight: 80
          nodeSelector:
            foo: bar
          tolerations:
            - key: t1
              operator: Equal
              value: v1
        deployment:
          podAnnotations:
            foo: bar
        serviceAnnotations:
          foo: bar
  beta: |
    serviceMeshController:
      cni:
        confDir: /foo/bar
        binDir: /foo/bar