> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes CRD Reference

> Every Metoro custom resource definition, with a working example of each

Metoro can be configured declaratively from Kubernetes. Alerts, dashboards, webhook integrations, ingestion exclusion rules, and access control can all be managed as Kubernetes custom resources, so they live in version control and roll out through GitOps alongside the workloads they apply to.

This page is the catalogue of every Metoro custom resource definition. Each section shows a complete, appliable example and links to the full guide for that resource.

## All resources at a glance

Metoro's CRDs live under two API groups: `observability.metoro.io/v1alpha1` for resources that manage observability configuration, and `rbac.metoro.io/v1alpha1` for access control.

| Kind                                                            | API group                          | Scope      | Apply to                 | Manages                                                                            | Short names        |
| --------------------------------------------------------------- | ---------------------------------- | ---------- | ------------------------ | ---------------------------------------------------------------------------------- | ------------------ |
| [`MetoroAlert`](#metoroalert)                                   | `observability.metoro.io/v1alpha1` | Namespaced | Any monitored cluster    | A Metoro alert                                                                     | `ma`, `malert`     |
| [`MetoroDashboard`](#metorodashboard)                           | `observability.metoro.io/v1alpha1` | Namespaced | Any monitored cluster    | A Metoro dashboard                                                                 | `md`, `mdashboard` |
| [`MetoroWebhook`](#metorowebhook)                               | `observability.metoro.io/v1alpha1` | Namespaced | Any monitored cluster    | A webhook integration                                                              | `mw`, `mwebhook`   |
| [`MetoroClusterIngestionRule`](#metoroclusteringestionrule)     | `observability.metoro.io/v1alpha1` | Cluster    | Any monitored cluster    | Log/span exclusion before telemetry leaves the cluster                             | `mcingrule`        |
| [`MetoroGroup`](#metorogroup)                                   | `rbac.metoro.io/v1alpha1`          | Cluster    | On-prem hub cluster only | A Metoro group                                                                     | `mgroup`           |
| [`MetoroNamespaceTelemetryRule`](#metoronamespacetelemetryrule) | `rbac.metoro.io/v1alpha1`          | Namespaced | Any monitored cluster    | Telemetry access grant for its namespace                                           | `mntelrule`        |
| [`MetoroClusterTelemetryRule`](#metoroclustertelemetryrule)     | `rbac.metoro.io/v1alpha1`          | Cluster    | Any monitored cluster    | Telemetry access grant for the whole cluster                                       | `mctelrule`        |
| [`MetoroNamespaceResourceRule`](#metoronamespaceresourcerule)   | `rbac.metoro.io/v1alpha1`          | Namespaced | Any monitored cluster    | Access grant to Kubernetes-managed alerts/dashboards/webhooks in its namespace     | `mnresrule`        |
| [`MetoroClusterResourceRule`](#metoroclusterresourcerule)       | `rbac.metoro.io/v1alpha1`          | Cluster    | Any monitored cluster    | Access grant to Kubernetes-managed alerts/dashboards/webhooks in the whole cluster | `mcresrule`        |

## How Kubernetes-managed resources behave

The same model applies to every resource on this page:

* **Kubernetes is the source of truth.** Resources synced from Kubernetes appear in the Metoro UI with a **Managed via K8s** badge and are read-only there. To change or remove one, edit or delete the custom resource.
* **Changes sync automatically.** Metoro detects creates, `spec` updates, and deletions for every resource in a monitored cluster. Most changes appear in about 30 seconds; allow up to one minute for the exporter and sync workflow to process a change. The exception is the hub-only `MetoroGroup`, which follows its own reconciliation schedule; see [Metoro Resource Sync Timing](/docs/kubernetes-resources/kubernetes-resources#metoro-resource-sync-timing).
* **CRDs are installed by the Metoro charts.** The Metoro exporter chart installs every CRD except `MetoroGroup` on each monitored cluster, so they are available on both Metoro cloud and on-prem. The `MetoroGroup` CRD is installed by the on-prem hub chart only, so group creation stays centralized in the hub cluster.
* **Synced resources get deterministic locations.** Alerts, dashboards, and webhooks land under `/alerts|/dashboards|/webhooks/kubernetes-managed/<cluster>/<namespace>/`, and dashboards and webhooks get the ID `kubernetes-managed.<cluster>.<namespace>.<name>`.

<Note>
  Alerts and dashboards can alternatively be managed through labelled
  ConfigMaps; see [ConfigMap-managed
  dashboards](/docs/dashboards/configmap-managed) and [alert
  examples](/docs/alerts-monitoring/example_alerts). ConfigMaps reconcile hourly
  rather than in near real time and don't get Kubernetes API validation; the
  custom resources on this page are the recommended path.
</Note>

## Listing Metoro resources with kubectl

Every Metoro CRD is in the `metoro` category, so one command lists all Metoro objects in a cluster:

```bash theme={null}
kubectl get metoro -A
```

The `metoro-observability` category covers the `observability.metoro.io` kinds and `metoro-rbac` covers the `rbac.metoro.io` kinds. Short names work as usual, e.g. `kubectl get malerts -n payments` or `kubectl get mcingrules`.

## Observability resources

### MetoroAlert

Declares a Metoro timeseries alert. The `spec.timeseries` body mirrors the [alert API](/docs/api-reference/alerts/createupdate-alert#body-alert-timeseries)'s timeseries configuration: a MetoroQL query plus evaluation rules, with optional notification actions (`slack`, `pagerDuty`, `email`, `webhook`).

```yaml theme={null}
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroAlert
metadata:
  name: checkout-high-error-logs
  namespace: payments
spec:
  displayName: Checkout high error logs
  description: More than 100 error logs per minute from the checkout service for 5 consecutive minutes.
  timeseries:
    expression:
      metoroQLTimeseries:
        query: count(logs{log_level="error", service_name="/k8s/payments/checkout"})
        bucketSize: 60
    evaluationRules:
      - name: critical
        type: static
        static:
          operators:
            - operator: greaterThan
              threshold: 100
          persistenceSettings:
            datapointsToAlarm: 5
            datapointsInEvaluationWindow: 5
            missingDatapointBehavior: notBreaching
        actions:
          - type: slack
            slackDestination:
              channel: alerts-critical
              notifyOnResolve: true
          - type: email
            emailDestination:
              emails:
                - oncall@example.com
```

* `spec.displayName` defaults to `metadata.name`; `spec.description` and `spec.aiInvestigateOnFire` (start an [AI investigation](/docs/ai-sre/alert-investigations) when the alert fires) are optional.
* You don't have to write these by hand: export any existing alert from the alert page via **Export → Metoro CRD Format**, then `kubectl apply -n <namespace>` it. See [exporting existing alerts](/docs/kubernetes-resources/kubernetes-resources#exporting-existing-alerts).

Full guide: [Creating/Updating an Alert](/docs/alerts-monitoring/create_alert) and [Metoro Alert Resources](/docs/kubernetes-resources/kubernetes-resources#metoro-alert-resources).

### MetoroDashboard

Declares a Metoro dashboard. `spec.content` is the dashboard's root widget group, in the same shape as the [dashboard API](/docs/api-reference/dashboards/createupdate-dashboard#body-dashboard).

```yaml theme={null}
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroDashboard
metadata:
  name: payments-overview
  namespace: payments
spec:
  title: Payments Overview
  settings:
    defaultTimeRange: "1h"
    layoutVersion: 2
  content:
    title: Payments Overview
    widgets:
      - type: chart
        position:
          type: absolute
          absolute: { x: 0, "y": 0, w: 12, h: 12 }
        chart:
          title: Checkout CPU usage (cores)
          chartType: line
          expression:
            queryMode: metoroql
            metoroQLQueries:
              - query: sum(rate(container_resources_cpu_usage_seconds_total{service_name="/k8s/payments/checkout"}))
                bucketSize: 60
```

* `spec.title` defaults to `metadata.name`; `spec.settings` is optional. Do not set a dashboard ID or folder: Metoro derives them from the cluster, namespace, and resource name.
* Export any existing dashboard as a ready-to-apply manifest from its settings via **Export → YAML (MetoroDashboard CRD)**.

Full guide: [Manage Dashboards with Kubernetes](/docs/dashboards/configmap-managed).

### MetoroWebhook

Declares a webhook integration that alerts and [AI SRE notifications](/docs/ai-sre/notifications) can use as a destination. The URL and body support [template variables](/docs/integrations/webhooks#template-variables).

```yaml theme={null}
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroWebhook
metadata:
  name: rootly-critical-alerts
  namespace: payments
spec:
  displayName: Rootly Critical Alerts
  url: https://api.example.com/webhook?alert=$alert_name
  method: POST
  headers:
    Content-Type: application/json
  headersFrom:
    Authorization:
      secretKeyRef:
        name: rootly-webhook
        key: authorization
  body: |
    {
      "alert": "$alert_name",
      "state": "$alert_state",
      "message": "$alert_message"
    }
```

* Only `spec.url` is required. `spec.displayName` defaults to `metadata.name`, `spec.method` defaults to `POST`, and `spec.headers`/`spec.body` are optional (an empty body sends Metoro's default JSON payload).
* `spec.headersFrom` and `spec.bodyFrom` reference Kubernetes Secrets in the webhook's own namespace, resolved only at delivery time so credentials never enter the manifest or Metoro's resource history. Requires the exporter's `secretRefs` opt-in and `metoro-exporter` chart 0.477.0 or later.
* The synced integration gets the deterministic ID `kubernetes-managed.<cluster>.<namespace>.<name>`, which is how alert manifests reference it in `webhookDestination.uuid`.
* Export any existing webhook as a manifest with the download icon on the integrations page.

Full guide: [Webhook Integration](/docs/integrations/webhooks#kubernetes-managed-webhooks).

### MetoroClusterIngestionRule

Excludes matching logs and trace spans **before they leave the cluster** where the rule is applied. Rules are exclude-only and per-cluster; expressions within a rule are ANDed, separate rules are ORed.

```yaml theme={null}
apiVersion: observability.metoro.io/v1alpha1
kind: MetoroClusterIngestionRule
metadata:
  name: drop-health-check-logs
spec:
  rules:
    - signals: [logs]
      action: Exclude
      match:
        matchExpressions:
          - key: message
            operator: RegexIn
            values: ["GET /healthz", "GET /readyz"]
```

* `signals` is `logs`, `traces`, or both; `action` must be `Exclude`. Omitting `match` drops **everything** for the rule's signals in that cluster.
* Supported operators are `In` (exact value) and `RegexIn` (unanchored RE2). Note that `service.name` values are stored in the canonical `/k8s/<namespace>/<service>` form.
* Synced rules appear in **Settings → Data Ingestion Settings** with a **Managed** badge.
* Requires `metoro-exporter` chart version 0.476.0 or later (Metoro cloud), or `metoro-exporter-onprem` chart version 11.0.0 or later; older charts do not install this CRD.

Full guide: [CRD Managed Ingestion Rules](/docs/ingestion-settings/crd-managed-ingestion-rules).

## Access control resources

Metoro's [RBAC model](/docs/user-management/rbac) can be declared as Kubernetes resources: groups plus telemetry and resource rules. A rule is a Role and RoleBinding in one object: it creates a managed Metoro role and binds it to the groups in `spec.groups`. Grants are allow-only and additive.

### MetoroGroup

Declares a Metoro group. The group name is `metadata.name`; the optional `spec.oidcMappings` list automatically adds users to the group when their OIDC groups claim matches.

<Note>
  On-prem only: apply `MetoroGroup` to the hub cluster. The CRD is
  intentionally not installed in monitored clusters. On Metoro cloud, create
  groups in **Settings → Users & Groups → Groups** instead.
</Note>

```yaml theme={null}
apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroGroup
metadata:
  name: sre-team
spec:
  oidcMappings:
    - /sre
    - /platform-oncall
```

Full guide: [Kubernetes RBAC Resources](/docs/user-management/kubernetes-crds#metorogroup).

### MetoroNamespaceTelemetryRule

Grants groups access to telemetry from the rule's own namespace. Signals are `logs`, `metrics`, `traces`, `profiles`, and `kubernetesResources`; an optional `match` narrows the grant by telemetry attributes.

```yaml theme={null}
apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroNamespaceTelemetryRule
metadata:
  name: kube-system-all-signals
  namespace: kube-system
spec:
  groups:
    - sre-team
  rules:
    - signals:
        - logs
        - metrics
        - traces
        - profiles
        - kubernetesResources
```

Full guide: [Kubernetes RBAC Resources](/docs/user-management/kubernetes-crds#reference).

### MetoroClusterTelemetryRule

The cluster-scoped variant: same spec as `MetoroNamespaceTelemetryRule`, but the grant spans the whole cluster rather than one namespace.

```yaml theme={null}
apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroClusterTelemetryRule
metadata:
  name: cluster-metrics-and-problem-logs
spec:
  groups:
    - sre-team
  rules:
    - signals:
        - metrics
    - signals:
        - logs
      match:
        matchExpressions:
          - key: log.severity
            operator: In
            values:
              - error
              - warn
```

Full guide: [Kubernetes RBAC Resources](/docs/user-management/kubernetes-crds#reference).

### MetoroNamespaceResourceRule

Grants groups verbs (`create`, `read`, `update`, `delete`) on Kubernetes-managed alerts, dashboards, and webhooks declared in the rule's own namespace. Resource rules never grant access to resources created in the UI.

```yaml theme={null}
apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroNamespaceResourceRule
metadata:
  name: kube-system-dashboards
  namespace: kube-system
spec:
  groups:
    - sre-team
  rules:
    - resources:
        - dashboards
      verbs:
        - create
        - read
        - update
        - delete
```

Full guide: [Kubernetes RBAC Resources](/docs/user-management/kubernetes-crds#resource-rules).

### MetoroClusterResourceRule

The cluster-scoped variant: same spec as `MetoroNamespaceResourceRule`, covering Kubernetes-managed resources across the whole cluster. An optional `rules[].path` narrows the grant to a subfolder.

```yaml theme={null}
apiVersion: rbac.metoro.io/v1alpha1
kind: MetoroClusterResourceRule
metadata:
  name: all-webhooks-read
spec:
  groups:
    - sre-team
  rules:
    - resources:
        - webhooks
      verbs:
        - read
```

Full guide: [Kubernetes RBAC Resources](/docs/user-management/kubernetes-crds#resource-rules).