The Gloo Mesh API helps you set up and manage an Istio service mesh in a single or many Kubernetes clusters.

Core concepts

Before diving into how the Gloo API is organized and designed, flip through the following core concepts.

API groups

The v2 API is organized into groups. Review the following table and diagram for a brief overview of the groups of APIs.

API groupAPI endpointDescription these APIs to configure how your team uses the service mesh across clusters. For example, use workspaces as team boundaries across Kubernetes clusters and namespaces. Decide which workspaces can import and reuse resources from other workspaces. Set up the ability to deploy extra servers for rate limiting or external auth. Then, you can delegate administration so that each team only accesses what they need to.
API managementapimanagement.gloo.solo.ioUse the API management group to manage configuration for your own APIs, such as through the GraphQL or Gloo Portal integrations in Gloo Mesh Gateway. For example, you can create an API doc resource to define your API schema. Then, you might create a GraphQL resolver map to define your GraphQL resolver servers, or create a portal resource to define a developer portal. the infrastructure APIs to configure interaction between resources in your Gloo setup and resources in your cloud infrastructure provider. For example, you can create a cloud provider custom resource to define the AWS region, account, and IAM roles that you want Gloo Mesh Gateway to use to access AWS Lambda functions. the networking APIs to set up connectivity across services. For example, you can create virtual gateways that use route tables with the host domains of your services. You can even route to services outside a Kubernetes cluster with external destinations. For example, you might have an app in a bare metal or virtual machine. Your networking resources reside in your workspaces for more control over your services.
Policy* policies to routes or destinations within your workspace for more granular control. The policies help you control resilience, security, observability, traffic, and more. Any service in the workspace can reuse the policies you want. You can even export policies to other workspaces, making policies consistent across teams.
Other,, and moreOther Gloo API groups are defined only for internal use or for building components of the main API groups. These other API groups do not define Gloo custom resources that you can create.

Using the Gloo API

  1. Install Gloo Mesh Enterprise in each management and workload cluster.
  2. Review the API groups of objects that you can create with API v2.
  3. When you create the custom resources, make sure to specify the API v2 endpoint in the configuration files. For example, you can create a global workspace with the following configuration.
    kind: Workspace
      annotations: ""
      name: anything
      namespace: gloo-mesh
      - name: '*'
        - name: '*'
  4. Develop a labeling strategy for your resources. The Gloo API relies on selectors to choose objects. For example, labels select the policies to apply to resources like virtual destinations. For more information about labels and selectors, see the Kubernetes documentation.

Creating Gloo custom resources

Review the following guidance for creating Gloo custom resources.

What Gloo resources can I create?

After installing Gloo in your cluster, you can list available custom resources with the following command.

  kubectl api-resources -o wide | grep solo

To learn more about each resource, review the API reference docs.

How do I create Gloo resources?

Create a configuration file, typically in YAML format. To help build your files, the docs provide many copiable examples. Then, review the API reference docs for more in-depth information on specific settings.

Where should I create Gloo resources?

With Gloo, you can set up multitenant workspaces that reflect how you organize your team. Very few custom resources are required to be created in particular cluster or namespace. However, you might prefer to create some custom resources together for simplicity.

Simple multicluster setup: Create all your Gloo resources in the management cluster. This way, your workload clusters are reserved for your apps, and all of the networking configuration is stored on the same management cluster. You can still set up multiple workspaces to keep each team’s configuration separate from each other.

More complex setups

Gloo provides the flexibility for you to create custom resources in workload clusters, too. This setup adds more complexity in terms of where resources live. On the other hand, you can offload the platform administrator’s work by giving each team the ability to create and manage their own resources in their own clusters.

Custom resource location requirements:

  • KubernetesCluster resources must be created in the management cluster.
  • Workspace resources must be created in the management cluster.
  • WorkspaceSettings must be created in a namespace and cluster that is part of the workspace. A workspace can only have one WorkspaceSettings.

Cluster and namespace considerations:

  • The management server and agent are expected to be created in the gloo-mesh namespace. If you want to create them in a different namespace, review their configuration for instances of gloo-mesh. For example, each agent’s relay certificate authority field authority: gloo-mesh-mgmt-server.gloo-mesh must be updated to the new namespace, authority: gloo-mesh-mgmt-server.<namespace>.
  • Resources that refer to another resource often default to assuming that the other resource is in the same namespace and cluster, such as an external auth policy that selects an external auth server or an OAuth secret. If the resources are not in the same location, make sure to update the configuration.

How can I share Gloo resources across workspaces and clusters?

To share resources, you set up importing and exporting at the workspace level. Review the following table to learn how where you create a resource restricts how you can share the resource. For more information, see Import and export resources across workspaces.

Where you want the resource availableWhere to create the resource
Only to resources in the same workspaceAny namespace in the workspace. Include a virtual destination for multicluster workspaces. Do not export the workspace to other workspaces.
Only to resources in the same workspace on the same clusterAny namespace in the cluster in the workspace. Do not include a virtual destination. Do not export the workspace to other workspaces.
To resources in other workspacesAnywhere in your workspace. Make sure that your workspace exports to the other workspaces. The other workspaces also must import your workspace. Consider adding labels to share workspace resources more scalably.

How can I apply policies to my app network traffic?

Policies might apply to the following resources:

  • Destinations: Destinations determine where incoming requests are routed to. A destination can be a Kubernetes Service, a Gloo VirtualDestination in a multicluster setup, or a Gloo ExternalService custom resource that you use to reach endpoints that are outside your service mesh.
  • Listeners: Listeners are the virtual gateways and ports that a gateway workload listens for incoming traffic on. You must apply a listener policy to a Gloo VirtualGateway custom resource, not the gateway workload directly.
  • Route: Routes define how to match an incoming request, and what actions you want to perform on a matched request. For example, you can decide to forward the request to a destination in the service mesh, directly respond to the request without forwarding, or manipulate and redirect requests. Routes are defined in a Gloo RouteTable custom resource.
  • Workloads: A workload represents the app that responds to incoming request. For example, you can have Kubernetes workloads such as Deployments or StatefulSets. Or, you can use an Istio WorkloadEntry that might run in a bare metal or virtual machine outside your Kubernetes cluster.

You can apply the policies by using Kubernetes labels and selectors that match the route table, virtual destination, or workload. Remember, all of these resources must be in the same workspace for the policy to apply the resource. To see what resources a policy might select, check the Kubernetes labels such as with the following commands.

  kubectl get <KIND> <RESOURCE> -n <NAMESPACE> -l <KEY=VALUE>
kubectl get all -A -l env=prod

Some policies support selecting multiple kinds of resources, such as both destinations and routes. When you have multiple selectors, you might wonder how the selectors impact each other. For more information, refer to each policy guide:

Custom resource translation

After installing and registering clusters with Gloo, certain Kubernetes and Istio resources are automatically discovered and translated as custom resources in Gloo. Going forward, you can configure Gloo custom resources to automatically create the Istio resources that are needed to manage your Gloo environment.

Translated resources follow a naming convention of <first-31-chars>-<32-char-hash-of-full-string> and are 63 characters or less. This convention is used because Kubernetes labels can only be up to 63 characters long, and translated names are sometimes used in labels.

The Gloo Mesh API simplifies the complexity of your service mesh by installing custom resource definitions (CRDs) that you configure. Then, Gloo Mesh translates these CRDs into Istio resources across your environment, and provides visibility across all of the resources and traffic. Enterprise features include multitenancy, global failover and routing, observability, and east-west rate limiting and policy enforcement through authorization and authentication plug-ins.

Using the Gloo Mesh API helps you simplify your networking setup because you can write advanced configurations one time and apply the same configuration in multiple places and different contexts. For example, you can write a rate limit or authentication policy once. Then, you can apply this policy both to traffic that enters the cluster via Gloo Mesh Gateway (north-south), as well as to traffic across clusters via the Istio service mesh gateway (east-west).

The following figure outlines how Gloo custom resources are translated into Istio resources.

Figure: Gloo custom resource translation.
Figure: Gloo custom resource translation.

Next Steps

With a firm grounding in the core API concepts, you’re ready to learn more about Gloo Mesh Enterprise’s architecture or dive into the Get Started guide.