Loki-k8s docs - index

Loki Charmed Operator for K8s

Welcome to the Loki Charmed Operator documentation!

This Charmed Operator handles instantiation, scaling, configuration, optimisation, networking, service mesh, observability, and Day 2 operations specific to Loki.

On the principle that an operator should “do one thing and do it well”, this operator drives Loki application only. However, it can be composed with other operators to deliver a complex application or service. Because operators package expert knowledge in a reusable and shareable form, they hugely simplify software management and operations.

Getting started

Basic deployment

Create a Juju model for your operator, say “observability”

juju add-model observability

The Loki Charmed Operator may be deployed using the Juju command line in a quite very way.

juju deploy loki-k8s --channel=edge --trust

Checking deployment status

Once the Charmed Operator is deployed, the status can be checked running:

juju status --color --relations
Model          Controller  Cloud/Region        Version  SLA          Timestamp
observability  mk8s        microk8s/localhost  2.9.21   unsupported  16:19:00-03:00

App       Version  Status  Scale  Charm     Store     Channel  Rev  OS          Address        Message
loki-k8s           active      1  loki-k8s  charmhub  edge      11  kubernetes

Unit         Workload  Agent  Address     Ports  Message
loki-k8s/0*  active    idle

As we can appreciate, deploying Loki in Kubernetes using Juju involves only two commands!


Loki Charmed Operator exposes its HTTP API over port 3100.

Example 1 - Get Loki version:

/loki/api/v1/status/buildinfo exposes the build information in a JSON object. The fields are version, revision, branch, buildDate, buildUser, and goVersion.

loki_ip=$(juju status loki-k8s/0 | grep "loki-k8s/0" | awk '{print $4}')

curl http://$loki_ip:3100/loki/api/v1/status/buildinfo

Example 2 - Send logs entries to Loki with curl:

/loki/api/v1/push is the endpoint used to send log entries to Loki. The default behavior is for the POST body to be a snappy-compressed protobuf message. Alternatively, if the Content-Type header is set to application/json, a JSON post body can be sent in the following format:

loki_ip=$(juju status loki-k8s/0 | grep "loki-k8s/0" | awk '{print $4}')

curl -v -H "Content-Type: application/json" -XPOST -s "http://$loki_ip:3100/loki/api/v1/push" --data-raw \
  '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}'

Example 3 - Send logs entries to Loki with Promtail:

Promtail is an agent which ships the contents of local logs to Loki. It is usually deployed to every machine that has applications needed to be monitored.

It primarily:

  • Discovers targets
  • Attaches labels to log streams
  • Pushes them to the Loki instance.

Currently, Promtail can tail logs from two sources: local log files and the systemd journal (on AMD64 machines only).

To set up a Promtail instance to work with Loki Charmed Operator please refer to Configuring Promtail documentation. Anyway the most important part is the clients section in Promtail config file, for instance:

  - url: http://<LOKI_ADDRESS>:3100/loki/api/v1/push

Network Requirements

By default, the promtail binary injected into the container will be downloaded from the internet. Specifically, the charm needs to be able to access the following domains:

If the container has limited network access, charm administrators can provide their own promtail binary at runtime. To do so, refer to the library documentation.

OCI Images

Every release of the Loki Charmed Operator uses the latest stable version of grafana/loki at the time of release.

Integrating with external (non-charmed) workloads

You can integrate loki-k8s with any workload, even if it’s not managed by Juju, by setting up a Grafana Agent instance to forward logs to it.

First, you’ll likely need an ingress integration with traefik-k8s to give your loki-k8s deployment a stable, external-facing url.

Once you have the url for loki, you can use it to configure Grafana Agent to forward logs to it.

You can do this with all charms in COS Lite!

Official Documentation

For further details about Loki configuration and usage, please refer to Grafana Loki Documentation


Level Path Navlink
1 overview Overview
1 relations Relations


Having an example IP address is pretty straightforward but if we want something copyable then maybe something like

alertmanager_ip=$(juju status alertmanager/0 --format=json | \
  jq -r ".applications.alertmanager.units.\"alertmanager/0\".address")

If deployed from charmhub then strictly speaking it is not the latest image. Maybe change to “Every release of the loki charm uses the latest stable version of loki at the time of release.”

1 Like

Thanks Leon!

@jose I had to run juju trust loki-k8s --scope=cluster in order to get it to work (stable rev 91). Otherwise, the charm stays in BlockedStatus with

unit-loki-k8s-0: 14:58:18 ERROR unit.loki-k8s/0.juju-log Failed to apply resource limit patch: statefulsets.apps "loki-k8s" is forbidden: User "system:serviceaccount:observability:loki-k8s" cannot get resource "statefulsets" in API group "apps" in the namespace "observability"

Hi @bartz


That’s because we are patching the StatefulSets… anyway, we are going to change this, so in the future you will not have to do it.

1 Like