Platform Process Logging

vCluster Platform writes operational logs to stdout from the platform pod. These logs cover initialization, controller reconciliation, API request handling, and runtime errors. Check these logs first when diagnosing unexpected platform behavior.

By default, logs use a human-readable console format at info level.

Log levels

Platform logging supports three log levels:

• info
• debug
• error

For a description of each level, see Platform process logs.

warning

Debug logging significantly increases log volume. Enable it only while reproducing an issue, then return to info.

To change the log level, upgrade the Helm release with the logging.level value:

helm upgrade vcluster-platform vcluster-platform \
  --repo https://charts.loft.sh \
  --namespace vcluster-platform \
  --reuse-values \
  --set logging.level=debug

Log format

vCluster Platform supports two output formats.

Console

The default console format produces human-readable output suited to manual log review:

2023-07-11 09:20:56     INFO    controller-runtime.metrics      metrics/listener.go:44  Metrics server is starting to listen    {"component": "loft", "addr": "127.0.0.1:12000"}
2023-07-11 09:20:56     INFO    initialize/context.go:68        Initialize...   {"component": "loft"}
2023-07-11 09:20:56     INFO    initialize/context.go:72        Ensure certificates...  {"component": "loft"}

JSON

The JSON format produces structured output suited to log aggregation systems such as Elasticsearch, Splunk, or Grafana Loki:

{"level":"info","ts":1689067388.209614,"logger":"controller-runtime.metrics","caller":"metrics/listener.go:44","msg":"Metrics server is starting to listen","component":"loft","addr":"127.0.0.1:12000"}
{"level":"info","ts":1689067388.2099726,"caller":"initialize/context.go:68","msg":"Initialize...","component":"loft"}
{"level":"info","ts":1689067388.2100549,"caller":"initialize/context.go:72","msg":"Ensure certificates...","component":"loft"}

Each entry contains at minimum:

Field	Type	Description
level	string	Log level (info, warn, error, debug)
ts	number	Unix timestamp (seconds since epoch)
caller	string	Source file and line number
msg	string	Log message
component	string	Platform component that emitted the log

Additional fields vary by subsystem and operation type. For example, controller events may include namespace and name while API handler logs may include method and status.

To switch to JSON format:

helm upgrade vcluster-platform vcluster-platform \
  --repo https://charts.loft.sh \
  --namespace vcluster-platform \
  --reuse-values \
  --set logging.encoding=json

View logs

kubectl logs -n vcluster-platform -l app=loft -f

In high-availability deployments, multiple platform pods run concurrently. Pipe through a log aggregator, or target a specific pod, to avoid interleaved output from multiple replicas.

File logging

Besides stdout, the platform pod can also write logs to a file. This is useful for tailing logs from a sidecar container instead of going through the container runtime's log driver.

Enable file logging with the logging.file.enabled Helm value:

helm upgrade vcluster-platform vcluster-platform \
  --repo https://charts.loft.sh \
  --namespace vcluster-platform \
  --reuse-values \
  --set logging.file.enabled=true

The log path is fixed at /var/log/vcluster-platform/platform.log and isn't configurable. Enabling this setting adds a platform-logs emptyDir volume (1Gi size limit) to the pod and mounts it into the manager container at /var/log/vcluster-platform. The chart reserves both the platform-logs volume name and the manager/audit container names, so a custom volumes, volumeMounts, or sidecarContainers entry can't reuse them.

Enabling logging.file.enabled only writes the file. Nothing reads it automatically, so add a sidecar container that mounts the reserved platform-logs volume to actually read it:

values.yaml

logging:
  file:
    enabled: true
sidecarContainers:
  - name: log-reader
    image: busybox
    command: ["sh", "-c", "tail -F /var/log/vcluster-platform/platform.log"]
    volumeMounts:
      - name: platform-logs
        mountPath: /var/log/vcluster-platform
        readOnly: true

View the sidecar's output the same way as the stdout logs above, targeting the sidecar's container name instead:

kubectl logs -n vcluster-platform -l app=loft -c log-reader -f

Distinct from tenant cluster file logging

This is the platform's own process logging. vCluster charts v0.37 and later have a separate, unrelated logging.file.enabled option for tenant cluster logs, configured in vcluster.yaml rather than the platform's Helm values.