Skip to content

Commit 7c36ed2

Browse files
annasong20annasong20
authored
Document AnnotationsTransformer (#5247)
* Restructure existing Reference docs Restructure Reference section for site to better match k8s.io. Change descriptions to complete sentences. Improve instructions to locally load site. * Document AnnotationsTransformer on site Dcoument AnnotationsTransformer API under Reference on site. * Document required fields Document required fields and explain effects of optional ones. * Make site setup instructions more explicit * Link required K8s fields
1 parent 985835f commit 7c36ed2

File tree

11 files changed

+134
-33
lines changed

11 files changed

+134
-33
lines changed

‎site/README.md

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,28 @@ docker-compomse up -d
2323
```
2424

2525
### hugo
26-
Building using the `hugo` command requires the following dependencies:
27-
* [hugo CLI](https://gohugo.io/getting-started/installing/)
28-
* [Go](https://go.dev/learn/)
29-
* [Node.js](https://nodejs.org/en/)
30-
* npm dependencies
26+
1. Building using the `hugo` command requires the following dependencies:
27+
* [hugo CLI](https://gohugo.io/getting-started/installing/)
28+
* [Go](https://go.dev/learn/)
29+
* [Node.js](https://nodejs.org/en/)
30+
* npm dependencies
31+
```bash
32+
npm install -D autoprefixer
33+
npm install -D postcss-cli
34+
npm install -D postcss
35+
```
36+
1. Initialize [Docsy](https://www.docsy.dev/docs/) and nested [submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
3137
```bash
32-
npm install -D autoprefixer
33-
npm install -D postcss-cli
34-
npm install -D postcss
38+
# In Kustomize repository root directory, fetch docsy submodule at site/themes/docsy.
39+
# See alternative submodule cloning options in the submodule documentation linked above.
40+
git submodule init
41+
git submodule update
42+
# Fetch submodules nested in docsy.
43+
cd site/themes/docsy
44+
git submodule init
45+
git submodule update
46+
```
47+
1. Start in development mode:
48+
```bash
49+
hugo serve -D
3550
```
36-
Start in development mode:
37-
```bash
38-
hugo serve -D
39-
```

‎site/content/en/docs/Reference/API/Common Definitions/FieldSpec.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "FieldSpec"
3+
linkTitle: "FieldSpec"
4+
weight: 1
5+
date: 2023-07-28
6+
description: >
7+
FieldSpec specifies a field for Kustomize to target.
8+
---
9+
10+
* **group** (string)
11+
12+
Kubernetes group that this FieldSpec applies to.
13+
If empty, this FieldSpec applies to all groups.
14+
Currently, there is no way to specify only the core group, which is also represented by the empty string.
15+
16+
* **version** (string)
17+
18+
Kubernetes version that this FieldSpec applies to.
19+
If empty, this FieldSpec applies to all versions.
20+
21+
* **kind** (string)
22+
23+
Kubernetes kind that this FieldSpec applies to.
24+
If empty, this FieldSpec applies to all kinds.
25+
26+
* **path** (string)
27+
28+
Path to target field. Fields in path are delimited by forward slashes "/".
29+
30+
* **create** (bool)
31+
32+
If true, creates fields in **path** not already present.

‎site/content/en/docs/Reference/API/Common Definitions/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "Common Definitions"
3+
linkTitle: "Common Definitions"
4+
weight: 10
5+
date: 2023-07-28
6+
description: >
7+
Common definitions are fields used across the Kustomize API.
8+
---

‎site/content/en/docs/Reference/API/Transformers/AnnotationsTransformer.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: "AnnotationsTransformer"
3+
linkTitle: "AnnotationsTransformer"
4+
weight: 1
5+
date: 2023-07-28
6+
description: >
7+
AnnotationsTransformer adds annotations to user-input resources.
8+
---
9+
10+
See [Transformers]({{< relref "../Transformers" >}}) for common required fields.
11+
12+
* **apiVersion**: builtin
13+
* **kind**: AnnotationsTransformer
14+
* **metadata** ([ObjectMeta](https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/object-meta/#ObjectMeta))
15+
16+
Standard object's metadata.
17+
18+
* **annotations** (map[string]string)
19+
20+
Map of annotations that AnnotationsTransformer will add to resources.
21+
22+
If not specified, AnnotationsTransformer leaves the resources unchanged.
23+
24+
* **fieldSpecs** (\[\][FieldSpec]({{< relref "../Common%20Definitions/FieldSpec.md" >}}))
25+
26+
fieldSpecs specifies the field on each resource that AnnotationsTransformer should add the annotations to.
27+
It essentially allows the user to re-define the field path of the Kubernetes annotations field from `metadata/annotations` for different resources.
28+
29+
If not specified, AnnotationsTransformer applies the annotations to the `metadata/annotations` field of all resources.

‎site/content/en/docs/Reference/API/Transformers/_index.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: "Transformers"
3+
linkTitle: "Transformers"
4+
weight: 3
5+
date: 2023-07-28
6+
description: >
7+
Transformers have the ability to modify user-input resources.
8+
---
9+
10+
Transformers are Kubernetes objects that dictate how Kustomize changes other Kubernetes objects that users provide.
11+
Besides `spec`, transformers require the same [fields](https://kubernetes.io/docs/concepts/overview/working-with-objects/#required-fields), listed below, as other Kubernetes objects:
12+
13+
* `apiVersion`
14+
* `kind`
15+
* `metadata`
16+
* `name`

‎site/content/en/docs/Reference/API/_index.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: "API"
3+
linkTitle: "API"
4+
weight: 2
5+
date: 2023-07-28
6+
description: >
7+
The Kustomize API is the set of custom resources that define its behavior.
8+
---
9+
10+
This section contains user-friendly definitions of resources custom to Kustomize that define its behavior.
11+
Required fields are marked as such.

‎site/content/en/docs/Reference/kustomization_file.md renamed to ‎site/content/en/docs/Reference/API/kustomization_file.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: "Kustomization File"
33
linkTitle: "Kustomization File"
44
weight: 1
5-
date: 2017-01-05
5+
date: 2023-07-28
66
description: >
7-
Reference for the Kustomization file
7+
The Kustomization file is the entry point for Kustomize execution.
88
---

‎site/content/en/docs/Reference/CLI/_index.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: "CLI"
3+
linkTitle: "CLI"
4+
weight: 3
5+
date: 2023-07-28
6+
description: >
7+
The command line tools to interact with Kustomize.
8+
---

‎site/content/en/docs/Reference/_index.md

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,7 @@
22
title: "Reference"
33
linkTitle: "Reference"
44
weight: 9
5+
date: 2023-07-28
56
description: >
6-
Low level reference docs for your project.
7+
References are the low-level definitions in Kustomize.
78
---
8-
9-
{{% pageinfo %}}
10-
This is a placeholder page that shows you how to use this template site.
11-
{{% /pageinfo %}}
12-
13-
If your project has an API, configuration, or other reference - anything that users need to look up that’s at an even lower level than a single task - put (or link to it) here. You can serve and link to generated reference docs created using Doxygen,
14-
Javadoc, or other doc generation tools by putting them in your `static/` directory. Find out more in [Adding static content](https://docsy.dev/docs/adding-content/content/#adding-static-content). For OpenAPI reference, Docsy also provides a [Swagger UI layout and shortcode](https://www.docsy.dev/docs/adding-content/shortcodes/#swaggerui) that renders [Swagger UI](https://swagger.io/tools/swagger-ui/) using any OpenAPI YAML or JSON file as source.

‎site/content/en/docs/Reference/glossary.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
22
title: "Glossary"
33
linkTitle: "Glossary"
4-
weight: 3
5-
date: 2017-01-05
4+
weight: 1
5+
date: 2023-07-28
66
description: >
7-
Definitions of the terminology used when interacting with kustomize
7+
Glossary defines terminology used to interact with Kustomize.
88
---

0 commit comments

Comments
 (0)