Go plugin example

Go plugin example

Go Plugin Guided Example for Linux

This is a (no reading allowed!) 60 second copy/paste guided example.

Full plugin docs here. Be sure to read the Go plugin caveats.

This demo uses a Go plugin, SopsEncodedSecrets, that lives in the sopsencodedsecrets repository. This is an inprocess Go plugin, not an sub-process exec plugin that happens to be written in Go (which is another option for Go authors).

This is a guide to try it without damaging your current setup.

requirements

  • linux, git, curl, Go 1.13

For encryption

  • gpg

Or

  • Google cloud (gcloud) install
  • a Google account with KMS permission

Make a place to work

  1. # Keeping these separate to avoid cluttering the DEMO dir.
  2. DEMO=$(mktemp -d)
  3. tmpGoPath=$(mktemp -d)

Install kustomize

Need v3.0.0 for what follows, and you must compile it (not download the binary from the release page):

  1. GOPATH=$tmpGoPath go install sigs.k8s.io/kustomize/kustomize

Make a home for plugins

A kustomize plugin is fully determined by its configuration file and source code.

Kustomize plugin configuration files are formatted as kubernetes resource objects, meaning apiVersion, kind and metadata are required fields in these config files.

The kustomize program reads the config file (because the config file name appears in the generators or transformers field in the kustomization file), then locates the Go plugin’s object code at the following location:

  1. $XDG_CONFIG_HOME/kustomize/plugin/$apiVersion/$lKind/$kind.so

where lKind holds the lowercased kind. The plugin is then loaded and fed its config, and the plugin’s output becomes part of the overall kustomize build process.

The same plugin might be used multiple times in one kustomize build, but with different config files. Also, kustomize might customize config data before sending it to the plugin, for whatever reason. For these reasons, kustomize owns the mapping between plugins and config data; it’s not left to plugins to find their own config.

This demo will house the plugin it uses at the ephemeral directory

  1. PLUGIN_ROOT=$DEMO/kustomize/plugin

and ephemerally set XDG_CONFIG_HOME on a command line below.

What apiVersion and kind

At this stage in the development of kustomize plugins, plugin code doesn’t know or care what apiVersion or kind appears in the config file sent to it.

The plugin could check these fields, but it’s the remaining fields that provide actual configuration data, and at this point the successful parsing of these other fields are the only thing that matters to a plugin.

This demo uses a plugin called SopsEncodedSecrets, and it lives in the SopsEncodedSecrets repository.

Somewhat arbitrarily, we’ll chose to install this plugin with

  1. apiVersion=mygenerators
  2. kind=SopsEncodedSecrets

Define the plugin’s home dir

By convention, the ultimate home of the plugin code and supplemental data, tests, documentation, etc. is the lowercase form of its kind.

  1. lKind=$(echo $kind | awk '{print tolower($0)}')

Download the SopsEncodedSecrets plugin

In this case, the repo name matches the lowercase kind already, so we just clone the repo and get the proper directory name automatically:

  1. mkdir -p $PLUGIN_ROOT/${apiVersion}
  2. cd $PLUGIN_ROOT/${apiVersion}
  3. git clone git@github.com:monopole/sopsencodedsecrets.git

Remember this directory:

  1. MY_PLUGIN_DIR=$PLUGIN_ROOT/${apiVersion}/${lKind}

Try the plugin’s own test

Plugins may come with their own tests. This one does, and it hopefully passes:

  1. cd $MY_PLUGIN_DIR
  2. go test SopsEncodedSecrets_test.go

Build the object code for use by kustomize:

  1. cd $MY_PLUGIN_DIR
  2. GOPATH=$tmpGoPath go build -buildmode plugin -o ${kind}.so ${kind}.go

This step may succeed, but kustomize might ultimately fail to load the plugin because of dependency skew.

On load failure

  • be sure to build the plugin with the same version of Go (go1.13) on the same $GOOS (linux) and $GOARCH (amd64) used to build the kustomize being used in this demo.

  • change the plugin’s dependencies in its go.mod to match the versions used by kustomize (check kustomize’s go.mod used in its tagged commit).

Lacking tools and metadata to allow this to be automated, there won’t be a Go plugin ecosystem.

Kustomize has adopted a Go plugin architecture as to ease accept new generators and transformers (just write a plugin), and to be sure that native operations (also constructed and tested as plugins) are compartmentalized, orderable and reusable instead of bizarrely woven throughout the code as a individual special cases.

Create a kustomization

Make a kustomization directory to hold all your config:

  1. MYAPP=$DEMO/myapp
  2. mkdir -p $MYAPP

Make a config file for the SopsEncodedSecrets plugin.

Its apiVersion and kind allow the plugin to be found:

  1. cat <<EOF >$MYAPP/secGenerator.yaml
  2. apiVersion: ${apiVersion}
  3. kind: ${kind}
  4. metadata:
  5.   name: mySecretGenerator
  6. name: forbiddenValues
  7. namespace: production
  8. file: myEncryptedData.yaml
  9. keys:
  10. - ROCKET
  11. - CAR
  12. EOF

This plugin expects to find more data in myEncryptedData.yaml; we’ll get to that shortly.

Make a kustomization file referencing the plugin config:

  1. cat <<EOF >$MYAPP/kustomization.yaml
  2. commonLabels:
  3.   app: hello
  4. generators:
  5. - secGenerator.yaml
  6. EOF

Now generate the real encrypted data.

Assure you have an encryption tool installed

We’re going to use sops to encode a file. Choose either GPG or Google Cloud KMS as the secret provider to continue.

GPG

Try this:

  1. gpg --list-keys

If it returns a list, presumably you’ve already created keys. If not, try import test keys from sops for dev.

  1. curl https://raw.githubusercontent.com/mozilla/sops/master/pgp/sops_functional_tests_key.asc | gpg --import
  2. SOPS_PGP_FP="1022470DE3F0BC54BC6AB62DE05550BC07FB1A0A"

Google Cloude KMS

Try this:

  1. gcloud kms keys list --location global --keyring sops

If it succeeds, presumably you’ve already created keys and placed them in a keyring called sops. If not, do this:

  1. gcloud kms keyrings create sops --location global
  2. gcloud kms keys create sops-key --location global \
  3.     --keyring sops --purpose encryption

Extract your keyLocation for use below:

  1. keyLocation=$(\
  2.     gcloud kms keys list --location global --keyring sops |\
  3.     grep GOOGLE | cut -d " " -f1)
  4. echo $keyLocation

Install sops

  1. GOPATH=$tmpGoPath go install go.mozilla.org/sops/cmd/sops

Create data encrypted with your private key

Create raw data to encrypt:

  1. cat <<EOF >$MYAPP/myClearData.yaml
  2. VEGETABLE: carrot
  3. ROCKET: saturn-v
  4. FRUIT: apple
  5. CAR: dymaxion
  6. EOF

Encrypt the data into file the plugin wants to read:

With PGP

  1. $tmpGoPath/bin/sops --encrypt \
  2.   --pgp $SOPS_PGP_FP \
  3.   $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml

Or GCP KMS

  1. $tmpGoPath/bin/sops --encrypt \
  2.   --gcp-kms $keyLocation \
  3.   $MYAPP/myClearData.yaml >$MYAPP/myEncryptedData.yaml

Review the files

  1. tree $DEMO

This should look something like:

  1. /tmp/tmp.0kIE9VclPt
  2. ├── kustomize
  3. │   └── plugin
  4. │       └── mygenerators
  5. │           └── sopsencodedsecrets
  6. │               ├── go.mod
  7. │               ├── go.sum
  8. │               ├── LICENSE
  9. │               ├── README.md
  10. │               ├── SopsEncodedSecrets.go
  11. │               ├── SopsEncodedSecrets.so
  12. │               └── SopsEncodedSecrets_test.go
  13. └── myapp
  14.     ├── kustomization.yaml
  15.     ├── myClearData.yaml
  16.     ├── myEncryptedData.yaml
  17.     └── secGenerator.yaml

Build your app, using the plugin

  1. XDG_CONFIG_HOME=$DEMO $tmpGoPath/bin/kustomize build --enable_alpha_plugins $MYAPP

This should emit a kubernetes secret, with encrypted data for the names ROCKET and CAR.

Above, if you had set

  1. PLUGIN_ROOT=$HOME/.config/kustomize/plugin

there would be no need to use XDG_CONFIG_HOME in the kustomize command above.