|
| 1 | +How to work with the terraform kind |
| 2 | +=================================== |
| 3 | + |
| 4 | +The file `terraform.go` here is like a 'main'. Instead of creating complex command line CLI options, |
| 5 | +you'd simply add define the data structure you need in the `Options` type and register a default value |
| 6 | +with Infrakit's plugin launcher framework (see line 36 of `terraform.go`): |
| 7 | + |
| 8 | +``` |
| 9 | +func init() { |
| 10 | + inproc.Register(Kind, Run, DefaultOptions) |
| 11 | +} |
| 12 | +``` |
| 13 | + |
| 14 | +Now you need to create a `plugins.json` file and use that when you use `infrakit plugin start`. |
| 15 | +This file will have the actual config parameters you need to start things up. |
| 16 | + |
| 17 | +This format actually supports a variety of plugin startup mechanism (eg. exec to shell, to docker, etc.) |
| 18 | +but the one we care about for best UX is the `inproc` which essentially embeds all the important plugins |
| 19 | +in the same binary and will run in the same infrakit daemon process. The `inproc` launch system uses |
| 20 | +the go packages and registration mechanism mentioned above (in the `pkg/run/v0` and all the subpackages |
| 21 | +below it). |
| 22 | + |
| 23 | +The block here will set up the input for a key `terraform` which uses `inproc` subsystem |
| 24 | +to launch the `terraform` kind: |
| 25 | + |
| 26 | +``` |
| 27 | + { |
| 28 | + "Key" : "terraform", |
| 29 | + "Launch" : { |
| 30 | + "inproc": { |
| 31 | + "Kind" : "terraform", |
| 32 | + "Options" : { |
| 33 | + "Dir": "{{ env `INFRAKIT_HOME` }}/terraform", |
| 34 | + "Standalone": true, |
| 35 | + "NewOption" : "hello world" |
| 36 | + } |
| 37 | + } |
| 38 | + } |
| 39 | + } |
| 40 | +``` |
| 41 | + |
| 42 | +This configuration file is used by the `infrakit plugin start` command. It has a usage like this: |
| 43 | + |
| 44 | +``` |
| 45 | +infrakit plugin start [--config-url <url>] <plugin_spec> [ <plugin_spec> ... ] |
| 46 | +``` |
| 47 | +where `--config-url` will point to the `plugins.json` file and |
| 48 | +`<plugin_spec>` is `<key>[:<socke_file>[=<exec>]]` |
| 49 | + |
| 50 | +For example: |
| 51 | + |
| 52 | +``` |
| 53 | +infrakit plugin start terraform |
| 54 | +``` |
| 55 | +is equal to |
| 56 | +``` |
| 57 | +infrakit plugin start terraform:terraform=inproc |
| 58 | +``` |
| 59 | + |
| 60 | +where the launch system will look for `Key` of `terraform`, and use the `inproc` launcher which uses the |
| 61 | +embeded `terraform` Kind. That then will look for the `Options` field and provide that to the code |
| 62 | +that is in `terraform.go`. |
| 63 | + |
| 64 | +Once you have the new fields defined and updated your `plugins.json` file to reflect these new changes, |
| 65 | +you have to provide this `plugins.json` to complement/override a set of defaults in the system: |
| 66 | + |
| 67 | +``` |
| 68 | +build/infrakit plugin --config-url file://$(pwd)/pkg/run/v0/terraform/plugins.json start terraform |
| 69 | +INFO[09-12|02:49:51] Launching module=cli/plugin kind=terraform name=terraform fn=github.com/docker/infrakit/cmd/infrakit/plugin.Command.func2 |
| 70 | +INFO[09-12|02:49:51] Starting plugin module=core/launch executor=inproc key=terraform name=terraform exec=inproc fn=github.com/docker/infrakit/pkg/launch.(*Monitor).Start.func1 |
| 71 | +INFO[09-12|02:49:51] No group spec URL specified for import module=run/v0/terraform fn=github.com/docker/infrakit/pkg/run/v0/terraform.parseInstanceSpecFromGroup |
| 72 | +INFO[09-12|02:49:51] NewOptions module=run/v0/terraform value="hello world" Dir=/Users/davidchung/.infrakit/terraform fn=github.com/docker/infrakit/pkg/run/v0/terraform.Run |
| 73 | +INFO[09-12|02:49:51] Listening module=rpc/server discover=/Users/davidchung/.infrakit/plugins/terraform fn=github.com/docker/infrakit/pkg/rpc/server.startAtPath |
| 74 | +INFO[09-12|02:49:51] Waiting for startup module=core/launch key=terraform name=terraform config="{\n\t\t\"Kind\" : \"terraform\",\n\t\t\"Options\" : {\n\t\t \"Dir\": \"/Users/davidchung/.infrakit/terraform\",\n\t\t \"Standalone\": true,\n\t\t \"NewOption\" : \"hello world\"\n\t\t}\n\t }" as=terraform fn=github.com/docker/infrakit/pkg/launch.(*Monitor).Start.func1 |
| 75 | +INFO[09-12|02:49:51] Done waiting on plugin starts module=cli/plugin fn=github.com/docker/infrakit/cmd/infrakit/plugin.Command.func2 |
| 76 | +INFO[0000] PID file at /Users/davidchung/.infrakit/plugins/terraform.pid |
| 77 | +INFO[0000] Server waiting at /Users/davidchung/.infrakit/plugins/terraform |
| 78 | +Empty or non-existent state file. |
| 79 | +
|
| 80 | +Refresh will do nothing. Refresh does not error or return an erroneous |
| 81 | +exit status because many automation scripts use refresh, plan, then apply |
| 82 | +and may not have a state file yet for the first run. |
| 83 | +
|
| 84 | +
|
| 85 | +``` |
| 86 | + |
| 87 | +There -- your plugin just came up with customized fields and is now running inside the same process |
| 88 | +as the rest of infrakit. Note that the value `hello world` for has been loaded and printed out in `INFO`. |
| 89 | + |
| 90 | +A couple of notes: |
| 91 | + |
| 92 | + 1. The `plugins.json` will be evaluated as a template. This means you can use template functions |
| 93 | + like `env` or even `source`/`include` to bring in other complex configurations. |
| 94 | + 2. The `Options` block in the schema actually corresponds to the `Options` in the global Spec |
| 95 | + (see pkg/types/Spec). The design here allows you to start up the plugin before the global Spec schema |
| 96 | + is in place, and when that arrives, you'd simply move this block into the global schema so that a single |
| 97 | + specs file will contain all the information necessary about how your infrastructure, as well as the settings |
| 98 | + for the plugins (hence Options and *not* Properties). |
0 commit comments