File: README.md

package info (click to toggle)
golang-k8s-sigs-kustomize-api 0.19.0%2Bds-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 3,732 kB
  • sloc: makefile: 206; sh: 67
file content (94 lines) | stat: -rw-r--r-- 2,941 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
# kustomize plugins

This directory holds [kustomize plugins][extending kustomize],
each in its own sub-directory.
 
### Directories
 
 * `builtin`
 
   These are plugins written as [Go plugins].
   
   They are converted to statically linked code in the
   kustomize binary by a code generator ([pluginator]) at
   kustomize build time.
   
   They are maintained as part of kustomize.

 * `someteam.example.com/v1`

   Example plugins, maintained
   and tested by the kustomize maintainers,
   but not built-in to kustomize.
   
   Some of these might get promoted to `builtin` someday,
   as happened with the [Helm Chart Inflator].
      
 * `untested/v1`
   
   Untested, unmaintained plugins.
   
   These might be former examples that have been abandoned and
   may soon be deleted, or they might be WIP plugins that will
   someday become examples or builtins.

#### Testing

Regardless of the [style](#plugin-styles) used to write a plugin,
it should be accompanied by a Go unit test, written using the framework
maintained by the kustomize maintainers for just that purpose.

To see how this works, run any plugin test, e.g.
this plugin written in bash:
```
pushd plugin/someteam.example.com/v1/bashedconfigmap
go test -v .
popd
```

For plugins with many tests, it's possible to target just one test:
```
pushd plugin/builtin/patchstrategicmergetransformer
go test -v -run TestBadPatchStrategicMergeTransformer PatchStrategicMergeTransformer_test.go
popd
```

### Plugin styles

For more discussion, see [extending kustomize].

* a bare executable
 
  This can be anything, e.g. a shell script, a shell
  script that runs java in a JVM, or python in a python
  VM, etc.  They accept a YAML stream of resources on
  stdin, and emit a YAML stream on stdout.  They accept
  configuration data in a file specified as the first
  argument on their command line.

  If the executable is written in Go, it can take advantage
  of the same libraries as the kustomize builtin plugins.
  
* a [KRM function]

  These are containerized executables, that are pickier
  about their input.  Rather than accepting a YAML stream
  of k8s resources, they want one `ResourceList` object
  (with the resources in that list).

* a [Go plugin]

  These are built as shared object libraries.  Like
  a Go program, they're written in an unimportable
  `main` package with its own `go.mod` file.
  Go plugins cannot be reliably distributed (see docs),
  and are meant only as a structured way to write a
  builtin plugin intended for distribution with kustomize.

[pluginator]: ../cmd/pluginator
[Helm Chart Inflator]: ./builtin/helmchartinflationgenerator
[KRM function]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md
[Go plugin]: https://golang.org/pkg/plugin
[Go plugins]: https://golang.org/pkg/plugin
[extending kustomize]: https://kubectl.docs.kubernetes.io/guides/extending_kustomize/