Skip to content

Commit 6e3869b

Browse files
suinsuin
committed
feat: support Kubernetes list and map semantic annotations
- Add x-kubernetes-list-type (atomic, set, map) support - Add x-kubernetes-list-map-keys for composite key documentation - Add x-kubernetes-map-type (atomic, granular) support - Display merge behavior explanations in generated docs - Add examples to input.yaml demonstrating all annotation types - Refactor converter functions to reduce cognitive complexity
1 parent a9419f5 commit 6e3869b

File tree

9 files changed

+551
-47
lines changed

9 files changed

+551
-47
lines changed

‎examples/input.yaml‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ spec:
107107
categories:
108108
type: array
109109
description: "Categories the book belongs to"
110+
x-kubernetes-list-type: set
110111
items:
111112
type: string
112113
enum:
@@ -118,6 +119,42 @@ spec:
118119
- Biography
119120
uniqueItems: true
120121
maxItems: 5
122+
123+
# Example of list-type=map with single key
124+
authors:
125+
type: array
126+
description: "List of authors for this book"
127+
x-kubernetes-list-type: map
128+
x-kubernetes-list-map-keys: ["name"]
129+
items:
130+
type: object
131+
required:
132+
- name
133+
properties:
134+
name:
135+
type: string
136+
description: "Author's full name"
137+
role:
138+
type: string
139+
description: "Author's role (author, co-author, editor, etc.)"
140+
enum: ["author", "co-author", "editor", "translator"]
141+
default: "author"
142+
143+
# Example of map-type=atomic
144+
libraryMetadata:
145+
type: object
146+
description: "Internal library metadata (replaced as a unit)"
147+
x-kubernetes-map-type: atomic
148+
additionalProperties:
149+
type: string
150+
151+
# Example of map-type=granular (default behavior)
152+
customFields:
153+
type: object
154+
description: "Custom metadata fields (can be updated individually)"
155+
x-kubernetes-map-type: granular
156+
additionalProperties:
157+
type: string
121158
edition:
122159
type: object
123160
description: |
@@ -357,12 +394,41 @@ spec:
357394
allowedIPRanges:
358395
type: array
359396
description: "IP ranges allowed to connect"
397+
x-kubernetes-list-type: atomic
360398
items:
361399
type: string
362400
pattern: "^([0-9]{1,3}\\.){3}[0-9]{1,3}/[0-9]{1,2}$"
363401
example:
364402
- "10.0.0.0/8"
365403
- "192.168.1.0/24"
404+
405+
# Example of list-type=map for environment variables
406+
env:
407+
type: array
408+
description: "Environment variables for the database"
409+
x-kubernetes-list-type: map
410+
x-kubernetes-list-map-keys: ["name"]
411+
items:
412+
type: object
413+
required:
414+
- name
415+
- value
416+
properties:
417+
name:
418+
type: string
419+
description: "Environment variable name"
420+
pattern: "^[A-Z_][A-Z0-9_]*$"
421+
value:
422+
type: string
423+
description: "Environment variable value"
424+
425+
# Example of map-type=granular for configuration
426+
configOverrides:
427+
type: object
428+
description: "Database configuration overrides (individual keys can be updated)"
429+
x-kubernetes-map-type: granular
430+
additionalProperties:
431+
type: string
366432
status:
367433
type: object
368434
description: "DatabaseStatus defines the observed state of a Database"
@@ -391,6 +457,8 @@ spec:
391457
conditions:
392458
type: array
393459
description: "Current conditions of the database"
460+
x-kubernetes-list-type: map
461+
x-kubernetes-list-map-keys: ["type"]
394462
items:
395463
type: object
396464
required:
@@ -474,6 +542,8 @@ spec:
474542
env:
475543
type: array
476544
description: "Environment variables to set"
545+
x-kubernetes-list-type: map
546+
x-kubernetes-list-map-keys: ["name"]
477547
items:
478548
type: object
479549
required:
@@ -488,6 +558,29 @@ spec:
488558
type: string
489559
description: "Value of the environment variable"
490560
maxItems: 50
561+
562+
# Example of list-type=map with composite keys
563+
volumeMounts:
564+
type: array
565+
description: "Volume mounts for the application"
566+
x-kubernetes-list-type: map
567+
x-kubernetes-list-map-keys: ["name", "mountPath"]
568+
items:
569+
type: object
570+
required:
571+
- name
572+
- mountPath
573+
properties:
574+
name:
575+
type: string
576+
description: "Name of the volume to mount"
577+
mountPath:
578+
type: string
579+
description: "Path within the container to mount the volume"
580+
readOnly:
581+
type: boolean
582+
description: "Whether the volume should be mounted read-only"
583+
default: false
491584
healthCheck:
492585
type: object
493586
description: "Health check configuration"
@@ -556,6 +649,7 @@ spec:
556649
annotations:
557650
type: object
558651
description: "Annotations to add to the ingress"
652+
x-kubernetes-map-type: atomic
559653
additionalProperties:
560654
type: string
561655
status:

‎examples/per-kind-output/apps.example.com-v2-webapp.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ WebApp represents a web application deployment
1717
| `spec.replicas` | `integer` | ✓ | Number of replicas to run |
1818
| `spec.port` | `integer` | | Port the application listens on |
1919
| `spec.env` | `object[]` | | Environment variables to set |
20+
| `spec.volumeMounts` | `object[]` | | Volume mounts for the application |
2021
| `spec.healthCheck` | `object` | | Health check configuration |
2122
| `spec.autoscaling` | `object` | | Autoscaling configuration |
2223
| `spec.ingress` | `object` | | Ingress configuration |
@@ -75,6 +76,7 @@ Environment variables to set
7576
7677
- **Type:** `object[]`
7778
- **Optional**
79+
- **List type:** List items are treated as a map using `name` as the composite key - individual items can be updated independently
7880
- **Constraints**
7981
- **Max items:** `50`
8082
@@ -97,6 +99,36 @@ Value of the environment variable
9799
- **Type:** `string`
98100
- **Required**
99101
102+
### `spec.volumeMounts`
103+
104+
Volume mounts for the application
105+
106+
- **Type:** `object[]`
107+
- **Optional**
108+
- **List type:** List items are treated as a map using `name` + `mountPath` as the composite key - individual items can be updated independently
109+
110+
### `spec.volumeMounts.name`
111+
112+
Name of the volume to mount
113+
114+
- **Type:** `string`
115+
- **Required**
116+
117+
### `spec.volumeMounts.mountPath`
118+
119+
Path within the container to mount the volume
120+
121+
- **Type:** `string`
122+
- **Required**
123+
124+
### `spec.volumeMounts.readOnly`
125+
126+
Whether the volume should be mounted read-only
127+
128+
- **Type:** `boolean`
129+
- **Optional**
130+
- **Default value:** `false`
131+
100132
### `spec.healthCheck`
101133
102134
Health check configuration
@@ -228,6 +260,7 @@ Annotations to add to the ingress
228260
229261
- **Type:** `object`
230262
- **Optional**
263+
- **Map type:** The entire map is replaced as a single unit during updates
231264
232265
## Status
233266

‎examples/per-kind-output/data.example.com-v1beta1-database.md‎

Lines changed: 53 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -31,20 +31,22 @@ For detailed configuration examples, see the [Database Guide](https://docs.examp
3131

3232
## Quick Reference
3333

34-
| Field path | Type | Required | Description |
35-
| ------------------- | ---------- | -------- | --------------------------------------------------- |
36-
| `spec.engine` | `string` | ✓ | Database engine to use |
37-
| `spec.version` | `string` | ✓ | Version of the database engine |
38-
| `spec.storage` | `object` | ✓ | Storage configuration for the database |
39-
| `spec.resources` | `object` | | Resource requirements for the database |
40-
| `spec.backup` | `object` | | Backup configuration |
41-
| `spec.connections` | `object` | | Connection pool configuration |
42-
| `spec.security` | `object` | | Security configuration |
43-
| `status.phase` | `string` | | Current phase of the database |
44-
| `status.endpoint` | `string` | | Connection endpoint for the database |
45-
| `status.ready` | `boolean` | | Whether the database is ready to accept connections |
46-
| `status.lastBackup` | `string` | | Timestamp of the last successful backup |
47-
| `status.conditions` | `object[]` | | Current conditions of the database |
34+
| Field path | Type | Required | Description |
35+
| ---------------------- | ---------- | -------- | ------------------------------------------------------------ |
36+
| `spec.engine` | `string` | ✓ | Database engine to use |
37+
| `spec.version` | `string` | ✓ | Version of the database engine |
38+
| `spec.storage` | `object` | ✓ | Storage configuration for the database |
39+
| `spec.resources` | `object` | | Resource requirements for the database |
40+
| `spec.backup` | `object` | | Backup configuration |
41+
| `spec.connections` | `object` | | Connection pool configuration |
42+
| `spec.security` | `object` | | Security configuration |
43+
| `spec.env` | `object[]` | | Environment variables for the database |
44+
| `spec.configOverrides` | `object` | | Database configuration overrides (individual keys can be ... |
45+
| `status.phase` | `string` | | Current phase of the database |
46+
| `status.endpoint` | `string` | | Connection endpoint for the database |
47+
| `status.ready` | `boolean` | | Whether the database is ready to accept connections |
48+
| `status.lastBackup` | `string` | | Timestamp of the last successful backup |
49+
| `status.conditions` | `object[]` | | Current conditions of the database |
4850

4951
Note: This table shows fields up to 2 levels deep. Deeper nested fields are documented in the sections below.
5052

@@ -260,12 +262,48 @@ IP ranges allowed to connect
260262
261263
- **Type:** `string[]`
262264
- **Optional**
265+
- **List type:** The entire list is replaced as a single unit during updates
263266
- **Example**
264267
```yaml
265268
- 10.0.0.0/8
266269
- 192.168.1.0/24
267270
```
268271

272+
### `spec.env`
273+
274+
Environment variables for the database
275+
276+
- **Type:** `object[]`
277+
- **Optional**
278+
- **List type:** List items are treated as a map using `name` as the composite key - individual items can be updated independently
279+
280+
### `spec.env.name`
281+
282+
Environment variable name
283+
284+
- **Type:** `string`
285+
- **Required**
286+
- **Constraints**
287+
- **Pattern:**
288+
```regex
289+
^[A-Z_][A-Z0-9_]*$
290+
```
291+
292+
### `spec.env.value`
293+
294+
Environment variable value
295+
296+
- **Type:** `string`
297+
- **Required**
298+
299+
### `spec.configOverrides`
300+
301+
Database configuration overrides (individual keys can be updated)
302+
303+
- **Type:** `object`
304+
- **Optional**
305+
- **Map type:** Individual map keys can be updated independently
306+
269307
## Status
270308
271309
### `status.phase`
@@ -305,6 +343,7 @@ Current conditions of the database
305343
306344
- **Type:** `object[]`
307345
- **Optional**
346+
- **List type:** List items are treated as a map using `type` as the composite key - individual items can be updated independently
308347
309348
### `status.conditions.type`
310349

‎examples/per-kind-output/library.example.com-v1-book.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,9 @@ spec:
4545
| `spec.summary` | `string` | | Brief summary of the book's content. This summary should ... |
4646
| `spec.language` | `string` | | Language of the book |
4747
| `spec.categories` | `string[]` | | Categories the book belongs to |
48+
| `spec.authors` | `object[]` | | List of authors for this book |
49+
| `spec.libraryMetadata` | `object` | | Internal library metadata (replaced as a unit) |
50+
| `spec.customFields` | `object` | | Custom metadata fields (can be updated individually) |
4851
| `spec.edition` | `object` | | Edition information for the book with \*\*special handling\*... |
4952
| `status.available` | `boolean` | | Whether the book is currently available for borrowing |
5053
| `status.lastBorrowed` | `string` | | Last time the book was borrowed |
@@ -137,10 +140,52 @@ Categories the book belongs to
137140

138141
- **Type:** `string[]`
139142
- **Optional**
143+
- **List type:** List items are treated as a set - no duplicates allowed, order doesn't matter
140144
- **Constraints**
141145
- **Max items:** `5`
142146
- **Unique items:** Yes
143147

148+
### `spec.authors`
149+
150+
List of authors for this book
151+
152+
- **Type:** `object[]`
153+
- **Optional**
154+
- **List type:** List items are treated as a map using `name` as the composite key - individual items can be updated independently
155+
156+
### `spec.authors.name`
157+
158+
Author's full name
159+
160+
- **Type:** `string`
161+
- **Required**
162+
163+
### `spec.authors.role`
164+
165+
Author's role (author, co-author, editor, etc.)
166+
167+
- **Type:** `string`
168+
- **Optional**
169+
- **Constraints**
170+
- **Allowed values:** `"author"`, `"co-author"`, `"editor"`, `"translator"`
171+
- **Default value:** `author`
172+
173+
### `spec.libraryMetadata`
174+
175+
Internal library metadata (replaced as a unit)
176+
177+
- **Type:** `object`
178+
- **Optional**
179+
- **Map type:** The entire map is replaced as a single unit during updates
180+
181+
### `spec.customFields`
182+
183+
Custom metadata fields (can be updated individually)
184+
185+
- **Type:** `object`
186+
- **Optional**
187+
- **Map type:** Individual map keys can be updated independently
188+
144189
### `spec.edition`
145190

146191
Edition information for the book with **special handling** for rare editions.

0 commit comments

Comments
 (0)