Skip to content

Commit d495a37

Browse files
dangrondahldangrondahl
committed
docs: add managing tags page and environment tagging guide
Closes #190
1 parent 66dcf74 commit d495a37

3 files changed

Lines changed: 272 additions & 1 deletion

File tree

‎administration/managing_tags.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
title: Managing Tags
3+
description: Use tags to label and organize Kosli resources with custom key-value pairs via Terraform, CLI, or API.
4+
---
5+
6+
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.
7+
8+
## Why use tags
9+
10+
- **Organize resources** — group related flows or environments by team, project, region, or any other dimension.
11+
- **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`.
12+
- **Add operational metadata** — store context such as cost center, service tier, or owner directly on the resource.
13+
14+
## Supported resources
15+
16+
You can tag the following Kosli resource types:
17+
18+
| Resource type | Terraform resource | CLI identifier |
19+
| :--- | :--- | :--- |
20+
| Flow | [`kosli_flow`](/terraform-reference/resources/flow) | `flow` |
21+
| Environment | [`kosli_environment`](/terraform-reference/resources/environment) | `env` |
22+
23+
## Tag key and value rules
24+
25+
- **Keys** must start with a letter or digit and can contain letters, digits, hyphens (`-`), underscores (`_`), dots (`.`), and tildes (`~`).
26+
- **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.
27+
- There is no fixed limit on the number of tags per resource, but keep them concise for readability.
28+
29+
## Add or update tags
30+
31+
<Tabs>
32+
<Tab title="Terraform" icon="cubes">
33+
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.
34+
35+
Tag an environment:
36+
37+
```hcl
38+
resource "kosli_environment" "production" {
39+
name = "production-k8s"
40+
type = "K8S"
41+
description = "Production Kubernetes cluster"
42+
tags = {
43+
region = "eu-west-1"
44+
tier = "critical"
45+
managed-by = "platform-team"
46+
}
47+
}
48+
```
49+
50+
Tag a flow:
51+
52+
```hcl
53+
resource "kosli_flow" "api_service" {
54+
name = "api-service"
55+
description = "API service pipeline"
56+
tags = {
57+
team = "platform"
58+
risk-level = "high"
59+
}
60+
}
61+
```
62+
63+
See the [`kosli_environment` resource](/terraform-reference/resources/environment) and [`kosli_flow` resource](/terraform-reference/resources/flow) for the full schema.
64+
</Tab>
65+
<Tab title="CLI" icon="terminal">
66+
Pass one or more `--set` flags with `key=value` pairs. If a key already exists, its value is updated:
67+
68+
```shell
69+
kosli tag flow my-flow \
70+
--set team=platform \
71+
--set risk-level=high
72+
```
73+
74+
```shell
75+
kosli tag env production \
76+
--set region=eu-west-1 \
77+
--set tier=critical
78+
```
79+
80+
See [`kosli tag`](/client_reference/kosli_tag) for all flags and options.
81+
</Tab>
82+
<Tab title="API" icon="code">
83+
Use the tags endpoint with `set_tags`:
84+
85+
<CodeGroup>
86+
```shell EU
87+
curl -X PATCH "https://app.kosli.com/api/v2/tags/{org}/flow/my-flow" \
88+
-H "Authorization: Bearer $KOSLI_API_TOKEN" \
89+
-H "Content-Type: application/json" \
90+
-d '{
91+
"set_tags": {"team": "platform", "risk-level": "high"}
92+
}'
93+
```
94+
```shell US
95+
curl -X PATCH "https://app.us.kosli.com/api/v2/tags/{org}/flow/my-flow" \
96+
-H "Authorization: Bearer $KOSLI_API_TOKEN" \
97+
-H "Content-Type: application/json" \
98+
-d '{
99+
"set_tags": {"team": "platform", "risk-level": "high"}
100+
}'
101+
```
102+
</CodeGroup>
103+
</Tab>
104+
</Tabs>
105+
106+
## Remove tags
107+
108+
<Tabs>
109+
<Tab title="Terraform" icon="cubes">
110+
Remove individual tags by deleting them from the `tags` map. Set `tags = {}` to remove all tags:
111+
112+
```hcl
113+
resource "kosli_environment" "production" {
114+
name = "production-k8s"
115+
type = "K8S"
116+
tags = {}
117+
}
118+
```
119+
</Tab>
120+
<Tab title="CLI" icon="terminal">
121+
Pass one or more `--unset` flags with the keys to remove:
122+
123+
```shell
124+
kosli tag env production \
125+
--unset region
126+
```
127+
</Tab>
128+
<Tab title="API" icon="code">
129+
Use the tags endpoint with `remove_tags`:
130+
131+
<CodeGroup>
132+
```shell EU
133+
curl -X PATCH "https://app.kosli.com/api/v2/tags/{org}/env/production" \
134+
-H "Authorization: Bearer $KOSLI_API_TOKEN" \
135+
-H "Content-Type: application/json" \
136+
-d '{
137+
"remove_tags": ["region"]
138+
}'
139+
```
140+
```shell US
141+
curl -X PATCH "https://app.us.kosli.com/api/v2/tags/{org}/env/production" \
142+
-H "Authorization: Bearer $KOSLI_API_TOKEN" \
143+
-H "Content-Type: application/json" \
144+
-d '{
145+
"remove_tags": ["region"]
146+
}'
147+
```
148+
</CodeGroup>
149+
</Tab>
150+
</Tabs>
151+
152+
## Read tags
153+
154+
<Tabs>
155+
<Tab title="Terraform" icon="cubes">
156+
Use data sources to read tags from existing resources:
157+
158+
```hcl
159+
data "kosli_environment" "production" {
160+
name = "production-k8s"
161+
}
162+
163+
output "production_tags" {
164+
value = data.kosli_environment.production.tags
165+
}
166+
167+
output "managed_by" {
168+
value = try(data.kosli_environment.production.tags["managed-by"], "unknown")
169+
}
170+
```
171+
</Tab>
172+
<Tab title="API" icon="code">
173+
Tags are included in the resource response when you fetch an environment or flow via the API.
174+
</Tab>
175+
</Tabs>
176+
177+
## Recommended tag patterns
178+
179+
A consistent tagging strategy makes it easier to organize resources as your Kosli usage grows. Here are common patterns:
180+
181+
| Tag key | Example values | Purpose |
182+
| :--- | :--- | :--- |
183+
| `tier` | `dev`, `staging`, `prod` | Distinguish environment stages |
184+
| `team` | `platform`, `payments`, `mobile` | Identify the owning team |
185+
| `region` | `eu-west-1`, `us-east-1` | Track geographic location |
186+
| `risk-level` | `high`, `medium`, `low` | Drive conditional policy behavior |
187+
| `cost-center` | `eng-1234`, `ops-5678` | Map to internal accounting |
188+
189+
<Tip>
190+
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.
191+
</Tip>
192+
193+
### Example: categorizing environments by stage
194+
195+
Tag your environments to reflect their deployment stage. This lets you quickly identify which environments are production-critical and apply policies accordingly:
196+
197+
<Tabs>
198+
<Tab title="Terraform" icon="cubes">
199+
```hcl
200+
resource "kosli_environment" "staging_k8s" {
201+
name = "staging-k8s"
202+
type = "K8S"
203+
description = "Staging Kubernetes cluster"
204+
tags = {
205+
tier = "staging"
206+
team = "platform"
207+
region = "eu-west-1"
208+
}
209+
}
210+
211+
resource "kosli_environment" "production_k8s" {
212+
name = "production-k8s"
213+
type = "K8S"
214+
description = "Production Kubernetes cluster"
215+
tags = {
216+
tier = "prod"
217+
team = "platform"
218+
region = "eu-west-1"
219+
}
220+
}
221+
```
222+
</Tab>
223+
<Tab title="CLI" icon="terminal">
224+
```shell
225+
kosli tag env staging-k8s \
226+
--set tier=staging \
227+
--set team=platform \
228+
--set region=eu-west-1
229+
```
230+
231+
```shell
232+
kosli tag env production-k8s \
233+
--set tier=prod \
234+
--set team=platform \
235+
--set region=eu-west-1
236+
```
237+
</Tab>
238+
</Tabs>
239+
240+
## Using tags in policies
241+
242+
Tags become powerful when combined with [Environment Policies](/getting_started/policies). You can reference flow tags in policy expressions to conditionally require attestations:
243+
244+
```yaml
245+
attestations:
246+
- if: ${{ flow.tags.risk-level == "high" }}
247+
name: security-scan
248+
type: snyk
249+
```
250+
251+
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.
252+
253+
For the full expression syntax, see the [Environment Policy reference](/policy-reference/environment_policy).

‎config/navigation.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,8 @@
5252
"pages": [
5353
"administration/managing_custom_attestation_types/overview"
5454
]
55-
}
55+
},
56+
"administration/managing_tags"
5657
]
5758
},
5859
{

‎getting_started/environments.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,23 @@ by default. To establish compliance requirements, you need to attach at least on
9090
If you detach all policies from an environment, its compliance state returns to <Badge color="gray">Unknown</Badge> since there are no longer any defined requirements for artifacts running in it.
9191
</Note>
9292

93+
## Tagging environments
94+
95+
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`).
96+
97+
You can add tags via the CLI, Terraform, or the API:
98+
99+
```shell
100+
kosli tag env production-k8s \
101+
--set tier=prod \
102+
--set team=platform \
103+
--set region=eu-west-1
104+
```
105+
106+
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`.
107+
108+
For the full guide on managing tags, recommended patterns, and usage in policies, see [Managing Tags](/administration/managing_tags).
109+
93110
## Logical Environments
94111

95112
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.

0 commit comments

Comments
 (0)