feat(core): providers can depend on and reference configs from each o…

…ther This adds some important features and improved testing for our provider mechanism. We can use this to explicitly declare dependencies between providers, to reference each others' configs and outputs, as well as a solid way for providers to bundle modules (i.e. without having to use nested Garden instances). To start, I've updated our OpenFaaS provider to use these features, resulting in a simpler, more elegant implementation. These changes will further enable more types of providers, including a Terraform provider that I've started implementing, where we'll be able to reference stack outputs to configure other providers, e.g. to connect to a Kubernetes cluster provisioned by Terraform. Another improvement is in how we declare providers in project configs, and how they are mapped to environments. Instead of declaring them under each environment, we can declare a provider once for all or selected environments, essentially inverting the spec. This feels more elegant to me. This is currently backwards compatible btw, so we can gradually transition examples and docs after releasing 0.10. BREAKING CHANGE: When using OpenFaaS with `local-kubernetes` you now need to use the `local-openfaas` provider, instead of `openfaas`. You also need to manually delete any existing `<my namespace>--openfaas` namespaces from your cluster after upgrading.
garden-io · Jun 6, 2019 · a67f522 · a67f522
1 parent efd632d
commit a67f522
Show file tree

Hide file tree

Showing 105 changed files with 4,298 additions and 1,548 deletions.
diff --git a/docs/reference/config.md b/docs/reference/config.md
@@ -50,7 +50,7 @@ The default environment to use when calling commands without the `--env` paramet
 | `string` | No
 ### `environmentDefaults`
 
-Default environment settings. These are inherited (but can be overridden) by each configured environment.
+DEPRECATED - Please use the `providers` field instead, and omit the environments key in the configured provider to use it for all environments, and use the `variables` field to configure variables across all environments.
 
 | Type | Required |
 | ---- | -------- |
@@ -65,7 +65,7 @@ environmentDefaults:
 ### `environmentDefaults.providers[]`
 [environmentDefaults](#environmentdefaults) > providers
 
-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.
+DEPRECATED - Please use the top-level `providers` field instead, and if needed use the `environments` key on the provider configurations to limit them to specific environments.
 
 | Type | Required |
 | ---- | -------- |
@@ -88,10 +88,30 @@ environmentDefaults:
   providers:
     - name: "local-kubernetes"
 ```
+### `environmentDefaults.providers[].environments[]`
+[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > environments
+
+If specified, this provider will only be used in the listed environments. Note that an empty array effectively disables the provider. To use a provider in all environments, omit this field.
+
+| Type | Required |
+| ---- | -------- |
+| `array[string]` | No
+
+Example:
+```yaml
+environmentDefaults:
+  providers: []
+  variables: {}
+  ...
+  providers:
+    - environments:
+      - dev
+      - stage
+```
 ### `environmentDefaults.variables`
 [environmentDefaults](#environmentdefaults) > variables
 
-A key/value map of variables that modules can reference when using this environment.
+A key/value map of variables that modules can reference when using this environment. These take precedence over variables defined in the top-level `variables` field.
 
 | Type | Required |
 | ---- | -------- |
@@ -102,26 +122,21 @@ A list of environments to configure for the project.
 
 | Type | Required |
 | ---- | -------- |
-| `array[object]` | No
+| `alternatives` | No
 
 Example:
 ```yaml
-environments:
-  - name: local
-    providers:
-      - name: local-kubernetes
-    variables: {}
+environments: [{"name":"local","providers":[{"name":"local-kubernetes","environments":[]}],"variables":{}}]
 ```
-### `environments[].providers[]`
-[environments](#environments) > providers
+### `providers`
 
-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.
+A list of providers that should be used for this project, and their configuration. Please refer to individual plugins/providers for details on how to configure them.
 
 | Type | Required |
 | ---- | -------- |
 | `array[object]` | No
-### `environments[].providers[].name`
-[environments](#environments) > [providers](#environments[].providers[]) > name
+### `providers[].name`
+[providers](#providers) > name
 
 The name of the provider plugin to use.
 
@@ -131,30 +146,25 @@ The name of the provider plugin to use.
 
 Example:
 ```yaml
-environments:
-  - name: local
-    providers:
-      - name: local-kubernetes
-    variables: {}
-  - providers:
-      - name: "local-kubernetes"
+providers:
+  - name: "local-kubernetes"
 ```
-### `environments[].variables`
-[environments](#environments) > variables
+### `providers[].environments[]`
+[providers](#providers) > environments
 
-A key/value map of variables that modules can reference when using this environment.
+If specified, this provider will only be used in the listed environments. Note that an empty array effectively disables the provider. To use a provider in all environments, omit this field.
 
 | Type | Required |
 | ---- | -------- |
-| `object` | No
-### `environments[].name`
-[environments](#environments) > name
-
-Valid RFC1035/RFC1123 (DNS) label (may contain lowercase letters, numbers and dashes, must start with a letter, and cannot end with a dash), cannot contain consecutive dashes or start with `garden`, or be longer than 63 characters.
+| `array[string]` | No
 
-| Type | Required |
-| ---- | -------- |
-| `string` | Yes
+Example:
+```yaml
+providers:
+  - environments:
+    - dev
+    - stage
+```
 ### `sources`
 
 A list of remote sources to import into project.
@@ -184,6 +194,13 @@ Example:
 sources:
   - repositoryUrl: "git+https://github.com/org/repo.git#v2.0"
 ```
+### `variables`
+
+Variables to configure for all environments.
+
+| Type | Required |
+| ---- | -------- |
+| `object` | No
 
 
 ## Project YAML schema
@@ -195,15 +212,16 @@ defaultEnvironment: ''
 environmentDefaults:
   providers:
     - name:
+      environments:
   variables: {}
 environments:
-  - providers:
-      - name:
-    variables: {}
-    name:
+providers:
+  - name:
+    environments:
 sources:
   - name:
     repositoryUrl:
+variables: {}
 ```
 
 ## Module configuration keys

diff --git a/docs/reference/module-types/openfaas.md b/docs/reference/module-types/openfaas.md
@@ -1,7 +1,6 @@
 # `openfaas` reference
 
-Deploy [OpenFaaS](https://www.openfaas.com/) functions using Garden. Requires either the `kubernetes` or
-`local-kubernetes` provider to be configured. Everything else is installed automatically.
+
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
@@ -153,153 +152,6 @@ POSIX-style path or filename to copy the directory or file(s) to (defaults to sa
 | Type | Required |
 | ---- | -------- |
 | `string` | No
-### `build.command[]`
-[build](#build) > command
-
-The command to run inside the module's directory to perform the build.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-
-Example:
-```yaml
-build:
-  ...
-  command:
-    - npm
-    - run
-    - build
-```
-### `env`
-
-Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with `GARDEN`) and values must be primitives.
-
-| Type | Required |
-| ---- | -------- |
-| `object` | No
-### `tasks`
-
-A list of tasks that can be run in this module.
-
-| Type | Required |
-| ---- | -------- |
-| `array[object]` | No
-### `tasks[].name`
-[tasks](#tasks) > name
-
-The name of the task.
-
-| Type | Required |
-| ---- | -------- |
-| `string` | Yes
-### `tasks[].description`
-[tasks](#tasks) > description
-
-A description of the task.
-
-| Type | Required |
-| ---- | -------- |
-| `string` | No
-### `tasks[].dependencies[]`
-[tasks](#tasks) > dependencies
-
-The names of any tasks that must be executed, and the names of any services that must be running, before this task is executed.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-### `tasks[].timeout`
-[tasks](#tasks) > timeout
-
-Maximum duration (in seconds) of the task's execution.
-
-| Type | Required |
-| ---- | -------- |
-| `number` | No
-### `tasks[].command[]`
-[tasks](#tasks) > command
-
-The command to run in the module build context.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-### `tests`
-
-A list of tests to run in the module.
-
-| Type | Required |
-| ---- | -------- |
-| `array[object]` | No
-### `tests[].name`
-[tests](#tests) > name
-
-The name of the test.
-
-| Type | Required |
-| ---- | -------- |
-| `string` | Yes
-### `tests[].dependencies[]`
-[tests](#tests) > dependencies
-
-The names of any services that must be running, and the names of any tasks that must be executed, before the test is run.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-### `tests[].timeout`
-[tests](#tests) > timeout
-
-Maximum duration (in seconds) of the test run.
-
-| Type | Required |
-| ---- | -------- |
-| `number` | No
-### `tests[].command[]`
-[tests](#tests) > command
-
-The command to run in the module build context in order to test it.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-### `tests[].env`
-[tests](#tests) > env
-
-Key/value map of environment variables. Keys must be valid POSIX environment variable names (must not start with `GARDEN`) and values must be primitives.
-
-| Type | Required |
-| ---- | -------- |
-| `object` | No
-### `dependencies`
-
-The names of services/functions that this function depends on at runtime.
-
-| Type | Required |
-| ---- | -------- |
-| `array[string]` | No
-### `handler`
-
-Specify which directory under the module contains the handler file/function.
-
-| Type | Required |
-| ---- | -------- |
-| `string` | No
-### `image`
-
-The image name to use for the built OpenFaaS container (defaults to the module name)
-
-| Type | Required |
-| ---- | -------- |
-| `string` | No
-### `lang`
-
-The OpenFaaS language template to use to build this function.
-
-| Type | Required |
-| ---- | -------- |
-| `string` | Yes
 
 
 ## Complete YAML schema
@@ -318,23 +170,4 @@ build:
       copy:
         - source:
           target: ''
-  command:
-    []
-env: {}
-tasks:
-  - name:
-    description:
-    dependencies: []
-    timeout: null
-    command:
-tests:
-  - name:
-    dependencies: []
-    timeout: null
-    command:
-    env: {}
-dependencies: []
-handler: .
-image:
-lang:
 ```