By using the Gloo operator to manage your service meshes, 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

Before you install Istio in ambient mode, review the following considerations and requirements.

Feature maturity

Version and license requirements

Single cluster setups:

  • In Gloo Mesh Core version 2.6 and later, ambient mode requires the Solo distribution of Istio version 1.22.3 or later (1.22.3-solo).
  • 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.

Multicluster ambient setups:

  • In Gloo Mesh version 2.7 and later, multicluster ambient setups require the Solo distribution of Istio version 1.24.3 or later (1.24.3-solo), including the Solo distribution of istioctl.
  • A Gloo Mesh Enterprise license. If you do not have one, contact an account representative.

Revision and canary upgrade limitations

Due to an upstream ambient limitation, the ztunnel and Istio CNI pods do not support revisioned canary upgrades, and can only be upgraded in-place. For this reason, creating named revisions for the istiod, cni, ztunnel, and gateways in an ambient mesh is not currently recommended, and the upgrade guides in this documentation set show you how to perform in-place upgrades only.

Single cluster

Install an ambient service mesh with the Gloo operator in a single-cluster Gloo Mesh Core environment.

Prepare the cluster environment

  1. Save the patch version of the Solo distribution of Istio that you want to install. For supported Istio versions in Gloo Mesh Core, see the Ambient section of the Istio images built by Solo.io support article.

      # Solo distrubution of Istio patch version
# in the format 1.x.x, with no tags
export ISTIO_VERSION=1.24.2

  2. Install istioctl, the Istio command line tool. Use the same version that you want to use to install your ambient mesh.

      curl -L https://istio.io/downloadIstio | ISTIO_VERSION=${ISTIO_VERSION} sh -
cd istio-${ISTIO_VERSION}
export PATH=$PWD/bin:$PATH

Install the ambient components

  1. Install the Gloo operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation.

      helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.1.0-rc.1 \
  -n gloo-mesh \
  --create-namespace

  2. Verify that the operator pod is running.

      kubectl get pods -n gloo-mesh | grep 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.

      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

  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

Multicluster

Install ambient service meshes with the Gloo operator in a multicluster Gloo Mesh Core environment.

Prepare the cluster environments

  1. Set environment variables for the Solo distribution of Istio that you want to install. You can find these values in the Ambient section of the Istio images built by Solo.io support article.

      # Solo distrubution of Istio patch version
# in the format 1.x.x, with no tags
export ISTIO_VERSION=1.24.2
# Repo key for the minor version of the Solo distribution of Istio
# This is the 12-character hash at the end of the repo URL: 'us-docker.pkg.dev/gloo-mesh/istio-<repo-key>'
export REPO_KEY=<repo_key>

# Solo distrubution of Istio patch version and Solo tag
# Optionally append other Solo tags as needed
export ISTIO_IMAGE=${ISTIO_VERSION}-solo
# Solo distrubution of Istio patch version and tag,
# image repo, Helm repo, and binary repo
export REPO=us-docker.pkg.dev/gloo-mesh/istio-${REPO_KEY}
export HELM_REPO=us-docker.pkg.dev/gloo-mesh/istio-helm-${REPO_KEY}
export BINARY_REPO=https://console.cloud.google.com/storage/browser/istio-binaries-${REPO_KEY}/${ISTIO_IMAGE}

  2. Download the Solo distribution of Istio binary and install istioctl, which you use for multicluster linking and gateway commands.

    1. Navigate to the storage repository for the Solo distribution of Istio binaries.
        open ${BINARY_REPO}
    2. Download the tar.gz file for your system, such as istio-1.24.2-solo-osx-amd64.tar.gz.
    3. Extract the downloaded tar.gz file.
    4. Navigate to the package directory and add the istioctl client to your system’s PATH.
        cd istio-${ISTIO_IMAGE}
export PATH=$PWD/bin:$PATH
    5. Verify that the istioctl client runs the Solo distribution of Istio that you want to install.
        istioctl version --remote=false
      Example output:
        client version: 1.24.2-solo

Create a shared root of trust

Each cluster in the multicluster setup must have a shared root of trust. This can be achieved by providing a root certificate signed by a PKI provider, or a custom root certificate created for this purpose. The root certificate signs a unique intermediate CA certificate for each cluster.

By default, the Istio CA generates a self-signed root certificate and key, and uses them to sign the workload certificates. For more information, see the Plug in CA Certificates in the community Istio documentation.

For demo installations, you can run the following function to quickly generate and plug in the certificates and key for the Istio CA:

  mkdir -p certs
pushd certs
make -f ../tools/certs/Makefile.selfsigned.mk root-ca

function create_cacerts_secret() {
  context=${1:?context}
  cluster=${2:?cluster}
  make -f ../tools/certs/Makefile.selfsigned.mk ${cluster}-cacerts
  kubectl --context=${context} create ns istio-system || true
  kubectl --context=${context} create secret generic cacerts -n istio-system \
    --from-file=${cluster}/ca-cert.pem \
    --from-file=${cluster}/ca-key.pem \
    --from-file=${cluster}/root-cert.pem \
    --from-file=${cluster}/cert-chain.pem
}

create_cacerts_secret ${REMOTE_CONTEXT1} ${REMOTE_CLUSTER1}
create_cacerts_secret ${REMOTE_CONTEXT2} ${REMOTE_CLUSTER2}

To enhance the security of your setup even further and have full control over the Istio CA lifecycle, you can generate and store the root and intermediate CA certificates and keys with your own PKI provider. You can then use tools such as cert-manager to send certificate signing requests on behalf of istiod to your PKI provider. Cert-manager stores the signed intermediate certificates and keys in the cacerts Kubernetes secret so that istiod can use these credentials to issue leaf certificates for the workloads in the service mesh. You can set up cert-manager to also check the certificates and renew them before they expire.

AWS Private CA issuer and cert-manager: For an architectural overview of this certificate setup, see Bring your own Istio CAs with AWS. For steps on how to deploy this certificate setup, check out this Solo.io blog post. Be sure to repeat the steps so that a cacerts secret exists in each cluster.

Install the ambient components

In each cluster, use the Gloo operator to install the ambient mesh components, and create an east-west gateway so that traffic requests can be routed cross-cluster.

  1. Save the name and kubeconfig context of a cluster where you want to install Istio in the following environment variables. Each time you repeat the steps in this guide, you change these variables to the next workload cluster’s name and context.

      export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>

  2. Install the Gloo operator to the gloo-mesh namespace. This operator deploys and manages your Istio installation.

      helm install gloo-operator oci://us-docker.pkg.dev/solo-public/gloo-operator-helm/gloo-operator \
  --version 0.1.0-rc.1 \
  -n gloo-mesh \
  --create-namespace \
  --kube-context ${CLUSTER_CONTEXT}

  3. Verify that the operator pod is running.

      kubectl get pods -n gloo-mesh --context ${CLUSTER_CONTEXT} | grep operator

    Example output:

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

  4. Create a ServiceMeshController custom resource to configure an Istio installation. For a description of each configurable field, see the ServiceMeshController reference.

      kubectl apply -n gloo-mesh --context ${CLUSTER_CONTEXT} -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}
  network: ${CLUSTER_NAME}
  dataplaneMode: Ambient
  installNamespace: istio-system
  version: ${ISTIO_VERSION}
EOF

  5. 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 --context ${CLUSTER_CONTEXT}

    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>

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

      kubectl get pods -n istio-system --context ${CLUSTER_CONTEXT}

    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

  7. 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 --context ${CLUSTER_CONTEXT}

  8. Create an east-west gateway in the istio-eastwest namespace. An east-west gateway facilitates traffic between services in each cluster in your multicluster ambient mesh.

    • You can use the following istioctl command to quickly create the east-west gateway.
        kubectl create namespace istio-eastwest --context ${CLUSTER_CONTEXT}
istioctl multicluster expose --namespace istio-eastwest --context ${CLUSTER_CONTEXT}
    • To take a look at the Gateway resource that this command creates, you can include the --generate flag in the command.
        kubectl create namespace istio-eastwest --context ${CLUSTER_CONTEXT}
istioctl multicluster expose --namespace istio-eastwest --context ${CLUSTER_CONTEXT} --generate
      In this example output, the gatewayClassName that is used, istio-eastwest, is included by default in the ambient control plane installation.
        apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  labels:
    istio.io/expose-istiod: "15012"
    topology.istio.io/network: "<cluster_network_name>"
  name: istio-eastwest
  namespace: istio-eastwest
spec:
  gatewayClassName: istio-eastwest
  listeners:
  - name: cross-network
    port: 15008
    protocol: HBONE
    tls:
      mode: Passthrough
  - name: xds-tls
    port: 15012
    protocol: TLS
    tls:
      mode: Passthrough

  9. For each cluster that you want to include in the multicluster ambient mesh setup, repeat steps 1 - 8 of this section to install the Gloo operator, ambient mesh components, and east-west gateway in each cluster. Remember to change the cluster name and context variables each time you repeat the steps.

      export CLUSTER_NAME=<cluster-name>
export CLUSTER_CONTEXT=<cluster-context>

Linking clusters enables cross-cluster service discovery and allows traffic to be routed through east-west gateways across clusters.

  1. Verify that the contexts for the clusters that you want to include in the multicluster ambient mesh are listed in your kubeconfig file.

      kubectl config get-contexts
    • In the output, note the names of the cluster contexts, which you use in the next step to link the clusters.
    • If you have multiple kubeconfig files, you can generate a merged kubeconfig file by running the following command.
        KUBECONFIG=<kubeconfig_file1>.yaml:<file2>.yaml:<file3>.yaml kubectl config view --flatten

  2. Using the names of the cluster contexts, link the clusters so that they can communicate. Note that you can either link the clusters bi-directionally or asymmetrically. In a standard bi-directional setup, services in any of the linked clusters can send requests to and receive requests from the services in any of the other linked clusters. In an asymmetrical setup, you allow one cluster to send requests to another cluster, but the other cluster cannot send requests back to the first cluster.

    You can use the following istioctl command to quickly link the clusters bi-directionally. In each cluster, Gateway resources are created to represent each other cluster in the multicluster setup. For example, if you run this command to link three clusters, the command creates six gateways in total: in cluster1, a gateway for cluster2 and a gateway for cluster3; in cluster2, a gateway for cluster1 and a gateway for cluster3; in cluster3, a gateway for cluster1 and a gateway for cluster2. These Gateways use the istio-remote GatewayClass that allows the gateway to connect to other clusters by using the clusters’ contexts.

      istioctl multicluster link --namespace istio-eastwest --contexts=<context1>,<context2>,<context3>

    To take a look at the Gateway resources that this command creates, you can include the --generate flag in the command.

    Example output for two clusters:

      Gateway istio-eastwest/istio-remote-peer-cluster1 applied to cluster "<cluster2_context>" pointing to cluster "<cluster1_context>" (network "cluster1")
Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "<cluster1_context>" pointing to cluster "<cluster2_context>" (network "cluster2")

    You can use the following istioctl command to quickly link the clusters asymmetrically. The services in the cluster in the --from flag can send requests to services in cluster in the --to flag, but sending requests in the reverse direction is not permitted.

      istioctl multicluster link --namespace istio-eastwest --from <context1> --to <context2>

    To take a look at the Gateway resources that this command creates, you can include the --generate flag in the command.

    For example, this command allows services in cluster1’s mesh to send requests to services in cluster2’s mesh through cluster2’s east-west gateway. However, the reverse is not permitted: services in cluster2’s mesh cannot send requests through cluster1’s east-west gateway to services in cluster1.

      istioctl multicluster link --namespace istio-eastwest --from cluster1 --to cluster2

    Example output:

      Gateway istio-eastwest/istio-remote-peer-cluster2 applied to cluster "<cluster1_context>" pointing to cluster "<cluster2_context>" (network "cluster2")

Next

Add apps to the ambient mesh. For multicluster setups, this includes making specific services available across your linked cluster setup.

ServiceMeshController reference

Review the following configurable fields for the ServiceMeshController custom resource.

SettingDescriptionSupported valuesDefault
clusterThe name of the cluster to install Istio into. This value is required to set the trust domain field in multicluster environments.
dataplaneModeThe dataplane mode to use.Ambient or SidecarAmbient
distributionOptional: A specific distribution of the Istio version, such as the standard or FIPS image distribution.Standard or FIPSStandard
image.repositoryOptional: An Istio image repository, such as to use an image from a private registry.The Solo distribution of Istio repo for the Istio minor version.
image.secretsOptional: A list of secrets to use for pulling images from a container registry. The secret list must be of type kubernetes.io/dockerconfigjson and exist in the installNamespace that you install Istio in.
installNamespaceNamespace to install the service mesh components into.istio-system
networkThe default network where workload endpoints exist. A network is a logical grouping of workloads that exist in the same Layer 3 domain. Workloads in the same network can directly communicate with each other, while workloads in different networks require an east-west gateway to establish connectivity. This value is required in multi-network environments. For example, an easy way to identify the network of in-mesh workloads in one cluster is to simply use the cluster’s name for the network, such as cluster1.
onConflictOptional: How to resolve conflicting Istio configuration, if the configuration in this ServiceMeshController conflicts with existing Istio resources in the cluster.
  • Force: The existing resources are updated with the new configuration.
  • Abort: The installation configured in this ServiceMeshController is aborted, and the existing resources remain unchanged.
Force or AbortAbort
repository.secretsOptional: A list of secrets to use for pulling manifests from an artifact registry. The secret list must be of type kubernetes.io/dockerconfigjson and can exist in any namespace, such as the same namespace that you create the ServiceMeshController in.
repository.insecureSkipVerifyOptional: If set to true, the repository server’s certificate chain and hostname are not verified.true or false
scalingProfileOptional: The istiod control plane scaling settings to use. In large environments, set to Large.
  • Default sets the following scaling values:
    • resources.requests.cpu=1000m
    • resources.requests.memory=1Gi
    • resources.limits.cpu=2000m
    • resources.limits.memory=2Gi
    • autoscaleEnabled=true
    • autoscaleMin=2
    • autoscaleMax=25
    • cpu.targetAverageUtilization=80
  • Large sets the following scaling values:
    • resources.requests.cpu=4000m
    • resources.requests.memory=4Gi
    • resources.limits.cpu=4000m
    • resources.limits.memory=4Gi
    • autoscaleEnabled=true
    • autoscaleMin=4
    • autoscaleMax=50
    • cpu.targetAverageUtilization=75
Default or LargeDefault
trafficCaptureModeOptional: Traffic capture mode to use.
  • Auto: The most suitable traffic capture mode is automatically selected based on the environment, such as using a CNI to capture traffic.
  • InitContainer: An init container is used for the traffic capture. This setting can only be used when the dataplaneMode is Sidecar.
Auto or InitContainerAuto
trustDomainThe trustDomain for Istio workloads.If cluster is set, defaults to that value. If cluster is unset, defaults to cluster.local.
versionThe Istio patch version to install. For more information, see Supported Solo distributions of Istio.Any Istio version supported for your Gloo version