Labels & Filter Queries

This guide provides a comprehensive reference for SPOG's label system and GlassQL filter query language. Labels are the foundation of cluster organization, and filters enable you to select, group, and display clusters based on their labels.

What You'll Learn

• How the label system works and how labels flow through SPOG
• Best practices for designing label taxonomies
• How to apply labels to clusters via Helm configuration
• The complete GlassQL filter query syntax with all operators
• Hands-on exercises using the quickstart deployment

The Label System

What Are Labels?

Labels are key-value pairs attached to clusters that describe their identity and organizational role. In SPOG, labels enable:

• Multi-dimensional organization: Categorize clusters by region, environment, team, tier, or any custom dimension
• Flexible filtering: Select clusters based on any combination of label values
• Authorization boundaries: Grant access based on label matching (covered in the authorization guide)
• Dynamic permissions: Combine with route parameters to create team-based dashboards that automatically filter by label values (see Dynamic Permission Arguments)
• Custom taxonomies: Define labels that match your specific organizational structure

Label Syntax

Labels are specified in YAML as key-value pairs. Values can be a single string or an array of strings:

1
2
3
4
5
6

labels:
  region: "us-east"           # Single value
  environment: "production"   # Single value
  team:                        # Multiple values (cluster managed by multiple teams)
    - "platform"
    - "security"

Reserved Label Keys

The following keywords are reserved and should not be used as label keys:

Using these as label keys will generate runtime warnings and may cause unexpected behavior when filtering. For example, if you had a label and: "value", the query and = "value" would be ambiguous to the parser.

Multi-Valued Labels

Some organizational scenarios require a cluster to belong to multiple values for a single dimension. For example:

• A cluster managed by multiple teams
• A cluster serving multiple customers
• A cluster spanning multiple availability zones

When filtering, multi-valued labels match if any of the values match the filter condition. For example, team = "security" will match a cluster with team: ["platform", "security"].

How Labels Flow Through SPOG

Labels propagate through the system in the following way:

1. Cluster Definition: Labels are defined in the Glass Instrumentation Helm values
2. NATS Discovery: Clusters announce themselves with their labels to the control plane
3. Backend Registry: The middleware service maintains a registry of all clusters and their labels
4. Frontend Store: The UI fetches cluster data including labels for display and filtering
5. Filter Evaluation: GlassQL queries match clusters based on their label values

Label Design Principles

Follow these principles when designing your label taxonomy:

1. Keep Labels Simple and Consistent

Use the same label keys across all clusters. This enables reliable filtering and grouping.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Good: Consistent labels across clusters
labels:
  region: "us-east"
  environment: "production"
  team: "platform"

# Avoid: Inconsistent naming
labels:
  reg: "us-east"      # Abbreviated
  env: "prod"         # Abbreviated
  department: "plat"  # Different key name

2. Use Meaningful, Human-Readable Values

Label values appear in the UI and filter autocomplete. Make them descriptive.

1
2
3
4
5
6
7
8
9

# Good: Clear, readable values
labels:
  environment: "production"
  tier: "critical"

# Avoid: Cryptic abbreviations
labels:
  environment: "prd"
  tier: "t1"

3. Limit to 5-7 Dimensions

Too many labels create confusion. Focus on the dimensions that matter for filtering and access control.

4. Plan for Growth

Consider how your organization might evolve. Will you add new regions? New teams? Design labels that can accommodate growth.

5. Document Your Taxonomy

Maintain a reference document that defines each label key, its allowed values, and when to use each value.

Design Patterns

Single-Dimension Organization

Organize clusters by a single primary dimension, typically region or team:

1
2
3
4
5
6
7

# Region-based organization
labels:
  region: "us-east"

# Team-based organization
labels:
  team: "platform"

Use when: You have a simple infrastructure with one clear organizational axis.

Multi-Dimensional Hierarchy

Combine multiple dimensions for richer organization:

1
2
3
4
5

labels:
  region: "us-east"
  environment: "production"
  team: "platform"
  tier: "critical"

Use when: You need to filter by multiple criteria (e.g., "all production clusters in US regions owned by the platform team").

Team-Based Isolation

Organize clusters by team ownership with environment sub-classification:

1
2
3
4
5
6
7
8
9

# DevOps team production cluster
labels:
  team: "devops"
  environment: "production"

# Platform team staging cluster
labels:
  team: "platform"
  environment: "staging"

Use when: Teams have distinct ownership boundaries and need separate views of their infrastructure.

Multi-Valued Labels for Shared Ownership

When a cluster is managed by multiple teams or serves multiple purposes, use array values:

1
2
3
4
5
6
7
8

# Cluster managed by both platform and security teams
labels:
  region: "us-east"
  environment: "production"
  team:
    - "platform"
    - "security"
  tier: "critical"

This cluster will appear when filtering for either team:

• team = "platform" → matches
• team = "security" → matches
• team in ("platform", "devops") → matches (platform is in the set)

Use when: Clusters have shared ownership, serve multiple customers, or span multiple availability zones. Multi-valued labels enable flexible filtering without duplicating cluster definitions.

Applying Labels

Via Helm Configuration

Labels are applied through the Glass Instrumentation Helm chart. Each cluster where you install glass-instrumentation gets its own values file specifying the cluster ID and labels:

1
2
3
4
5
6
7
8

# values-my-cluster.yaml
clusterId: "my-cluster"
labels:
  environment: "production"
  region: "us-east"
  role: "dns"
  team: "platform"
  tier: "critical"

To assign multiple values to a label, use YAML array syntax:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# values-shared-cluster.yaml
clusterId: "shared-cluster"
labels:
  environment: "production"
  region: "us-east"
  role: "dns"
  team:                        # Cluster managed by multiple teams
    - "platform"
    - "security"
  tier: "critical"

Both single-value strings and arrays are supported for any label. The Helm chart automatically formats them correctly for the discovery service.

Quickstart Cluster Labels

The quickstart deployment includes three clusters with the following labels:

quickstart-1 (US East Production, multi-team):

1
2
3
4
5
6
7
8
9

clusterId: "quickstart-1"
labels:
  environment: "production"
  region: "us-east"
  role: "dns"
  team:
    - "platform"
    - "security"
  tier: "critical"

quickstart-2 (US West Production):

1
2
3
4
5
6
7

clusterId: "quickstart-2"
labels:
  environment: "production"
  region: "us-west"
  role: "dns"
  team: "platform"
  tier: "standard"

quickstart-3 (EU West Development):

1
2
3
4
5
6
7

clusterId: "quickstart-3"
labels:
  environment: "development"
  region: "eu-west"
  role: "dns"
  team: "infrastructure"
  tier: "standard"

This gives you a realistic multi-cluster environment for practicing filter queries:

GlassQL Filter Query Language

GlassQL is SPOG's filter query language for selecting and grouping clusters based on their labels. It uses a SQL-like syntax that's intuitive for anyone familiar with database queries.

When to Use Filters

• Interactive filtering: Type queries in the Glass UI filter input to narrow the cluster list
• Dashboard widgets: Configure widgets to show specific cluster subsets
• Programmatic selection: Use filters in API calls to target specific clusters

Query Anatomy

A GlassQL query consists of:

1. Conditions: Label comparisons (e.g., region = "us-east")
2. Logical operators: Combine conditions (and, or, not)
3. Grouping clause (optional): Organize results (group by)

1

[conditions] [group by labels]

Technical Specifications

Case Sensitivity: All label keys and values are case-sensitive. region = "US-East" will not match region: "us-east".

Quoting Requirements: String values containing spaces or special characters must be enclosed in double quotes:

1
2
3

team = "dev ops"           # Required - contains space
description = "Primary cluster"  # Required - contains space
region = "us-east"         # Quotes optional but recommended

Reserved Keywords: The following are reserved and cannot be used as label keys without special handling: - and, or, not - in, like, contains - group, by - cluster_id (special field, not a label)

Comparison Operators

Equality: = and !=

Match exact label values:

1

region = "us-east"

1

environment != "production"

The equality operators perform exact string matching. Values are case-sensitive. For multi-valued labels, a cluster matches if any of its values equals the filter value.

Set Membership: in and not in

Match any value from a set:

1

region in ("us-east", "us-west")

Exclude values from a set:

1

tier not in ("experimental", "deprecated")

The in operator is useful when you want to match multiple possible values for a label. For multi-valued labels, a cluster matches if any of its values is in the filter set.

Pattern Matching: like and not like

Match using glob patterns with * (any characters) and ? (single character):

1

region like "us-*"

1

cluster_id not like "*-3"

Pattern matching is useful for:

• Matching regions by prefix: region like "us-*" (all US regions)
• Matching clusters by naming convention: cluster_id like "prod-*"
• Excluding test clusters: cluster_id not like "*-test"

Escaping Special Characters: If your label values contain literal * or ? characters, you cannot escape them in the current implementation. Consider using the contains operator or exact equality matching instead.

Substring Matching: contains and not contains

Check if a value contains a substring:

1

team contains "plat"

1

region contains "west"

Numeric Comparison: <, >, <=, >=

Compare numeric label values:

1

priority < 3

1

replicas >= 2

Numeric operators parse label values as numbers. They're useful when you have labels like priority, replicas, or version that contain numeric values.

Logical Operators

AND: Both Conditions Must Match

1

environment = "production" and team = "platform"

Both conditions must be true for a cluster to match.

OR: Either Condition Matches

1

region = "us-east" or region = "eu-west"

Either condition can be true for a cluster to match.

NOT: Negate a Condition

1

not (environment = "development")

Inverts the match result. Note the parentheses around the condition being negated.

Combining Conditions & Operator Precedence

When combining multiple operators, SPOG evaluates them in this order (highest precedence first):

1. Parentheses ()
2. not
3. Comparison operators (=, !=, in, like, etc.)
4. and
5. or

Example: Without parentheses

1

region = "us-east" or region = "us-west" and environment = "production"

Due to operator precedence, this evaluates as: region = "us-east" or (region = "us-west" and environment = "production")

Step-by-step evaluation for each cluster:

• quickstart-1 (region: "us-east", environment: "production"):
• First condition: region = "us-east" → TRUE

• OR operator: Since first condition is true, entire query is TRUE ✓

• quickstart-2 (region: "us-west", environment: "production"):

• First condition: region = "us-east" → FALSE
• Second condition: region = "us-west" → TRUE
• Third condition: environment = "production" → TRUE
• Second AND third: TRUE and TRUE → TRUE

• OR operator: FALSE or TRUE → TRUE ✓

• quickstart-3 (region: "eu-west", environment: "development"):

• First condition: region = "us-east" → FALSE
• Second condition: region = "us-west" → FALSE
• OR operator: FALSE or (FALSE and anything) → FALSE ✗

→ Result: quickstart-1, quickstart-2

Example: With parentheses for clarity

1

(region = "us-east" or region = "us-west") and environment = "production"

This ensures the OR is evaluated first, then the AND.

→ quickstart-1, quickstart-2 (both are in US regions AND are production)

Complex query example:

1

(tier = "critical" and environment = "production") or team = "infrastructure"

Group By Clause

The group by clause organizes results into a hierarchical structure based on label values.

Basic Grouping

1

environment = "production" group by region

Result structure:

1
2
3
4

{
  "us-east": ["quickstart-1"],
  "us-west": ["quickstart-2"]
}

Multi-Level Grouping

1

team = "platform" group by region, environment

Result structure:

1
2
3
4
5
6
7
8

{
  "us-east": {
    "production": ["quickstart-1"]
  },
  "us-west": {
    "production": ["quickstart-2"]
  }
}

Filter Then Group

Apply conditions first, then organize the results:

1

tier in ("critical", "standard") group by tier, team

Groups clusters first by tier, then by team within each tier.

Cluster ID Field

The special cluster_id field lets you query by cluster identity. This is not a label, but a built-in field available for all clusters:

1

cluster_id = "quickstart-1"

1

cluster_id in ("quickstart-1", "quickstart-3")

1

cluster_id like "quickstart-*"

The cluster_id field supports all string comparison operators (=, !=, in, not in, like, not like, contains, not contains).

Simple Filters: Implicit Substring Matching

When you enter a simple string without any operators, GlassQL automatically treats it as a substring search against cluster_id. This enables very concise filtering:

1

us

This means typing just us will match clusters like us-east-prod-001, dns-us-west, or any cluster with "us" anywhere in its ID.

Leveraging Hierarchical Cluster IDs

This behavior becomes powerful when you adopt a hierarchical naming convention for cluster IDs:

1
2
3
4
5

# Example hierarchical naming: {region}-{environment}-{service}-{instance}
clusterId: "us-east-prod-dns-001"
clusterId: "us-west-prod-dns-002"
clusterId: "eu-central-staging-dns-001"
clusterId: "ap-north-dev-dns-001"

With this naming scheme, simple filters become very effective:

Quick Reference

Hands-On Exercises

These exercises use the quickstart deployment. If you haven't completed the quickstart, do so first.

Exercise 1: Explore Labels in the UI

Open the Glass UI and examine the quickstart clusters.

Tasks:

1. Click the filter input field and start typing a few letters (e.g., reg) to see autocomplete suggestions
2. Note which label keys are available (region, environment, team, tier, role)
3. Continue typing region = and observe the value suggestions
4. Identify which cluster has the critical tier
5. Click on a label value in the tree table (e.g., click "us-east" under a cluster's region) to automatically populate a filter query

Exercise 2: Practice Filter Queries

Test these queries in the Glass UI filter input. After each query, verify which clusters are displayed.

Task 1: Show only production clusters

Query: environment = "production"

Task 2: Show US-based clusters

Query: region in ("us-east", "us-west")

Task 3: Combine conditions - production AND platform team

Query: environment = "production" and team = "platform"

Task 4: Pattern match - regions starting with "us"

Query: region like "us-*"

Task 5: Complex query - critical OR infrastructure team

Query: tier = "critical" or team = "infrastructure"

Task 6: Query multi-valued labels - security team

Query: team = "security"

Task 7: Quick filter using cluster_id shorthand

Query: quick

Exercise 3: Add a Fourth Cluster

Extend the quickstart by adding a fourth cluster with new label values.

Step 1: Create the values file

Create quickstart-4.yaml:

1
2
3
4
5
6
7

clusterId: "quickstart-4"
labels:
  environment: "staging"
  region: "ap-north"
  role: "dns"
  team: "devops"
  tier: "standard"

Step 2: Deploy the cluster

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Create namespace
kubectl create namespace quickstart-4

# Create registry credentials (if using private registry)
kubectl create secret docker-registry registry-credentials \
  --docker-server=registry.open-xchange.com \
  --docker-username="$REGISTRY_USERNAME" \
  --docker-password="$REGISTRY_PASSWORD" \
  --namespace=quickstart-4

# Deploy PowerDNS
helm install quickstart-4 \
  oci://registry.open-xchange.com/cloudcontrol/powerdns \
  --version "3.1.13" \
  --namespace quickstart-4 \
  -f helm/3rd-party-examples/powerdns/examples/quickstart.yaml

# Deploy Glass Instrumentation
helm install glass-instrumentation \
  oci://registry.open-xchange.com/cc-glass/glass-instrumentation \
  --version "1.0.0" \
  --namespace quickstart-4 \
  -f quickstart-4.yaml

Step 3: Verify in the UI

After deployment, verify the new cluster appears:

1

region = "ap-north"

Step 4: Test new filter combinations

Now you have a staging cluster. Test these queries:

1

environment = "staging"

1

environment != "production"

1

team = "devops"

Step 5: Cleanup (Optional)

To remove the fourth cluster when you're done experimenting:

1
2
3
4
5
6
7
8

# Remove Glass Instrumentation
helm uninstall glass-instrumentation --namespace quickstart-4

# Remove PowerDNS
helm uninstall quickstart-4 --namespace quickstart-4

# Delete namespace
kubectl delete namespace quickstart-4

Best Practices & Troubleshooting

Best Practices

Label Naming Conventions

Taxonomy Planning Checklist

Before deploying SPOG to production, document your label taxonomy:

• List all label keys you'll use
• Define allowed values for each key
• Document which labels are required vs optional
• Specify who owns/maintains each label
• Plan how labels map to access control policies

Common Pitfalls to Avoid

1. Inconsistent label keys: Using env in some clusters and environment in others
2. Too many labels: Creating labels that aren't used for filtering or access control
3. Changing labels frequently: Labels should be stable; frequent changes break filters
4. Forgetting quotes: region = us-east fails; use region = "us-east"