Cluster Monitoring

Codesphere provides two monitoring options for your private cloud installation: cluster-level monitoring for individual cluster oversight, and aggregated monitoring across multiple clusters for enterprise-wide visibility. Choose the option that best fits your operational needs.

Cluster-Level Monitoring (Grafana)​

As part of the regular Codesphere installation, a Grafana instance with predefined dashboards is automatically deployed into the cluster. The login credentials are automatically generated. The Grafana UI can be reached via port-forwarding to localhost.

Steps to access the Grafana instance:

1. Retrieve credentials:
   1. Username: admin
   2. Password: kubectl get secret grafana -n monitoring -o jsonpath={.data.admin-password} | base64 -d
2. Access Grafana in your local browser:
   1. Start port-forward with kubectl port-forward deployment/grafana 3000:3000 -n monitoring
   2. On your local browser visit localhost:3000
   3. Login with the credentials from the previous step.
3. Hint: if you only have kubectl access via e.g. a jumphost, you can use ssh port-forwarding to continue to your local machine: ssh -L 3000:localhost:3000 user@jumphost

Aggregated Multi-Cluster Monitoring​

For organizations managing multiple Codesphere clusters, aggregated monitoring provides centralized visibility across all installations. This option enables Prometheus remote write for metrics, central OpenTelemetry export for traces and span-derived metrics, and Grafana Alloy based forwarding for logs to Loki.

Codesphere recommends using Thanos as the central monitoring system for aggregated metrics. Thanos fits the OMS remote write configuration directly and is well suited for multi-cluster Prometheus ingestion, long-term retention, and centralized querying.

Enabling Aggregated Monitoring​

To enable aggregated monitoring, configure the following settings in your installation values file as described in the installation guide:

cluster:
  monitoring:
    prometheus:
      remoteWrite:
        enabled: true
        clusterName: production-eu-west
        url: https://thanos-receive.example.com/api/v1/receive
    grafanaAlloy:
      enabled: true
      loki:
        endpoint: https://loki.example.com/loki/api/v1/push
        user: loki-user
    centralOtelExport:
      enabled: true

codesphere:
  telemetryExport:
    remoteEndpoint: https://otel.example.com
    remoteExport: true
    traces: true
    traceEndpoint: https://tempo.example.com/v1/traces
    spanMetrics: true

Configuration Parameters​

• cluster.monitoring.prometheus.remoteWrite.enabled: Enables Prometheus remote write.
• cluster.monitoring.prometheus.remoteWrite.clusterName: Unique identifier for this cluster in the central monitoring system.
• cluster.monitoring.prometheus.remoteWrite.url: Remote write endpoint of your central metrics backend. For Thanos this is typically the Thanos Receive endpoint.
• cluster.monitoring.grafanaAlloy.enabled: Enables Grafana Alloy to export cluster logs to Loki.
• cluster.monitoring.grafanaAlloy.loki.endpoint: Loki push endpoint for central log aggregation.
• cluster.monitoring.grafanaAlloy.loki.user: Optional basic auth username for Loki.
• cluster.monitoring.centralOtelExport.enabled: Enables credential wiring for central OpenTelemetry export.
• codesphere.telemetryExport.remoteEndpoint: Optional OTLP/HTTP endpoint of the central OpenTelemetry collector that receives telemetry exports.
• codesphere.telemetryExport.remoteExport: Optional boolean that enables export to codesphere.telemetryExport.remoteEndpoint.
• codesphere.telemetryExport.traces: Optional boolean that enables trace export to an external tracing backend such as Tempo.
• codesphere.telemetryExport.traceEndpoint: Optional OTLP endpoint of the external tracing backend. Required when codesphere.telemetryExport.traces is true.
• codesphere.telemetryExport.spanMetrics: Optional boolean that enables generation and export of span-based metrics via the spanmetrics connector.

Credentials​

OMS stores the passwords for Prometheus remote write, Loki, and central OpenTelemetry in the generated secrets vault rather than in plain YAML. In practice this means:

Add these entries to prod.vault.yaml:

secrets:
  - name: promRemoteWriteUser
    fields:
      password: <prometheus-remote-write-user>
  - name: promRemoteWritePassword
    fields:
      password: <prometheus-remote-write-password>
  - name: lokiGatewayBasicAuthPassword
    fields:
      password: <loki-password>
  - name: centralOtelCreds
    fields:
      username: <central-otel-export-username>
      password: <central-otel-export-password>