From df288d7f19d75d923f0f6ccdbe6fe846082d8129 Mon Sep 17 00:00:00 2001
From: Thomas Krampl <thomas.siegfried.krampl@nav.no>
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/<key>: <value>
+<key>: <value>
 ```
 
-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: <MY-APP>
       namespace: <MY-TEAM>
       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](<<tenant_url("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/<key>: <value>
+<key>: <value>
 ```
 
 | Part | Description |
 |:-----|:------------|
-| `labels.nais.io/` | Required prefix. It is the only constraint Nais adds on top of the standard Kubernetes label rules. |
 | `<key>` | Your label name. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). |
 | `<value>` | 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 <thomas.siegfried.krampl@nav.no>
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
 <key>: <value>
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:
 | `<key>` | Your label name. Must follow the [Kubernetes label syntax](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#syntax-and-character-set). |
 | `<value>` | 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 <thomas.siegfried.krampl@nav.no>
Date: Fri, 12 Jun 2026 13:24:07 +0200
Subject: [PATCH 3/3] No more cost center

Co-authored-by: Frode Sundby <frode.sundby@nav.no>
---
 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: <MY-TEAM>
       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:
   ...
 ```
