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  10.152.183.26

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

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

Loki HTTP API

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
{"version":"2.4.1","revision":"f61a4d261","branch":"HEAD","buildUser":"root@39a6e600b2df","buildDate":"2021-11-08T13:09:51Z","goVersion":""}

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:

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

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