Overview

Mimir and Loki are multi-tenant systems. In kubriX, authentication and tenant isolation are enforced at the gateway layer using an nginx reverse proxy.

During installation, kubriX automatically creates a default tenant. This tenant is used for all telemetry data ingested from kubriX Hub and Spoke clusters in your Kubernetes environment.

Additional tenants can be used if you want to ingest data from other sources and keep that data logically separated.

Authentication and tenant isolation

Mimir and Loki expose a gateway that handles authentication. kubriX configures this gateway with an authentication layer and maps the authenticated username to the tenant ID.

Specifically:

• Clients authenticate using defined credentials
• The nginx gateway sets the header
  X-Scope-OrgID = $remote_user
• Mimir and Loki use this header as the tenant identifier

As a result, a client can only read and write data belonging to its own tenant.

Clients such as Alloy or Prometheus must therefore be configured with valid tenant credentials when sending or querying data.

The monitoring stack shipped with kubriX is already configured:

• Alloy automatically uses the default tenant credentials
• Grafana datasources are preconfigured with the same credentials

No manual setup is required for built-in kubriX components.

External clients

If you connect external systems (outside kubriX Hub or Spokes) to Mimir or Loki, you must configure authentication manually.

Because these systems are outside kubriX trust boundaries, it is strongly recommended to create separate tenant credentials for each external client or system.

This ensures:

• isolation between data sources
• limited blast radius if credentials leak
• auditability of data origin
• isolated metrics cardinality management

Tenant lifecycle

Tenants do not need to be created explicitly in Mimir or Loki.

A tenant is created automatically the first time data is ingested with a new X-Scope-OrgID value.

Therefore, onboarding a new tenant consists only of:

1. creating credentials
2. configuring the client to use them

Creating tenant credentials

Tenant credentials are managed in Vault.

To create credentials, follow the runbooks:

• Loki: backstage-resources/docs/runbooks/loki.md#create-loki-tenant-credentials
• Mimir: backstage-resources/docs/runbooks/mimir.md#create-mimir-tenant-credentials

Once credentials exist in Vault, they are automatically synced into the gateway authentication configuration.

Using tenant credentials in agents

Monitoring agents (for example Alloy or Prometheus) must retrieve credentials securely. Recommended approaches:

• External Secrets Operator (preferred and automatically done for kubriX k8s-monitoring helm chart)
• Secret injection via any other custom platform tooling or customer specific procedure

Changing tenant for kubriX monitoring agents

To configure kubriX-managed monitoring agents to use a different tenant, override the following values in your customer-specific Helm values file:

.writeCredentials.mimirCreds.tenant
.writeCredentials.lokiCreds.tenant

Support

If you need help creating tenants, configuring credentials, or integrating external systems, contact kubriX support.