Skip to main content

​
Overview

Grafana Loki is a horizontally scalable, multi-tenant log aggregation system. Control Plane can forward all Org logs natively to any Loki-compatible target — a self-hosted Loki, Grafana Cloud Logs, or any backend that accepts the Loki push API — using the native Loki output rather than a generic protocol. Because logs are sent over the native Loki API, Control Plane log metadata is attached as indexed Loki labels (including service_name, which drives Grafana’s service detection), so logs are immediately queryable by workload, GVC, location, and more. Follow the steps below to configure log shipping to Loki.

​
Step 1 - Prerequisites

  • Endpoint: A reachable URL for your Loki instance (see Endpoint Format).
  • Authentication (optional): A Username & Password Secret for HTTP basic auth, if your Loki target requires it (Grafana Cloud and most hosted Loki services do).
  • Tenant ID (optional): The tenant identifier for multi-tenant Loki deployments (for example, the user/instance ID for Grafana Cloud).

​
Step 2 - Configure External Logging

External logging can be configured by using either the UI Console or CLI.

​
Enable Logging using the UI Console

  1. From the Control Plane Console UI, click on Org in the left menu.
  2. Click External Logs in the middle context menu.
  3. Select Loki and fill out the endpoint, and the credentials and tenant ID if your target requires them.
  4. Click Save.
  5. After the configuration is complete, log entries will begin forwarding to Loki within a few minutes.

​
Enable Logging using the CLI

The external logging configuration can be created / updated using the CLI’s cpln org patch ORG_NAME -f FILE.yaml command. Below is an example of an Org manifest (in YAML). Edit and save the YAML as a file and use it as an input to the CLI’s cpln org patch ORG_NAME -f FILE.yaml command.
  • Substitute: ORG_NAME, the endpoint, and (if required) USERPASS_SECRET and tenantId.
YAML
kind: org
name: ORG_NAME
spec:
  logging:
    loki:
      endpoint: https://logs-prod-001.grafana.net
      credentials: //secret/USERPASS_SECRET
      tenantId: "123456"
credentials and tenantId are both optional. Provide whichever your target requires (or neither for an unauthenticated, single-tenant endpoint).

​
Endpoint Format

The endpoint is required. TLS, the port, and the push path are derived from its format:
EndpointTLSPortPush URI
https://host[:port][/path]OnFrom URL, else 443The URL path, else /loki/api/v1/push
http://host[:port][/path]OffFrom URL, else 80The URL path, else /loki/api/v1/push
host[:port]OnAs given, else 443/loki/api/v1/push
Provide the base URL (for example https://logs-prod-001.grafana.net) and Control Plane will append the default /loki/api/v1/push path. Include an explicit path only if your target uses a non-standard push endpoint.

​
Authentication

If your Loki target requires authentication, set credentials to a Username & Password Secret. The username and password are sent as HTTP basic auth on every push request. For Grafana Cloud, the username is your instance/user ID and the password is a Grafana Cloud access token. Omit credentials for an unauthenticated endpoint, such as a Loki instance reachable only on a trusted internal network.

​
Multi-Tenant Loki

For multi-tenant Loki deployments, set tenantId to the tenant the logs should be written under. It is sent as the tenant ID on each push request. Leave it unset for single-tenant Loki.

​
Forwarded Log Labels

Each forwarded record carries the Control Plane log metadata as indexed Loki labels, and the log message body as the log line:
LabelDescription
service_nameWorkload name (drives Grafana service detection)
workloadWorkload name
orgOrg name
gvcGVC name
locationLocation the log originated from
providerCloud provider
versionWorkload version
containerContainer name
streamOutput stream (stdout or stderr)
replicaReplica name
All logs continue to remain accessible through Control Plane, adhering to the current log retention policy.