Get started

Gloo Mesh Core deploys alongside your Istio installations in single or multicluster environments, and gives you instant insights into your Istio environment through a custom dashboard. You can follow this guide to quickly get started with Gloo Mesh Core. To learn more about the benefits and architecture, see About. To customize your installation with Helm instead, see the advanced installation guide.

Before you begin link

1. Install the following command-line (CLI) tools.

   • kubectl, the Kubernetes command line tool. Download the kubectl version that is within one minor version of the Kubernetes clusters you plan to use.
   • meshctl, the Solo command line tool.

       curl -sL https://run.solo.io/meshctl/install | sh
       

2. Set your Gloo 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.

     export GLOO_MESH_CORE_LICENSE_KEY=<GLOO_MESH_CORE_LICENSE_KEY>
     

Install Gloo Mesh Core link

Deploy the Gloo Mesh Core components into one cluster that runs Istio, or across a multicluster Istio environment.

Single cluster link

Install all Gloo Mesh Core components in the same cluster as your Istio service mesh.

1. Create or use an existing Kubernetes cluster, and save the name of the cluster as an environment variable. Note: The cluster name must be alphanumeric with no special characters except a hyphen (-), lowercase, and begin with a letter (not a number).

     export CLUSTER_NAME=<cluster_name>
     

2. Install Gloo Mesh Core in your cluster. This command uses a basic profile to create a gloo-mesh namespace and install the Gloo control and data plane components. For more information, check out the CLI install profiles.

     meshctl install --profiles gloo-core-single-cluster \
     --set common.cluster=$CLUSTER_NAME \
     --set licensing.glooMeshCoreLicenseKey=$GLOO_MESH_CORE_LICENSE_KEY \
     --release-name gloo-mesh-core
     

3. Verify that Gloo Mesh Core installed correctly. This check might take a few seconds to verify that:

   • Your Gloo Mesh Core product license is valid and current.
   • The Gloo CRDs installed at the correct version.
   • The Gloo pods are running and healthy.
   • The Gloo agent is running and connected to the management server.

     meshctl check
     

4. Check whether an Istio control plane already exists.

     kubectl get pods -n istio-system
     

   If an istiod pod exists, such as in this example output, you already installed an Istio control plane. Continue to the next step.

     NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-19-3-b65676555-g2vmr   1/1     Running   0          57s
     

   If no istiod pod exists, you can use Gloo Mesh Core to quickly install and manage a service mesh for you. For more information about service mesh lifecycle management with Gloo, check out Service mesh lifecycle and Solo Istio images.

   1. Apply an IstioLifecycleManager custom resource, which Gloo translates into the istiod control plane.

        kubectl apply -f- <<EOF
      apiVersion: admin.gloo.solo.io/v2
      kind: IstioLifecycleManager
      metadata:
        name: istiod-control-plane
        namespace: gloo-mesh
      spec:
        installations:
        - clusters:
          - defaultRevision: true
            name: $CLUSTER_NAME
          istioOperatorSpec:
            components:
              pilot:
                k8s:
                  env:
                  - name: PILOT_SKIP_VALIDATE_TRUST_DOMAIN
                    value: "true"
            meshConfig:
              accessLogFile: /dev/stdout
              defaultConfig:
                holdApplicationUntilProxyStarts: true
                proxyMetadata:
                  ISTIO_META_DNS_CAPTURE: "true"
              outboundTrafficPolicy:
                mode: ALLOW_ANY
            namespace: istio-system
            profile: minimal
          revision: auto
      EOF
        

   2. Verify that the istiod pod has a status of Running.

        kubectl get pods -n istio-system
        

      Example output:

        NAME                            READY   STATUS    RESTARTS   AGE
      istiod-1-19-3-b65676555-g2vmr   1/1     Running   0          57s
        

   3. Optional: To deploy an ingress gateway, apply a GatewayLifecycleManager custom resource.

        kubectl apply -f- <<EOF
      apiVersion: admin.gloo.solo.io/v2
      kind: GatewayLifecycleManager
      metadata:
        name: istio-ingressgateway
        namespace: gloo-mesh
      spec:
        installations:
        - clusters:
          - activeGateway: true
            name: $CLUSTER_NAME
          gatewayRevision: auto
          istioOperatorSpec:
            components:
              ingressGateways:
              - enabled: true
                k8s:
                  service:
                    ports:
                    # For AWS ELBs, must be listed as the first port
                    - name: status-port
                      port: 15021
                      targetPort: 15021
                    - name: http2
                      port: 80
                      targetPort: 8080
                    - name: https
                      port: 443
                      targetPort: 8443
                    - name: tls
                      port: 15443
                      targetPort: 15443
                    selector:
                      istio: ingressgateway
                    type: LoadBalancer
                label:
                  app: istio-ingressgateway
                  istio: ingressgateway
                name: istio-ingressgateway
                namespace: gloo-mesh-gateways
            meshConfig:
              accessLogFile: /dev/stdout
            profile: empty
      EOF
        

   4. Verify that the ingress gateway pod is running and that the load balancer service has an external address.

        kubectl get pods -n gloo-mesh-gateways
      kubectl get svc -n gloo-mesh-gateways
        

      Example output:

        NAME                                    READY   STATUS    RESTARTS   AGE
      istio-ingressgateway-665d46686f-nhh52   1/1     Running   0          106s
      
      NAME                        TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                         AGE
      istio-ingressgateway        LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP      2m2s
        

5. To analyze your service mesh with Gloo Mesh Core, be sure to include your services in the mesh.

   • If you already deployed apps that you want to include in the mesh, you can run the following command to label the service namespace for Istio sidecar injection.

       kubectl label ns <namespace> istio-injection=enabled
       

   • If you don’t have any apps yet, you can deploy Bookinfo, the Istio sample app.
     1. Create the bookinfo namespace and label it for Istio injection so that the services become part of the service mesh.

          kubectl create ns bookinfo
        kubectl label ns bookinfo istio-injection=enabled
          

     2. Deploy the Bookinfo app.

          # deploy bookinfo application components for all versions less than v3
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app,version notin (v3)'
        # deploy an updated product page with extra container utilities such as 'curl' and 'netcat'
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/productpage-with-curl.yaml
        # deploy all bookinfo service accounts
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account'
          

     3. Verify that the Bookinfo app deployed successfully.

          kubectl get pods -n bookinfo
        kubectl get svc -n bookinfo
          

Multicluster link

In a multicluster setup, you deploy the Gloo Mesh Core control plane into a dedicated management cluster, and the Gloo data plane into one or more workload clusters that run Istio service meshes.

Install the control plane link

Deploy the Gloo Mesh Core control plane into a dedicated management cluster.

1. Create or use at least two existing Kubernetes clusters. The instructions in this guide assume one management cluster and two workload clusters. Note: The cluster name must be alphanumeric with no special characters except a hyphen (-), lowercase, and begin with a letter (not a number).

2. Set the names of your clusters from your infrastructure provider. If your clusters have different names, specify those names instead.

     export MGMT_CLUSTER=mgmt
   export REMOTE_CLUSTER1=cluster1
   export REMOTE_CLUSTER2=cluster2
     

3. Save the kubeconfig contexts for your clusters. Run kubectl config get-contexts, look for your cluster in the CLUSTER column, and get the context name in the NAME column. Note: Do not use context names with underscores. The generated certificate that connects workload clusters to the management cluster uses the context name as a SAN specification, and underscores in SAN are not FQDN compliant. You can rename a context by running kubectl config rename-context "<oldcontext>" <newcontext>.

     export MGMT_CONTEXT=<management-cluster-context>
   export REMOTE_CONTEXT1=<remote-cluster1-context>
   export REMOTE_CONTEXT2=<remote-cluster2-context>
     

4. Install Gloo Mesh Core in your management cluster. This command uses a basic profile to create a gloo-mesh namespace and install the Gloo control plane components, such as the management server and Prometheus server, in your management cluster. For more information, check out the CLI install profiles.

     meshctl install --profiles gloo-core-mgmt \
     --kubecontext $MGMT_CONTEXT \
     --set common.cluster=$MGMT_CLUSTER \
     --set licensing.glooMeshCoreLicenseKey=$GLOO_MESH_CORE_LICENSE_KEY \
     --release-name gloo-mesh-core
     

5. Verify that the control plane pods have a status of Running.

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

Install the data plane link

Register each workload cluster with the Gloo Mesh Core control plane by deploying Gloo data plane components. A deployment named gloo-mesh-agent runs the Gloo agent in each workload cluster.

1. Save the external address and port that your cloud provider assigned to the Gloo OpenTelemetry (OTel) gateway service. The OTel collector agents in each workload cluster send metrics to this address.

        export TELEMETRY_GATEWAY_IP=$(kubectl get svc -n gloo-mesh gloo-telemetry-gateway --context $MGMT_CONTEXT -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
      export TELEMETRY_GATEWAY_PORT=$(kubectl get svc -n gloo-mesh gloo-telemetry-gateway --context $MGMT_CONTEXT -o jsonpath='{.spec.ports[?(@.name=="otlp")].port}')
      export TELEMETRY_GATEWAY_ADDRESS=${TELEMETRY_GATEWAY_IP}:${TELEMETRY_GATEWAY_PORT}
      echo $TELEMETRY_GATEWAY_ADDRESS
        

        export TELEMETRY_GATEWAY_HOSTNAME=$(kubectl get svc -n gloo-mesh gloo-telemetry-gateway --context $MGMT_CONTEXT -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
      export TELEMETRY_GATEWAY_PORT=$(kubectl get svc -n gloo-mesh gloo-telemetry-gateway --context $MGMT_CONTEXT -o jsonpath='{.spec.ports[?(@.name=="otlp")].port}')
      export TELEMETRY_GATEWAY_ADDRESS=${TELEMETRY_GATEWAY_HOSTNAME}:${TELEMETRY_GATEWAY_PORT}
      echo $TELEMETRY_GATEWAY_ADDRESS
        

2. Register both workload clusters with the management server. These commands use a basic profile to create a gloo-mesh namespace and install the Gloo data plane components, such as the Gloo agent. For more information, check out the CLI install profiles.

     meshctl cluster register $REMOTE_CLUSTER1 \
     --kubecontext $MGMT_CONTEXT \
     --profiles gloo-core-agent \
     --remote-context $REMOTE_CONTEXT1 \
     --telemetry-server-address $TELEMETRY_GATEWAY_ADDRESS \
     --release-name gloo-mesh-core
   
   meshctl cluster register $REMOTE_CLUSTER2 \
     --kubecontext $MGMT_CONTEXT \
     --profiles gloo-core-agent \
     --remote-context $REMOTE_CONTEXT2 \
     --telemetry-server-address $TELEMETRY_GATEWAY_ADDRESS \
     --release-name gloo-mesh-core
     

3. Verify that the Gloo data plane components are healthy.

     meshctl check --kubecontext $REMOTE_CONTEXT1
   meshctl check --kubecontext $REMOTE_CONTEXT2
     

4. Verify that your multicluster Gloo Mesh Core setup installed correctly. Note that this check might take a few seconds to verify that:

   • Your Gloo Mesh Core product license is valid and current.
   • The Gloo CRDs installed at the correct version.
   • The Gloo pods are running and healthy.
   • The Gloo agent is running and connected to the management server.

     meshctl check --kubecontext $MGMT_CONTEXT
     

5. Check whether Istio control planes already exist in the workload clusters.

     kubectl get pods -n istio-system --context $REMOTE_CONTEXT1
   kubectl get pods -n istio-system --context $REMOTE_CONTEXT2
     

   If istiod pods exist in each workload cluster, such as in this example output, you already installed Istio control planes. Continue to the next step.

     NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-19-3-b65676555-g2vmr   1/1     Running   0          8d
   NAME                            READY   STATUS    RESTARTS   AGE
   istiod-1-19-3-7b96cb895-4nzv9   1/1     Running   0          8d
     

   If no istiod pods exist, you can use Gloo Mesh Core to quickly install and manage service meshes in each workload cluster for you. For more information about service mesh lifecycle management with Gloo, check out Service mesh lifecycle and Solo Istio images.

   1. Apply an IstioLifecycleManager custom resource in your management cluster, which Gloo translates into the istiod control plane.

        kubectl apply --context $MGMT_CONTEXT -f- <<EOF
      apiVersion: admin.gloo.solo.io/v2
      kind: IstioLifecycleManager
      metadata:
        name: istiod-control-plane
        namespace: gloo-mesh
      spec:
        installations:
        - clusters:
          - defaultRevision: true
            name: $REMOTE_CLUSTER1
          - defaultRevision: true
            name: $REMOTE_CLUSTER2
          istioOperatorSpec:
            components:
              pilot:
                k8s:
                  env:
                  - name: PILOT_SKIP_VALIDATE_TRUST_DOMAIN
                    value: "true"
            meshConfig:
              accessLogFile: /dev/stdout
              defaultConfig:
                holdApplicationUntilProxyStarts: true
                proxyMetadata:
                  ISTIO_META_DNS_CAPTURE: "true"
              outboundTrafficPolicy:
                mode: ALLOW_ANY
            namespace: istio-system
            profile: minimal
          revision: auto
      EOF
        

   2. In each workload cluster, verify that the Istio pods have a status of Running.

        kubectl get pods -n istio-system --context $REMOTE_CONTEXT1
      kubectl get pods -n istio-system --context $REMOTE_CONTEXT2
        

      Example output:

        NAME                            READY   STATUS    RESTARTS   AGE
      istiod-1-19-3-b65676555-g2vmr   1/1     Running   0          57s
      NAME                            READY   STATUS    RESTARTS   AGE
      istiod-1-19-3-7b96cb895-4nzv9   1/1     Running   0          48s
        

   3. Optional: To deploy ingress gateways to each workload cluster, apply a GatewayLifecycleManager custom resource to the management cluster.

        kubectl apply --context $MGMT_CONTEXT -f- <<EOF
      apiVersion: admin.gloo.solo.io/v2
      kind: GatewayLifecycleManager
      metadata:
        name: istio-ingressgateway
        namespace: gloo-mesh
      spec:
        installations:
        - clusters:
          - activeGateway: true
            name: $REMOTE_CLUSTER1
          - activeGateway: true
            name: $REMOTE_CLUSTER2
          gatewayRevision: auto
          istioOperatorSpec:
            components:
              ingressGateways:
              - enabled: true
                k8s:
                  service:
                    ports:
                    # For AWS ELBs, must be listed as the first port
                    - name: status-port
                      port: 15021
                      targetPort: 15021
                    - name: http2
                      port: 80
                      targetPort: 8080
                    - name: https
                      port: 443
                      targetPort: 8443
                    - name: tls
                      port: 15443
                      targetPort: 15443
                    selector:
                      istio: ingressgateway
                    type: LoadBalancer
                label:
                  app: istio-ingressgateway
                  istio: ingressgateway
                name: istio-ingressgateway
                namespace: gloo-mesh-gateways
            profile: empty
      EOF
        

   4. In each workload cluster, verify that the ingress gateway pods are running.

        kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
      kubectl get pods -n gloo-mesh-gateways --context $REMOTE_CONTEXT2
        

      Example output for one cluster:

        NAME                                    READY   STATUS    RESTARTS   AGE
      istio-ingressgateway-665d46686f-nhh52   1/1     Running   0          106s
        

   5. In each workload cluster, verify that the load balancer service has an external address.

        kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT1
      kubectl get svc -n gloo-mesh-gateways --context $REMOTE_CONTEXT2
        

      Example output for one cluster:

        NAME                        TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)                                                                                                      AGE
      istio-ingressgateway        LoadBalancer   10.96.252.49    <externalip>  15021:32378/TCP,80:30315/TCP,443:32186/TCP,31400:30313/TCP,15443:31632/TCP                                   2m2s
        

6. To analyze your service mesh with Gloo Mesh Core, be sure to include your services in the mesh.

   • If you already deployed apps that you want to include in the mesh, you can run the following command to label the service namespaces for Istio sidecar injection.

       kubectl label ns <namespace> istio-injection=enabled --context $REMOTE_CONTEXT1
       

   • If you don’t have any apps yet, you can deploy Bookinfo, the Istio sample app.

     1. Create the bookinfo namespace in each cluster, and label the workload cluster namespaces for Istio injection so that the services become part of the service mesh.

          kubectl create ns bookinfo --context $REMOTE_CONTEXT1
        kubectl label ns bookinfo istio.io/rev=$REVISION --overwrite=true --context $REMOTE_CONTEXT1
        
        kubectl create ns bookinfo --context $REMOTE_CONTEXT2
        kubectl label ns bookinfo istio.io/rev=$REVISION --overwrite=true --context $REMOTE_CONTEXT2
          

     2. Deploy Bookinfo with the details, productpage, ratings, reviews-v1, and reviews-v2 services in cluster1.

          # deploy bookinfo application components for all versions less than v3
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app,version notin (v3)' --context $REMOTE_CONTEXT1
        # deploy an updated product page with extra container utilities such as 'curl' and 'netcat'
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/solo-io/gloo-mesh-use-cases/main/policy-demo/productpage-with-curl.yaml
        # deploy all bookinfo service accounts --context $REMOTE_CONTEXT1
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account' --context $REMOTE_CONTEXT1
          

     3. Deploy Bookinfo with the ratings and reviews-v3 services in cluster2.

          # deploy reviews and ratings services
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'service in (reviews)' --context $REMOTE_CONTEXT2
        # deploy reviews-v3
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app in (reviews),version in (v3)' --context $REMOTE_CONTEXT2
        # deploy ratings
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'app in (ratings)' --context $REMOTE_CONTEXT2
        # deploy reviews and ratings service accounts
        kubectl -n bookinfo apply -f https://raw.githubusercontent.com/istio/istio/1.19.3/samples/bookinfo/platform/kube/bookinfo.yaml -l 'account in (reviews, ratings)' --context $REMOTE_CONTEXT2
          

     4. Verify that the Bookinfo app deployed successfully.

          kubectl get pods -n bookinfo --context $REMOTE_CONTEXT1
        kubectl get pods -n bookinfo --context $REMOTE_CONTEXT2
          

Explore the UI link

Use the Gloo UI to evaluate the health and efficiency of your service mesh. You can review the analysis and insights for your service mesh, such as recommendations to harden your Istio environment and steps to implement them in your environment.

Launch the dashboard link

1. Open the Gloo UI. The Gloo UI is served from the gloo-mesh-ui service on port 8090. You can connect by using the meshctl or kubectl CLIs.

   • meshctl: For more information, see the CLI documentation.

       meshctl dashboard
       

   • kubectl:
     1. Port-forward the gloo-mesh-ui service on 8090.

          kubectl port-forward -n gloo-mesh svc/gloo-mesh-ui 8090:8090
          

     2. Open your browser and connect to http://localhost:8090.

2. Review your Dashboard for an at-a-glance overview of your Istio service mesh. Service mesh insights, health, status, inventories, security, and more are summarized in the following cards:

   • Analysis and Insights: Gloo Mesh Core recommendations for how to improve your service mesh setup, which you check out in the next step.
   • Gloo and Istio health: A status check of the Gloo Mesh Core and Istio installations in your clusters.
   • Certificates Expiry: Validity timelines for your root and intermediate Istio certificates.
   • Cluster Services: Inventory of services across all clusters in your Gloo Mesh Core setup, and whether those services are in-mesh or not.
   • Istio FIPS: FIPS compliance checks for the istiod control plane and Istio data plane workloads.
   • Zero Trust: Number of service mesh workloads that receive only mutual TLS (mTLS)-encrypted traffic, and number of external services that are accessed from the mesh.

Check Istio insights link

Review your Istio insights. Gloo Mesh Core comes with an insights engine that automatically analyzes your Istio setup for health issues. Then, Gloo shares these issues along with recommendations to harden your Istio setup. The insights give you a checklist to address issues that might otherwise be hard to detect across your environment.

1. On the Analysis and Insights card of the dashboard, you can quickly see a summary of the insights for your environment, including how many insights are available at each severity level, and what type of insights are available.
   

2. View the list of insights by clicking the Details button, or go to the Insights page.

3. On the Insights page, you can view recommendations to harden your Istio setup and steps to implement them in your environment. Gloo Mesh Core analyzes your Istio service meshes, and returns individual insights that contain information about errors and warnings in your environment, best practices you can use to improve your configuration and security, and more.
   
   

4. On an insight that you want to resolve, click Details. The details modal shows more data about the insight, such as the time when it was last observed in your environment, and if applicable, the extended settings or configuration that the insight applies to.
   

5. Click the Target YAML tab to see the resource file that the insight references, and click the View Resolution Steps tab to see guidance such as steps for fixing warnings and errors in your resource configuration or recommendations for improving your security and setup.

Next steps link

Now that you have Gloo Mesh Core up and running, check out the following guides to expand your service mesh capabilities.

• Continue exploring insights to review your Istio health and security posture.
• Find out more about hardened Istio n-4 version support built into Solo Istio images.
• Use Gloo Mesh Core to quickly install and manage your service mesh for you with service mesh lifecycle management.
• Monitor and observe your Istio environment with Gloo Mesh Core’s built-in telemetry tools.
• Customize your Gloo Mesh Core installation with a Helm-based setup.
• When it’s time to upgrade Gloo Mesh Core, see the upgrade guide.

Cleanup link

If you no longer need this quick-start Gloo Mesh Core environment, you can uninstall the Gloo management and agent components, and any Gloo-managed Istio resources, by following the steps in the uninstall guide.