1 // Copyright 2019 The Kubernetes Authors. 2 // SPDX-License-Identifier: Apache-2.0 3 4 /* 5 6 Read docs/plugins.md first for an overview of kustomize plugins. 7 8 9 BUILTIN PLUGIN CONFIGURATION 10 11 There are two kinds of plugins, Go plugins (shared 12 object library) and exec plugins (independent binary). 13 For performance and standardized testing reasons, all 14 builtin plugins are Go plugins (not exec plugins). 15 16 Using "SecretGenerator" as an example in what 17 follows. 18 19 The plugin config file looks like 20 21 apiVersion: builtin 22 kind: SecretGenerator 23 metadata: 24 name: whatever 25 otherField1: whatever 26 otherField2: whatever 27 ... 28 29 The apiVersion must be 'builtin'. 30 31 The kind is the CamelCase name of the plugin. 32 33 The source for a builtin plugin must be at: 34 35 repo=$GOPATH/src/sigs.k8s.io/kustomize 36 ${repo}/plugin/builtin/LOWERCASE(${kind})/${kind} 37 38 k8s wants 'kind' values to follow CamelCase, while 39 Go style doesn't like but does allow such names. 40 41 The lowercased value of kind is used as the name of the 42 directory holding the plugin, its test, and any 43 optional associated files (possibly a go.mod file). 44 45 46 BUILTIN PLUGIN GENERATION 47 48 The `pluginator` program is a code generator that 49 converts kustomize generator (G) and/or 50 transformer (T) Go plugins to statically linkable 51 code. 52 53 It arises from following requirements: 54 55 * extension 56 kustomize does two things - generate or 57 transform k8s resources. Plugins let 58 users write their own G&T's without 59 having to fork kustomize and learn its 60 internals. 61 62 * dogfooding 63 A G&T extension framework one can trust 64 should be used by its authors to deliver 65 builtin G&T's. 66 67 * distribution 68 kustomize should be distributable via 69 `go get` and should run where Go 70 programs are expected to run. 71 72 The extension requirement led to building 73 a framework that accommodates writing a 74 G or T as either 75 76 * an 'exec' plugin (any executable file 77 runnable as a kustomize subprocess), or 78 79 * as a Go plugin - see 80 https://golang.org/pkg/plugin. 81 82 The dogfooding (and an implicit performance 83 requirement) requires a 'builtin' G or T to 84 be written as a Go plugin. 85 86 The distribution ('go get') requirement demands 87 conversion of Go plugins to statically linked 88 code, hence this program. 89 90 91 TO GENERATE CODE 92 93 repo=$GOPATH/src/sigs.k8s.io/kustomize 94 cd $repo/plugin/builtin 95 go generate ./... 96 97 This creates 98 99 $repo/api/plugins/builtins/SecretGenerator.go 100 101 etc. 102 103 Generated plugins are used in kustomize via 104 105 package whatever 106 import sigs.k8s.io/kustomize/api/plugins/builtins 107 ... 108 g := builtin.NewSecretGenerator() 109 g.Config(h, k) 110 resources, err := g.Generate() 111 err = g.Transform(resources) 112 // Eventually emit resources. 113 114 */ 115 package plugins 116