Skip to content

Commit

Permalink
refactor: tighten plugin context API considerably
Browse files Browse the repository at this point in the history
This is a fairly major refactor, geared at stabilising and limiting
the surface area of the plugin API, and getting closer to only passing
primitive values to plugin actions, as opposed to framework code.

The only user facing change here is changing the currently unused
`get/set/delete config` to more expressly handle user secrets
management, dropping the notion of namespaced configuration
in favour of plugin-managed secrets.

Other notable changes:
- Most of PluginContext has been split into a separate ActionHelper,
  which is only accessible internally via the `garden.actions`. Plugins
  can thus no longer affect workflows imperatively.
- Because of the above, we now pass Module objects to actions directly,
  simplifying flows somewhat and getting rid of some race condition
  issues.
- A lot of internal code that used to receive a PluginContext, now just
  receives a Garden instance.
- The PluginContext is now initialised with a provider, and includes it,
  removing the separate `env` and `provider` action params.
- I discovered that Command args and opts were not type-safe anymore,
  so I needed to fix a couple of things there along the way, and cleaned
  up a bit as well.
- I added thorough documentation to the plugin schema, along with full
  input parameter schemas for every action, as well as tests for the
  ActionHelper and those schemas.
- Some handlers have been renamed, and some schemas updated slightly
  for clarity and consistency.

Next steps: Generate documentation for providers and better docs for
plugin module types via the `describeType` action handler.
  • Loading branch information
edvald committed Sep 12, 2018
1 parent b7d03cf commit af2af06
Show file tree
Hide file tree
Showing 103 changed files with 2,780 additions and 2,272 deletions.
51 changes: 28 additions & 23 deletions docs/reference/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,28 +135,29 @@ Examples:

| Argument | Alias | Type | Description |
| -------- | ----- | ---- | ----------- |
| `--name` | | boolean | Assigns a custom name to the module. (Defaults to name of the current directory.)
| `--name` | | string | Assigns a custom name to the module. (Defaults to name of the current directory.)
| `--type` | | `container` `google-cloud-function` `npm-package` | Type of module.

### garden delete config
### garden delete secret

Delete a configuration variable from the environment.
Delete a secret from the environment.

Returns with an error if the provided key could not be found in the configuration.
Returns with an error if the provided key could not be found by the provider.

Examples:

garden delete config somekey
garden del config some.nested.key
garden delete secret kubernetes somekey
garden del secret local-kubernetes some-other-key

##### Usage

garden delete config <key>
garden delete secret <provider> <key>

##### Arguments

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `provider` | Yes | The name of the provider to remove the secret from.
| `key` | Yes | The key of the configuration variable. Separate with dots to get a nested key (e.g. key.nested).

### garden delete environment
Expand Down Expand Up @@ -275,26 +276,27 @@ Examples:
| `service` | Yes | The service to exec the command in.
| `command` | Yes | The command to run.

### garden get config
### garden get secret

Get a configuration variable from the environment.
Get a secret from the environment.

Returns with an error if the provided key could not be found in the configuration.
Returns with an error if the provided key could not be found.

Examples:

garden get config somekey
garden get config some.nested.key
garden get secret kubernetes somekey
garden get secret local-kubernetes some-other-key

##### Usage

garden get config <key>
garden get secret <provider> <key>

##### Arguments

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `key` | Yes | The key of the configuration variable. Separate with dots to get a nested key (e.g. key.nested).
| `provider` | Yes | The name of the provider to read the secret from.
| `key` | Yes | The key of the configuration variable.

### garden get status

Expand Down Expand Up @@ -553,29 +555,32 @@ Scans your project and outputs an overview of all modules.

garden scan

### garden set config
### garden set secret

Set a configuration variable in the environment.
Set a secret value for a provider in an environment.

These configuration values can be referenced in module templates, for example as environment variables.
These secrets are handled by each provider, and may for example be exposed as environment
variables for services or mounted as files, depending on how the provider is implemented
and configured.

_Note: The value is always stored as a string._
_Note: The value is currently always stored as a string._

Examples:

garden set config somekey myvalue
garden set config some.nested.key myvalue
garden set secret kubernetes somekey myvalue
garden set secret local-kubernets somekey myvalue

##### Usage

garden set config <key> <value>
garden set secret <provider> <key> <value>

##### Arguments

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `key` | Yes | The key of the configuration variable. Separate with dots to get a nested key (e.g. key.nested).
| `value` | Yes | The value of the configuration variable.
| `provider` | Yes | The name of the provider to store the secret with.
| `key` | Yes | A unique identifier for the secret.
| `value` | Yes | The value of the secret.

### garden test

Expand Down
14 changes: 1 addition & 13 deletions docs/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,12 +127,6 @@ project:
#
# Optional.
environmentDefaults:
# Specify the provider that should store configuration variables for this environment. Use
# this when you configure multiple providers that can manage configuration.
#
# Optional.
configurationHandler:

# A list of providers that should be used for this environment, and their configuration.
# Please refer to individual plugins/providers for details on how to configure them.
#
Expand Down Expand Up @@ -161,13 +155,7 @@ project:
#
# Optional.
environments:
- # Specify the provider that should store configuration variables for this environment. Use
# this when you configure multiple providers that can manage configuration.
#
# Optional.
configurationHandler:

# A list of providers that should be used for this environment, and their configuration.
- # A list of providers that should be used for this environment, and their configuration.
# Please refer to individual plugins/providers for details on how to configure them.
#
# Optional.
Expand Down
2 changes: 2 additions & 0 deletions examples/hello-world/garden.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
project:
name: hello-world
environmentDefaults:
providers:
- name: npm-package
variables:
my-variable: hello-variable
environments:
Expand Down

0 comments on commit af2af06

Please sign in to comment.