Filter by Namespace¶

This guide explains how to configure MonitorAccessPolicy resources to restrict visibility to specific namespaces.

Overview¶

Namespace filtering controls which namespaces a user can see within a cluster. When namespace filtering is applied:

Namespace lists are filtered to show only permitted namespaces
Pod, deployment, and service counts reflect only resources in permitted namespaces
Cluster metrics are recalculated based on visible namespaces

Basic Namespace Filter¶

The following policy allows access only to namespaces starting with app-:

apiVersion: clusterpulse.io/v1alpha1
kind: MonitorAccessPolicy
metadata:
  name: app-namespace-access
  namespace: clusterpulse
spec:
  identity:
    priority: 100
    subjects:
      groups:
        - app-developers

  access:
    effect: Allow
    enabled: true

  scope:
    clusters:
      default: filtered
      rules:
        - selector:
            matchPattern: .*
          permissions:
            view: true
            viewMetrics: true
          resources:
            - type: namespaces
              visibility: filtered
              filters:
                names:
                  allowed:
                    - "app-*"

Visibility Options¶

The visibility field accepts three values:

Value	Behavior
`all`	No filtering. User sees all namespaces.
`none`	Complete restriction. User sees no namespaces.
`filtered`	Apply include/exclude rules from `filters`.

Filter Patterns¶

Wildcard Patterns¶

Use * to match any characters and ? to match a single character:

filters:
  names:
    allowed:
      - "app-*"        # Matches app-frontend, app-backend, etc.
      - "team-?-prod"  # Matches team-a-prod, team-b-prod, etc.

Literal Values¶

Exact namespace names without wildcards:

filters:
  names:
    allowed:
      - default
      - monitoring
      - logging

Combining Allowed and Denied¶

The denied list takes precedence over allowed:

resources:
  - type: namespaces
    visibility: filtered
    filters:
      names:
        allowed:
          - "app-*"
        denied:
          - "app-internal"
          - "app-secrets"

This configuration allows all app-* namespaces except app-internal and app-secrets.

Complete Example: Team-Based Access¶

apiVersion: clusterpulse.io/v1alpha1
kind: MonitorAccessPolicy
metadata:
  name: team-alpha-access
  namespace: clusterpulse
spec:
  identity:
    priority: 100
    subjects:
      groups:
        - team-alpha

  access:
    effect: Allow
    enabled: true

  scope:
    clusters:
      default: filtered
      rules:
        - selector:
            environment: production
          permissions:
            view: true
            viewMetrics: true
          resources:
            - type: namespaces
              visibility: filtered
              filters:
                names:
                  allowed:
                    - "alpha-*"
                    - "shared-*"
                  denied:
                    - "shared-admin"
            - type: pods
              visibility: filtered
              filters:
                namespaces:
                  allowed:
                    - "alpha-*"
                    - "shared-*"

When filtering namespaces, you should also filter namespace-scoped resources to maintain consistency even though not explicitly necessary:

resources:
  - type: namespaces
    visibility: filtered
    filters:
      names:
        allowed:
          - "app-*"

  - type: pods
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"

  - type: operators
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"

Filtering Operators by Namespace¶

Operators can be filtered by the namespaces where they are available. Remember that cluster scoped (operators shown in every namespace) operators will always show:

resources:
  - type: operators
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "operator-*"
          - monitoring
      names:
        denied:
          - "*-test"

How Metrics Are Affected¶

When namespace filtering is active, cluster metrics are recalculated:

Metric	Behavior
`namespaces`	Count of visible namespaces only
`pods`	Count of pods in visible namespaces
`pods_running`	Running pods in visible namespaces
`deployments`	Deployments in visible namespaces
`services`	Services in visible namespaces

The API response includes filtering metadata:

{
  "metrics": {
    "namespaces": 5,
    "pods": 42,
    "filtered": true,
    "filter_metadata": {
      "allowed_namespaces": 5,
      "total_namespaces": 50
    }
  }
}

Verification¶

Check Allowed Namespaces via API¶

curl -H "Authorization: Bearer $TOKEN" \
  https://clusterpulse.example.com/api/v1/clusters/my-cluster/namespaces

Check Filtered Metrics¶

curl -H "Authorization: Bearer $TOKEN" \
  https://clusterpulse.example.com/api/v1/clusters/my-cluster/metrics?detailed=true

The response includes filter_details when filtering is applied.

Common Patterns¶

Exclude System Namespaces¶

filters:
  names:
    allowed:
      - "*"
    denied:
      - kube-system
      - kube-public
      - kube-node-lease
      - openshift-*

Development Team Access¶

filters:
  names:
    allowed:
      - "dev-*"
      - "staging-*"
    denied:
      - "*-secrets"
      - "*-internal"

Production Read-Only with Limited Namespaces¶

filters:
  names:
    allowed:
      - "prod-frontend"
      - "prod-backend"
      - "prod-api"

Filtering Custom Resources by Namespace¶

Custom resources collected by MetricSource can also be filtered by namespace. Custom resource types are listed alongside built-in types in the resources list:

resources:
  - type: pvc
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"
        denied:
          - "kube-system"
  - type: certificate
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"

The same pattern rules apply — denied takes precedence over allowed, and wildcards (*, ?) are supported.

Combining with Built-In Namespace Filters¶

When restricting namespace visibility, apply matching filters to custom resources for consistency:

resources:
  - type: namespaces
    visibility: filtered
    filters:
      names:
        allowed:
          - "app-*"

  - type: pods
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"

  - type: pvc
    visibility: filtered
    filters:
      namespaces:
        allowed:
          - "app-*"

Aggregation Recomputation¶

When namespace filters reduce the set of visible custom resources, aggregations are automatically recomputed from the filtered set (if filterAggregations: true in the MetricSource, which is the default). This means a user filtered to app-* namespaces will see aggregation values that reflect only PVCs in those namespaces.

Troubleshooting¶

Namespace Not Visible¶

Verify the namespace name matches the allowed patterns exactly
Check that the namespace is not in the denied list
Confirm the policy is active and applies to the user

Metrics Show Zero¶

If metrics show zero but namespaces exist:

Verify the pod filter matches the namespace filter
Check that visibility is set to filtered, not none

Debug Policy Application¶

Use the auth endpoint to see effective permissions:

curl -H "Authorization: Bearer $TOKEN" \
  https://clusterpulse.example.com/api/v1/auth/permissions

Next Steps¶

Create Read-Only Policy - Basic policy creation
Grant Custom Resource Access - Full custom resource RBAC guide
Policy Evaluation - Understand how policies are evaluated