diff --git a/docs/guides/cert-manager-integration.md b/docs/guides/cert-manager-integration.md index 50826e9914..9cf8bd74fd 100644 --- a/docs/guides/cert-manager-integration.md +++ b/docs/guides/cert-manager-integration.md @@ -1,29 +1,31 @@ -# cert-manager integration +# cert-manager Integration -## Scope, requirements and version supported +When starting a new Kubernetes project or when maintaining your existing ones, dealing with the creation and renewal of TLS certificates can easily become a headache. A popular tool to help automate certficate generation and renewal is [cert-manager](https://github.com/jetstack/cert-manager). -### Scope +The [kubernetes](./remote-kubernetes.md) and [local-kubernetes](./local-kubernetes.md) providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults. +We don't aim to support all the features of cert-manager, but rather accommodate the most common use case, while still allowing full control of the underlying setup when needed. -This guide aims at outlining configuration and best practices when dealing with TLS certificates, cert-manager and Garden. +## Requirements -When starting a new project or when maintaining your existing ones, dealing with the creation and renewal of certificates can easily become a very complex task. Many projects appeared in the last few years to help managing this complexity and one that stood out is [cert-manager](https://github.com/jetstack/cert-manager). +You need to have an ingress controller configured, that is configured using Ingress resources (e.g. nginx). You can install nginx automatically by setting `setupIngressController: nginx` in your `kubernetes` provider config. +You also need make sure your DNS and routing are configured to point the domains you will configure below to your ingress controller. -The goal of this integration is to give you a head start when setting the TLS certificates for your project with cert-manager, providing an easy way for installation and some sensible defaults while allowing full control of the underlying configuration. -We don't aim to fully support all the features of cert-manager, but rather accommodate the most common use case while still allowing full control of the underlying setup. +## Limitations -Please read the defaults settings and configurations in each of the following sections. +cert-manager is currently under development. Currently we only support cert-manager v0.11.0, which requires Kubernetes v1.11 or higher. -### Requirements +If you set `certManager.install: false` garden will expect to find a `cert-manager` installation in the `cert-manager` namespace. +If you already have installed `cert-manager` please verify it's running by checking the status of the main pods as suggested in the [documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#verifying-the-installation). -We require you to have configured your DNS and routing so that the domains you will configure below are pointed to your ingress controller. +The integration currently only supports Let's Encrypt and HTTP-01 challenges. We also only support cert-manager ClusterIssuers and not namespace Issuers. -### Supported versions +> More configuration options will be implemented, but we need your help to prioritize them! Please [file an issue](https://github.com/garden-io/garden/issues) to request the features you need. -cert-manager is currently under development and will soon go in beta. Currently we only support `cert-manager v0.11.0` which requires `kubernetes >v1.11`. +## Usage -## Enable the integration and configuration +### Enabling and configuring cert-manager -To enable cert-manager, you'll need to configure it on your Kubernetes Provider configuration in your project `garden.yml` file: +To enable cert-manager, you'll need to configure it in the `kubernetes` provider configuration in your project `garden.yml` file: ```yaml kind: Project @@ -37,28 +39,26 @@ To enable cert-manager, you'll need to configure it on your Kubernetes Provider ... certManager: install: true # let garden install cert-manager - email: name@example.com # your email (used to create Let's Encrypt certificates) - issuer: acme # the type of issuer for the certificate generation. This integration supports Let's Encrypt ACME - acmeChallengeType: HTTP-01 # type of ACME challenge. This integration supports "HTTP-01" - acmeServer: letsencrypt-staging # ACME server. "letsencrypt-staging" or "letsencrypt-prod" + email: name@example.com # your email (required when requesting Let's Encrypt certificates) + issuer: acme # the type of issuer for the certificate generation (currently only Let's Encrypt ACME is supported) + acmeChallengeType: HTTP-01 # type of ACME challenge (currently only "HTTP-01" is supported) + acmeServer: letsencrypt-staging # the ACME server to use ("letsencrypt-staging" or "letsencrypt-prod") tlsCertificates: ... ``` -Unless you want to use your own installation of cert-manager, you will need to set the option `install: true`: garden will install cert-manager for you under the `cert-manager` namespace. +Unless you want to use your own installation of cert-manager, you will need to set the option `install: true`. Garden will then install cert-manager for you under the `cert-manager` namespace. -If nothing is specified or `install: false` garden will assume to find a valid and running cert-manager installation in the `cert-manager` namespace. +If nothing is specified or `install: false`, Garden will assume you already have a valid and running cert-manager installation in the `cert-manager` namespace. -A valid email address is also required if you are planning to generate Certificates through the integrations (we are using a Let's Encrypt HTTP-01 challenge, see below). +A valid email address is also required for Let's Encrypt certificate requests. -## Issuing your first certificate +### Issuing your first certificate -cert-manager is a very powerful tool with a lot of different possible configurations. While integrating it with Garden we decided to implement some opinionated behaviours which should get you up to speed fast without thinking too much about configuration. -In case you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself by enabling the option `tlsCertificates[].managedBy: cert-manager`. +cert-manager is a powerful tool with a lot of different possible configurations. While integrating it with Garden we decided to start with an opinionated setup which should get you up to speed quickly, without thinking too much about configuration. +If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the [`tlsCertificates[].managedBy` config field](../reference/providers/kubernetes.md#providerstlscertificatesmanagedby). -For advance configuration please take a look at the official [cert-manager documentation](https://docs.cert-manager.io/en/latest/tasks/index.html). - -### Example +#### Example The configuration for letting Garden create a Certificate through cert-manager happens at the tlsCertificate level. See the [providers[].tlsCertificates[] reference](https://docs.garden.io/reference/providers/kubernetes#providers-tlscertificates) for more details): @@ -79,48 +79,30 @@ The configuration for letting Garden create a Certificate through cert-manager h acmeServer: letsencrypt-staging tlsCertificates: - name: example-certificate-staging-01 - managedBy: cert-manager # Allow cert-manager to manage this certificate - serverType: staging # Let's Encrypt server: "staging" or "prod". Defaults to "prod" + managedBy: cert-manager # allow cert-manager to manage this certificate hostnames: - - your-domain-name.com # The domain name for the certificate + - your-domain-name.com # the domain name(s) to be covered by the certificate secretRef: - name: tls-secret-for-certificate # The secret where cert-manage will store the TLS certificate once it's generated + name: tls-secret-for-certificate # the secret where cert-manager will store the TLS certificate once it's generated namespace: cert-manager-example ``` The above configuration will trigger the following workflow: -1) cert-manager will create a ClusterIssuer in your cluster which will generate your certificate. -2) It will then create a Certificate resource to request the TLS certificate. -3) Cert-manager will then automatically spin up an nginx ingress to solve the HTTP-01 acmeChallenge. -4) Once the challenge is solved the TLS certificate will be stored as a secret using the name/namespace specified above (eg. `cert-manager-example/tls-secret-for-certificate`) +1) cert-manager will create a ClusterIssuer in your cluster which will generate your certificate. Each certificate gets an associated ClusterIssuer, which will take care of performing the issue challenge. +2) Garden will then create a Certificate resource to request the TLS certificate. +3) cert-manager will then automatically create an Ingress to solve the HTTP-01 ACME challenge. +4) Once the challenge is solved the TLS certificate will be stored as a Secret using the name/namespace specified above (e.g. `cert-manager-example/tls-secret-for-certificate`). All the steps above will happen at system startup/init. All your services will be built/tested/deployed after all the secrets have been populated. -### ClusterIssuer vs Issuer - -cert-manager have two different Certificate issuers: namespaced and cluster one. Garden will only create ClusterIssuers. - -### One certificate per tlsCertificate and one ClusterIssuer per certificate - -Garden will create one certificate for each certificate with `managedBy: true` in the `tlsCertificates` array. Each certificate will have an associated ClusterIssuer which will take care of starting and carrying on the challenge and creating the secret containing the TLS certificate once it succeeds. - -### Challenge Type - -The challenge type currently supported is Let's Encrypt [HTTP-01 challenge](https://letsencrypt.org/docs/challenge-types/). +For advanced configuration, please take a look at the official [cert-manager documentation](https://docs.cert-manager.io/en/latest/tasks/index.html). ## Troubleshooting -### Couldn't find a cert-manager installation - -If you set `certManager.install: false` garden will expect to find a `cert-manager` installation in the `cert-manager` namespace. -If you already have installed `cert-manager` please verify it's running by checking the status of the main pods as suggested in the [documentation](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html#verifying-the-installation). - -At the moment we don't support cert-manager installed in different namespaces. - ### The certificate creation timeouts and garden terminates -> Please make sure your domain name is pointing at the right ip address. +> Please make sure your domain name is pointing at the right IP address. The best way to figure out why a certificate is not being generated is using `kubectl describe`. @@ -139,4 +121,4 @@ $: kubectl describe Certificate certificate-name -n your-namespace Please find more info in the ["Issuing an ACME certificate using HTTP validation"](https://docs.cert-manager.io/en/release-0.11/tutorials/acme/http-validation.html#issuing-an-acme-certificate-using-http-validation) guide in the official cert-manager documentation. --- -If have any issue, found a bug or something is not clear in the documentation, please don't hesitate opening a new [Github issue](https://github.com/garden-io/garden/issues/new?template=BUG_REPORT.md) or ask us any question in our [Slack channel](https://chat.garden.io/). +If have any issue, find a bug, or something is not clear from the documentation, please don't hesitate opening a new [GitHub issue](https://github.com/garden-io/garden/issues/new?template=BUG_REPORT.md) or ask us questions in our [Slack channel](https://chat.garden.io/). diff --git a/docs/reference/config.md b/docs/reference/config.md index a6eb426e81..ee449774ee 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -652,7 +652,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | diff --git a/docs/reference/module-types/container.md b/docs/reference/module-types/container.md index 4b80b34917..eb0b44ae0c 100644 --- a/docs/reference/module-types/container.md +++ b/docs/reference/module-types/container.md @@ -205,7 +205,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | @@ -350,7 +351,7 @@ The list of services to deploy from this container module. [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. +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 | | -------- | -------- | @@ -728,7 +729,7 @@ Example: ```yaml services: - ports: - - containerPort: "8080" + - containerPort: 8080 ``` ### `services[].ports[].servicePort` @@ -750,7 +751,7 @@ Example: ```yaml services: - ports: - - servicePort: "80" + - servicePort: 80 ``` ### `services[].ports[].hostPort` @@ -873,11 +874,11 @@ Maximum duration (in seconds) of the test run. | -------- | -------- | ------- | | `number` | No | `null` | -### `tests[].command[]` +### `tests[].args[]` -[tests](#tests) > command +[tests](#tests) > args -The command/entrypoint used to run the test inside the container. +The arguments used to run the test inside the container. | Type | Required | | --------------- | -------- | @@ -887,16 +888,73 @@ Example: ```yaml tests: - - command: - - /bin/sh - - '-c' + - args: + - npm + - test ``` -### `tests[].args[]` +### `tests[].artifacts[]` -[tests](#tests) > args +[tests](#tests) > artifacts -The arguments used to run the test inside the container. +Specify artifacts to copy out of the container after the run. +Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable the file transfer. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* +``` + +### `tests[].artifacts[].source` + +[tests](#tests) > [artifacts](#testsartifacts) > source + +A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* + - source: "/output/**/*" +``` + +### `tests[].artifacts[].target` + +[tests](#tests) > [artifacts](#testsartifacts) > target + +A POSIX-style path to copy the artifacts to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* + - target: "outputs/foo/" +``` + +### `tests[].command[]` + +[tests](#tests) > command + +The command/entrypoint used to run the test inside the container. | Type | Required | | --------------- | -------- | @@ -906,9 +964,9 @@ Example: ```yaml tests: - - args: - - npm - - test + - command: + - /bin/sh + - '-c' ``` ### `tests[].env` @@ -981,11 +1039,11 @@ Maximum duration (in seconds) of the task's execution. | -------- | -------- | ------- | | `number` | No | `null` | -### `tasks[].command[]` +### `tasks[].args[]` -[tasks](#tasks) > command +[tasks](#tasks) > args -The command/entrypoint used to run the task inside the container. +The arguments used to run the task inside the container. | Type | Required | | --------------- | -------- | @@ -995,16 +1053,73 @@ Example: ```yaml tasks: - - command: - - /bin/sh - - '-c' + - args: + - rake + - 'db:migrate' ``` -### `tasks[].args[]` +### `tasks[].artifacts[]` -[tasks](#tasks) > args +[tasks](#tasks) > artifacts -The arguments used to run the task inside the container. +Specify artifacts to copy out of the container after the run. +Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable the file transfer. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* +``` + +### `tasks[].artifacts[].source` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > source + +A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* + - source: "/output/**/*" +``` + +### `tasks[].artifacts[].target` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > target + +A POSIX-style path to copy the artifacts to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* + - target: "outputs/foo/" +``` + +### `tasks[].command[]` + +[tasks](#tasks) > command + +The command/entrypoint used to run the task inside the container. | Type | Required | | --------------- | -------- | @@ -1014,9 +1129,9 @@ Example: ```yaml tasks: - - args: - - rake - - 'db:migrate' + - command: + - /bin/sh + - '-c' ``` ### `tasks[].env` @@ -1112,16 +1227,22 @@ tests: - name: dependencies: [] timeout: null - command: args: + artifacts: + - source: + target: . + command: env: {} tasks: - name: description: dependencies: [] timeout: null - command: args: + artifacts: + - source: + target: . + command: env: {} ``` diff --git a/docs/reference/module-types/exec.md b/docs/reference/module-types/exec.md index 09a1e43271..8dc8c8415e 100644 --- a/docs/reference/module-types/exec.md +++ b/docs/reference/module-types/exec.md @@ -208,7 +208,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | @@ -306,6 +307,36 @@ Maximum duration (in seconds) of the task's execution. | -------- | -------- | ------- | | `number` | No | `null` | +### `tasks[].artifacts[]` + +[tasks](#tasks) > artifacts + +A list of artifacts to copy after the task run. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +### `tasks[].artifacts[].source` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > source + +A POSIX-style path or glob to copy, relative to the build root. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +### `tasks[].artifacts[].target` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > target + +A POSIX-style path to copy the artifact to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + ### `tasks[].command[]` [tasks](#tasks) > command @@ -390,6 +421,36 @@ Key/value map of environment variables. Keys must be valid POSIX environment var | -------- | -------- | ------- | | `object` | No | `{}` | +### `tests[].artifacts[]` + +[tests](#tests) > artifacts + +A list of artifacts to copy after the test run. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +### `tests[].artifacts[].source` + +[tests](#tests) > [artifacts](#testsartifacts) > source + +A POSIX-style path or glob to copy, relative to the build root. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +### `tests[].artifacts[].target` + +[tests](#tests) > [artifacts](#testsartifacts) > target + +A POSIX-style path to copy the artifact to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + ## Complete YAML schema ```yaml @@ -416,6 +477,9 @@ tasks: description: dependencies: [] timeout: null + artifacts: + - source: + target: . command: env: {} tests: @@ -424,6 +488,9 @@ tests: timeout: null command: env: {} + artifacts: + - source: + target: . ``` ## Outputs diff --git a/docs/reference/module-types/helm.md b/docs/reference/module-types/helm.md index 3d86499be8..ec70e50b4c 100644 --- a/docs/reference/module-types/helm.md +++ b/docs/reference/module-types/helm.md @@ -200,7 +200,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | diff --git a/docs/reference/module-types/kubernetes.md b/docs/reference/module-types/kubernetes.md index b6f7518df7..817351aea4 100644 --- a/docs/reference/module-types/kubernetes.md +++ b/docs/reference/module-types/kubernetes.md @@ -208,7 +208,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | diff --git a/docs/reference/module-types/maven-container.md b/docs/reference/module-types/maven-container.md index 466c137560..62debfbedb 100644 --- a/docs/reference/module-types/maven-container.md +++ b/docs/reference/module-types/maven-container.md @@ -210,7 +210,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | @@ -355,7 +356,7 @@ The list of services to deploy from this container module. [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. +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 | | -------- | -------- | @@ -733,7 +734,7 @@ Example: ```yaml services: - ports: - - containerPort: "8080" + - containerPort: 8080 ``` ### `services[].ports[].servicePort` @@ -755,7 +756,7 @@ Example: ```yaml services: - ports: - - servicePort: "80" + - servicePort: 80 ``` ### `services[].ports[].hostPort` @@ -878,11 +879,11 @@ Maximum duration (in seconds) of the test run. | -------- | -------- | ------- | | `number` | No | `null` | -### `tests[].command[]` +### `tests[].args[]` -[tests](#tests) > command +[tests](#tests) > args -The command/entrypoint used to run the test inside the container. +The arguments used to run the test inside the container. | Type | Required | | --------------- | -------- | @@ -892,16 +893,73 @@ Example: ```yaml tests: - - command: - - /bin/sh - - '-c' + - args: + - npm + - test ``` -### `tests[].args[]` +### `tests[].artifacts[]` -[tests](#tests) > args +[tests](#tests) > artifacts -The arguments used to run the test inside the container. +Specify artifacts to copy out of the container after the run. +Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable the file transfer. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* +``` + +### `tests[].artifacts[].source` + +[tests](#tests) > [artifacts](#testsartifacts) > source + +A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* + - source: "/output/**/*" +``` + +### `tests[].artifacts[].target` + +[tests](#tests) > [artifacts](#testsartifacts) > target + +A POSIX-style path to copy the artifacts to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + +Example: + +```yaml +tests: + - artifacts: + - source: /report/**/* + - target: "outputs/foo/" +``` + +### `tests[].command[]` + +[tests](#tests) > command + +The command/entrypoint used to run the test inside the container. | Type | Required | | --------------- | -------- | @@ -911,9 +969,9 @@ Example: ```yaml tests: - - args: - - npm - - test + - command: + - /bin/sh + - '-c' ``` ### `tests[].env` @@ -986,11 +1044,11 @@ Maximum duration (in seconds) of the task's execution. | -------- | -------- | ------- | | `number` | No | `null` | -### `tasks[].command[]` +### `tasks[].args[]` -[tasks](#tasks) > command +[tasks](#tasks) > args -The command/entrypoint used to run the task inside the container. +The arguments used to run the task inside the container. | Type | Required | | --------------- | -------- | @@ -1000,16 +1058,73 @@ Example: ```yaml tasks: - - command: - - /bin/sh - - '-c' + - args: + - rake + - 'db:migrate' ``` -### `tasks[].args[]` +### `tasks[].artifacts[]` -[tasks](#tasks) > args +[tasks](#tasks) > artifacts -The arguments used to run the task inside the container. +Specify artifacts to copy out of the container after the run. +Note: Depending on the provider, this may require the container image to include `sh` `tar`, in order to enable the file transfer. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* +``` + +### `tasks[].artifacts[].source` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > source + +A POSIX-style path or glob to copy. Must be an absolute path. May contain wildcards. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* + - source: "/output/**/*" +``` + +### `tasks[].artifacts[].target` + +[tasks](#tasks) > [artifacts](#tasksartifacts) > target + +A POSIX-style path to copy the artifacts to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + +Example: + +```yaml +tasks: + - artifacts: + - source: /report/**/* + - target: "outputs/foo/" +``` + +### `tasks[].command[]` + +[tasks](#tasks) > command + +The command/entrypoint used to run the task inside the container. | Type | Required | | --------------- | -------- | @@ -1019,9 +1134,9 @@ Example: ```yaml tasks: - - args: - - rake - - 'db:migrate' + - command: + - /bin/sh + - '-c' ``` ### `tasks[].env` @@ -1162,16 +1277,22 @@ tests: - name: dependencies: [] timeout: null - command: args: + artifacts: + - source: + target: . + command: env: {} tasks: - name: description: dependencies: [] timeout: null - command: args: + artifacts: + - source: + target: . + command: env: {} imageVersion: jarPath: diff --git a/docs/reference/module-types/openfaas.md b/docs/reference/module-types/openfaas.md index b061f8cc62..b184fd5da3 100644 --- a/docs/reference/module-types/openfaas.md +++ b/docs/reference/module-types/openfaas.md @@ -200,7 +200,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | @@ -304,6 +305,36 @@ Key/value map of environment variables. Keys must be valid POSIX environment var | -------- | -------- | ------- | | `object` | No | `{}` | +### `tests[].artifacts[]` + +[tests](#tests) > artifacts + +A list of artifacts to copy after the test run. + +| Type | Required | +| --------------- | -------- | +| `array[object]` | No | + +### `tests[].artifacts[].source` + +[tests](#tests) > [artifacts](#testsartifacts) > source + +A POSIX-style path or glob to copy, relative to the build root. + +| Type | Required | +| -------- | -------- | +| `string` | Yes | + +### `tests[].artifacts[].target` + +[tests](#tests) > [artifacts](#testsartifacts) > target + +A POSIX-style path to copy the artifact to, relative to the project artifacts directory. + +| Type | Required | Default | +| -------- | -------- | ------- | +| `string` | No | `"."` | + ## Complete YAML schema ```yaml @@ -333,6 +364,9 @@ tests: timeout: null command: env: {} + artifacts: + - source: + target: . ``` ## Outputs diff --git a/docs/reference/module-types/terraform.md b/docs/reference/module-types/terraform.md index d83f78090d..f0b5810f04 100644 --- a/docs/reference/module-types/terraform.md +++ b/docs/reference/module-types/terraform.md @@ -214,7 +214,8 @@ POSIX-style path or filename of the directory or file(s) to copy to the target. [build](#build) > [dependencies](#builddependencies) > [copy](#builddependenciescopy) > target -POSIX-style path or filename to copy the directory or file(s). +POSIX-style path or filename to copy the directory or file(s), relative to the build directory. +Defaults to to same as source path. | Type | Required | Default | | -------- | -------- | ------------------------- | diff --git a/docs/reference/providers/kubernetes.md b/docs/reference/providers/kubernetes.md index dfcd171dfe..d81cd5b864 100644 --- a/docs/reference/providers/kubernetes.md +++ b/docs/reference/providers/kubernetes.md @@ -768,7 +768,9 @@ The namespace where the secret is stored. If necessary, the secret may be copied [providers](#providers) > [tlsCertificates](#providerstlscertificates) > managedBy -A reference to the TLS certificates manager used to generate the certificate. +Set to `cert-manager` to configure [cert-manager](https://github.com/jetstack/cert-manager) to manage this +certificate. See our +[cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. | Type | Required | | -------- | -------- | @@ -787,7 +789,7 @@ providers: [providers](#providers) > certManager cert-manager configuration, for creating and managing TLS certificates. See the -[Configuration Files guide](https://docs.garden.io/guides/cert-manager-integration) for details +[cert-manager guide](https://docs.garden.io/guides/cert-manager-integration) for details. | Type | Required | | -------- | -------- | @@ -797,7 +799,8 @@ cert-manager configuration, for creating and managing TLS certificates. See the [providers](#providers) > [certManager](#providerscertmanager) > install -When set to "true" Garden will install cert-manager. +Automatically install `cert-manager` on initialization. See the +[cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. | Type | Required | Default | | --------- | -------- | ------- | @@ -807,7 +810,7 @@ When set to "true" Garden will install cert-manager. [providers](#providers) > [certManager](#providerscertmanager) > email -The email which will be used for creating Let's Encrypt certificates: if your certificates are being created by Garden this field is required. +The email to use when requesting Let's Encrypt certificates. | Type | Required | | -------- | -------- | @@ -826,11 +829,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > issuer -the type of issuer for the certificate. Currently only supporting ACME Let's Encrypt issuers. +The type of issuer for the certificate (only ACME is supported for now). | Type | Required | Default | | -------- | -------- | -------- | -| `string` | Yes | `"acme"` | +| `string` | No | `"acme"` | Example: @@ -845,11 +848,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > acmeServer -If the certificate is managed by cert-manager, this allows to specify which LetsEncrypt endpoint to use to validate the certificate challenge. Defaults to "letsencrypt-staging." +Specify which ACME server to request certificates from. Currently Let's Encrypt staging and prod servers are supported. | Type | Required | Default | | -------- | -------- | ----------------------- | -| `string` | Yes | `"letsencrypt-staging"` | +| `string` | No | `"letsencrypt-staging"` | Example: @@ -864,11 +867,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > acmeChallengeType -The acmeChallenge used by the integration to validate hostnames and generate the certificates through Let's Encrypt. +The type of ACME challenge used to validate hostnames and generate the certificates (only HTTP-01 is supported for now). | Type | Required | Default | | -------- | -------- | ----------- | -| `string` | Yes | `"HTTP-01"` | +| `string` | No | `"HTTP-01"` | Example: diff --git a/docs/reference/providers/local-kubernetes.md b/docs/reference/providers/local-kubernetes.md index 0cb18ed28d..5d42f8a19c 100644 --- a/docs/reference/providers/local-kubernetes.md +++ b/docs/reference/providers/local-kubernetes.md @@ -768,7 +768,9 @@ The namespace where the secret is stored. If necessary, the secret may be copied [providers](#providers) > [tlsCertificates](#providerstlscertificates) > managedBy -A reference to the TLS certificates manager used to generate the certificate. +Set to `cert-manager` to configure [cert-manager](https://github.com/jetstack/cert-manager) to manage this +certificate. See our +[cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. | Type | Required | | -------- | -------- | @@ -787,7 +789,7 @@ providers: [providers](#providers) > certManager cert-manager configuration, for creating and managing TLS certificates. See the -[Configuration Files guide](https://docs.garden.io/guides/cert-manager-integration) for details +[cert-manager guide](https://docs.garden.io/guides/cert-manager-integration) for details. | Type | Required | | -------- | -------- | @@ -797,7 +799,8 @@ cert-manager configuration, for creating and managing TLS certificates. See the [providers](#providers) > [certManager](#providerscertmanager) > install -When set to "true" Garden will install cert-manager. +Automatically install `cert-manager` on initialization. See the +[cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. | Type | Required | Default | | --------- | -------- | ------- | @@ -807,7 +810,7 @@ When set to "true" Garden will install cert-manager. [providers](#providers) > [certManager](#providerscertmanager) > email -The email which will be used for creating Let's Encrypt certificates: if your certificates are being created by Garden this field is required. +The email to use when requesting Let's Encrypt certificates. | Type | Required | | -------- | -------- | @@ -826,11 +829,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > issuer -the type of issuer for the certificate. Currently only supporting ACME Let's Encrypt issuers. +The type of issuer for the certificate (only ACME is supported for now). | Type | Required | Default | | -------- | -------- | -------- | -| `string` | Yes | `"acme"` | +| `string` | No | `"acme"` | Example: @@ -845,11 +848,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > acmeServer -If the certificate is managed by cert-manager, this allows to specify which LetsEncrypt endpoint to use to validate the certificate challenge. Defaults to "letsencrypt-staging." +Specify which ACME server to request certificates from. Currently Let's Encrypt staging and prod servers are supported. | Type | Required | Default | | -------- | -------- | ----------------------- | -| `string` | Yes | `"letsencrypt-staging"` | +| `string` | No | `"letsencrypt-staging"` | Example: @@ -864,11 +867,11 @@ providers: [providers](#providers) > [certManager](#providerscertmanager) > acmeChallengeType -The acmeChallenge used by the integration to validate hostnames and generate the certificates through Let's Encrypt. +The type of ACME challenge used to validate hostnames and generate the certificates (only HTTP-01 is supported for now). | Type | Required | Default | | -------- | -------- | ----------- | -| `string` | Yes | `"HTTP-01"` | +| `string` | No | `"HTTP-01"` | Example: diff --git a/docs/reference/template-strings.md b/docs/reference/template-strings.md index 7f17a394af..06a06e7018 100644 --- a/docs/reference/template-strings.md +++ b/docs/reference/template-strings.md @@ -25,9 +25,20 @@ The following keys are available in any template strings within project definiti `providers`): ```yaml +# Context variables that are specific to the currently running environment/machine. +# # Type: object # local: + # The absolute path to the directory where exported artifacts from test and task runs are + # stored. + # + # Type: string + # + # Example: "/home/me/my-project/.garden/artifacts" + # + artifactsPath: + # A map of all local environment variables (see # https://nodejs.org/api/process.html#process_process_env). # @@ -59,9 +70,20 @@ The following keys are available in template strings under the `providers` key in `garden.yml` project config files: ```yaml +# Context variables that are specific to the currently running environment/machine. +# # Type: object # local: + # The absolute path to the directory where exported artifacts from test and task runs are + # stored. + # + # Type: string + # + # Example: "/home/me/my-project/.garden/artifacts" + # + artifactsPath: + # A map of all local environment variables (see # https://nodejs.org/api/process.html#process_process_env). # @@ -129,9 +151,20 @@ providers: {} The following keys are available in template strings with module definitions in `garden.yml` config files: ```yaml +# Context variables that are specific to the currently running environment/machine. +# # Type: object # local: + # The absolute path to the directory where exported artifacts from test and task runs are + # stored. + # + # Type: string + # + # Example: "/home/me/my-project/.garden/artifacts" + # + artifactsPath: + # A map of all local environment variables (see # https://nodejs.org/api/process.html#process_process_env). # diff --git a/garden-service/src/plugins/kubernetes/config.ts b/garden-service/src/plugins/kubernetes/config.ts index e6436a7d31..85602f8cc0 100644 --- a/garden-service/src/plugins/kubernetes/config.ts +++ b/garden-service/src/plugins/kubernetes/config.ts @@ -266,7 +266,11 @@ const tlsCertificateSchema = joi.object().keys({ .example({ name: "my-tls-secret", namespace: "default" }), managedBy: joi .string() - .description("A reference to the TLS certificates manager used to generate the certificate.") + .description(dedent` + Set to \`cert-manager\` to configure [cert-manager](https://github.com/jetstack/cert-manager) to manage this + certificate. See our + [cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. + `) .allow("cert-manager") .example("cert-manager"), }) @@ -403,47 +407,41 @@ export const kubernetesConfigBase = providerConfigBaseSchema.keys({ .object() .optional() .keys({ - install: joi - .bool() - .default(false) - .description('When set to "true" Garden will install cert-manager.'), + install: joi.bool().default(false).description(dedent` + Automatically install \`cert-manager\` on initialization. See the + [cert-manager integration guide](https://docs.garden.io/using-garden/cert-manager-integration) for details. + `), email: joi .string() .required() - .description( - deline` - The email which will be used for creating Let's Encrypt certificates: - if your certificates are being created by Garden this field is required.` - ) + .description("The email to use when requesting Let's Encrypt certificates.") .example("yourname@example.com"), issuer: joi .string() - .required() .allow("acme") .default("acme") - .description("the type of issuer for the certificate. Currently only supporting ACME Let's Encrypt issuers.") + .description("The type of issuer for the certificate (only ACME is supported for now).") .example("acme"), acmeServer: joi .string() - .required() .allow("letsencrypt-staging", "letsencrypt-prod") .default("letsencrypt-staging") .description( - deline`If the certificate is managed by cert-manager, this allows to specify which - LetsEncrypt endpoint to use to validate the certificate challenge. Defaults to "letsencrypt-staging."` + deline`Specify which ACME server to request certificates from. Currently Let's Encrypt staging and prod + servers are supported.` ) .example("letsencrypt-staging"), acmeChallengeType: joi .string() - .required() .allow("HTTP-01") .default("HTTP-01") .description( - deline`The acmeChallenge used by the integration to validate hostnames and generate the certificates through Let's Encrypt.` + deline`The type of ACME challenge used to validate hostnames and generate the certificates + (only HTTP-01 is supported for now).` ) .example("HTTP-01"), }).description(dedent`cert-manager configuration, for creating and managing TLS certificates. See the - [Configuration Files guide](https://docs.garden.io/guides/cert-manager-integration) for details`), + [cert-manager guide](https://docs.garden.io/guides/cert-manager-integration) for details.`), _systemServices: joiArray(joiIdentifier()).meta({ internal: true }), registryProxyTolerations: joiArray( joi.object().keys({