From df288d7f19d75d923f0f6ccdbe6fe846082d8129 Mon Sep 17 00:00:00 2001 From: Thomas Krampl Date: Fri, 12 Jun 2026 12:03:42 +0200 Subject: [PATCH 1/3] Update label docs to remove prefix requirement Document that labels follow standard Kubernetes syntax without a `labels.nais.io/` prefix, update examples accordingly, and clarify that internal labels (`app`, `team`, and keys containing `nais.io/`) are hidden in Console and API views. --- docs/operate/explanations/labels.md | 16 ++++++++++++---- docs/operate/how-to/labels.md | 8 ++++---- docs/operate/reference/labels.md | 23 ++++++++++++++++++----- 3 files changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/operate/explanations/labels.md b/docs/operate/explanations/labels.md index b8694216..eb3d4d8d 100644 --- a/docs/operate/explanations/labels.md +++ b/docs/operate/explanations/labels.md @@ -10,16 +10,24 @@ A label might describe ownership, a project, an environment grouping, or anythin ## How labels work on Nais -Labels on Nais are regular [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) with one requirement: the key must use the `labels.nais.io/` prefix. +Labels on Nais are regular [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). You can use any key and value that follows the standard Kubernetes label syntax — no special prefix is required. ```text -labels.nais.io/: +: ``` -This prefix keeps your own labels clearly separated from the labels that Nais manage internally, so the two never collide. - When you set a label on a resource, Nais keeps it verbatim and propagates it to the underlying Kubernetes resources that the resource owns. For a [workload](../../workloads/README.md), this means the label is also applied to the resources Nais generates on your behalf. +## Hidden labels + +Nais surfaces all labels on your resources, except for a few that Nais and Kubernetes manage internally. The following labels are hidden in [Nais Console](../console/README.md) and the [Nais API](../console/api.md): + +- the `app` label +- the `team` label +- any label whose key contains the substring `nais.io/` + +These labels are still present on the underlying Kubernetes resources — they are only hidden from the Nais-managed views. + ## Where you can use labels You can define labels on any of the Kubernetes resources that Nais supports, under `metadata.labels`. diff --git a/docs/operate/how-to/labels.md b/docs/operate/how-to/labels.md index a69e44bb..c795d771 100644 --- a/docs/operate/how-to/labels.md +++ b/docs/operate/how-to/labels.md @@ -8,7 +8,7 @@ This guide shows you how to add [labels](../explanations/labels.md) to your reso ## Add labels in your manifest -Add your labels under `metadata.labels`, using the `labels.nais.io/` prefix: +Add your labels under `metadata.labels`: === "app.yaml" @@ -19,8 +19,8 @@ Add your labels under `metadata.labels`, using the `labels.nais.io/` prefix: name: namespace: labels: - labels.nais.io/team-area: payments - labels.nais.io/sensitive: "true" + team-area: payments + cost-center: "1234" spec: ... ``` @@ -33,7 +33,7 @@ You can add and edit labels from Console for [Valkey](../../persistence/valkey/R 1. Open [Nais Console](<>) and navigate to the resource you want to label. 2. Find the **Labels** section in the sidebar and click the edit icon. -3. Enter a key and a value. The `labels.nais.io/` prefix is added automatically. +3. Enter a key and a value. 4. Click **Add label** to add more labels. 5. Click **Save**. diff --git a/docs/operate/reference/labels.md b/docs/operate/reference/labels.md index 536c2f1e..1b434d8e 100644 --- a/docs/operate/reference/labels.md +++ b/docs/operate/reference/labels.md @@ -11,21 +11,34 @@ Labels are user-defined key-value pairs used to organize and categorize your res A label consists of a key and a value: ```text -labels.nais.io/: +: ``` | Part | Description | |:-----|:------------| -| `labels.nais.io/` | Required prefix. It is the only constraint Nais adds on top of the standard Kubernetes label rules. | | `` | Your label name. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | | `` | Your label value. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | +No Nais-specific prefix is required. + ## Behavior - Labels are kept **verbatim** — Nais does not rewrite or strip them. - Labels are **propagated** to the underlying Kubernetes resources that the resource owns. - Labels carry **no special meaning** to Nais. They are only used for your own organization. +## Hidden labels + +[Nais Console](../console/README.md) and the [Nais API](../console/api.md) surface all labels on a resource, except for the following internal labels, which are hidden: + +| Label key | Match | +|:----------|:------| +| `app` | Exact match | +| `team` | Exact match | +| `*nais.io/*` | Any key containing the substring `nais.io/` | + +Hidden labels remain present on the underlying Kubernetes resources. + ## Setting labels Labels are defined under `metadata.labels` for any Kubernetes resource that Nais supports: @@ -37,13 +50,13 @@ metadata: name: myapplication namespace: myteam labels: - labels.nais.io/team-area: payments - labels.nais.io/sensitive: "true" + team-area: payments + cost-center: "1234" spec: ... ``` -Labels can also be added and edited from [Nais Console](../console/README.md) for [Valkey](../../persistence/valkey/README.md), [OpenSearch](../../persistence/opensearch/README.md), [Config](../../services/config/README.md), and [Secret](../../services/secrets/README.md). +Labels can also be added and edited from [Nais Console](../console/README.md) for [Valkey](../../persistence/valkey/README.md), [OpenSearch](../../persistence/opensearch/README.md), [Config](../../services/config/README.md), and [Secret](../../services/secrets/README.md). ## Related pages From af466d8c3886b5b8dd76d77e8eebb6fd1a824058 Mon Sep 17 00:00:00 2001 From: Thomas Krampl Date: Fri, 12 Jun 2026 13:21:55 +0200 Subject: [PATCH 2/3] No need to mention prefix --- docs/operate/explanations/labels.md | 2 +- docs/operate/reference/labels.md | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/operate/explanations/labels.md b/docs/operate/explanations/labels.md index eb3d4d8d..5f6bb7bf 100644 --- a/docs/operate/explanations/labels.md +++ b/docs/operate/explanations/labels.md @@ -10,7 +10,7 @@ A label might describe ownership, a project, an environment grouping, or anythin ## How labels work on Nais -Labels on Nais are regular [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). You can use any key and value that follows the standard Kubernetes label syntax — no special prefix is required. +Labels on Nais are regular [Kubernetes labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). You can use any key and value that follows the standard Kubernetes label syntax. ```text : diff --git a/docs/operate/reference/labels.md b/docs/operate/reference/labels.md index 1b434d8e..92f4c22e 100644 --- a/docs/operate/reference/labels.md +++ b/docs/operate/reference/labels.md @@ -19,8 +19,6 @@ A label consists of a key and a value: | `` | Your label name. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | | `` | Your label value. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). | -No Nais-specific prefix is required. - ## Behavior - Labels are kept **verbatim** — Nais does not rewrite or strip them. From 258619f07714105faf7a4fdee6926dca7867af0f Mon Sep 17 00:00:00 2001 From: Thomas Krampl Date: Fri, 12 Jun 2026 13:24:07 +0200 Subject: [PATCH 3/3] No more cost center Co-authored-by: Frode Sundby --- docs/operate/how-to/labels.md | 2 +- docs/operate/reference/labels.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/operate/how-to/labels.md b/docs/operate/how-to/labels.md index c795d771..a502e253 100644 --- a/docs/operate/how-to/labels.md +++ b/docs/operate/how-to/labels.md @@ -20,7 +20,7 @@ Add your labels under `metadata.labels`: namespace: labels: team-area: payments - cost-center: "1234" + sensitive: "true" spec: ... ``` diff --git a/docs/operate/reference/labels.md b/docs/operate/reference/labels.md index 92f4c22e..13a86d9e 100644 --- a/docs/operate/reference/labels.md +++ b/docs/operate/reference/labels.md @@ -49,7 +49,7 @@ metadata: namespace: myteam labels: team-area: payments - cost-center: "1234" + sensitive: "true" spec: ... ```