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 themetadata.labels
section of theKubernetesCluster
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 theCLUSTER
column, and get the context name in theNAME
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.- All clusters and namespaces
- All team namespaces in regional clusters
- Different namespaces in different clusters
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 thoseregion: 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
andcluster-2
. - Namespaces: In
cluster-1
, only namespaces that begin withbackend1
are included. Incluster-2
, only namespaces that begin withbackend2
are included. - Importing or exporting: The workspace includes the
gloo.solo.io/exportToGateway: tier1
andteam: backend
labels. Other workspaces can use either label for thisbackend
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 resourceglobal
. Keep in mind that each workspace still needs its own unique workspace settings resource, which your app owner configures in the next section.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.
-
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 namedbackend-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.
- 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
-
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 prefixgateway
in the name. - Import: This workspace imports resources from other workspaces with either a
team: backend
label or with the namebackend
. - 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 aweb
namespace to other workspaces with theteam: gateway
label. - Import: This workspace imports any resource with an
app: recs
label from workspaces with ateam: 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 thebookinfo
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
:- Port-forward the
gloo-mesh-ui
service on 8090.kubectl port-forward -n gloo-mesh svc/gloo-mesh-ui 8090:8090 --context ${MGMT_CONTEXT}
- Open your browser and connect to http://localhost:8090.
- Port-forward the
-
Check your workspace import and export settings.
- 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. - 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.
- From the Overview tab, expand your workspaces to see an overview of the import and export settings, such as in the following figure.
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.