loki

Loki Generator

Published on kadet-hub: pin a released version by digest from its catalog page.

Built for Loki Operator 0.11.0 (loki.grafana.com/v1). The compiled output is not checked against JSON Schemas: the upstream CRDs are AGPL-3.0-only, so this generator does not ship them.

Kapitan kadet generator for Loki Operator resources:

• LokiStack: a managed Loki deployment
• AlertingRule: LogQL alerting rules for one tenant
• RecordingRule: LogQL recording rules for one tenant
• RulerConfig: ruler settings (Alertmanager, remote write) for a LokiStack

The object storage Secret belongs in the kubernetes generator.

Usage

Kapitan Configuration

parameters:
  kapitan:
    dependencies:
      - type: oci
        source: ghcr.io/kadet-hub/loki@sha256:<digest>
        output_path: lib/loki
    compile:
      - output_path: manifests/loki/
        input_type: kadet
        output_type: yml
        input_paths:
          - lib/loki

Inventory Contract

All keys live under parameters.generators.loki.

The CRDs define no shortNames, so the suffix is the lowercase kind.

Every resource accepts namespace, labels, annotations and spec; rules also accept loki_stack. Precedence, lowest first: generator defaults, spec, flat keys and shorthands. A flat key replaces the same field from spec and logs a warning.

Flat keys are the snake_case spelling of the CRD spec fields; values pass through unchanged:

The deprecated replicationFactor is not a flat key; use replication.factor.

LokiStack Defaults

The generator fills these fields only where neither spec nor a flat key sets them.

The storage shorthand follows the Secret naming of the operator’s object storage guide (lokistack-dev-s3 for the stack lokistack-dev). <type> is one of s3, azure, gcs, swift, alibabacloud. A Secret with another name, a credentialMode or tls needs the full storage block.

Without schemas the CRD applies v11 from 2020-10-11 (CRD default), and the operator then sets the StorageNeedsSchemaUpdate warning because the latest schema is not v13 (status). The API recommends the latest schema with a past effective date for a new stack (API), and Loki calls v13 the recommended schema (Loki schema docs). The date is fixed to keep the output deterministic. It is the one the operator’s own examples use (tenancy modes).

A stack that already runs on the CRD default keeps v11 in status.storage.schemas. The operator’s webhook rejects an update that drops it or adds a schema with a past date (validation). For such a stack, set storage.schemas to its current entries plus v13 with an effective date in the future.

The CRD default for tenants.mode is openshift-logging. It works only on OpenShift and rejects custom authentication and authorization. The derived mode is the only one the operator’s mode validation accepts for that block; see the tenancy modes guide. The operator’s default configuration enables the gateway (config), and a stack without tenants is then degraded (gateway). Set tenants on every stack.

Rules are bound to a stack by the label loki.grafana.com/lokistack: <stack name>. A rule gets it for the stack named in its loki_stack; without loki_stack, rules are bound to the only stack when loki_stacks has exactly one entry. A labels entry with the same key wins. The operator selects rules by rules.selector, and a stack without a selector loads none (rule discovery, nil selector). It searches only the stack namespace unless rules.namespaceSelector matches other namespaces (design). The namespace selector uses the label Kubernetes sets on every namespace (Kubernetes docs), so the generator does not need to label namespaces. The operator documents no label convention of its own. Its samples select on openshift.io/cluster-monitoring (sample), which marks a namespace for monitoring rather than naming a stack. An explicit selector or namespaceSelector is never changed, and rules bound by other labels stay as they are.

Not defaulted:

• size: depends on the daily log volume, from 50 GB/day for 1x.pico to 2 TB/day for 1x.medium (sizing). Required by the CRD.
• storage_class_name: depends on the cluster. Required by the CRD.
• replication.factor: the operator sets 2 for every size except 1x.demo (sizes).
• Retention: Loki deletes nothing unless limits.global.retention or a tenant retention is set (config). There is no vendor default; set limits.global.retention.days or a lifecycle rule on the bucket.
• Other CRD defaults (managementState: Managed, evaluationInterval: 1m, pollInterval: 1m) are left to the API server.

A RulerConfig applies to the LokiStack with the same name in the same namespace.

Example

parameters:
  generators:
    loki:
      namespace: logging
      loki_stacks:
        logs:
          size: 1x.small
          storage: s3
          storage_class_name: standard
          limits:
            global:
              retention:
                days: 30
          tenants:
            authentication:
              - tenantName: application
                tenantId: application
                oidc:
                  secret:
                    name: application-oidc
                  issuerURL: https://idp.example.com/
            authorization:
              roles:
                - name: read-write
                  permissions: [read, write]
                  resources: [logs]
                  tenants: [application]
              roleBindings:
                - name: developers
                  roles: [read-write]
                  subjects:
                    - kind: group
                      name: developers
          rules:
            enabled: true
      alerting_rules:
        high-error-rate:
          tenant_id: application
          groups:
            - name: errors
              interval: 1m
              rules:
                - alert: HighErrorRate
                  expr: sum(rate({app="web"} |= "error" [5m])) > 10
                  for: 10m
                  labels:
                    severity: warning
      recording_rules:
        request-rates:
          tenant_id: application
          groups:
            - name: rates
              interval: 1m
              rules:
                - record: web:requests:rate5m
                  expr: sum(rate({app="web"}[5m]))
      ruler_configs:
        logs:
          evaluation_interval: 1m
          alertmanager:
            endpoints:
              - http://alertmanager.monitoring.svc:9093

The logs stack compiles to the logs-s3 Secret reference, the v13 schema, tenants.mode: static and a rules selector on loki.grafana.com/lokistack: logs, the label both rules get.