From d495a378776f5eadf5c502861979a9d0c9622c22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Thu, 30 Apr 2026 15:55:12 +0200 Subject: [PATCH] docs: add managing tags page and environment tagging guide Closes #190 --- administration/managing_tags.md | 253 ++++++++++++++++++++++++++++++++ config/navigation.json | 3 +- getting_started/environments.md | 17 +++ 3 files changed, 272 insertions(+), 1 deletion(-) create mode 100644 administration/managing_tags.md diff --git a/administration/managing_tags.md b/administration/managing_tags.md new file mode 100644 index 0000000..dce25bc --- /dev/null +++ b/administration/managing_tags.md @@ -0,0 +1,253 @@ +--- +title: Managing Tags +description: Use tags to label and organize Kosli resources with custom key-value pairs via Terraform, CLI, or API. +--- + +Tags are custom key-value pairs you attach to Kosli resources. They let you categorize, filter, and add metadata to your flows and environments without changing the resources themselves. + +## Why use tags + +- **Organize resources** — group related flows or environments by team, project, region, or any other dimension. +- **Drive policy behavior** — reference tags in [Environment Policy](/getting_started/policies) expressions to make attestation requirements conditional. For example, require security scans only for flows tagged `risk-level=high`. +- **Add operational metadata** — store context such as cost center, service tier, or owner directly on the resource. + +## Supported resources + +You can tag the following Kosli resource types: + +| Resource type | Terraform resource | CLI identifier | +| :--- | :--- | :--- | +| Flow | [`kosli_flow`](/terraform-reference/resources/flow) | `flow` | +| Environment | [`kosli_environment`](/terraform-reference/resources/environment) | `env` | + +## Tag key and value rules + +- **Keys** must start with a letter or digit and can contain letters, digits, hyphens (`-`), underscores (`_`), dots (`.`), and tildes (`~`). +- **Values** are strings. If a value is a valid URL (e.g. `https://example.com`), Kosli automatically renders it as a clickable link in the UI. +- There is no fixed limit on the number of tags per resource, but keep them concise for readability. + +## Add or update tags + + + + Add a `tags` map to any `kosli_environment` or `kosli_flow` resource. Tags are applied via a diff — only changed tags are sent to the API. + + Tag an environment: + + ```hcl + resource "kosli_environment" "production" { + name = "production-k8s" + type = "K8S" + description = "Production Kubernetes cluster" + tags = { + region = "eu-west-1" + tier = "critical" + managed-by = "platform-team" + } + } + ``` + + Tag a flow: + + ```hcl + resource "kosli_flow" "api_service" { + name = "api-service" + description = "API service pipeline" + tags = { + team = "platform" + risk-level = "high" + } + } + ``` + + See the [`kosli_environment` resource](/terraform-reference/resources/environment) and [`kosli_flow` resource](/terraform-reference/resources/flow) for the full schema. + + + Pass one or more `--set` flags with `key=value` pairs. If a key already exists, its value is updated: + + ```shell + kosli tag flow my-flow \ + --set team=platform \ + --set risk-level=high + ``` + + ```shell + kosli tag env production \ + --set region=eu-west-1 \ + --set tier=critical + ``` + + See [`kosli tag`](/client_reference/kosli_tag) for all flags and options. + + + Use the tags endpoint with `set_tags`: + + + ```shell EU + curl -X PATCH "https://app.kosli.com/api/v2/tags/{org}/flow/my-flow" \ + -H "Authorization: Bearer $KOSLI_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "set_tags": {"team": "platform", "risk-level": "high"} + }' + ``` + ```shell US + curl -X PATCH "https://app.us.kosli.com/api/v2/tags/{org}/flow/my-flow" \ + -H "Authorization: Bearer $KOSLI_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "set_tags": {"team": "platform", "risk-level": "high"} + }' + ``` + + + + +## Remove tags + + + + Remove individual tags by deleting them from the `tags` map. Set `tags = {}` to remove all tags: + + ```hcl + resource "kosli_environment" "production" { + name = "production-k8s" + type = "K8S" + tags = {} + } + ``` + + + Pass one or more `--unset` flags with the keys to remove: + + ```shell + kosli tag env production \ + --unset region + ``` + + + Use the tags endpoint with `remove_tags`: + + + ```shell EU + curl -X PATCH "https://app.kosli.com/api/v2/tags/{org}/env/production" \ + -H "Authorization: Bearer $KOSLI_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "remove_tags": ["region"] + }' + ``` + ```shell US + curl -X PATCH "https://app.us.kosli.com/api/v2/tags/{org}/env/production" \ + -H "Authorization: Bearer $KOSLI_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "remove_tags": ["region"] + }' + ``` + + + + +## Read tags + + + + Use data sources to read tags from existing resources: + + ```hcl + data "kosli_environment" "production" { + name = "production-k8s" + } + + output "production_tags" { + value = data.kosli_environment.production.tags + } + + output "managed_by" { + value = try(data.kosli_environment.production.tags["managed-by"], "unknown") + } + ``` + + + Tags are included in the resource response when you fetch an environment or flow via the API. + + + +## Recommended tag patterns + +A consistent tagging strategy makes it easier to organize resources as your Kosli usage grows. Here are common patterns: + +| Tag key | Example values | Purpose | +| :--- | :--- | :--- | +| `tier` | `dev`, `staging`, `prod` | Distinguish environment stages | +| `team` | `platform`, `payments`, `mobile` | Identify the owning team | +| `region` | `eu-west-1`, `us-east-1` | Track geographic location | +| `risk-level` | `high`, `medium`, `low` | Drive conditional policy behavior | +| `cost-center` | `eng-1234`, `ops-5678` | Map to internal accounting | + + +Pick a small set of tag keys and document them for your organization. Consistent keys across environments and flows make filtering and policy expressions predictable. + + +### Example: categorizing environments by stage + +Tag your environments to reflect their deployment stage. This lets you quickly identify which environments are production-critical and apply policies accordingly: + + + + ```hcl + resource "kosli_environment" "staging_k8s" { + name = "staging-k8s" + type = "K8S" + description = "Staging Kubernetes cluster" + tags = { + tier = "staging" + team = "platform" + region = "eu-west-1" + } + } + + resource "kosli_environment" "production_k8s" { + name = "production-k8s" + type = "K8S" + description = "Production Kubernetes cluster" + tags = { + tier = "prod" + team = "platform" + region = "eu-west-1" + } + } + ``` + + + ```shell + kosli tag env staging-k8s \ + --set tier=staging \ + --set team=platform \ + --set region=eu-west-1 + ``` + + ```shell + kosli tag env production-k8s \ + --set tier=prod \ + --set team=platform \ + --set region=eu-west-1 + ``` + + + +## Using tags in policies + +Tags become powerful when combined with [Environment Policies](/getting_started/policies). You can reference flow tags in policy expressions to conditionally require attestations: + +```yaml +attestations: + - if: ${{ flow.tags.risk-level == "high" }} + name: security-scan + type: snyk +``` + +In this example, the `security-scan` attestation is only required when the flow is tagged with `risk-level=high`. This lets you enforce stricter compliance for high-risk services while keeping lighter requirements for lower-risk ones. + +For the full expression syntax, see the [Environment Policy reference](/policy-reference/environment_policy). diff --git a/config/navigation.json b/config/navigation.json index 171cb9d..343227a 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -52,7 +52,8 @@ "pages": [ "administration/managing_custom_attestation_types/overview" ] - } + }, + "administration/managing_tags" ] }, { diff --git a/getting_started/environments.md b/getting_started/environments.md index fe6ff3f..dc4a5b3 100644 --- a/getting_started/environments.md +++ b/getting_started/environments.md @@ -90,6 +90,23 @@ by default. To establish compliance requirements, you need to attach at least on If you detach all policies from an environment, its compliance state returns to Unknown since there are no longer any defined requirements for artifacts running in it. +## Tagging environments + +Tags are custom key-value pairs you attach to environments to categorize, filter, and add metadata. Common patterns include tagging by deployment stage (`tier=prod`), owning team (`team=platform`), or region (`region=eu-west-1`). + +You can add tags via the CLI, Terraform, or the API: + +```shell +kosli tag env production-k8s \ + --set tier=prod \ + --set team=platform \ + --set region=eu-west-1 +``` + +Tags can also be referenced in [Environment Policy](/getting_started/policies) expressions to make attestation requirements conditional — for example, requiring security scans only for flows tagged `risk-level=high`. + +For the full guide on managing tags, recommended patterns, and usage in policies, see [Managing Tags](/administration/managing_tags). + ## Logical Environments Logical environments are a way to group your Kosli environments so you can view all changes happening in your group in the same place. For example, if what you consider to be “Production” is a combination of a Kubernetes cluster, an S3 bucket, and a configuration file, you can combine the reports sent to these Kosli environments into a “Production” logical environment.