diff --git a/docs/reference/commands.md b/docs/reference/commands.md index c3507fe439..bc7311e985 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -16,6 +16,7 @@ The following option flags can be used with any of the CLI commands: | `--root` | `-r` | string | Override project root directory (defaults to working directory). | `--silent` | `-s` | boolean | Suppress log output. | `--env` | `-e` | string | The environment (and optionally namespace) to work against. + | `--logger-type` | | `quiet` `basic` `fancy` `json` | Set logger type: fancy: updates log lines in-place when their status changes (e.g. when tasks complete), basic: appends a new log line when a log line's status changes, json: same as basic, but renders log lines as JSON, quiet: uppresses all log output, | `--loglevel` | `-l` | `error` `warn` `info` `verbose` `debug` `silly` `0` `1` `2` `3` `4` `5` | Set logger level. Values can be either string or numeric and are prioritized from 0 to 5 (highest to lowest) as follows: error: 0, warn: 1, info: 2, verbose: 3, debug: 4, silly: 5. | `--output` | `-o` | `json` `yaml` | Output command result in specified format (note: disables progress logging and interactive functionality). | `--emoji` | | boolean | Enable emoji in output (defaults to true if the environment supports it). @@ -170,7 +171,7 @@ Examples: | `--force` | | boolean | Force redeploy of service(s). | `--force-build` | | boolean | Force rebuild of module(s). | `--watch` | `-w` | boolean | Watch for changes in module(s) and auto-deploy. - | `--hot-reload` | | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services. When this option is used, the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag). + | `--hot-reload` | `-hot` | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services. When this option is used, the command is run in watch mode (i.e. implicitly assumes the --watch/-w flag). ### garden dev @@ -183,7 +184,8 @@ as you modify the code. Examples: garden dev - garden dev --hot-reload=foo-service,bar-service # enable hot reloading for foo-service and bar-service + garden dev --hot-reload=foo-service # enable hot reloading for foo-service + garden dev --hot=foo-service,bar-service # enable hot reloading for foo-service and bar-service ##### Usage @@ -193,7 +195,7 @@ Examples: | Argument | Alias | Type | Description | | -------- | ----- | ---- | ----------- | - | `--hot-reload` | | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services. + | `--hot-reload` | `-hot` | array:string | The name(s) of the service(s) to deploy with hot reloading enabled. Use comma as a separator to specify multiple services. ### garden exec @@ -740,12 +742,3 @@ Throws an error and exits with code 1 if something's not right in your garden.ym garden validate -### garden version - -Show's the current cli version. - - -##### Usage - - garden version - diff --git a/docs/reference/config.md b/docs/reference/config.md index ccf34d6a5a..c851240dd6 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -15,23 +15,21 @@ Please refer to those for more details on provider and module configuration. ## Project configuration keys -### `project` - -Configuration for a Garden project. This should be specified in the garden.yml file in your project root. - -| Type | Required | -| ---- | -------- | -| `object` | Yes -### `project.apiVersion` -[project](#project) > apiVersion +### `apiVersion` The schema version of this project's config (currently not used). | Type | Required | Allowed Values | | ---- | -------- | -------------- | | `string` | Yes | "garden.io/v0" -### `project.name` -[project](#project) > name +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Project" +### `name` The name of the project. @@ -41,20 +39,16 @@ The name of the project. Example: ```yaml -project: - ... - name: "my-sweet-project" +name: "my-sweet-project" ``` -### `project.defaultEnvironment` -[project](#project) > defaultEnvironment +### `defaultEnvironment` The default environment to use when calling commands without the `--env` parameter. | Type | Required | | ---- | -------- | | `string` | No -### `project.environmentDefaults` -[project](#project) > environmentDefaults +### `environmentDefaults` Default environment settings. These are inherited (but can be overridden) by each configured environment. @@ -64,22 +58,20 @@ Default environment settings. These are inherited (but can be overridden) by eac Example: ```yaml -project: - ... - environmentDefaults: - providers: [] - variables: {} +environmentDefaults: + providers: [] + variables: {} ``` -### `project.environmentDefaults.providers[]` -[project](#project) > [environmentDefaults](#project.environmentdefaults) > providers +### `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. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environmentDefaults.providers[].name` -[project](#project) > [environmentDefaults](#project.environmentdefaults) > [providers](#project.environmentdefaults.providers[]) > name +### `environmentDefaults.providers[].name` +[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name The name of the provider plugin to use. @@ -89,25 +81,22 @@ The name of the provider plugin to use. Example: ```yaml -project: +environmentDefaults: + providers: [] + variables: {} ... - environmentDefaults: - providers: [] - variables: {} - ... - providers: - - name: "local-kubernetes" + providers: + - name: "local-kubernetes" ``` -### `project.environmentDefaults.variables` -[project](#project) > [environmentDefaults](#project.environmentdefaults) > variables +### `environmentDefaults.variables` +[environmentDefaults](#environmentdefaults) > variables A key/value map of variables that modules can reference when using this environment. | Type | Required | | ---- | -------- | | `object` | No -### `project.environments[]` -[project](#project) > environments +### `environments` A list of environments to configure for the project. @@ -117,24 +106,22 @@ A list of environments to configure for the project. Example: ```yaml -project: - ... - environments: - - name: local - providers: - - name: local-kubernetes - variables: {} +environments: + - name: local + providers: + - name: local-kubernetes + variables: {} ``` -### `project.environments[].providers[]` -[project](#project) > [environments](#project.environments[]) > providers +### `environments[].providers[]` +[environments](#environments) > 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. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > name +### `environments[].providers[].name` +[environments](#environments) > [providers](#environments[].providers[]) > name The name of the provider plugin to use. @@ -144,50 +131,47 @@ The name of the provider plugin to use. Example: ```yaml -project: - ... - environments: - - name: local - providers: - - name: local-kubernetes - variables: {} - - providers: - - name: "local-kubernetes" +environments: + - name: local + providers: + - name: local-kubernetes + variables: {} + - providers: + - name: "local-kubernetes" ``` -### `project.environments[].variables` -[project](#project) > [environments](#project.environments[]) > variables +### `environments[].variables` +[environments](#environments) > variables A key/value map of variables that modules can reference when using this environment. | Type | Required | | ---- | -------- | | `object` | No -### `project.environments[].name` -[project](#project) > [environments](#project.environments[]) > name +### `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. | Type | Required | | ---- | -------- | | `string` | Yes -### `project.sources[]` -[project](#project) > sources +### `sources` A list of remote sources to import into project. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.sources[].name` -[project](#project) > [sources](#project.sources[]) > name +### `sources[].name` +[sources](#sources) > name The name of the source to import | Type | Required | | ---- | -------- | | `string` | Yes -### `project.sources[].repositoryUrl` -[project](#project) > [sources](#project.sources[]) > repositoryUrl +### `sources[].repositoryUrl` +[sources](#sources) > repositoryUrl A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # @@ -197,52 +181,48 @@ A remote repository URL. Currently only supports git servers. Must contain a has Example: ```yaml -project: - ... - sources: - - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +sources: + - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" ``` ## Project YAML schema ```yaml -project: - apiVersion: garden.io/v0 - name: - defaultEnvironment: '' - environmentDefaults: - providers: +apiVersion: garden.io/v0 +kind: Project +name: +defaultEnvironment: '' +environmentDefaults: + providers: + - name: + variables: {} +environments: + - providers: - name: variables: {} - environments: - - providers: - - name: - variables: {} - name: - sources: - - name: - repositoryUrl: + name: +sources: + - name: + repositoryUrl: ``` ## Module configuration keys -### `module` - -Configure a module whose sources are located in this directory. - -| Type | Required | -| ---- | -------- | -| `object` | Yes -### `module.apiVersion` -[module](#module) > apiVersion +### `apiVersion` The schema version of this module's config (currently not used). | Type | Required | Allowed Values | | ---- | -------- | -------------- | | `string` | Yes | "garden.io/v0" -### `module.type` -[module](#module) > type +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` The type of this module. @@ -252,12 +232,9 @@ The type of this module. Example: ```yaml -module: - ... - type: "container" +type: "container" ``` -### `module.name` -[module](#module) > name +### `name` The name of this module. @@ -267,20 +244,16 @@ The name of this module. Example: ```yaml -module: - ... - name: "my-sweet-module" +name: "my-sweet-module" ``` -### `module.description` -[module](#module) > description +### `description` | Type | Required | | ---- | -------- | | `string` | No -### `module.include[]` -[module](#module) > include +### `include` Specify a list of POSIX-style paths or globs that should be regarded as the source files for this module. Files that do *not* match these paths or globs are excluded when computing the version of the module, @@ -297,14 +270,11 @@ Also note that specifying an empty list here means _no sources_ should be includ Example: ```yaml -module: - ... - include: - - Dockerfile - - my-app.js +include: + - Dockerfile + - my-app.js ``` -### `module.repositoryUrl` -[module](#module) > repositoryUrl +### `repositoryUrl` A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # @@ -317,28 +287,24 @@ config from the local garden.yml file. Example: ```yaml -module: - ... - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" ``` -### `module.allowPublish` -[module](#module) > allowPublish +### `allowPublish` When false, disables pushing this module to remote registries. | Type | Required | | ---- | -------- | | `boolean` | No -### `module.build` -[module](#module) > build +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -348,39 +314,37 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). @@ -391,19 +355,19 @@ POSIX-style path or filename to copy the directory or file(s) to (defaults to sa ## Module YAML schema ```yaml -module: - apiVersion: garden.io/v0 - type: - name: - description: - include: - repositoryUrl: - allowPublish: true - build: - dependencies: - - name: - copy: - - source: - target: '' +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: + - name: + copy: + - source: + target: '' ``` diff --git a/docs/reference/module-types/README.md b/docs/reference/module-types/README.md index 202ba73a66..3c38f4962a 100644 --- a/docs/reference/module-types/README.md +++ b/docs/reference/module-types/README.md @@ -1,6 +1,8 @@ # Module Types -* [Container](./container.md) * [Exec](./exec.md) +* [Container](./container.md) * [Helm](./helm.md) -* [OpenFaaS](./openfaas.md) +* [Kubernetes](./kubernetes.md) +* [Maven Container](./maven-container.md) +* [Openfaas](./openfaas.md) \ No newline at end of file diff --git a/docs/reference/module-types/container.md b/docs/reference/module-types/container.md index cfa7065088..0d8b8945c1 100644 --- a/docs/reference/module-types/container.md +++ b/docs/reference/module-types/container.md @@ -1,28 +1,117 @@ # `container` reference -Below is the schema reference for the `container` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +Specify a container image to build or pull from a remote registry. +You may also optionally specify services to deploy, tasks or tests to run inside the container. -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Note that the runtime services have somewhat limited features in this module type. For example, you cannot +specify replicas for redundancy, and various platform-specific options are not included. For those, look at +other module types like [helm](https://docs.garden.io/reference/module-types/helm) or +[kubernetes](https://docs.garden.io/reference/module-types/kubernetes). + +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` + +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + -Configuration for a container module. + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` + +The type of this module. | Type | Required | | ---- | -------- | -| `object` | No -### `module.build` -[module](#module) > build +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + + + +| Type | Required | +| ---- | -------- | +| `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No + +Example: +```yaml +include: + - Dockerfile + - my-app.js +``` +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -32,87 +121,82 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.build.targetImage` -[module](#module) > [build](#module.build) > targetImage +### `build.targetImage` +[build](#build) > targetImage For multi-stage Dockerfiles, specify which image to build (see https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target for details). | Type | Required | | ---- | -------- | | `string` | No -### `module.buildArgs` -[module](#module) > buildArgs +### `buildArgs` Specify build arguments to use when building the container image. | Type | Required | | ---- | -------- | | `object` | No -### `module.image` -[module](#module) > image +### `image` Specify the image name for the container. Should be a valid Docker image identifier. If specified and the module does not contain a Dockerfile, this image will be used to deploy services for this module. If specified and the module does contain a Dockerfile, this identifier is used when pushing the built image. | Type | Required | | ---- | -------- | | `string` | No -### `module.hotReload` -[module](#module) > hotReload +### `hotReload` Specifies which files or directories to sync to which paths inside the running containers of hot reload-enabled services when those files or directories are modified. Applies to this module's services, and to services with this module as their `sourceModule`. | Type | Required | | ---- | -------- | | `object` | No -### `module.hotReload.sync[]` -[module](#module) > [hotReload](#module.hotreload) > sync +### `hotReload.sync[]` +[hotReload](#hotreload) > sync Specify one or more source files or directories to automatically sync into the running container. | Type | Required | | ---- | -------- | | `array[object]` | Yes -### `module.hotReload.sync[].source` -[module](#module) > [hotReload](#module.hotreload) > [sync](#module.hotreload.sync[]) > source +### `hotReload.sync[].source` +[hotReload](#hotreload) > [sync](#hotreload.sync[]) > source POSIX-style path of the directory to sync to the target, relative to the module's top-level directory. Must be a relative path if provided. Defaults to the module's top-level directory if no value is provided. @@ -122,15 +206,13 @@ POSIX-style path of the directory to sync to the target, relative to the module' Example: ```yaml -module: +hotReload: ... - hotReload: - ... - sync: - - source: "src" + sync: + - source: "src" ``` -### `module.hotReload.sync[].target` -[module](#module) > [hotReload](#module.hotreload) > [sync](#module.hotreload.sync[]) > target +### `hotReload.sync[].target` +[hotReload](#hotreload) > [sync](#hotreload.sync[]) > target POSIX-style absolute path to sync the directory to inside the container. The root path (i.e. "/") is not allowed. @@ -140,71 +222,67 @@ POSIX-style absolute path to sync the directory to inside the container. The roo Example: ```yaml -module: +hotReload: ... - hotReload: - ... - sync: - - target: "/app/src" + sync: + - target: "/app/src" ``` -### `module.dockerfile` -[module](#module) > dockerfile +### `dockerfile` POSIX-style name of Dockerfile, relative to project root. Defaults to $MODULE_ROOT/Dockerfile. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[]` -[module](#module) > services +### `services` The list of services to deploy from this container module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].name` -[module](#module) > [services](#module.services[]) > name +### `services[].name` +[services](#services) > 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. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].dependencies[]` -[module](#module) > [services](#module.services[]) > dependencies +### `services[].dependencies[]` +[services](#services) > dependencies The names of any services that this service depends on at runtime, and the names of any tasks that should be executed before this service is deployed. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].annotations` -[module](#module) > [services](#module.services[]) > annotations +### `services[].annotations` +[services](#services) > annotations Annotations to attach to the service (Note: May not be applicable to all providers) | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].args[]` -[module](#module) > [services](#module.services[]) > args +### `services[].args[]` +[services](#services) > args The arguments to run the container with when starting the service. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].daemon` -[module](#module) > [services](#module.services[]) > daemon +### `services[].daemon` +[services](#services) > daemon Whether to run the service as a daemon (to ensure only one runs per node). | Type | Required | | ---- | -------- | | `boolean` | No -### `module.services[].ingresses[]` -[module](#module) > [services](#module.services[]) > ingresses +### `services[].ingresses[]` +[services](#services) > ingresses List of ingress endpoints that the service exposes. @@ -214,23 +292,21 @@ List of ingress endpoints that the service exposes. Example: ```yaml -module: - ... - services: - - ingresses: - - path: /api - port: http +services: + - ingresses: + - path: /api + port: http ``` -### `module.services[].ingresses[].annotations` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > annotations +### `services[].ingresses[].annotations` +[services](#services) > [ingresses](#services[].ingresses[]) > annotations Annotations to attach to the ingress (Note: May not be applicable to all providers) | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].ingresses[].hostname` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > hostname +### `services[].ingresses[].hostname` +[services](#services) > [ingresses](#services[].ingresses[]) > hostname The hostname that should route to this service. Defaults to the default hostname configured in the provider configuration. @@ -240,120 +316,120 @@ Note that if you're developing locally you may need to add this hostname to your | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ingresses[].path` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > path +### `services[].ingresses[].path` +[services](#services) > [ingresses](#services[].ingresses[]) > path The path which should be routed to the service. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ingresses[].port` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > port +### `services[].ingresses[].port` +[services](#services) > [ingresses](#services[].ingresses[]) > port The name of the container port where the specified paths should be routed. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].env` -[module](#module) > [services](#module.services[]) > env +### `services[].env` +[services](#services) > 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 -### `module.services[].healthCheck` -[module](#module) > [services](#module.services[]) > healthCheck +### `services[].healthCheck` +[services](#services) > healthCheck Specify how the service's health should be checked after deploying. | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].healthCheck.httpGet` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > httpGet +### `services[].healthCheck.httpGet` +[services](#services) > [healthCheck](#services[].healthcheck) > httpGet Set this to check the service's health by making an HTTP request. | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].healthCheck.httpGet.path` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > path +### `services[].healthCheck.httpGet.path` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > path The path of the service's health check endpoint. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].healthCheck.httpGet.port` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > port +### `services[].healthCheck.httpGet.port` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > port The name of the port where the service's health check endpoint should be available. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].healthCheck.httpGet.scheme` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > scheme +### `services[].healthCheck.httpGet.scheme` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > scheme | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].healthCheck.command[]` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > command +### `services[].healthCheck.command[]` +[services](#services) > [healthCheck](#services[].healthcheck) > command Set this to check the service's health by running a command in its container. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].healthCheck.tcpPort` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > tcpPort +### `services[].healthCheck.tcpPort` +[services](#services) > [healthCheck](#services[].healthcheck) > tcpPort Set this to check the service's health by checking if this TCP port is accepting connections. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].hotReloadArgs[]` -[module](#module) > [services](#module.services[]) > hotReloadArgs +### `services[].hotReloadArgs[]` +[services](#services) > hotReloadArgs If this module uses the `hotReload` field, the container will be run with these arguments instead of those in `args` when the service is deployed with hot reloading enabled. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].ports[]` -[module](#module) > [services](#module.services[]) > ports +### `services[].ports[]` +[services](#services) > ports List of ports that the service container exposes. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].ports[].name` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > name +### `services[].ports[].name` +[services](#services) > [ports](#services[].ports[]) > name The name of the port (used when referencing the port elsewhere in the service configuration). | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].ports[].protocol` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > protocol +### `services[].ports[].protocol` +[services](#services) > [ports](#services[].ports[]) > protocol The protocol of the port. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ports[].containerPort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > containerPort +### `services[].ports[].containerPort` +[services](#services) > [ports](#services[].ports[]) > containerPort The port exposed on the container by the running process. This will also be the default value for `servicePort`. `servicePort:80 -> containerPort:8080 -> process:8080` @@ -364,14 +440,12 @@ The port exposed on the container by the running process. This will also be the Example: ```yaml -module: - ... - services: - - ports: - - containerPort: "8080" +services: + - ports: + - containerPort: "8080" ``` -### `module.services[].ports[].servicePort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > servicePort +### `services[].ports[].servicePort` +[services](#services) > [ports](#services[].ports[]) > servicePort The port exposed on the service. Defaults to `containerPort` if not specified. `servicePort:80 -> containerPort:8080 -> process:8080` @@ -382,94 +456,91 @@ The port exposed on the service. Defaults to `containerPort` if not specified. Example: ```yaml -module: - ... - services: - - ports: - - servicePort: "80" +services: + - ports: + - servicePort: "80" ``` -### `module.services[].ports[].hostPort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > hostPort +### `services[].ports[].hostPort` +[services](#services) > [ports](#services[].ports[]) > hostPort | Type | Required | | ---- | -------- | | `number` | No -### `module.services[].ports[].nodePort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > nodePort +### `services[].ports[].nodePort` +[services](#services) > [ports](#services[].ports[]) > nodePort Set this to expose the service on the specified port on the host node (may not be supported by all providers). | Type | Required | | ---- | -------- | | `number` | No -### `module.services[].volumes[]` -[module](#module) > [services](#module.services[]) > volumes +### `services[].volumes[]` +[services](#services) > volumes List of volumes that should be mounted when deploying the container. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].volumes[].name` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > name +### `services[].volumes[].name` +[services](#services) > [volumes](#services[].volumes[]) > name The name of the allocated volume. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].volumes[].containerPath` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > containerPath +### `services[].volumes[].containerPath` +[services](#services) > [volumes](#services[].volumes[]) > containerPath The path where the volume should be mounted in the container. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].volumes[].hostPath` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > hostPath +### `services[].volumes[].hostPath` +[services](#services) > [volumes](#services[].volumes[]) > hostPath | Type | Required | | ---- | -------- | | `string` | No -### `module.tests[]` -[module](#module) > tests +### `tests` A list of tests to run in the module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tests[].name` -[module](#module) > [tests](#module.tests[]) > name +### `tests[].name` +[tests](#tests) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tests[].dependencies[]` -[module](#module) > [tests](#module.tests[]) > dependencies +### `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 -### `module.tests[].timeout` -[module](#module) > [tests](#module.tests[]) > timeout +### `tests[].timeout` +[tests](#tests) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tests[].args[]` -[module](#module) > [tests](#module.tests[]) > args +### `tests[].args[]` +[tests](#tests) > args The arguments used to run the test inside the container. @@ -479,63 +550,60 @@ The arguments used to run the test inside the container. Example: ```yaml -module: - ... - tests: - - args: - - npm - - test +tests: + - args: + - npm + - test ``` -### `module.tests[].env` -[module](#module) > [tests](#module.tests[]) > env +### `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 -### `module.tasks[]` -[module](#module) > tasks +### `tasks` A list of tasks that can be run from this container module. These can be used as dependencies for services (executed before the service is deployed) or for other tasks. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tasks[].name` -[module](#module) > [tasks](#module.tasks[]) > name +### `tasks[].name` +[tasks](#tasks) > name The name of the task. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tasks[].description` -[module](#module) > [tasks](#module.tasks[]) > description +### `tasks[].description` +[tasks](#tasks) > description A description of the task. | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].dependencies[]` -[module](#module) > [tasks](#module.tasks[]) > dependencies +### `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 -### `module.tasks[].timeout` -[module](#module) > [tasks](#module.tasks[]) > timeout +### `tasks[].timeout` +[tasks](#tasks) > timeout Maximum duration (in seconds) of the task's execution. | Type | Required | | ---- | -------- | | `number` | No -### `module.tasks[].args[]` -[module](#module) > [tasks](#module.tasks[]) > args +### `tasks[].args[]` +[tasks](#tasks) > args The arguments used to run the task inside the container. @@ -545,15 +613,13 @@ The arguments used to run the task inside the container. Example: ```yaml -module: - ... - tasks: - - args: - - rake - - 'db:migrate' +tasks: + - args: + - rake + - 'db:migrate' ``` -### `module.tasks[].env` -[module](#module) > [tasks](#module.tasks[]) > env +### `tasks[].env` +[tasks](#tasks) > 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. @@ -564,63 +630,70 @@ Key/value map of environment variables. Keys must be valid POSIX environment var ## Complete YAML schema ```yaml -module: - build: - dependencies: - - name: - copy: - - source: - target: '' - targetImage: - buildArgs: {} - image: - hotReload: - sync: - - source: . - target: - dockerfile: - services: - - name: - dependencies: [] - annotations: {} - args: - daemon: false - ingresses: - - annotations: {} - hostname: - path: / - port: - env: {} - healthCheck: - httpGet: - path: - port: - scheme: HTTP - command: - tcpPort: - hotReloadArgs: - ports: - - name: - protocol: TCP - containerPort: - servicePort: - hostPort: - nodePort: - volumes: - - name: - containerPath: - hostPath: - tests: +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: - name: - dependencies: [] - timeout: null - args: - env: {} - tasks: - - name: - description: - dependencies: [] - timeout: null - args: - env: {} -``` + copy: + - source: + target: '' + targetImage: +buildArgs: {} +image: +hotReload: + sync: + - source: . + target: +dockerfile: +services: + - name: + dependencies: [] + annotations: {} + args: + daemon: false + ingresses: + - annotations: {} + hostname: + path: / + port: + env: {} + healthCheck: + httpGet: + path: + port: + scheme: HTTP + command: + tcpPort: + hotReloadArgs: + ports: + - name: + protocol: TCP + containerPort: + servicePort: + hostPort: + nodePort: + volumes: + - name: + containerPath: + hostPath: +tests: + - name: + dependencies: [] + timeout: null + args: + env: {} +tasks: + - name: + description: + dependencies: [] + timeout: null + args: + env: {} +``` \ No newline at end of file diff --git a/docs/reference/module-types/exec.md b/docs/reference/module-types/exec.md index a08e42506e..b0ec35b966 100644 --- a/docs/reference/module-types/exec.md +++ b/docs/reference/module-types/exec.md @@ -1,28 +1,112 @@ # `exec` reference -Below is the schema reference for the `exec` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +A simple module for executing commands in your shell. This can be a useful escape hatch if no other module +type fits your needs, and you just need to execute something (as opposed to deploy it, track its status etc.). -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` -The module specification for an exec module. +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` + +The type of this module. | Type | Required | | ---- | -------- | -| `object` | No -### `module.build` -[module](#module) > build +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + + + +| Type | Required | +| ---- | -------- | +| `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No + +Example: +```yaml +include: + - Dockerfile + - my-app.js +``` +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -32,47 +116,45 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.build.command[]` -[module](#module) > [build](#module.build) > command +### `build.command[]` +[build](#build) > command The command to run inside the module's directory to perform the build. @@ -82,113 +164,108 @@ The command to run inside the module's directory to perform the build. Example: ```yaml -module: +build: ... - build: - ... - command: - - npm - - run - - build + command: + - npm + - run + - build ``` -### `module.env` -[module](#module) > env +### `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 -### `module.tasks[]` -[module](#module) > tasks +### `tasks` A list of tasks that can be run in this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tasks[].name` -[module](#module) > [tasks](#module.tasks[]) > name +### `tasks[].name` +[tasks](#tasks) > name The name of the task. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tasks[].description` -[module](#module) > [tasks](#module.tasks[]) > description +### `tasks[].description` +[tasks](#tasks) > description A description of the task. | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].dependencies[]` -[module](#module) > [tasks](#module.tasks[]) > dependencies +### `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 -### `module.tasks[].timeout` -[module](#module) > [tasks](#module.tasks[]) > timeout +### `tasks[].timeout` +[tasks](#tasks) > timeout Maximum duration (in seconds) of the task's execution. | Type | Required | | ---- | -------- | | `number` | No -### `module.tasks[].command[]` -[module](#module) > [tasks](#module.tasks[]) > command +### `tasks[].command[]` +[tasks](#tasks) > command The command to run in the module build context. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tests[]` -[module](#module) > tests +### `tests` A list of tests to run in the module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tests[].name` -[module](#module) > [tests](#module.tests[]) > name +### `tests[].name` +[tests](#tests) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tests[].dependencies[]` -[module](#module) > [tests](#module.tests[]) > dependencies +### `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 -### `module.tests[].timeout` -[module](#module) > [tests](#module.tests[]) > timeout +### `tests[].timeout` +[tests](#tests) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tests[].command[]` -[module](#module) > [tests](#module.tests[]) > command +### `tests[].command[]` +[tests](#tests) > command The command to run in the module build context in order to test it. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tests[].env` -[module](#module) > [tests](#module.tests[]) > env +### `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. @@ -199,26 +276,33 @@ Key/value map of environment variables. Keys must be valid POSIX environment var ## Complete YAML schema ```yaml -module: - build: - dependencies: - - name: - copy: - - source: - target: '' - command: - [] - env: {} - tasks: - - name: - description: - dependencies: [] - timeout: null - command: - tests: +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: - name: - dependencies: [] - timeout: null - command: - env: {} -``` + copy: + - source: + target: '' + command: + [] +env: {} +tasks: + - name: + description: + dependencies: [] + timeout: null + command: +tests: + - name: + dependencies: [] + timeout: null + command: + env: {} +``` \ No newline at end of file diff --git a/docs/reference/module-types/helm.md b/docs/reference/module-types/helm.md index 08c987ceaa..6e30ae6b4a 100644 --- a/docs/reference/module-types/helm.md +++ b/docs/reference/module-types/helm.md @@ -1,45 +1,112 @@ # `helm` reference -Below is the schema reference for the `helm` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +Specify a Helm chart (either in your repository or remote from a registry) to deploy. +Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts) for usage instructions. -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` + +The type of this module. + | Type | Required | | ---- | -------- | -| `object` | No -### `module.base` -[module](#module) > base +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + -The name of another `helm` module to use as a base for this one. Use this to re-use a Helm chart across multiple services. For example, you might have an organization-wide base chart for certain types of services. -If set, this module will by default inherit the following properties from the base module: `serviceResource`, `values` -Each of those can be overridden in this module. They will be merged with a JSON Merge Patch (RFC 7396). | Type | Required | | ---- | -------- | | `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No Example: ```yaml -module: - ... - base: "my-base-chart" +include: + - Dockerfile + - my-app.js ``` -### `module.build` -[module](#module) > build +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -49,47 +116,58 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.chart` -[module](#module) > chart +### `base` + +The name of another `helm` module to use as a base for this one. Use this to re-use a Helm chart across multiple services. For example, you might have an organization-wide base chart for certain types of services. +If set, this module will by default inherit the following properties from the base module: `serviceResource`, `values` +Each of those can be overridden in this module. They will be merged with a JSON Merge Patch (RFC 7396). + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +base: "my-base-chart" +``` +### `chart` A valid Helm chart name or URI (same as you'd input to `helm install`). Required if the module doesn't contain the Helm chart itself. @@ -99,44 +177,37 @@ A valid Helm chart name or URI (same as you'd input to `helm install`). Required Example: ```yaml -module: - ... - chart: "stable/nginx-ingress" +chart: "stable/nginx-ingress" ``` -### `module.chartPath` -[module](#module) > chartPath +### `chartPath` The path, relative to the module path, to the chart sources (i.e. where the Chart.yaml file is, if any). Not used when `base` is specified. | Type | Required | | ---- | -------- | | `string` | No -### `module.dependencies[]` -[module](#module) > dependencies +### `dependencies` List of names of services that should be deployed before this chart. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.releaseName` -[module](#module) > releaseName +### `releaseName` Optionally override the release name used when installing (defaults to the module name). | Type | Required | | ---- | -------- | | `string` | No -### `module.repo` -[module](#module) > repo +### `repo` The repository URL to fetch the chart from. | Type | Required | | ---- | -------- | | `string` | No -### `module.serviceResource` -[module](#module) > serviceResource +### `serviceResource` The Deployment, DaemonSet or StatefulSet that Garden should regard as the _Garden service_ in this module (not to be confused with Kubernetes Service resources). Because a Helm chart can contain any number of Kubernetes resources, this needs to be specified for certain Garden features and commands to work, such as hot-reloading. We currently map a Helm chart to a single Garden service, because all the resources in a Helm chart are deployed at once. @@ -144,16 +215,16 @@ We currently map a Helm chart to a single Garden service, because all the resour | Type | Required | | ---- | -------- | | `object` | No -### `module.serviceResource.kind` -[module](#module) > [serviceResource](#module.serviceresource) > kind +### `serviceResource.kind` +[serviceResource](#serviceresource) > kind The type of Kubernetes resource to sync files to. | Type | Required | Allowed Values | | ---- | -------- | -------------- | | `string` | Yes | "Deployment", "DaemonSet", "StatefulSet" -### `module.serviceResource.name` -[module](#module) > [serviceResource](#module.serviceresource) > name +### `serviceResource.name` +[serviceResource](#serviceresource) > name The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . }}'. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly. @@ -161,16 +232,16 @@ This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . | Type | Required | | ---- | -------- | | `string` | No -### `module.serviceResource.containerName` -[module](#module) > [serviceResource](#module.serviceresource) > containerName +### `serviceResource.containerName` +[serviceResource](#serviceresource) > containerName The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec. | Type | Required | | ---- | -------- | | `string` | No -### `module.serviceResource.containerModule` -[module](#module) > [serviceResource](#module.serviceresource) > containerModule +### `serviceResource.containerModule` +[serviceResource](#serviceresource) > containerModule The Garden module that contains the sources for the container. This needs to be specified under `serviceResource` in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a `container` module, and for hot-reloading to work you must specify the `hotReload` field on the container module. @@ -182,14 +253,12 @@ Note: If you specify a module here, you don't need to specify it additionally un Example: ```yaml -module: +serviceResource: ... - serviceResource: - ... - containerModule: "my-container-module" + containerModule: "my-container-module" ``` -### `module.serviceResource.hotReloadArgs[]` -[module](#module) > [serviceResource](#module.serviceresource) > hotReloadArgs +### `serviceResource.hotReloadArgs[]` +[serviceResource](#serviceresource) > hotReloadArgs If specified, overrides the arguments for the main container when running in hot-reload mode. @@ -199,72 +268,68 @@ If specified, overrides the arguments for the main container when running in hot Example: ```yaml -module: +serviceResource: ... - serviceResource: - ... - hotReloadArgs: - - nodemon - - my-server.js + hotReloadArgs: + - nodemon + - my-server.js ``` -### `module.skipDeploy` -[module](#module) > skipDeploy +### `skipDeploy` Set this to true if the chart should only be built, but not deployed as a service. Use this, for example, if the chart should only be used as a base for other modules. | Type | Required | | ---- | -------- | | `boolean` | No -### `module.tasks[]` -[module](#module) > tasks +### `tasks` The task definitions for this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tasks[].name` -[module](#module) > [tasks](#module.tasks[]) > name +### `tasks[].name` +[tasks](#tasks) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tasks[].dependencies[]` -[module](#module) > [tasks](#module.tasks[]) > dependencies +### `tasks[].dependencies[]` +[tasks](#tasks) > 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 -### `module.tasks[].timeout` -[module](#module) > [tasks](#module.tasks[]) > timeout +### `tasks[].timeout` +[tasks](#tasks) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tasks[].resource` -[module](#module) > [tasks](#module.tasks[]) > resource +### `tasks[].resource` +[tasks](#tasks) > resource The Deployment, DaemonSet or StatefulSet that Garden should use to execute this task. If not specified, the `serviceResource` configured on the module will be used. If neither is specified, an error will be thrown. | Type | Required | | ---- | -------- | | `object` | No -### `module.tasks[].resource.kind` -[module](#module) > [tasks](#module.tasks[]) > [resource](#module.tasks[].resource) > kind +### `tasks[].resource.kind` +[tasks](#tasks) > [resource](#tasks[].resource) > kind The type of Kubernetes resource to sync files to. | Type | Required | Allowed Values | | ---- | -------- | -------------- | | `string` | Yes | "Deployment", "DaemonSet", "StatefulSet" -### `module.tasks[].resource.name` -[module](#module) > [tasks](#module.tasks[]) > [resource](#module.tasks[].resource) > name +### `tasks[].resource.name` +[tasks](#tasks) > [resource](#tasks[].resource) > name The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . }}'. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly. @@ -272,16 +337,16 @@ This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].resource.containerName` -[module](#module) > [tasks](#module.tasks[]) > [resource](#module.tasks[].resource) > containerName +### `tasks[].resource.containerName` +[tasks](#tasks) > [resource](#tasks[].resource) > containerName The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec. | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].resource.containerModule` -[module](#module) > [tasks](#module.tasks[]) > [resource](#module.tasks[].resource) > containerModule +### `tasks[].resource.containerModule` +[tasks](#tasks) > [resource](#tasks[].resource) > containerModule The Garden module that contains the sources for the container. This needs to be specified under `serviceResource` in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a `container` module, and for hot-reloading to work you must specify the `hotReload` field on the container module. @@ -293,15 +358,13 @@ Note: If you specify a module here, you don't need to specify it additionally un Example: ```yaml -module: - ... - tasks: - - resource: - ... - containerModule: "my-container-module" +tasks: + - resource: + ... + containerModule: "my-container-module" ``` -### `module.tasks[].resource.hotReloadArgs[]` -[module](#module) > [tasks](#module.tasks[]) > [resource](#module.tasks[].resource) > hotReloadArgs +### `tasks[].resource.hotReloadArgs[]` +[tasks](#tasks) > [resource](#tasks[].resource) > hotReloadArgs If specified, overrides the arguments for the main container when running in hot-reload mode. @@ -311,81 +374,78 @@ If specified, overrides the arguments for the main container when running in hot Example: ```yaml -module: - ... - tasks: - - resource: - ... - hotReloadArgs: - - nodemon - - my-server.js +tasks: + - resource: + ... + hotReloadArgs: + - nodemon + - my-server.js ``` -### `module.tasks[].args[]` -[module](#module) > [tasks](#module.tasks[]) > args +### `tasks[].args[]` +[tasks](#tasks) > args The arguments to pass to the pod used for execution. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tasks[].env` -[module](#module) > [tasks](#module.tasks[]) > env +### `tasks[].env` +[tasks](#tasks) > 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 -### `module.tests[]` -[module](#module) > tests +### `tests` The test suite definitions for this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tests[].name` -[module](#module) > [tests](#module.tests[]) > name +### `tests[].name` +[tests](#tests) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tests[].dependencies[]` -[module](#module) > [tests](#module.tests[]) > dependencies +### `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 -### `module.tests[].timeout` -[module](#module) > [tests](#module.tests[]) > timeout +### `tests[].timeout` +[tests](#tests) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tests[].resource` -[module](#module) > [tests](#module.tests[]) > resource +### `tests[].resource` +[tests](#tests) > resource The Deployment, DaemonSet or StatefulSet that Garden should use to execute this test suite. If not specified, the `serviceResource` configured on the module will be used. If neither is specified, an error will be thrown. | Type | Required | | ---- | -------- | | `object` | No -### `module.tests[].resource.kind` -[module](#module) > [tests](#module.tests[]) > [resource](#module.tests[].resource) > kind +### `tests[].resource.kind` +[tests](#tests) > [resource](#tests[].resource) > kind The type of Kubernetes resource to sync files to. | Type | Required | Allowed Values | | ---- | -------- | -------------- | | `string` | Yes | "Deployment", "DaemonSet", "StatefulSet" -### `module.tests[].resource.name` -[module](#module) > [tests](#module.tests[]) > [resource](#module.tests[].resource) > name +### `tests[].resource.name` +[tests](#tests) > [resource](#tests[].resource) > name The name of the resource to sync to. If the chart contains a single resource of the specified Kind, this can be omitted. This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . }}'. This allows you to easily match the dynamic names given by Helm. In most cases you should copy this directly from the template in question in order to match it. Note that you may need to add single quotes around the string for the YAML to be parsed correctly. @@ -393,16 +453,16 @@ This can include a Helm template string, e.g. '{{ template "my-chart.fullname" . | Type | Required | | ---- | -------- | | `string` | No -### `module.tests[].resource.containerName` -[module](#module) > [tests](#module.tests[]) > [resource](#module.tests[].resource) > containerName +### `tests[].resource.containerName` +[tests](#tests) > [resource](#tests[].resource) > containerName The name of a container in the target. Specify this if the target contains more than one container and the main container is not the first container in the spec. | Type | Required | | ---- | -------- | | `string` | No -### `module.tests[].resource.containerModule` -[module](#module) > [tests](#module.tests[]) > [resource](#module.tests[].resource) > containerModule +### `tests[].resource.containerModule` +[tests](#tests) > [resource](#tests[].resource) > containerModule The Garden module that contains the sources for the container. This needs to be specified under `serviceResource` in order to enable hot-reloading for the chart, but is not necessary for tasks and tests. Must be a `container` module, and for hot-reloading to work you must specify the `hotReload` field on the container module. @@ -414,15 +474,13 @@ Note: If you specify a module here, you don't need to specify it additionally un Example: ```yaml -module: - ... - tests: - - resource: - ... - containerModule: "my-container-module" +tests: + - resource: + ... + containerModule: "my-container-module" ``` -### `module.tests[].resource.hotReloadArgs[]` -[module](#module) > [tests](#module.tests[]) > [resource](#module.tests[].resource) > hotReloadArgs +### `tests[].resource.hotReloadArgs[]` +[tests](#tests) > [resource](#tests[].resource) > hotReloadArgs If specified, overrides the arguments for the main container when running in hot-reload mode. @@ -432,41 +490,37 @@ If specified, overrides the arguments for the main container when running in hot Example: ```yaml -module: - ... - tests: - - resource: - ... - hotReloadArgs: - - nodemon - - my-server.js +tests: + - resource: + ... + hotReloadArgs: + - nodemon + - my-server.js ``` -### `module.tests[].args[]` -[module](#module) > [tests](#module.tests[]) > args +### `tests[].args[]` +[tests](#tests) > args The arguments to pass to the pod used for testing. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tests[].env` -[module](#module) > [tests](#module.tests[]) > env +### `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 -### `module.version` -[module](#module) > version +### `version` The chart version to deploy. | Type | Required | | ---- | -------- | | `string` | No -### `module.values` -[module](#module) > values +### `values` Map of values to pass to Helm when rendering the templates. May include arrays and nested objects. @@ -477,50 +531,57 @@ Map of values to pass to Helm when rendering the templates. May include arrays a ## Complete YAML schema ```yaml -module: - base: - build: - dependencies: - - name: - copy: - - source: - target: '' - chart: - chartPath: . - dependencies: [] - releaseName: - repo: - serviceResource: - kind: Deployment - name: - containerName: - containerModule: - hotReloadArgs: - skipDeploy: false - tasks: +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: - name: - dependencies: [] - timeout: null - resource: - kind: Deployment - name: - containerName: - containerModule: - hotReloadArgs: - args: - env: {} - tests: - - name: - dependencies: [] - timeout: null - resource: - kind: Deployment - name: - containerName: - containerModule: - hotReloadArgs: - args: - env: {} - version: - values: {} -``` + copy: + - source: + target: '' +base: +chart: +chartPath: . +dependencies: [] +releaseName: +repo: +serviceResource: + kind: Deployment + name: + containerName: + containerModule: + hotReloadArgs: +skipDeploy: false +tasks: + - name: + dependencies: [] + timeout: null + resource: + kind: Deployment + name: + containerName: + containerModule: + hotReloadArgs: + args: + env: {} +tests: + - name: + dependencies: [] + timeout: null + resource: + kind: Deployment + name: + containerName: + containerModule: + hotReloadArgs: + args: + env: {} +version: +values: {} +``` \ No newline at end of file diff --git a/docs/reference/module-types/kubernetes.md b/docs/reference/module-types/kubernetes.md index 60be33be01..8586896969 100644 --- a/docs/reference/module-types/kubernetes.md +++ b/docs/reference/module-types/kubernetes.md @@ -1,28 +1,120 @@ # `kubernetes` reference -Below is the schema reference for the `kubernetes` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +Specify one or more Kubernetes manifests to deploy. -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +You can either (or both) specify the manifests as part of the `garden.yml` configuration, or you can refer to +one or more files with existing manifests. + +Note that if you include the manifests in the `garden.yml` file, you can use +[template strings](https://docs.garden.io/reference/template-strings) to interpolate values into the manifests. + +If you need more advanced templating features you can use the +[helm](https://docs.garden.io/reference/module-types/helm) module type. + +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` + +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` +The type of this module. | Type | Required | | ---- | -------- | -| `object` | No -### `module.build` -[module](#module) > build +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + + + +| Type | Required | +| ---- | -------- | +| `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No + +Example: +```yaml +include: + - Dockerfile + - my-app.js +``` +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -32,95 +124,90 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.dependencies[]` -[module](#module) > dependencies +### `dependencies` List of names of services that should be deployed before this chart. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.manifests[]` -[module](#module) > manifests +### `manifests` List of Kubernetes resource manifests to deploy. Use this instead of the `files` field if you need to resolve template strings in any of the manifests. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.manifests[].apiVersion` -[module](#module) > [manifests](#module.manifests[]) > apiVersion +### `manifests[].apiVersion` +[manifests](#manifests) > apiVersion The API version of the resource. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.manifests[].kind` -[module](#module) > [manifests](#module.manifests[]) > kind +### `manifests[].kind` +[manifests](#manifests) > kind The kind of the resource. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.manifests[].metadata` -[module](#module) > [manifests](#module.manifests[]) > metadata +### `manifests[].metadata` +[manifests](#manifests) > metadata | Type | Required | | ---- | -------- | | `object` | Yes -### `module.manifests[].metadata.name` -[module](#module) > [manifests](#module.manifests[]) > [metadata](#module.manifests[].metadata) > name +### `manifests[].metadata.name` +[manifests](#manifests) > [metadata](#manifests[].metadata) > name The name of the resource. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.files[]` -[module](#module) > files +### `files` POSIX-style paths to YAML files to load manifests from. Each can contain multiple manifests. @@ -131,18 +218,25 @@ POSIX-style paths to YAML files to load manifests from. Each can contain multipl ## Complete YAML schema ```yaml -module: - build: - dependencies: - - name: - copy: - - source: - target: '' - dependencies: [] - manifests: - - apiVersion: - kind: - metadata: - name: - files: [] -``` +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: + - name: + copy: + - source: + target: '' +dependencies: [] +manifests: + - apiVersion: + kind: + metadata: + name: +files: [] +``` \ No newline at end of file diff --git a/docs/reference/module-types/maven-container.md b/docs/reference/module-types/maven-container.md index fbe991c3db..656f832896 100644 --- a/docs/reference/module-types/maven-container.md +++ b/docs/reference/module-types/maven-container.md @@ -1,28 +1,122 @@ # `maven-container` reference -Below is the schema reference for the `maven-container` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +A specialized version of the [container](https://docs.garden.io/reference/module-types/container) module type +that has special semantics for JAR files built with Maven. -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Rather than build the JAR inside the container (or in a multi-stage build) this plugin runs `mvn package` +ahead of building the container, which tends to be much more performant, especially when building locally +with a warm artifact cache. + +A default Dockerfile is also provided for convenience, but you may override it by including one in the module +directory. + +To use it, make sure to add the `maven-container` provider to your project configuration. +The provider will automatically fetch and cache Maven and the appropriate OpenJDK version ahead of building. + +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` + +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` -Configuration for a container module. + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` + +The type of this module. | Type | Required | | ---- | -------- | -| `object` | No -### `module.build` -[module](#module) > build +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + + + +| Type | Required | +| ---- | -------- | +| `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No + +Example: +```yaml +include: + - Dockerfile + - my-app.js +``` +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -32,87 +126,82 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.build.targetImage` -[module](#module) > [build](#module.build) > targetImage +### `build.targetImage` +[build](#build) > targetImage For multi-stage Dockerfiles, specify which image to build (see https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target for details). | Type | Required | | ---- | -------- | | `string` | No -### `module.buildArgs` -[module](#module) > buildArgs +### `buildArgs` Specify build arguments to use when building the container image. | Type | Required | | ---- | -------- | | `object` | No -### `module.image` -[module](#module) > image +### `image` Specify the image name for the container. Should be a valid Docker image identifier. If specified and the module does not contain a Dockerfile, this image will be used to deploy services for this module. If specified and the module does contain a Dockerfile, this identifier is used when pushing the built image. | Type | Required | | ---- | -------- | | `string` | No -### `module.hotReload` -[module](#module) > hotReload +### `hotReload` Specifies which files or directories to sync to which paths inside the running containers of hot reload-enabled services when those files or directories are modified. Applies to this module's services, and to services with this module as their `sourceModule`. | Type | Required | | ---- | -------- | | `object` | No -### `module.hotReload.sync[]` -[module](#module) > [hotReload](#module.hotreload) > sync +### `hotReload.sync[]` +[hotReload](#hotreload) > sync Specify one or more source files or directories to automatically sync into the running container. | Type | Required | | ---- | -------- | | `array[object]` | Yes -### `module.hotReload.sync[].source` -[module](#module) > [hotReload](#module.hotreload) > [sync](#module.hotreload.sync[]) > source +### `hotReload.sync[].source` +[hotReload](#hotreload) > [sync](#hotreload.sync[]) > source POSIX-style path of the directory to sync to the target, relative to the module's top-level directory. Must be a relative path if provided. Defaults to the module's top-level directory if no value is provided. @@ -122,15 +211,13 @@ POSIX-style path of the directory to sync to the target, relative to the module' Example: ```yaml -module: +hotReload: ... - hotReload: - ... - sync: - - source: "src" + sync: + - source: "src" ``` -### `module.hotReload.sync[].target` -[module](#module) > [hotReload](#module.hotreload) > [sync](#module.hotreload.sync[]) > target +### `hotReload.sync[].target` +[hotReload](#hotreload) > [sync](#hotreload.sync[]) > target POSIX-style absolute path to sync the directory to inside the container. The root path (i.e. "/") is not allowed. @@ -140,71 +227,67 @@ POSIX-style absolute path to sync the directory to inside the container. The roo Example: ```yaml -module: +hotReload: ... - hotReload: - ... - sync: - - target: "/app/src" + sync: + - target: "/app/src" ``` -### `module.dockerfile` -[module](#module) > dockerfile +### `dockerfile` POSIX-style name of Dockerfile, relative to project root. Defaults to $MODULE_ROOT/Dockerfile. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[]` -[module](#module) > services +### `services` The list of services to deploy from this container module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].name` -[module](#module) > [services](#module.services[]) > name +### `services[].name` +[services](#services) > 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. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].dependencies[]` -[module](#module) > [services](#module.services[]) > dependencies +### `services[].dependencies[]` +[services](#services) > dependencies The names of any services that this service depends on at runtime, and the names of any tasks that should be executed before this service is deployed. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].annotations` -[module](#module) > [services](#module.services[]) > annotations +### `services[].annotations` +[services](#services) > annotations Annotations to attach to the service (Note: May not be applicable to all providers) | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].args[]` -[module](#module) > [services](#module.services[]) > args +### `services[].args[]` +[services](#services) > args The arguments to run the container with when starting the service. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].daemon` -[module](#module) > [services](#module.services[]) > daemon +### `services[].daemon` +[services](#services) > daemon Whether to run the service as a daemon (to ensure only one runs per node). | Type | Required | | ---- | -------- | | `boolean` | No -### `module.services[].ingresses[]` -[module](#module) > [services](#module.services[]) > ingresses +### `services[].ingresses[]` +[services](#services) > ingresses List of ingress endpoints that the service exposes. @@ -214,23 +297,21 @@ List of ingress endpoints that the service exposes. Example: ```yaml -module: - ... - services: - - ingresses: - - path: /api - port: http +services: + - ingresses: + - path: /api + port: http ``` -### `module.services[].ingresses[].annotations` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > annotations +### `services[].ingresses[].annotations` +[services](#services) > [ingresses](#services[].ingresses[]) > annotations Annotations to attach to the ingress (Note: May not be applicable to all providers) | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].ingresses[].hostname` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > hostname +### `services[].ingresses[].hostname` +[services](#services) > [ingresses](#services[].ingresses[]) > hostname The hostname that should route to this service. Defaults to the default hostname configured in the provider configuration. @@ -240,120 +321,120 @@ Note that if you're developing locally you may need to add this hostname to your | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ingresses[].path` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > path +### `services[].ingresses[].path` +[services](#services) > [ingresses](#services[].ingresses[]) > path The path which should be routed to the service. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ingresses[].port` -[module](#module) > [services](#module.services[]) > [ingresses](#module.services[].ingresses[]) > port +### `services[].ingresses[].port` +[services](#services) > [ingresses](#services[].ingresses[]) > port The name of the container port where the specified paths should be routed. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].env` -[module](#module) > [services](#module.services[]) > env +### `services[].env` +[services](#services) > 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 -### `module.services[].healthCheck` -[module](#module) > [services](#module.services[]) > healthCheck +### `services[].healthCheck` +[services](#services) > healthCheck Specify how the service's health should be checked after deploying. | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].healthCheck.httpGet` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > httpGet +### `services[].healthCheck.httpGet` +[services](#services) > [healthCheck](#services[].healthcheck) > httpGet Set this to check the service's health by making an HTTP request. | Type | Required | | ---- | -------- | | `object` | No -### `module.services[].healthCheck.httpGet.path` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > path +### `services[].healthCheck.httpGet.path` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > path The path of the service's health check endpoint. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].healthCheck.httpGet.port` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > port +### `services[].healthCheck.httpGet.port` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > port The name of the port where the service's health check endpoint should be available. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].healthCheck.httpGet.scheme` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > [httpGet](#module.services[].healthcheck.httpget) > scheme +### `services[].healthCheck.httpGet.scheme` +[services](#services) > [healthCheck](#services[].healthcheck) > [httpGet](#services[].healthcheck.httpget) > scheme | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].healthCheck.command[]` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > command +### `services[].healthCheck.command[]` +[services](#services) > [healthCheck](#services[].healthcheck) > command Set this to check the service's health by running a command in its container. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].healthCheck.tcpPort` -[module](#module) > [services](#module.services[]) > [healthCheck](#module.services[].healthcheck) > tcpPort +### `services[].healthCheck.tcpPort` +[services](#services) > [healthCheck](#services[].healthcheck) > tcpPort Set this to check the service's health by checking if this TCP port is accepting connections. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].hotReloadArgs[]` -[module](#module) > [services](#module.services[]) > hotReloadArgs +### `services[].hotReloadArgs[]` +[services](#services) > hotReloadArgs If this module uses the `hotReload` field, the container will be run with these arguments instead of those in `args` when the service is deployed with hot reloading enabled. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.services[].ports[]` -[module](#module) > [services](#module.services[]) > ports +### `services[].ports[]` +[services](#services) > ports List of ports that the service container exposes. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].ports[].name` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > name +### `services[].ports[].name` +[services](#services) > [ports](#services[].ports[]) > name The name of the port (used when referencing the port elsewhere in the service configuration). | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].ports[].protocol` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > protocol +### `services[].ports[].protocol` +[services](#services) > [ports](#services[].ports[]) > protocol The protocol of the port. | Type | Required | | ---- | -------- | | `string` | No -### `module.services[].ports[].containerPort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > containerPort +### `services[].ports[].containerPort` +[services](#services) > [ports](#services[].ports[]) > containerPort The port exposed on the container by the running process. This will also be the default value for `servicePort`. `servicePort:80 -> containerPort:8080 -> process:8080` @@ -364,14 +445,12 @@ The port exposed on the container by the running process. This will also be the Example: ```yaml -module: - ... - services: - - ports: - - containerPort: "8080" +services: + - ports: + - containerPort: "8080" ``` -### `module.services[].ports[].servicePort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > servicePort +### `services[].ports[].servicePort` +[services](#services) > [ports](#services[].ports[]) > servicePort The port exposed on the service. Defaults to `containerPort` if not specified. `servicePort:80 -> containerPort:8080 -> process:8080` @@ -382,94 +461,91 @@ The port exposed on the service. Defaults to `containerPort` if not specified. Example: ```yaml -module: - ... - services: - - ports: - - servicePort: "80" +services: + - ports: + - servicePort: "80" ``` -### `module.services[].ports[].hostPort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > hostPort +### `services[].ports[].hostPort` +[services](#services) > [ports](#services[].ports[]) > hostPort | Type | Required | | ---- | -------- | | `number` | No -### `module.services[].ports[].nodePort` -[module](#module) > [services](#module.services[]) > [ports](#module.services[].ports[]) > nodePort +### `services[].ports[].nodePort` +[services](#services) > [ports](#services[].ports[]) > nodePort Set this to expose the service on the specified port on the host node (may not be supported by all providers). | Type | Required | | ---- | -------- | | `number` | No -### `module.services[].volumes[]` -[module](#module) > [services](#module.services[]) > volumes +### `services[].volumes[]` +[services](#services) > volumes List of volumes that should be mounted when deploying the container. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.services[].volumes[].name` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > name +### `services[].volumes[].name` +[services](#services) > [volumes](#services[].volumes[]) > name The name of the allocated volume. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].volumes[].containerPath` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > containerPath +### `services[].volumes[].containerPath` +[services](#services) > [volumes](#services[].volumes[]) > containerPath The path where the volume should be mounted in the container. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.services[].volumes[].hostPath` -[module](#module) > [services](#module.services[]) > [volumes](#module.services[].volumes[]) > hostPath +### `services[].volumes[].hostPath` +[services](#services) > [volumes](#services[].volumes[]) > hostPath | Type | Required | | ---- | -------- | | `string` | No -### `module.tests[]` -[module](#module) > tests +### `tests` A list of tests to run in the module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tests[].name` -[module](#module) > [tests](#module.tests[]) > name +### `tests[].name` +[tests](#tests) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tests[].dependencies[]` -[module](#module) > [tests](#module.tests[]) > dependencies +### `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 -### `module.tests[].timeout` -[module](#module) > [tests](#module.tests[]) > timeout +### `tests[].timeout` +[tests](#tests) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tests[].args[]` -[module](#module) > [tests](#module.tests[]) > args +### `tests[].args[]` +[tests](#tests) > args The arguments used to run the test inside the container. @@ -479,63 +555,60 @@ The arguments used to run the test inside the container. Example: ```yaml -module: - ... - tests: - - args: - - npm - - test +tests: + - args: + - npm + - test ``` -### `module.tests[].env` -[module](#module) > [tests](#module.tests[]) > env +### `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 -### `module.tasks[]` -[module](#module) > tasks +### `tasks` A list of tasks that can be run from this container module. These can be used as dependencies for services (executed before the service is deployed) or for other tasks. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tasks[].name` -[module](#module) > [tasks](#module.tasks[]) > name +### `tasks[].name` +[tasks](#tasks) > name The name of the task. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tasks[].description` -[module](#module) > [tasks](#module.tasks[]) > description +### `tasks[].description` +[tasks](#tasks) > description A description of the task. | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].dependencies[]` -[module](#module) > [tasks](#module.tasks[]) > dependencies +### `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 -### `module.tasks[].timeout` -[module](#module) > [tasks](#module.tasks[]) > timeout +### `tasks[].timeout` +[tasks](#tasks) > timeout Maximum duration (in seconds) of the task's execution. | Type | Required | | ---- | -------- | | `number` | No -### `module.tasks[].args[]` -[module](#module) > [tasks](#module.tasks[]) > args +### `tasks[].args[]` +[tasks](#tasks) > args The arguments used to run the task inside the container. @@ -545,23 +618,20 @@ The arguments used to run the task inside the container. Example: ```yaml -module: - ... - tasks: - - args: - - rake - - 'db:migrate' +tasks: + - args: + - rake + - 'db:migrate' ``` -### `module.tasks[].env` -[module](#module) > [tasks](#module.tasks[]) > env +### `tasks[].env` +[tasks](#tasks) > 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 -### `module.jarPath` -[module](#module) > jarPath +### `jarPath` The path to the packaged JAR artifact, relative to the module directory. @@ -571,20 +641,16 @@ The path to the packaged JAR artifact, relative to the module directory. Example: ```yaml -module: - ... - jarPath: "target/my-module.jar" +jarPath: "target/my-module.jar" ``` -### `module.jdkVersion` -[module](#module) > jdkVersion +### `jdkVersion` The JDK version to use. | Type | Required | | ---- | -------- | | `number` | No -### `module.mvnOpts[]` -[module](#module) > mvnOpts +### `mvnOpts` Options to add to the `mvn package` command when building. @@ -595,66 +661,73 @@ Options to add to the `mvn package` command when building. ## Complete YAML schema ```yaml -module: - build: - dependencies: - - name: - copy: - - source: - target: '' - targetImage: - buildArgs: {} - image: - hotReload: - sync: - - source: . - target: - dockerfile: - services: - - name: - dependencies: [] - annotations: {} - args: - daemon: false - ingresses: - - annotations: {} - hostname: - path: / - port: - env: {} - healthCheck: - httpGet: - path: - port: - scheme: HTTP - command: - tcpPort: - hotReloadArgs: - ports: - - name: - protocol: TCP - containerPort: - servicePort: - hostPort: - nodePort: - volumes: - - name: - containerPath: - hostPath: - tests: +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: - name: - dependencies: [] - timeout: null - args: - env: {} - tasks: - - name: - description: - dependencies: [] - timeout: null - args: - env: {} - jarPath: - jdkVersion: 8 - mvnOpts: [] -``` + copy: + - source: + target: '' + targetImage: +buildArgs: {} +image: +hotReload: + sync: + - source: . + target: +dockerfile: +services: + - name: + dependencies: [] + annotations: {} + args: + daemon: false + ingresses: + - annotations: {} + hostname: + path: / + port: + env: {} + healthCheck: + httpGet: + path: + port: + scheme: HTTP + command: + tcpPort: + hotReloadArgs: + ports: + - name: + protocol: TCP + containerPort: + servicePort: + hostPort: + nodePort: + volumes: + - name: + containerPath: + hostPath: +tests: + - name: + dependencies: [] + timeout: null + args: + env: {} +tasks: + - name: + description: + dependencies: [] + timeout: null + args: + env: {} +jarPath: +jdkVersion: 8 +mvnOpts: [] +``` \ No newline at end of file diff --git a/docs/reference/module-types/openfaas.md b/docs/reference/module-types/openfaas.md index 43e647a596..1ce4f6a9d5 100644 --- a/docs/reference/module-types/openfaas.md +++ b/docs/reference/module-types/openfaas.md @@ -1,28 +1,112 @@ # `openfaas` reference -Below is the schema reference for the `openfaas` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +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. -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys -### `module` +### `apiVersion` -The module specification for an OpenFaaS module. +The schema version of this module's config (currently not used). + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Module" +### `type` + +The type of this module. | Type | Required | | ---- | -------- | -| `object` | No -### `module.build` -[module](#module) > build +| `string` | Yes + +Example: +```yaml +type: "container" +``` +### `name` + +The name of this module. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-module" +``` +### `description` + + + +| Type | Required | +| ---- | -------- | +| `string` | No +### `include` + +Specify a list of POSIX-style paths or globs that should be regarded as the source files for this +module. Files that do *not* match these paths or globs are excluded when computing the version of the module, +as well as when responding to filesystem watch events. + +Note that you can also _exclude_ files by placing `.gardenignore` files in your source tree, which use the +same format as `.gitignore` files. + +Also note that specifying an empty list here means _no sources_ should be included. + +| Type | Required | +| ---- | -------- | +| `array[string]` | No + +Example: +```yaml +include: + - Dockerfile + - my-app.js +``` +### `repositoryUrl` + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +Garden will import the repository source code into this module, but read the module's +config from the local garden.yml file. + +| Type | Required | +| ---- | -------- | +| `string` | No + +Example: +```yaml +repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `allowPublish` + +When false, disables pushing this module to remote registries. + +| Type | Required | +| ---- | -------- | +| `boolean` | No +### `build` Specify how to build the module. Note that plugins may define additional keys on this object. | Type | Required | | ---- | -------- | | `object` | No -### `module.build.dependencies[]` -[module](#module) > [build](#module.build) > dependencies +### `build.dependencies[]` +[build](#build) > dependencies A list of modules that must be built before this module is built. @@ -32,47 +116,45 @@ A list of modules that must be built before this module is built. Example: ```yaml -module: +build: ... - build: - ... - dependencies: - - name: some-other-module-name + dependencies: + - name: some-other-module-name ``` -### `module.build.dependencies[].name` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > name +### `build.dependencies[].name` +[build](#build) > [dependencies](#build.dependencies[]) > name Module name to build ahead of this module. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[]` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > copy +### `build.dependencies[].copy[]` +[build](#build) > [dependencies](#build.dependencies[]) > copy Specify one or more files or directories to copy from the built dependency to this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.build.dependencies[].copy[].source` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > source +### `build.dependencies[].copy[].source` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > source POSIX-style path or filename of the directory or file(s) to copy to the target. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.build.dependencies[].copy[].target` -[module](#module) > [build](#module.build) > [dependencies](#module.build.dependencies[]) > [copy](#module.build.dependencies[].copy[]) > target +### `build.dependencies[].copy[].target` +[build](#build) > [dependencies](#build.dependencies[]) > [copy](#build.dependencies[].copy[]) > target POSIX-style path or filename to copy the directory or file(s) to (defaults to same as source path). | Type | Required | | ---- | -------- | | `string` | No -### `module.build.command[]` -[module](#module) > [build](#module.build) > command +### `build.command[]` +[build](#build) > command The command to run inside the module's directory to perform the build. @@ -82,145 +164,136 @@ The command to run inside the module's directory to perform the build. Example: ```yaml -module: +build: ... - build: - ... - command: - - npm - - run - - build + command: + - npm + - run + - build ``` -### `module.env` -[module](#module) > env +### `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 -### `module.tasks[]` -[module](#module) > tasks +### `tasks` A list of tasks that can be run in this module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tasks[].name` -[module](#module) > [tasks](#module.tasks[]) > name +### `tasks[].name` +[tasks](#tasks) > name The name of the task. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tasks[].description` -[module](#module) > [tasks](#module.tasks[]) > description +### `tasks[].description` +[tasks](#tasks) > description A description of the task. | Type | Required | | ---- | -------- | | `string` | No -### `module.tasks[].dependencies[]` -[module](#module) > [tasks](#module.tasks[]) > dependencies +### `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 -### `module.tasks[].timeout` -[module](#module) > [tasks](#module.tasks[]) > timeout +### `tasks[].timeout` +[tasks](#tasks) > timeout Maximum duration (in seconds) of the task's execution. | Type | Required | | ---- | -------- | | `number` | No -### `module.tasks[].command[]` -[module](#module) > [tasks](#module.tasks[]) > command +### `tasks[].command[]` +[tasks](#tasks) > command The command to run in the module build context. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tests[]` -[module](#module) > tests +### `tests` A list of tests to run in the module. | Type | Required | | ---- | -------- | | `array[object]` | No -### `module.tests[].name` -[module](#module) > [tests](#module.tests[]) > name +### `tests[].name` +[tests](#tests) > name The name of the test. | Type | Required | | ---- | -------- | | `string` | Yes -### `module.tests[].dependencies[]` -[module](#module) > [tests](#module.tests[]) > dependencies +### `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 -### `module.tests[].timeout` -[module](#module) > [tests](#module.tests[]) > timeout +### `tests[].timeout` +[tests](#tests) > timeout Maximum duration (in seconds) of the test run. | Type | Required | | ---- | -------- | | `number` | No -### `module.tests[].command[]` -[module](#module) > [tests](#module.tests[]) > command +### `tests[].command[]` +[tests](#tests) > command The command to run in the module build context in order to test it. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.tests[].env` -[module](#module) > [tests](#module.tests[]) > env +### `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 -### `module.dependencies[]` -[module](#module) > dependencies +### `dependencies` The names of services/functions that this function depends on at runtime. | Type | Required | | ---- | -------- | | `array[string]` | No -### `module.handler` -[module](#module) > handler +### `handler` Specify which directory under the module contains the handler file/function. | Type | Required | | ---- | -------- | | `string` | No -### `module.image` -[module](#module) > image +### `image` The image name to use for the built OpenFaaS container (defaults to the module name) | Type | Required | | ---- | -------- | | `string` | No -### `module.lang` -[module](#module) > lang +### `lang` The OpenFaaS language template to use to build this function. @@ -231,30 +304,37 @@ The OpenFaaS language template to use to build this function. ## Complete YAML schema ```yaml -module: - build: - dependencies: - - name: - copy: - - source: - target: '' - command: - [] - env: {} - tasks: - - name: - description: - dependencies: [] - timeout: null - command: - tests: +apiVersion: garden.io/v0 +kind: Module +type: +name: +description: +include: +repositoryUrl: +allowPublish: true +build: + dependencies: - name: - dependencies: [] - timeout: null - command: - env: {} - dependencies: [] - handler: . - image: - lang: -``` + copy: + - source: + target: '' + command: + [] +env: {} +tasks: + - name: + description: + dependencies: [] + timeout: null + command: +tests: + - name: + dependencies: [] + timeout: null + command: + env: {} +dependencies: [] +handler: . +image: +lang: +``` \ No newline at end of file diff --git a/docs/reference/providers/kubernetes.md b/docs/reference/providers/kubernetes.md index eb2b4a8f02..b5ec215b09 100644 --- a/docs/reference/providers/kubernetes.md +++ b/docs/reference/providers/kubernetes.md @@ -6,31 +6,133 @@ The reference is divided into two sections. The [first section](#configuration-k ## Configuration keys -### `project` +### `apiVersion` +The schema version of this project's config (currently not used). +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Project" +### `name` + +The name of the project. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-project" +``` +### `defaultEnvironment` + +The default environment to use when calling commands without the `--env` parameter. + +| Type | Required | +| ---- | -------- | +| `string` | No +### `environmentDefaults` + +Default environment settings. These are inherited (but can be overridden) by each configured environment. + +| Type | Required | +| ---- | -------- | +| `object` | No + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} +``` +### `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. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `environmentDefaults.providers[].name` +[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name + +The name of the provider plugin to use. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} + ... + providers: + - name: "local-kubernetes" +``` +### `environmentDefaults.variables` +[environmentDefaults](#environmentdefaults) > variables + +A key/value map of variables that modules can reference when using this environment. | Type | Required | | ---- | -------- | | `object` | No -### `project.environments[]` -[project](#project) > environments +### `sources` + +A list of remote sources to import into project. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `sources[].name` +[sources](#sources) > name + +The name of the source to import + +| Type | Required | +| ---- | -------- | +| `string` | Yes +### `sources[].repositoryUrl` +[sources](#sources) > repositoryUrl + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +sources: + - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `environments` | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[]` -[project](#project) > [environments](#project.environments[]) > providers +### `environments[].providers[]` +[environments](#environments) > providers | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].defaultHostname` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > defaultHostname +### `environments[].providers[].defaultHostname` +[environments](#environments) > [providers](#environments[].providers[]) > defaultHostname A default hostname to use when no hostname is explicitly configured for a service. @@ -40,30 +142,28 @@ A default hostname to use when no hostname is explicitly configured for a servic Example: ```yaml -project: - ... - environments: - - providers: - - defaultHostname: "api.mydomain.com" +environments: + - providers: + - defaultHostname: "api.mydomain.com" ``` -### `project.environments[].providers[].defaultUsername` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > defaultUsername +### `environments[].providers[].defaultUsername` +[environments](#environments) > [providers](#environments[].providers[]) > defaultUsername Set a default username (used for namespacing within a cluster). | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].forceSsl` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > forceSsl +### `environments[].providers[].forceSsl` +[environments](#environments) > [providers](#environments[].providers[]) > forceSsl Require SSL on all services. If set to true, an error is raised when no certificate is available for a configured hostname. | Type | Required | | ---- | -------- | | `boolean` | No -### `project.environments[].providers[].imagePullSecrets[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > imagePullSecrets +### `environments[].providers[].imagePullSecrets[]` +[environments](#environments) > [providers](#environments[].providers[]) > imagePullSecrets References to `docker-registry` secrets to use for authenticating with remote registries when pulling images. This is necessary if you reference private images in your module configuration, and is required @@ -72,8 +172,8 @@ when configuring a remote Kubernetes environment. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].imagePullSecrets[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [imagePullSecrets](#project.environments[].providers[].imagepullsecrets[]) > name +### `environments[].providers[].imagePullSecrets[].name` +[environments](#environments) > [providers](#environments[].providers[]) > [imagePullSecrets](#environments[].providers[].imagepullsecrets[]) > name The name of the Kubernetes secret. @@ -83,31 +183,29 @@ The name of the Kubernetes secret. Example: ```yaml -project: - ... - environments: - - providers: - - imagePullSecrets: - - name: "my-secret" +environments: + - providers: + - imagePullSecrets: + - name: "my-secret" ``` -### `project.environments[].providers[].imagePullSecrets[].namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [imagePullSecrets](#project.environments[].providers[].imagepullsecrets[]) > namespace +### `environments[].providers[].imagePullSecrets[].namespace` +[environments](#environments) > [providers](#environments[].providers[]) > [imagePullSecrets](#environments[].providers[].imagepullsecrets[]) > namespace The namespace where the secret is stored. If necessary, the secret may be copied to the appropriate namespace before use. | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].tlsCertificates[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > tlsCertificates +### `environments[].providers[].tlsCertificates[]` +[environments](#environments) > [providers](#environments[].providers[]) > tlsCertificates One or more certificates to use for ingress. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].tlsCertificates[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > name +### `environments[].providers[].tlsCertificates[].name` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > name A unique identifier for this certificate. @@ -117,15 +215,13 @@ A unique identifier for this certificate. Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - name: "wildcard" +environments: + - providers: + - tlsCertificates: + - name: "wildcard" ``` -### `project.environments[].providers[].tlsCertificates[].hostnames[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > hostnames +### `environments[].providers[].tlsCertificates[].hostnames[]` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > hostnames A list of hostnames that this certificate should be used for. If you don't specify these, they will be automatically read from the certificate. @@ -135,16 +231,14 @@ A list of hostnames that this certificate should be used for. If you don't speci Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - hostnames: - - www.mydomain.com +environments: + - providers: + - tlsCertificates: + - hostnames: + - www.mydomain.com ``` -### `project.environments[].providers[].tlsCertificates[].secretRef` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > secretRef +### `environments[].providers[].tlsCertificates[].secretRef` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > secretRef A reference to the Kubernetes secret that contains the TLS certificate and key for the domain. @@ -154,17 +248,15 @@ A reference to the Kubernetes secret that contains the TLS certificate and key f Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - secretRef: - name: my-tls-secret - namespace: default +environments: + - providers: + - tlsCertificates: + - secretRef: + name: my-tls-secret + namespace: default ``` -### `project.environments[].providers[].tlsCertificates[].secretRef.name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > [secretRef](#project.environments[].providers[].tlscertificates[].secretref) > name +### `environments[].providers[].tlsCertificates[].secretRef.name` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > [secretRef](#environments[].providers[].tlscertificates[].secretref) > name The name of the Kubernetes secret. @@ -174,27 +266,25 @@ The name of the Kubernetes secret. Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - secretRef: - name: my-tls-secret - namespace: default - ... - name: "my-secret" +environments: + - providers: + - tlsCertificates: + - secretRef: + name: my-tls-secret + namespace: default + ... + name: "my-secret" ``` -### `project.environments[].providers[].tlsCertificates[].secretRef.namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > [secretRef](#project.environments[].providers[].tlscertificates[].secretref) > namespace +### `environments[].providers[].tlsCertificates[].secretRef.namespace` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > [secretRef](#environments[].providers[].tlscertificates[].secretref) > namespace The namespace where the secret is stored. If necessary, the secret may be copied to the appropriate namespace before use. | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > name +### `environments[].providers[].name` +[environments](#environments) > [providers](#environments[].providers[]) > name The name of the provider plugin to use. @@ -204,14 +294,12 @@ The name of the provider plugin to use. Example: ```yaml -project: - ... - environments: - - providers: - - name: "kubernetes" +environments: + - providers: + - name: "kubernetes" ``` -### `project.environments[].providers[].context` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > context +### `environments[].providers[].context` +[environments](#environments) > [providers](#environments[].providers[]) > context The kubectl context to use to connect to the Kubernetes cluster. @@ -221,22 +309,20 @@ The kubectl context to use to connect to the Kubernetes cluster. Example: ```yaml -project: - ... - environments: - - providers: - - context: "my-dev-context" +environments: + - providers: + - context: "my-dev-context" ``` -### `project.environments[].providers[].deploymentRegistry` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > deploymentRegistry +### `environments[].providers[].deploymentRegistry` +[environments](#environments) > [providers](#environments[].providers[]) > deploymentRegistry The registry where built containers should be pushed to, and then pulled to the cluster when deploying services. | Type | Required | | ---- | -------- | | `object` | Yes -### `project.environments[].providers[].deploymentRegistry.hostname` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [deploymentRegistry](#project.environments[].providers[].deploymentregistry) > hostname +### `environments[].providers[].deploymentRegistry.hostname` +[environments](#environments) > [providers](#environments[].providers[]) > [deploymentRegistry](#environments[].providers[].deploymentregistry) > hostname The hostname (and optionally port, if not the default port) of the registry. @@ -246,24 +332,22 @@ The hostname (and optionally port, if not the default port) of the registry. Example: ```yaml -project: - ... - environments: - - providers: - - deploymentRegistry: - ... - hostname: "gcr.io" +environments: + - providers: + - deploymentRegistry: + ... + hostname: "gcr.io" ``` -### `project.environments[].providers[].deploymentRegistry.port` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [deploymentRegistry](#project.environments[].providers[].deploymentregistry) > port +### `environments[].providers[].deploymentRegistry.port` +[environments](#environments) > [providers](#environments[].providers[]) > [deploymentRegistry](#environments[].providers[].deploymentregistry) > port The port where the registry listens on, if not the default. | Type | Required | | ---- | -------- | | `number` | No -### `project.environments[].providers[].deploymentRegistry.namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [deploymentRegistry](#project.environments[].providers[].deploymentregistry) > namespace +### `environments[].providers[].deploymentRegistry.namespace` +[environments](#environments) > [providers](#environments[].providers[]) > [deploymentRegistry](#environments[].providers[].deploymentregistry) > namespace The namespace in the registry where images should be pushed. @@ -273,16 +357,14 @@ The namespace in the registry where images should be pushed. Example: ```yaml -project: - ... - environments: - - providers: - - deploymentRegistry: - ... - namespace: "my-project" +environments: + - providers: + - deploymentRegistry: + ... + namespace: "my-project" ``` -### `project.environments[].providers[].ingressClass` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > ingressClass +### `environments[].providers[].ingressClass` +[environments](#environments) > [providers](#environments[].providers[]) > ingressClass The ingress class to use on configured Ingresses (via the `kubernetes.io/ingress.class` annotation) when deploying `container` services. Use this if you have multiple ingress controllers in your cluster. @@ -290,24 +372,24 @@ when deploying `container` services. Use this if you have multiple ingress contr | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].ingressHttpPort` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > ingressHttpPort +### `environments[].providers[].ingressHttpPort` +[environments](#environments) > [providers](#environments[].providers[]) > ingressHttpPort The external HTTP port of the cluster's ingress controller. | Type | Required | | ---- | -------- | | `number` | No -### `project.environments[].providers[].ingressHttpsPort` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > ingressHttpsPort +### `environments[].providers[].ingressHttpsPort` +[environments](#environments) > [providers](#environments[].providers[]) > ingressHttpsPort The external HTTPS port of the cluster's ingress controller. | Type | Required | | ---- | -------- | | `number` | No -### `project.environments[].providers[].namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > namespace +### `environments[].providers[].namespace` +[environments](#environments) > [providers](#environments[].providers[]) > namespace Specify which namespace to deploy services to (defaults to --). Note that the framework generates other namespaces as well with this name as a prefix. @@ -318,29 +400,39 @@ Specify which namespace to deploy services to (defaults to -- environments +| `string` | Yes +Example: +```yaml +name: "my-sweet-project" +``` +### `defaultEnvironment` +The default environment to use when calling commands without the `--env` parameter. | Type | Required | | ---- | -------- | -| `array[object]` | No -### `project.environments[].providers[]` -[project](#project) > [environments](#project.environments[]) > providers +| `string` | No +### `environmentDefaults` + +Default environment settings. These are inherited (but can be overridden) by each configured environment. +| Type | Required | +| ---- | -------- | +| `object` | No + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} +``` +### `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. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > name +### `environmentDefaults.providers[].name` +[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name The name of the provider plugin to use. @@ -40,14 +72,67 @@ The name of the provider plugin to use. Example: ```yaml -project: +environmentDefaults: + providers: [] + variables: {} ... - environments: - - providers: - - name: "local-kubernetes" + providers: + - name: "local-kubernetes" ``` -### `project.environments[].providers[].defaultHostname` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > defaultHostname +### `environmentDefaults.variables` +[environmentDefaults](#environmentdefaults) > variables + +A key/value map of variables that modules can reference when using this environment. + +| Type | Required | +| ---- | -------- | +| `object` | No +### `sources` + +A list of remote sources to import into project. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `sources[].name` +[sources](#sources) > name + +The name of the source to import + +| Type | Required | +| ---- | -------- | +| `string` | Yes +### `sources[].repositoryUrl` +[sources](#sources) > repositoryUrl + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +sources: + - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `environments` + + + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `environments[].providers[]` +[environments](#environments) > providers + + + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `environments[].providers[].defaultHostname` +[environments](#environments) > [providers](#environments[].providers[]) > defaultHostname A default hostname to use when no hostname is explicitly configured for a service. @@ -57,30 +142,28 @@ A default hostname to use when no hostname is explicitly configured for a servic Example: ```yaml -project: - ... - environments: - - providers: - - defaultHostname: "api.mydomain.com" +environments: + - providers: + - defaultHostname: "api.mydomain.com" ``` -### `project.environments[].providers[].defaultUsername` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > defaultUsername +### `environments[].providers[].defaultUsername` +[environments](#environments) > [providers](#environments[].providers[]) > defaultUsername Set a default username (used for namespacing within a cluster). | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].forceSsl` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > forceSsl +### `environments[].providers[].forceSsl` +[environments](#environments) > [providers](#environments[].providers[]) > forceSsl Require SSL on all services. If set to true, an error is raised when no certificate is available for a configured hostname. | Type | Required | | ---- | -------- | | `boolean` | No -### `project.environments[].providers[].imagePullSecrets[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > imagePullSecrets +### `environments[].providers[].imagePullSecrets[]` +[environments](#environments) > [providers](#environments[].providers[]) > imagePullSecrets References to `docker-registry` secrets to use for authenticating with remote registries when pulling images. This is necessary if you reference private images in your module configuration, and is required @@ -89,8 +172,8 @@ when configuring a remote Kubernetes environment. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].imagePullSecrets[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [imagePullSecrets](#project.environments[].providers[].imagepullsecrets[]) > name +### `environments[].providers[].imagePullSecrets[].name` +[environments](#environments) > [providers](#environments[].providers[]) > [imagePullSecrets](#environments[].providers[].imagepullsecrets[]) > name The name of the Kubernetes secret. @@ -100,31 +183,29 @@ The name of the Kubernetes secret. Example: ```yaml -project: - ... - environments: - - providers: - - imagePullSecrets: - - name: "my-secret" +environments: + - providers: + - imagePullSecrets: + - name: "my-secret" ``` -### `project.environments[].providers[].imagePullSecrets[].namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [imagePullSecrets](#project.environments[].providers[].imagepullsecrets[]) > namespace +### `environments[].providers[].imagePullSecrets[].namespace` +[environments](#environments) > [providers](#environments[].providers[]) > [imagePullSecrets](#environments[].providers[].imagepullsecrets[]) > namespace The namespace where the secret is stored. If necessary, the secret may be copied to the appropriate namespace before use. | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].tlsCertificates[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > tlsCertificates +### `environments[].providers[].tlsCertificates[]` +[environments](#environments) > [providers](#environments[].providers[]) > tlsCertificates One or more certificates to use for ingress. | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].tlsCertificates[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > name +### `environments[].providers[].tlsCertificates[].name` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > name A unique identifier for this certificate. @@ -134,15 +215,13 @@ A unique identifier for this certificate. Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - name: "wildcard" +environments: + - providers: + - tlsCertificates: + - name: "wildcard" ``` -### `project.environments[].providers[].tlsCertificates[].hostnames[]` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > hostnames +### `environments[].providers[].tlsCertificates[].hostnames[]` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > hostnames A list of hostnames that this certificate should be used for. If you don't specify these, they will be automatically read from the certificate. @@ -152,16 +231,14 @@ A list of hostnames that this certificate should be used for. If you don't speci Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - hostnames: - - www.mydomain.com +environments: + - providers: + - tlsCertificates: + - hostnames: + - www.mydomain.com ``` -### `project.environments[].providers[].tlsCertificates[].secretRef` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > secretRef +### `environments[].providers[].tlsCertificates[].secretRef` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > secretRef A reference to the Kubernetes secret that contains the TLS certificate and key for the domain. @@ -171,17 +248,15 @@ A reference to the Kubernetes secret that contains the TLS certificate and key f Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - secretRef: - name: my-tls-secret - namespace: default +environments: + - providers: + - tlsCertificates: + - secretRef: + name: my-tls-secret + namespace: default ``` -### `project.environments[].providers[].tlsCertificates[].secretRef.name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > [secretRef](#project.environments[].providers[].tlscertificates[].secretref) > name +### `environments[].providers[].tlsCertificates[].secretRef.name` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > [secretRef](#environments[].providers[].tlscertificates[].secretref) > name The name of the Kubernetes secret. @@ -191,35 +266,48 @@ The name of the Kubernetes secret. Example: ```yaml -project: - ... - environments: - - providers: - - tlsCertificates: - - secretRef: - name: my-tls-secret - namespace: default - ... - name: "my-secret" +environments: + - providers: + - tlsCertificates: + - secretRef: + name: my-tls-secret + namespace: default + ... + name: "my-secret" ``` -### `project.environments[].providers[].tlsCertificates[].secretRef.namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > [tlsCertificates](#project.environments[].providers[].tlscertificates[]) > [secretRef](#project.environments[].providers[].tlscertificates[].secretref) > namespace +### `environments[].providers[].tlsCertificates[].secretRef.namespace` +[environments](#environments) > [providers](#environments[].providers[]) > [tlsCertificates](#environments[].providers[].tlscertificates[]) > [secretRef](#environments[].providers[].tlscertificates[].secretref) > namespace The namespace where the secret is stored. If necessary, the secret may be copied to the appropriate namespace before use. | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].namespace` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > namespace +### `environments[].providers[].name` +[environments](#environments) > [providers](#environments[].providers[]) > name + +The name of the provider plugin to use. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +environments: + - providers: + - name: "local-kubernetes" +``` +### `environments[].providers[].namespace` +[environments](#environments) > [providers](#environments[].providers[]) > namespace Specify which namespace to deploy services to (defaults to the project name). Note that the framework generates other namespaces as well with this name as a prefix. | Type | Required | | ---- | -------- | | `string` | No -### `project.environments[].providers[].setupIngressController` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > setupIngressController +### `environments[].providers[].setupIngressController` +[environments](#environments) > [providers](#environments[].providers[]) > setupIngressController Set this to null or false to skip installing/enabling the `nginx` ingress controller. @@ -230,22 +318,32 @@ Set this to null or false to skip installing/enabling the `nginx` ingress contro ## Complete YAML schema ```yaml -project: - environments: - - providers: - - name: - defaultHostname: - defaultUsername: - forceSsl: false - imagePullSecrets: - - name: +apiVersion: garden.io/v0 +kind: Project +name: +defaultEnvironment: '' +environmentDefaults: + providers: + - name: + variables: {} +sources: + - name: + repositoryUrl: +environments: + - providers: + - defaultHostname: + defaultUsername: + forceSsl: false + imagePullSecrets: + - name: + namespace: default + tlsCertificates: + - name: + hostnames: + secretRef: + name: namespace: default - tlsCertificates: - - name: - hostnames: - secretRef: - name: - namespace: default - namespace: - setupIngressController: nginx + name: local-kubernetes + namespace: + setupIngressController: nginx ``` diff --git a/docs/reference/providers/maven-container.md b/docs/reference/providers/maven-container.md index e221ef6faa..ed037b254a 100644 --- a/docs/reference/providers/maven-container.md +++ b/docs/reference/providers/maven-container.md @@ -6,31 +6,133 @@ The reference is divided into two sections. The [first section](#configuration-k ## Configuration keys -### `project` +### `apiVersion` +The schema version of this project's config (currently not used). +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Project" +### `name` + +The name of the project. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-project" +``` +### `defaultEnvironment` + +The default environment to use when calling commands without the `--env` parameter. + +| Type | Required | +| ---- | -------- | +| `string` | No +### `environmentDefaults` + +Default environment settings. These are inherited (but can be overridden) by each configured environment. + +| Type | Required | +| ---- | -------- | +| `object` | No + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} +``` +### `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. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `environmentDefaults.providers[].name` +[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name + +The name of the provider plugin to use. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} + ... + providers: + - name: "local-kubernetes" +``` +### `environmentDefaults.variables` +[environmentDefaults](#environmentdefaults) > variables + +A key/value map of variables that modules can reference when using this environment. | Type | Required | | ---- | -------- | | `object` | No -### `project.environments[]` -[project](#project) > environments +### `sources` + +A list of remote sources to import into project. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `sources[].name` +[sources](#sources) > name + +The name of the source to import + +| Type | Required | +| ---- | -------- | +| `string` | Yes +### `sources[].repositoryUrl` +[sources](#sources) > repositoryUrl + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +sources: + - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `environments` | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[]` -[project](#project) > [environments](#project.environments[]) > providers +### `environments[].providers[]` +[environments](#environments) > providers | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > name +### `environments[].providers[].name` +[environments](#environments) > [providers](#environments[].providers[]) > name The name of the provider plugin to use. @@ -40,18 +142,26 @@ The name of the provider plugin to use. Example: ```yaml -project: - ... - environments: - - providers: - - name: "local-kubernetes" +environments: + - providers: + - name: "maven-container" ``` ## Complete YAML schema ```yaml -project: - environments: - - providers: - - name: +apiVersion: garden.io/v0 +kind: Project +name: +defaultEnvironment: '' +environmentDefaults: + providers: + - name: + variables: {} +sources: + - name: + repositoryUrl: +environments: + - providers: + - name: maven-container ``` diff --git a/docs/reference/providers/openfaas.md b/docs/reference/providers/openfaas.md index 909fea98c9..e6152e3a9f 100644 --- a/docs/reference/providers/openfaas.md +++ b/docs/reference/providers/openfaas.md @@ -6,31 +6,133 @@ The reference is divided into two sections. The [first section](#configuration-k ## Configuration keys -### `project` +### `apiVersion` +The schema version of this project's config (currently not used). +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "garden.io/v0" +### `kind` + + + +| Type | Required | Allowed Values | +| ---- | -------- | -------------- | +| `string` | Yes | "Project" +### `name` + +The name of the project. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +name: "my-sweet-project" +``` +### `defaultEnvironment` + +The default environment to use when calling commands without the `--env` parameter. + +| Type | Required | +| ---- | -------- | +| `string` | No +### `environmentDefaults` + +Default environment settings. These are inherited (but can be overridden) by each configured environment. + +| Type | Required | +| ---- | -------- | +| `object` | No + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} +``` +### `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. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `environmentDefaults.providers[].name` +[environmentDefaults](#environmentdefaults) > [providers](#environmentdefaults.providers[]) > name + +The name of the provider plugin to use. + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +environmentDefaults: + providers: [] + variables: {} + ... + providers: + - name: "local-kubernetes" +``` +### `environmentDefaults.variables` +[environmentDefaults](#environmentdefaults) > variables + +A key/value map of variables that modules can reference when using this environment. | Type | Required | | ---- | -------- | | `object` | No -### `project.environments[]` -[project](#project) > environments +### `sources` + +A list of remote sources to import into project. + +| Type | Required | +| ---- | -------- | +| `array[object]` | No +### `sources[].name` +[sources](#sources) > name + +The name of the source to import + +| Type | Required | +| ---- | -------- | +| `string` | Yes +### `sources[].repositoryUrl` +[sources](#sources) > repositoryUrl + +A remote repository URL. Currently only supports git servers. Must contain a hash suffix pointing to a specific branch or tag, with the format: # + +| Type | Required | +| ---- | -------- | +| `string` | Yes + +Example: +```yaml +sources: + - repositoryUrl: "git+https://github.com/org/repo.git#v2.0" +``` +### `environments` | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[]` -[project](#project) > [environments](#project.environments[]) > providers +### `environments[].providers[]` +[environments](#environments) > providers | Type | Required | | ---- | -------- | | `array[object]` | No -### `project.environments[].providers[].name` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > name +### `environments[].providers[].name` +[environments](#environments) > [providers](#environments[].providers[]) > name The name of the provider plugin to use. @@ -40,14 +142,12 @@ The name of the provider plugin to use. Example: ```yaml -project: - ... - environments: - - providers: - - name: "openfaas" +environments: + - providers: + - name: "openfaas" ``` -### `project.environments[].providers[].hostname` -[project](#project) > [environments](#project.environments[]) > [providers](#project.environments[].providers[]) > hostname +### `environments[].providers[].hostname` +[environments](#environments) > [providers](#environments[].providers[]) > hostname The hostname to configure for the function gateway. Defaults to the default hostname of the configured Kubernetes provider. @@ -61,19 +161,27 @@ or the other services should not expose paths under /function and /system to avo Example: ```yaml -project: - ... - environments: - - providers: - - hostname: "functions.mydomain.com" +environments: + - providers: + - hostname: "functions.mydomain.com" ``` ## Complete YAML schema ```yaml -project: - environments: - - providers: - - name: - hostname: +apiVersion: garden.io/v0 +kind: Project +name: +defaultEnvironment: '' +environmentDefaults: + providers: + - name: + variables: {} +sources: + - name: + repositoryUrl: +environments: + - providers: + - name: openfaas + hostname: ``` diff --git a/docs/reference/template-strings.md b/docs/reference/template-strings.md index aad31f9a21..b64bca4410 100644 --- a/docs/reference/template-strings.md +++ b/docs/reference/template-strings.md @@ -43,18 +43,6 @@ lookups of keys. However, it is possible to do nested templating. For a somewhat There the name of the module is pulled from the project/environment configuration, and used to find the appropriate key under the `modules` configuration context. -You can also do simple OR statements: - - -```yaml - # ... - env: - PROFILE_NAME: ${local.env.PROFILE || "default"} - LOG_LEVEL: ${local.env.LOG_LEVEL || variables.default-log-level} -``` - -This allows you to easily set default values when certain template keys are not available. - ## Reference ### Project configuration context @@ -62,15 +50,21 @@ This allows you to easily set default values when certain template keys are not The following keys are available in template strings under the `project` key in `garden.yml` files: ```yaml - +# Type: object +# local: # A map of all local environment variables (see # https://nodejs.org/api/process.html#process_process_env). - env: {} + # + # Type: object + # + env: # A string indicating the platform that the framework is running on (see # https://nodejs.org/api/process.html#process_process_platform) # + # Type: string + # # Example: "posix" # platform: @@ -81,53 +75,73 @@ local: The following keys are available in template strings under the `module` key in `garden.yml` files: ```yaml - +# Type: object +# local: # A map of all local environment variables (see # https://nodejs.org/api/process.html#process_process_env). - env: {} + # + # Type: object + # + env: # A string indicating the platform that the framework is running on (see # https://nodejs.org/api/process.html#process_process_platform) # + # Type: string + # # Example: "posix" # platform: # Information about the environment that Garden is running against. +# +# Type: object +# environment: # The name of the environment Garden is running against. # + # Type: string + # # Example: "local" # name: # Retrieve information about modules that are defined in the project. # +# Type: object +# # Example: # my-module: # path: /home/me/code/my-project/my-module -# version: v17ad4cb3fd +# version: v-v17ad4cb3fd # -modules: - {} +modules: {} # A map of all configured plugins/providers for this environment and their configuration. # +# Type: object +# # Example: # kubernetes: # name: local-kubernetes # context: my-kube-context # -providers: - {} +providers: {} # A map of all variables defined in the project configuration. # +# Type: object +# # Example: # team-name: bananaramallama # some-service-endpoint: 'https://someservice.com/api/v2' # -variables: - {} +variables: {} + +# Alias for the variables field. +# +# Type: object +# +var: {} ``` diff --git a/garden-service/bin/generate-docs.ts b/garden-service/bin/generate-docs.ts index 25205540bf..3833e9f6b2 100755 --- a/garden-service/bin/generate-docs.ts +++ b/garden-service/bin/generate-docs.ts @@ -2,5 +2,23 @@ import { generateDocs } from "../src/docs/generate" import { resolve } from "path" +import { Logger } from "../src/logger/logger" +import { LogLevel } from "../src/logger/log-node" + +// make sure logger is initialized +try { + Logger.initialize({ + level: LogLevel.info, + // level: LogLevel.debug, + // writers: [new BasicTerminalWriter()], + }) +} catch (_) { } generateDocs(resolve(__dirname, "..", "..", "docs")) + .then(() => { + console.log("Done!") + }) + .catch(err => { + console.error(err) + process.exit(1) + }) diff --git a/garden-service/src/actions.ts b/garden-service/src/actions.ts index b4db998b8a..71d4e63f02 100644 --- a/garden-service/src/actions.ts +++ b/garden-service/src/actions.ts @@ -83,6 +83,7 @@ import { CleanupEnvironmentParams } from "./types/plugin/params" import { ConfigurationError, PluginError, ParameterError } from "./exceptions" import { defaultProvider } from "./config/project" import { validate } from "./config/common" +import * as Joi from "joi" type TypeGuard = { readonly [P in keyof (PluginActionParams | ModuleActionParams)]: (...args: any[]) => Promise @@ -234,6 +235,19 @@ export class ActionHelper implements TypeGuard { //region Module Actions //=========================================================================== + async describeType(moduleType: string) { + const handler = await this.getModuleActionHandler({ + actionType: "describeType", + moduleType, + defaultHandler: async ({ }) => ({ + docs: "", + schema: Joi.object().options({ allowUnknown: true }), + }), + }) + + return handler({}) + } + async getBuildStatus( params: ModuleActionHelperParams>, ): Promise { diff --git a/garden-service/src/config/common.ts b/garden-service/src/config/common.ts index 7d08363580..8aeb111a51 100644 --- a/garden-service/src/config/common.ts +++ b/garden-service/src/config/common.ts @@ -44,6 +44,7 @@ export const joiIdentifier = () => Joi.string() export const joiProviderName = (name: string) => joiIdentifier().required() .description("The name of the provider plugin to use.") + .default(name) .example(name) export const joiStringMap = (valueSchema: JoiObject) => Joi diff --git a/garden-service/src/config/module.ts b/garden-service/src/config/module.ts index 7d9a455bda..6e2383143d 100644 --- a/garden-service/src/config/module.ts +++ b/garden-service/src/config/module.ts @@ -94,6 +94,7 @@ export const baseModuleSpecSchema = Joi.object() .default("garden.io/v0") .only("garden.io/v0") .description("The schema version of this module's config (currently not used)."), + kind: Joi.string().default("Module").only("Module"), type: joiIdentifier() .required() .description("The type of this module.") diff --git a/garden-service/src/config/project.ts b/garden-service/src/config/project.ts index 3caf086936..039d0b39c4 100644 --- a/garden-service/src/config/project.ts +++ b/garden-service/src/config/project.ts @@ -127,6 +127,7 @@ export const projectSchema = Joi.object() .default("garden.io/v0") .only("garden.io/v0") .description("The schema version of this project's config (currently not used)."), + kind: Joi.string().default("Project").only("Project"), name: projectNameSchema, defaultEnvironment: Joi.string() .default("", "") diff --git a/garden-service/src/docs/config.ts b/garden-service/src/docs/config.ts index c4e8f2fc09..3b0cad5799 100644 --- a/garden-service/src/docs/config.ts +++ b/garden-service/src/docs/config.ts @@ -18,54 +18,44 @@ import { get, flatten, padEnd, + uniq, + startCase, } from "lodash" -import { containerModuleSpecSchema } from "../plugins/container/config" -import { execModuleSpecSchema } from "../plugins/exec" import { projectSchema } from "../config/project" import { baseModuleSpecSchema } from "../config/module" import handlebars = require("handlebars") import { configSchema as localK8sConfigSchema } from "../plugins/kubernetes/local/config" import { configSchema as k8sConfigSchema } from "../plugins/kubernetes/kubernetes" import { configSchema as openfaasConfigSchema } from "../plugins/openfaas/openfaas" -import { openfaasModuleSpecSchema } from "../plugins/openfaas/openfaas" -import { helmModuleSpecSchema } from "../plugins/kubernetes/helm/config" import { joiArray } from "../config/common" -import { mavenContainerModuleSpecSchema, mavenContainerConfigSchema } from "../plugins/maven-container/maven-container" -import { kubernetesModuleSpecSchema } from "../plugins/kubernetes/kubernetes-module/config" - -const baseProjectSchema = Joi.object().keys({ - project: projectSchema, -}) -const baseModuleSchema = Joi.object().keys({ - module: baseModuleSpecSchema, -}) - -const populateModuleSchema = (schema: Joi.Schema) => Joi.object().keys({ module: schema }) -const populateProviderSchema = (schema: Joi.Schema) => ( - Joi.object({ - project: Joi.object({ - environments: joiArray(Joi.object().keys({ - providers: joiArray(schema), - })), - }), +import { mavenContainerConfigSchema } from "../plugins/maven-container/maven-container" +import { Garden } from "../garden" + +const populateModuleSchema = (schema: Joi.ObjectSchema) => baseModuleSpecSchema + .concat(schema) + +const populateProviderSchema = (schema: Joi.Schema) => projectSchema + .keys({ + environments: joiArray(Joi.object().keys({ + providers: joiArray(schema), + })), }) -) const maxWidth = 100 const moduleTypes = [ - { name: "exec", schema: populateModuleSchema(execModuleSpecSchema) }, - { name: "container", schema: populateModuleSchema(containerModuleSpecSchema) }, - { name: "openfaas", schema: populateModuleSchema(openfaasModuleSpecSchema) }, - { name: "helm", schema: populateModuleSchema(helmModuleSpecSchema) }, - { name: "maven-container", schema: populateModuleSchema(mavenContainerModuleSpecSchema) }, - { name: "kubernetes", schema: populateModuleSchema(kubernetesModuleSpecSchema) }, + { name: "exec" }, + { name: "container" }, + { name: "helm", pluginName: "local-kubernetes" }, + { name: "kubernetes", pluginName: "local-kubernetes" }, + { name: "maven-container" }, + { name: "openfaas" }, ] const providers = [ { name: "local-kubernetes", schema: populateProviderSchema(localK8sConfigSchema) }, { name: "kubernetes", schema: populateProviderSchema(k8sConfigSchema) }, - { name: "openfaas", schema: populateProviderSchema(openfaasConfigSchema) }, { name: "maven-container", schema: populateProviderSchema(mavenContainerConfigSchema) }, + { name: "openfaas", schema: populateProviderSchema(openfaasConfigSchema) }, ] interface RenderOpts { @@ -393,11 +383,11 @@ function renderProviderReference(schema: Joi.ObjectSchema, name: string) { * Generates the module types reference from the module-type.hbs template. * The reference includes the rendered output from the config-partial.hbs template. */ -function renderModuleTypeReference(schema: Joi.ObjectSchema, name: string) { +function renderModuleTypeReference(schema: Joi.ObjectSchema, name: string, docs: string) { const moduleTemplatePath = resolve(__dirname, "templates", "module-type.hbs") const { markdownReference, yaml } = renderConfigReference(schema) const template = handlebars.compile(readFileSync(moduleTemplatePath).toString()) - return template({ name, markdownReference, yaml }) + return template({ name, docs, markdownReference, yaml }) } /** @@ -407,31 +397,65 @@ function renderModuleTypeReference(schema: Joi.ObjectSchema, name: string) { */ function renderBaseConfigReference() { const baseTemplatePath = resolve(__dirname, "templates", "base-config.hbs") - const { markdownReference: projectMarkdownReference, yaml: projectYaml } = renderConfigReference(baseProjectSchema) - const { markdownReference: moduleMarkdownReference, yaml: moduleYaml } = renderConfigReference(baseModuleSchema) + const { markdownReference: projectMarkdownReference, yaml: projectYaml } = renderConfigReference(projectSchema) + const { markdownReference: moduleMarkdownReference, yaml: moduleYaml } = renderConfigReference(baseModuleSpecSchema) const template = handlebars.compile(readFileSync(baseTemplatePath).toString()) return template({ projectMarkdownReference, projectYaml, moduleMarkdownReference, moduleYaml }) } -export function writeConfigReferenceDocs(docsRoot: string) { +export async function writeConfigReferenceDocs(docsRoot: string) { const referenceDir = resolve(docsRoot, "reference") const configPath = resolve(referenceDir, "config.md") + const moduleProviders = uniq(moduleTypes.map(m => m.pluginName || m.name)).map(name => ({ name })) + const garden = await Garden.factory(__dirname, { + config: { + dirname: "generate-docs", + path: __dirname, + project: { + apiVersion: "garden.io/v0", + name: "generate-docs", + defaultEnvironment: "default", + environmentDefaults: { + providers: [], + variables: {}, + }, + environments: [ + { + name: "default", + providers: moduleProviders, + variables: {}, + }, + ], + }, + }, + }) + // Render provider docs const providerDir = resolve(referenceDir, "providers") for (const { name, schema } of providers) { const path = resolve(providerDir, `${name}.md`) + console.log("->", path) writeFileSync(path, renderProviderReference(schema, name)) } // Render module type docs const moduleTypeDir = resolve(referenceDir, "module-types") - for (const { name, schema } of moduleTypes) { + const readme = ["# Module Types", ""] + for (const { name } of moduleTypes) { const path = resolve(moduleTypeDir, `${name}.md`) - writeFileSync(path, renderModuleTypeReference(schema, name)) + const { docs, schema, title } = await garden.actions.describeType(name) + + console.log("->", path) + writeFileSync(path, renderModuleTypeReference(populateModuleSchema(schema), name, docs)) + + readme.push(`* [${title || startCase(name.replace("-", " "))}](./${name}.md)`) } + writeFileSync(resolve(moduleTypeDir, `README.md`), readme.join("\n")) + // Render base config docs + console.log("->", configPath) writeFileSync(configPath, renderBaseConfigReference()) } diff --git a/garden-service/src/docs/generate.ts b/garden-service/src/docs/generate.ts index c7b29ada7a..4c4485390e 100644 --- a/garden-service/src/docs/generate.ts +++ b/garden-service/src/docs/generate.ts @@ -9,21 +9,15 @@ import { resolve } from "path" import { writeCommandReferenceDocs } from "./commands" import { writeConfigReferenceDocs } from "./config" -import { argv } from "process" import { writeTemplateStringReferenceDocs } from "./template-strings" -export function generateDocs(targetDir: string) { - const write = false +export async function generateDocs(targetDir: string) { const docsRoot = resolve(process.cwd(), targetDir) - if (write) { - writeCommandReferenceDocs(docsRoot) - writeConfigReferenceDocs(docsRoot) - writeTemplateStringReferenceDocs(docsRoot) - } else { - writeConfigReferenceDocs(docsRoot) - } -} -if (require.main === module) { - generateDocs(argv[2]) + console.log("Updating command references...") + writeCommandReferenceDocs(docsRoot) + console.log("Updating config references...") + await writeConfigReferenceDocs(docsRoot) + console.log("Updating template string reference...") + writeTemplateStringReferenceDocs(docsRoot) } diff --git a/garden-service/src/docs/templates/module-type.hbs b/garden-service/src/docs/templates/module-type.hbs index 1103d0192e..fe1984b783 100644 --- a/garden-service/src/docs/templates/module-type.hbs +++ b/garden-service/src/docs/templates/module-type.hbs @@ -1,8 +1,11 @@ # `{{{name}}}` reference -Below is the schema reference for the `{{{name}}}` module type. For an introduction to configuring Garden modules, please look at our [Configuration guide](../../using-garden/configuration-files.md). +{{{docs}}} -The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. +Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration +guide](../../using-garden/configuration-files.md). +The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available +schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema. ## Configuration keys @@ -11,4 +14,4 @@ The reference is divided into two sections. The [first section](#configuration-k ## Complete YAML schema ```yaml {{{yaml}}} -``` +``` \ No newline at end of file diff --git a/garden-service/src/garden.ts b/garden-service/src/garden.ts index 60c2e90f05..a7418afe40 100644 --- a/garden-service/src/garden.ts +++ b/garden-service/src/garden.ts @@ -46,7 +46,7 @@ import { ConfigGraph } from "./config-graph" import { TaskGraph, TaskResults } from "./task-graph" import { getLogger } from "./logger/logger" import { pluginActionNames, PluginActions, PluginFactory, GardenPlugin } from "./types/plugin/plugin" -import { joiIdentifier, validate, PrimitiveMap } from "./config/common" +import { joiIdentifier, validate, PrimitiveMap, validateWithPath } from "./config/common" import { resolveTemplateStrings } from "./template-string" import { configSchema, @@ -504,6 +504,15 @@ export class Garden { return Bluebird.map(configs, async (config) => { config = await resolveTemplateStrings(cloneDeep(config), opts.configContext!, opts) + const description = await this.actions.describeType(config.type) + + config.spec = validateWithPath({ + config: config.spec, + schema: description.schema, + name: config.name, + path: config.path, + projectRoot: this.projectRoot, + }) const configureHandler = await this.actions.getModuleActionHandler({ actionType: "configure", diff --git a/garden-service/src/plugins/container/container.ts b/garden-service/src/plugins/container/container.ts index a1dad7d229..29edd85bb5 100644 --- a/garden-service/src/plugins/container/container.ts +++ b/garden-service/src/plugins/container/container.ts @@ -7,26 +7,17 @@ */ import dedent = require("dedent") +import { keyBy } from "lodash" -import { validateWithPath } from "../../config/common" import { ConfigurationError } from "../../exceptions" import { GardenPlugin } from "../../types/plugin/plugin" import { ConfigureModuleParams, HotReloadServiceParams, PublishModuleParams } from "../../types/plugin/params" -import { keyBy } from "lodash" import { containerHelpers } from "./helpers" import { ContainerModule, containerModuleSpecSchema } from "./config" import { buildContainerModule, getContainerBuildStatus } from "./build" import { KubernetesProvider } from "../kubernetes/kubernetes" export async function configureContainerModule({ ctx, moduleConfig }: ConfigureModuleParams) { - moduleConfig.spec = validateWithPath({ - config: moduleConfig.spec, - schema: containerModuleSpecSchema, - name: moduleConfig.name, - path: moduleConfig.path, - projectRoot: ctx.projectRoot, - }) - // validate hot reload configuration // TODO: validate this when validating this action's output const hotReloadConfig = moduleConfig.spec.hotReload @@ -136,6 +127,7 @@ export async function configureContainerModule({ ctx, moduleConfig }: ConfigureM export const gardenPlugin = (): GardenPlugin => ({ moduleActions: { container: { + describeType, configure: configureContainerModule, getBuildStatus: getContainerBuildStatus, build: buildContainerModule, @@ -170,3 +162,18 @@ export const gardenPlugin = (): GardenPlugin => ({ }, }, }) + +async function describeType() { + return { + docs: dedent` + Specify a container image to build or pull from a remote registry. + You may also optionally specify services to deploy, tasks or tests to run inside the container. + + Note that the runtime services have somewhat limited features in this module type. For example, you cannot + specify replicas for redundancy, and various platform-specific options are not included. For those, look at + other module types like [helm](https://docs.garden.io/reference/module-types/helm) or + [kubernetes](https://docs.garden.io/reference/module-types/kubernetes). + `, + schema: containerModuleSpecSchema, + } +} diff --git a/garden-service/src/plugins/exec.ts b/garden-service/src/plugins/exec.ts index a62c2ee020..fb51a78c81 100644 --- a/garden-service/src/plugins/exec.ts +++ b/garden-service/src/plugins/exec.ts @@ -39,6 +39,7 @@ import { GARDEN_BUILD_VERSION_FILENAME } from "../constants" import { ModuleSpec, BaseBuildSpec, baseBuildSpecSchema } from "../config/module" import execa = require("execa") import { BaseTaskSpec, baseTaskSpecSchema } from "../config/task" +import { dedent } from "../util/string" export const name = "exec" @@ -235,9 +236,20 @@ export async function runExecTask(params: RunTaskParams): Promise } } +async function describeType() { + return { + docs: dedent` + A simple module for executing commands in your shell. This can be a useful escape hatch if no other module + type fits your needs, and you just need to execute something (as opposed to deploy it, track its status etc.). + `, + schema: execModuleSpecSchema, + } +} + export const execPlugin: GardenPlugin = { moduleActions: { exec: { + describeType, configure: configureExecModule, getBuildStatus: getExecModuleBuildStatus, build: buildExecModule, diff --git a/garden-service/src/plugins/kubernetes/helm/config.ts b/garden-service/src/plugins/kubernetes/helm/config.ts index f960519642..20361ed0f1 100644 --- a/garden-service/src/plugins/kubernetes/helm/config.ts +++ b/garden-service/src/plugins/kubernetes/helm/config.ts @@ -16,7 +16,6 @@ import { joiArray, joiIdentifier, joiEnvVars, - validateWithPath, joiUserIdentifier, } from "../../../config/common" import { Module, FileCopySpec } from "../../../types/module" @@ -210,16 +209,8 @@ export const helmModuleSpecSchema = Joi.object().keys({ ), }) -export async function validateHelmModule({ ctx, moduleConfig }: ConfigureModuleParams) +export async function validateHelmModule({ moduleConfig }: ConfigureModuleParams) : Promise> { - moduleConfig.spec = validateWithPath({ - config: moduleConfig.spec, - schema: helmModuleSpecSchema, - name: moduleConfig.name, - path: moduleConfig.path, - projectRoot: ctx.projectRoot, - }) - const { base, chart, dependencies, serviceResource, skipDeploy, tasks, tests, } = moduleConfig.spec diff --git a/garden-service/src/plugins/kubernetes/helm/handlers.ts b/garden-service/src/plugins/kubernetes/helm/handlers.ts index b156806abd..b3f24f7269 100644 --- a/garden-service/src/plugins/kubernetes/helm/handlers.ts +++ b/garden-service/src/plugins/kubernetes/helm/handlers.ts @@ -7,7 +7,7 @@ */ import { ModuleAndRuntimeActions } from "../../../types/plugin/plugin" -import { HelmModule, validateHelmModule as configureHelmModule } from "./config" +import { HelmModule, validateHelmModule as configureHelmModule, helmModuleSpecSchema } from "./config" import { buildHelmModule } from "./build" import { getServiceStatus } from "./status" import { deployService, deleteService } from "./deployment" @@ -16,6 +16,17 @@ import { runHelmTask, runHelmModule } from "./run" import { hotReloadHelmChart } from "./hot-reload" import { getServiceLogs } from "./logs" import { testHelmModule } from "./test" +import { dedent } from "../../../util/string" + +async function describeType() { + return { + docs: dedent` + Specify a Helm chart (either in your repository or remote from a registry) to deploy. + Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts) for usage instructions. + `, + schema: helmModuleSpecSchema, + } +} export const helmHandlers: Partial> = { build: buildHelmModule, @@ -23,6 +34,7 @@ export const helmHandlers: Partial> = { // TODO: add execInService handler deleteService, deployService, + describeType, getServiceLogs, getServiceStatus, getTestResult, diff --git a/garden-service/src/plugins/kubernetes/kubernetes-module/config.ts b/garden-service/src/plugins/kubernetes/kubernetes-module/config.ts index f909ff6ab1..b7bfbfc13a 100644 --- a/garden-service/src/plugins/kubernetes/kubernetes-module/config.ts +++ b/garden-service/src/plugins/kubernetes/kubernetes-module/config.ts @@ -9,7 +9,7 @@ import Joi = require("joi") import { ServiceSpec } from "../../../config/service" -import { joiArray, joiIdentifier, validateWithPath } from "../../../config/common" +import { joiArray, joiIdentifier } from "../../../config/common" import { Module } from "../../../types/module" import { ConfigureModuleParams } from "../../../types/plugin/params" import { ConfigureModuleResult } from "../../../types/plugin/outputs" @@ -17,7 +17,7 @@ import { Service } from "../../../types/service" import { ContainerModule } from "../../container/config" import { baseBuildSpecSchema } from "../../../config/module" import { KubernetesResource } from "../types" -import { deline } from "../../../util/string" +import { deline, dedent } from "../../../util/string" // A Kubernetes Module always maps to a single Service export type KubernetesModuleSpec = KubernetesServiceSpec @@ -52,7 +52,7 @@ const kubernetesResourceSchema = Joi.object() }) .unknown(true) -export const kubernetesModuleSpecSchema = Joi.object() +const kubernetesModuleSpecSchema = Joi.object() .keys({ build: baseBuildSpecSchema, dependencies: joiArray(joiIdentifier()) @@ -66,16 +66,26 @@ export const kubernetesModuleSpecSchema = Joi.object() .description("POSIX-style paths to YAML files to load manifests from. Each can contain multiple manifests."), }) -export async function configureKubernetesModule({ ctx, moduleConfig }: ConfigureModuleParams) - : Promise> { - moduleConfig.spec = validateWithPath({ - config: moduleConfig.spec, +export async function describeType() { + return { + docs: dedent` + Specify one or more Kubernetes manifests to deploy. + + You can either (or both) specify the manifests as part of the \`garden.yml\` configuration, or you can refer to + one or more files with existing manifests. + + Note that if you include the manifests in the \`garden.yml\` file, you can use + [template strings](https://docs.garden.io/reference/template-strings) to interpolate values into the manifests. + + If you need more advanced templating features you can use the + [helm](https://docs.garden.io/reference/module-types/helm) module type. + `, schema: kubernetesModuleSpecSchema, - name: moduleConfig.name, - path: moduleConfig.path, - projectRoot: ctx.projectRoot, - }) + } +} +export async function configureKubernetesModule({ moduleConfig }: ConfigureModuleParams) + : Promise> { moduleConfig.serviceConfigs = [{ name: moduleConfig.name, dependencies: moduleConfig.spec.dependencies, diff --git a/garden-service/src/plugins/kubernetes/kubernetes-module/handlers.ts b/garden-service/src/plugins/kubernetes/kubernetes-module/handlers.ts index 729d5a5ed3..0aa5ccbcc8 100644 --- a/garden-service/src/plugins/kubernetes/kubernetes-module/handlers.ts +++ b/garden-service/src/plugins/kubernetes/kubernetes-module/handlers.ts @@ -19,7 +19,7 @@ import { DeleteServiceParams, GetServiceLogsParams, } from "../../../types/plugin/params" -import { KubernetesModule, configureKubernetesModule, KubernetesService } from "./config" +import { KubernetesModule, configureKubernetesModule, KubernetesService, describeType } from "./config" import { BuildResult } from "../../../types/plugin/outputs" import { getNamespace, getAppNamespace } from "../namespace" import { KubernetesPluginContext } from "../kubernetes" @@ -37,6 +37,7 @@ export const kubernetesHandlers: Partial") .description( diff --git a/garden-service/src/plugins/maven-container/maven-container.ts b/garden-service/src/plugins/maven-container/maven-container.ts index ecf7e52131..a34ef38de8 100644 --- a/garden-service/src/plugins/maven-container/maven-container.ts +++ b/garden-service/src/plugins/maven-container/maven-container.ts @@ -17,7 +17,7 @@ import { ContainerModuleConfig, ContainerTaskSpec, } from "../container/config" -import { validateWithPath, joiArray } from "../../config/common" +import { joiArray, joiProviderName } from "../../config/common" import { BuildModuleParams, ConfigureModuleParams, GetBuildStatusParams } from "../../types/plugin/params" import { Module } from "../../types/module" import { configureContainerModule, gardenPlugin as containerPlugin } from "../container/container" @@ -32,6 +32,7 @@ import { providerConfigBaseSchema } from "../../config/project" import { openJdks } from "./openjdk" import { maven } from "./maven" import { LogEntry } from "../../logger/log-entry" +import { dedent } from "../../util/string" import AsyncLock = require("async-lock") const defaultDockerfilePath = resolve(STATIC_DIR, "maven-container", "Dockerfile") @@ -66,11 +67,11 @@ const mavenKeys = { .description("Options to add to the `mvn package` command when building."), } -const mavenFieldsSchema = Joi.object() - .keys(mavenKeys) - -export const mavenContainerModuleSpecSchema = containerModuleSpecSchema.keys(mavenKeys) +const mavenContainerModuleSpecSchema = containerModuleSpecSchema.keys(mavenKeys) export const mavenContainerConfigSchema = providerConfigBaseSchema + .keys({ + name: joiProviderName("maven-container"), + }) export const gardenPlugin = (): GardenPlugin => { const basePlugin = containerPlugin() @@ -80,6 +81,7 @@ export const gardenPlugin = (): GardenPlugin => { moduleActions: { "maven-container": { ...basePlugin.moduleActions!.container, + describeType, configure: configureMavenContainerModule, getBuildStatus, build, @@ -88,21 +90,33 @@ export const gardenPlugin = (): GardenPlugin => { } } +async function describeType() { + return { + docs: dedent` + A specialized version of the [container](https://docs.garden.io/reference/module-types/container) module type + that has special semantics for JAR files built with Maven. + + Rather than build the JAR inside the container (or in a multi-stage build) this plugin runs \`mvn package\` + ahead of building the container, which tends to be much more performant, especially when building locally + with a warm artifact cache. + + A default Dockerfile is also provided for convenience, but you may override it by including one in the module + directory. + + To use it, make sure to add the \`maven-container\` provider to your project configuration. + The provider will automatically fetch and cache Maven and the appropriate OpenJDK version ahead of building. + `, + schema: mavenContainerModuleSpecSchema, + } +} + export async function configureMavenContainerModule(params: ConfigureModuleParams) { - const { ctx, moduleConfig } = params - - const mavenFields = validateWithPath({ - config: pick(params.moduleConfig.spec, Object.keys(mavenKeys)), - schema: mavenFieldsSchema, - name: moduleConfig.name, - path: moduleConfig.path, - projectRoot: ctx.projectRoot, - }) + const { moduleConfig } = params let containerConfig: ContainerModuleConfig = { ...moduleConfig } containerConfig.spec = omit(moduleConfig.spec, Object.keys(mavenKeys)) - const jdkVersion = mavenFields.jdkVersion! + const jdkVersion = moduleConfig.spec.jdkVersion! containerConfig.spec.buildArgs = { JAR_PATH: "app.jar", @@ -122,7 +136,7 @@ export async function configureMavenContainerModule(params: ConfigureModuleParam ...configured, spec: { ...configured.spec, - ...mavenFields, + ...pick(moduleConfig.spec, Object.keys(mavenKeys)), }, } } diff --git a/garden-service/src/plugins/openfaas/openfaas.ts b/garden-service/src/plugins/openfaas/openfaas.ts index a095d06191..695ab63763 100644 --- a/garden-service/src/plugins/openfaas/openfaas.ts +++ b/garden-service/src/plugins/openfaas/openfaas.ts @@ -13,7 +13,7 @@ import { STATIC_DIR } from "../../constants" import { PluginError, ConfigurationError } from "../../exceptions" import { Garden } from "../../garden" import { PluginContext } from "../../plugin-context" -import { joiArray, validate, PrimitiveMap, joiProviderName } from "../../config/common" +import { joiArray, PrimitiveMap, joiProviderName } from "../../config/common" import { Module } from "../../types/module" import { ConfigureModuleResult } from "../../types/plugin/outputs" import { @@ -108,6 +108,16 @@ export const configSchema = providerConfigBaseSchema type OpenFaasProvider = Provider type OpenFaasPluginContext = PluginContext +async function describeType() { + return { + docs: dedent` + 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. + `, + schema: openfaasModuleSpecSchema, + } +} + export function gardenPlugin(): GardenPlugin { return { configSchema, @@ -165,13 +175,9 @@ export function gardenPlugin(): GardenPlugin { }, moduleActions: { openfaas: { - async configure({ ctx, moduleConfig }: ConfigureModuleParams): Promise { - moduleConfig.spec = validate( - moduleConfig.spec, - openfaasModuleSpecSchema, - { context: `module ${moduleConfig.name}` }, - ) + describeType, + async configure({ ctx, moduleConfig }: ConfigureModuleParams): Promise { moduleConfig.build.dependencies.push({ name: "templates", plugin: "openfaas", diff --git a/garden-service/src/types/plugin/outputs.ts b/garden-service/src/types/plugin/outputs.ts index b2bfed2c2c..81c7c9f14a 100644 --- a/garden-service/src/types/plugin/outputs.ts +++ b/garden-service/src/types/plugin/outputs.ts @@ -133,7 +133,9 @@ export const getServiceLogsResultSchema = Joi.object().keys({}) export interface ModuleTypeDescription { docs: string - schema: object + // TODO: specify the schema using primitives and not Joi objects + schema: Joi.ObjectSchema + title?: string } export const moduleTypeDescriptionSchema = Joi.object() @@ -144,7 +146,12 @@ export const moduleTypeDescriptionSchema = Joi.object() schema: Joi.object() .required() .description( - "A valid OpenAPI schema describing the configuration keys for the `module` field in the module's `garden.yml`.", + "A valid Joi schema describing the configuration keys for the `module` " + + "field in the module's `garden.yml`.", + ), + title: Joi.string() + .description( + "Readable title for the module type. Defaults to the title-cased type name, with dashes replaced by spaces.", ), }) diff --git a/garden-service/src/types/plugin/plugin.ts b/garden-service/src/types/plugin/plugin.ts index b9f99eae5d..eee5e34706 100644 --- a/garden-service/src/types/plugin/plugin.ts +++ b/garden-service/src/types/plugin/plugin.ts @@ -287,7 +287,7 @@ export const taskActionDescriptions: { [P in TaskActionName]: PluginActionDescri export const moduleActionDescriptions: { [P in ModuleActionName | ServiceActionName | TaskActionName]: PluginActionDescription } = { - // TODO: implement this method (it is currently not defined or used) + // TODO: specify the schema using primitives and not Joi objects describeType: { description: dedent` Return documentation and a schema description of the module type. @@ -295,9 +295,8 @@ export const moduleActionDescriptions: The documentation should be in markdown format. A reference for the module type is automatically generated based on the provided schema, and a section appended to the provided documentation. - The schema should be a valid OpenAPI schema describing the configuration keys that the user - should use under the \`module\` key in a \`garden.yml\` configuration file. Note that the schema - should not specify the built-in fields (such as \`name\`, \`type\` and \`description\`). + The schema should be a valid Joi schema describing the configuration keys that the user + should use under the \`module\` key in a \`garden.yml\` configuration file. Used when auto-generating framework documentation. diff --git a/garden-service/test/unit/src/actions.ts b/garden-service/test/unit/src/actions.ts index 921455df88..ded7f7a630 100644 --- a/garden-service/test/unit/src/actions.ts +++ b/garden-service/test/unit/src/actions.ts @@ -11,6 +11,7 @@ import { Task } from "../../../src/types/task" import Stream from "ts-stream" import { ServiceLogEntry } from "../../../src/types/plugin/outputs" import { LogEntry } from "../../../src/logger/log-entry" +import * as Joi from "joi" import { describeModuleTypeParamsSchema, configureModuleParamsSchema, @@ -450,7 +451,8 @@ const testPlugin: PluginFactory = async () => ({ validate(params, describeModuleTypeParamsSchema) return { docs: "bla bla bla", - schema: {}, + schema: Joi.object(), + title: "Bla", } }, diff --git a/garden-service/test/unit/src/config/base.ts b/garden-service/test/unit/src/config/base.ts index 63d49ef9bf..caa7beba73 100644 --- a/garden-service/test/unit/src/config/base.ts +++ b/garden-service/test/unit/src/config/base.ts @@ -46,6 +46,7 @@ describe("loadConfig", () => { expect(parsed!.project).to.eql({ apiVersion: "garden.io/v0", + kind: "Project", name: "test-project-a", defaultEnvironment: "local", sources: [], @@ -77,6 +78,7 @@ describe("loadConfig", () => { expect(parsed!.modules).to.eql([ { apiVersion: "garden.io/v0", + kind: "Module", name: "module-a", type: "test", description: undefined, @@ -115,6 +117,7 @@ describe("loadConfig", () => { expect(parsed!.project).to.eql({ apiVersion: "garden.io/v0", + kind: "Project", defaultEnvironment: "local", environmentDefaults: { providers: [], @@ -143,6 +146,7 @@ describe("loadConfig", () => { expect(parsed!.modules).to.eql([{ apiVersion: "garden.io/v0", + kind: "Module", name: "module-from-project-config", type: "test", description: undefined, @@ -170,6 +174,7 @@ describe("loadConfig", () => { expect(parsed!.modules).to.eql([ { apiVersion: "garden.io/v0", + kind: "Module", name: "module-a1", type: "test", allowPublish: true, @@ -200,6 +205,7 @@ describe("loadConfig", () => { }, { apiVersion: "garden.io/v0", + kind: "Module", name: "module-a2", type: "test", allowPublish: true, @@ -230,6 +236,7 @@ describe("loadConfig", () => { expect(parsed!.project).to.eql({ apiVersion: "garden.io/v0", + kind: "Project", defaultEnvironment: "local", environmentDefaults: { providers: [], @@ -256,6 +263,7 @@ describe("loadConfig", () => { expect(parsed!.modules).to.eql([{ apiVersion: "garden.io/v0", + kind: "Module", name: "module-from-project-config", type: "test", description: undefined, diff --git a/garden-service/test/unit/src/plugins/container.ts b/garden-service/test/unit/src/plugins/container.ts index d806c412a6..c2f18e7dba 100644 --- a/garden-service/test/unit/src/plugins/container.ts +++ b/garden-service/test/unit/src/plugins/container.ts @@ -445,7 +445,7 @@ describe("plugins.container", () => { SOME_ENV_VAR: "value", }, healthCheck: - { httpGet: { path: "/health", port: "http", scheme: "HTTP" } }, + { httpGet: { path: "/health", port: "http" } }, ports: [{ name: "http", protocol: "TCP", containerPort: 8080, servicePort: 8080 }], outputs: {}, volumes: [], @@ -492,7 +492,7 @@ describe("plugins.container", () => { SOME_ENV_VAR: "value", }, healthCheck: - { httpGet: { path: "/health", port: "http", scheme: "HTTP" } }, + { httpGet: { path: "/health", port: "http" } }, ports: [{ name: "http", protocol: "TCP", containerPort: 8080, servicePort: 8080 }], outputs: {}, volumes: [], diff --git a/garden-service/test/unit/src/plugins/kubernetes/helm/config.ts b/garden-service/test/unit/src/plugins/kubernetes/helm/config.ts index 71b59823c7..57970059ad 100644 --- a/garden-service/test/unit/src/plugins/kubernetes/helm/config.ts +++ b/garden-service/test/unit/src/plugins/kubernetes/helm/config.ts @@ -4,9 +4,10 @@ import { cloneDeep } from "lodash" import { TestGarden, dataDir, makeTestGarden, expectError } from "../../../../../helpers" import { PluginContext } from "../../../../../../src/plugin-context" -import { validateHelmModule } from "../../../../../../src/plugins/kubernetes/helm/config" +import { validateHelmModule, helmModuleSpecSchema } from "../../../../../../src/plugins/kubernetes/helm/config" import { deline } from "../../../../../../src/util/string" import { LogEntry } from "../../../../../../src/logger/log-entry" +import { validate } from "../../../../../../src/config/common" describe("validateHelmModule", () => { let garden: TestGarden @@ -27,6 +28,7 @@ describe("validateHelmModule", () => { function getModuleConfig(name: string) { const config = cloneDeep((garden).moduleConfigs[name]) + config.spec = validate(config.spec, helmModuleSpecSchema) config.serviceConfigs = [] config.taskConfigs = [] config.testConfigs = [] @@ -40,12 +42,13 @@ describe("validateHelmModule", () => { const { versionString } = imageModule.version expect(config).to.eql({ + apiVersion: "garden.io/v0", + kind: "Module", allowPublish: true, build: { dependencies: [], }, description: "The API backend for the voting UI", - apiVersion: "garden.io/v0", include: undefined, name: "api", outputs: {