diff --git a/docs/operate/explanations/labels.md b/docs/operate/explanations/labels.md index b8694216..5f6bb7bf 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. ```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..a502e253 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 + sensitive: "true" 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..13a86d9e 100644 --- a/docs/operate/reference/labels.md +++ b/docs/operate/reference/labels.md @@ -11,12 +11,11 @@ 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). | @@ -26,6 +25,18 @@ labels.nais.io/: - 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 +48,13 @@ metadata: name: myapplication namespace: myteam labels: - labels.nais.io/team-area: payments - labels.nais.io/sensitive: "true" + team-area: payments + sensitive: "true" 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