Navigation :

Organize team resources with workspaces

In v2 of the Gloo Mesh API, Gloo Mesh introduces a new concept, the Workspace custom resource. A workspace consists of one or more Kubernetes namespaces that are in one or more clusters. Think of a workspace as the boundary of your team's resources. To get started, create a workspace for each of your teams. Your teams might start with their apps in a couple Kubernetes namespaces in a single cluster. As your teams scale across namespaces and clusters, their workspaces scale with them. For more information, see the Workspaces concept.

Before you begin

Install Gloo Mesh Enterprise in your management cluster.
Register each workload cluster that you want to add to the workspace. As part of the registration, you create KubernetesCluster resources in your management cluster.
Make sure to use labels in the metadata.labels section of the KubernetesCluster resource. Your workspace uses these labels to decide which clusters are part of the workspace. Gloo Mesh even detects when you register more clusters with the same label down the road, and adds them to the workspace!

Set the names of your clusters from your infrastructure provider.

export MGMT_CLUSTER=<management_cluster_name>
export REMOTE_CLUSTER=<remote_cluster_name>

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.
```
export MGMT_CONTEXT=<management-cluster-context>
export REMOTE_CONTEXT=<remote-cluster-context>
```
If you are new to workspaces, review the following resources to understand more about the concepts.
- Workspaces concept, including how workspaces function as resource boundaries and a person-driven setup flow.
- API reference

Create a workspace

As a platform administrator, you can create a workspace for each of your teams.

Pick a name for the workspace. This name might be the same as your team's name, such as frontend, and must be unique.
Come up with a label for your workspace. Later, other workspaces can use this label to import or export to your workspace. You might want to set up a naming convention for all of your workspaces. For example, you might use gloo.solo.io/global for workspaces that are available to any other workspace.
Decide which clusters you want the workspace to include. A workspace can have many clusters. Also, the same cluster might belong to several workspaces. Instead of selecting individual clusters by name, use labels. Labels allow you to treat clusters “like cattle.” Gloo Mesh adds or removes clusters with the same label to your workspace. Workspace labels must match the KubernetesCluster labels on the management cluster. You can check those labels with the following command.
```
kubectl get kubernetescluster -n gloo-mesh --context $MGMT_CONTEXT -o=jsonpath="{.items[*]['metadata.name', 'metadata.labels']}"
```
Decide which Kubernetes namespaces across clusters you want the workspace to include. Often, these namespaces include a similar prefix that matches your team, such as frontend-*. Unlike a cluster, a namespace can belong to only one workspace. To list existing namespaces, you can use the following command.
```
kubectl get ns --context $MGMT_CONTEXT && kubectl get ns --context $REMOTE_CONTEXT
```
Create the workspace with the information that you just gathered. Note that you must create the workspace resource in the gloo-mesh namespace of the management cluster. You can review the following YAML examples.
The following example creates the web workspace.
- Clusters: The workspace includes all workload clusters by using a regex to match all clusters names.
- Namespaces: The workspace includes all namespaces in all workload clusters.
- Importing or exporting: The workspace is not labelled. Other workspaces can use to set up importing and exporting by referring to the web workspace by name.
```
kubectl apply --context $MGMT_CONTEXT -n gloo-mesh -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: Workspace
metadata:
  name: web
  namespace: gloo-mesh
spec:
  workloadClusters:
  - name: '*'
    namespaces:
    - name: '*'
EOF
```
The following example creates the web workspace.
- Clusters: The workspace includes only workload clusters with the region: us-east label.
- Namespaces: Only namespaces that are named web in those region: us-east clusters are included in the workspace.
- Importing or exporting: The workspace includes the gloo.solo.io/global: 'true' label that other workspaces can use to set up importing and exporting.
```
kubectl apply --context $MGMT_CONTEXT -n gloo-mesh -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: Workspace
metadata:
  name: web
  namespace: gloo-mesh
  labels:
    gloo.solo.io/global: 'true'
spec:
  workloadClusters:
    - selector:
        region: us-east
      namespaces:
        - name: web
EOF
```
The following example creates the backend workspace.
- Clusters: The workspace includes only cluster-1 and cluster-2.
- Namespaces: In cluster-1, only namespaces that begin with backend1 are included. In cluster-2, only namespaces that begin with backend2 are included.
- Importing or exporting: The workspace includes the gloo.solo.io/exportToGateway: tier1 and team: backend labels. Other workspaces can use either label for this backend workspace to set up importing and exporting.
```
kubectl apply --context $MGMT_CONTEXT -n gloo-mesh -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: Workspace
metadata:
  name: backend
  namespace: gloo-mesh
  labels:
    gloo.solo.io/exportToGateway: tier1
    team: backend
spec:
  workloadClusters:
    - name: cluster-1
      namespaces:
        - name: backend1*
    - name: cluster-2
      namespaces:
        - name: backend2*
EOF
```
Optionally, you can configure global workspace settings. These settings apply by default to each workspace in your Gloo Mesh environment. Later, the app owner for each workspace can override the defaults in their own workspace settings.
You must create the global workspace settings resource in the gloo-mesh namespace of the management cluster, and name the resource global. Keep in mind that each workspace still needs its own unique workspace settings resource, which your app owner configures in the next section.
- Disable service isolation and federation
- Enable service isolation and federation
The following example disables service isolation and federation. This can help developers and operators when they first transition their apps into workspaces.
- Disabled service isolation: Services both within and outside the mesh, as well as across workspaces, can communicate with each other by default. This way, if one team's app relies on a service in another team's workspace, the app continues to work as the teams set up their workspace boundaries.
- Disabled federation: Services in different clusters cannot communicate with each other by default. You might enable this globally if your team uses a single-cluster environment. Your team can check that their apps work in a single cluster before moving to a multicluster environment.
```
kubectl apply --context $MGMT_CONTEXT -n gloo-mesh -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
 name: global
 namespace: gloo-mesh
spec:
 options:
   serviceIsolation:
     enabled: false
   federation:
     enabled: false
EOF
```
The following example enables service isolation and federation.
- Enabled service isolation: Services are isolated and cannot communicate with services outside the mesh or in another workspace by default. mTLS is used for communication across services. Teams must set up their workspaces to import and export the services that they need. You can enable service isolation if you need to enforce a zero trust model from the start. Note: Service isolation is enabled or disabled at the workspace level. To isolate services within the workspace, use access policies.
- Enabled federation: Services in different clusters can communicate with each other. Gloo Mesh generates a virtual destination with the hostname for each selected service. Then, routes in a route table can forward traffic across clusters. You can optionally set a suffix for the hostnames. The hostname is in the format {{ service name }}.{{ service namespace }}.{{ service cluster }}.{{ host suffix }}. Enable federation when your workspaces span multiple clusters.
```
kubectl apply --context $MGMT_CONTEXT -n gloo-mesh -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
 name: global
 namespace: gloo-mesh
spec:
 options:
   serviceIsolation:
     enabled: true
   federation:
     enabled: true
     hostSuffix: gloo.test.io
EOF
```
Give the app owner for the team the workspace details, or viewer permission for the resource in the management cluster.

Configure workspace settings

As an app owner for your team, you configure the workspace that your platform administrator set up for you by creating a WorkspaceSettings resource.

Each workspace must have only one of its own workspace settings resource. You still need one workspace settings per workspace even if your platform admin set up global settings.

Decide which workload cluster and Kubernetes namespace you want to create the workspace settings in. Check with your platform admin to see which clusters and namespaces are included in your workspace. Or, if you have access to the management cluster, run the following command.
```
kubectl get workspaces -n gloo-mesh --context $MGMT_CONTEXT -o=jsonpath='{.items[*].spec.workloadClusters}'
```
Make sure that the $REMOTE_CONTEXT variable is set to the cluster that you want to use.
```
export REMOTE_CONTEXT=<root-cluster-context>
```
Verify that the namespace that you want to use exists in the cluster.
```
kubectl get ns --context $REMOTE_CONTEXT
```
If not, create the namespace. For example, if your workspace automatically includes any namespace that begins with backend-*, you might create a namespace named backend-settings.
```
kubectl create ns --context $REMOTE_CONTEXT backend-settings
```
Set the namespace as an environment variable.
```
export WS_NAMESPACE=<namespace>
```
Decide which workspaces you want to export your resources to. Get their labels from the platform admin or the other team's app owners.
Decide which workspaces you want to import resources from. Get their labels from the platform admin or the other team's app owners.
Decide if you want to restrict importing or exporting to certain resources, such as Kubernetes services.
Decide if you want to set up service isolation for your workspace.
- Enable service isolation: Services are isolated and cannot communicate with services outside the mesh or in another workspace by default. mTLS is used for communication across services. Teams must set up their workspaces to import and export the services that they need. You can enable service isolation if you need to enforce a zero trust model from the start. Note: Service isolation is enabled or disabled at the workspace level. To isolate services within the workspace, use access policies.
- Disable service isolation: Services both within and outside the mesh, as well as across workspaces, can communicate with each other by default. This way, if one team's app relies on a service in another team's workspace, the app continues to work as the teams set up their workspace boundaries.
Decide if you want to set up federation for your workspace.
- Enable federation: Services in different clusters can communicate with each other. Gloo Mesh generates a virtual destination with the hostname for each selected service. Then, routes in a route table can forward traffic across clusters. You can optionally set a suffix for the hostnames. The hostname is in the format {{ service name }}.{{ service namespace }}.{{ service cluster }}.{{ host suffix }}. Enable federation when your workspaces span multiple clusters.
- Disable federation: Services in different clusters cannot communicate with each other by default. You might enable this globally if your team uses a single-cluster environment. Your team can check that their apps work in a single cluster before moving to a multicluster environment.
Optional: Select the gateway to use for east-west traffic across clusters in the service mesh. If you enable federation for your workspace, virtual destinations are automatically created for your services. To route traffic to a service that backs the virtual destination in another cluster, Gloo Mesh uses the east-west gateway that you select in the workspace settings. You can even select different gateways for different hostnames.

Create the workspace settings with the information that you just gathered, in the cluster and namespace that you want. You can review the following YAML examples.

Export by label
Import by name
Import and export by label and name
Export and import select services
Federate and select gateway

The following example configures the settings for a backend workspace.

Export: This workspace exports to any other workspaces with the label team: web.
Import: This workspace does not import from any other workspace.
Federation: Federation is enabled for services that run in the backend namespace across clusters.
Service isolation: Service isolation is enabled, to enforce mTLS connections from services outside the mesh or workspace.

kubectl apply --context ${REMOTE_CONTEXT} -n ${WS_NAMESPACE} -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: default
  namespace: backend-settings
spec:
  exportTo:
  - workspaces:
    - selector:
        team: web
  options:
    federation:
      enabled: true
      hostSuffix: gloo.test.io
      serviceSelector:
      - namespace: backend
    serviceIsolation:
     enabled: true
EOF

The following example configures the settings for a web workspace.

Export: This workspace does not export to other workspaces.
Import: This workspace imports from only the backend workspace.
Federation: Federation is enabled for services that run in the web namespace across clusters.
Service isolation: Service isolation is enabled, to enforce mTLS connections from services outside the mesh or workspace.

kubectl apply --context ${REMOTE_CONTEXT} -n ${WS_NAMESPACE} -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: default
  namespace: web-settings
spec:
  importFrom:
  - workspaces:
    - name: backend
  options:
    federation:
      enabled: true
      hostSuffix: gloo.test.io
      serviceSelector:
      - namespace: web
    serviceIsolation:
     enabled: true
EOF

The following example configures the settings for a web workspace.

Export: This workspace exports to other workspaces with both a team: gateway label and with the prefix gateway in the name.
Import: This workspace imports resources from other workspaces with either a team: backend label or with the name backend.
Federation: Federation is disabled, because the gateway runs in a single cluster environment.
Service isolation: Service isolation is disabled, to allow traffic routing to services in other workspaces.

kubectl apply --context ${REMOTE_CONTEXT} -n ${WS_NAMESPACE} -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: default
  namespace: web-settings
spec:
  exportTo:
  - workspaces:
    - selector:
        team: gateway    
    - name: gateway*
  importFrom:
  - workspaces:
    - selector:
        team: backend    
    - name: backend
  options:
    federation:
      enabled: false
    serviceIsolation:
     enabled: true
EOF

The following example configures the settings for a web workspace.

Export: This workspace exports only Kubernetes services with the label app: web in a web namespace to other workspaces with the team: gateway label.
Import: This workspace imports any resource with an app: recs label from workspaces with a team: backend label.

kubectl apply --context ${REMOTE_CONTEXT} -n ${WS_NAMESPACE} -f- <<EOF
apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: default
  namespace: web-settings
spec:
  exportTo:
  - workspaces:
    - selector:
        team: gateway    
    resources:
    - kind: SERVICE
    - namespace: web
    - labels: 
        app: web
  importFrom:
  - workspaces:
    - selector:
        team: backend    
    resources:
    - labels:
        app: recs
  options:
    federation:
      enabled: false
    serviceIsolation:
     enabled: true
EOF

The following example configures the settings for a federated-anything workspace.

Export and import: Exporting and importing are not configured, so no resources can be shared across workspaces.
Federation: Federation is enabled for the gloo.test.io hostname, backed by services in the bookinfo namespace.
Gateway: The workspace uses all gateways with the istio: eastwestgateway label for federated traffic.

apiVersion: admin.gloo.solo.io/v2
kind: WorkspaceSettings
metadata:
  name: federated-anything
  namespace: bookinfo
spec:
  options:
    eastWestGateways:
    - selector:
        labels:
          istio: eastwestgateway
    federation:
      enabled: true
      hostSuffix: gloo.test.io
      serviceSelector:
      - namespace: bookinfo

Verify your workspace setup

To verify your workspace setup, you can try to import and export Gloo Mesh resources. To do so, you need access to at least two different workspaces that are set up to import and export to each other. You might have this access yourself, or work with another team's app owner to verify.

In your workspace settings, make sure that you export to and import the other workspace, such as in the following example.

kubectl get workspacesettings default -n ${WS_NAMESPACE} --context ${REMOTE_CONTEXT} -o=jsonpath='{.spec}'

Example output:

{"exportTo":[{"selector":{"team":"backend"}}, "imports":[{"selector":{"team":"frontend"}}}

Repeat the previous step for the other workspace. Make sure to use the right ${WS_NAMESPACE} and ${REMOTE_CONTEXT} values for that workspace.

Create a Gloo Mesh resource to export. Make sure that your workspace settings export the resource, and that the workspace settings of the other workspace import the resource, such as via a label. The following example is for a virtual destination.

kubectl apply --context ${REMOTE_CONTEXT} -n ${WS_NAMESPACE} -f - << EOF
apiVersion: networking.gloo.solo.io/v2
kind: VirtualDestination
metadata:
  name: test-details
  namespace: ${WS_NAMESPACE}
  labels:
     export: true
spec:
  hosts:
  - reviews.global
  ports:
  - name: http
    number: 9080
    protocol: HTTP
  services:
  - labels:
      app: reviews
EOF

Open the Gloo Mesh UI.
- meshctl: For more information, see the CLI documentation.
```
meshctl dashboard --context ${MGMT_CONTEXT}
```
- kubectl:
  1. Port-forward the gloo-mesh-ui service on 8090.
```
kubectl port-forward -n gloo-mesh svc/gloo-mesh-ui 8090:8090 --context ${MGMT_CONTEXT}
```
  2. Open your browser and connect to http://localhost:8090.
Check your workspace import and export settings.
1. From the Overview tab, expand your workspaces to see an overview of the import and export settings, such as in the following figure.
  
  Figure of workspaces overview in the Gloo Mesh UI. Note the **Imports / Exports** section.
2. Click MORE DETAILS and review the Workspace Dependencies and the tabbed section of Destination, Routing, and Policies.
  
  Figure of workspaces detail in the Gloo Mesh UI. Note that you can review available resources to import.

What's next?

Now that you set up your workspaces, your teams can deploy their apps. Tell them the clusters and namespaces that are part of their workspaces. They can create their Kubernetes deployments and services. Istio automatically adds the services to the mesh.

As part of your team setup, you might want to set up role-based access control (RBAC) for your Kubernetes and Gloo Mesh resources.

Then, you can create Gloo Mesh resources to manage traffic to the services. For example, you might set up the following resources.

Networking resources, such as virtual gateways.
Policies, such as retries or timeouts, that can be reused across routes and destinations.