feat(k8s): cert-manager integration (#1261)

docs/README.md

@@ -22,6 +22,7 @@
   * [Remote Sources](./guides/using-remote-sources.md)
   * [Terraform](./guides/terraform.md)
   * [Variables and templating](./guides/variables-and-templating.md)
+  * [cert-manager Integration](./guides/cert-manager-integration.md)
 * [Example Projects](./examples/README.md)
   * [Demo Project](./examples/demo-project.md)
   * [TLS Project](./examples/tls-project.md)

docs/guides/cert-manager-integration.md

@@ -0,0 +1,124 @@
+# cert-manager Integration
+
+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).
+
+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.
+
+## Requirements
+
+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.
+
+## Limitations
+
+cert-manager is currently under development. Currently we only support cert-manager v0.11.0, which requires Kubernetes v1.11 or higher.
+
+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).
+
+The integration currently only supports Let's Encrypt and HTTP-01 challenges. We also only support cert-manager ClusterIssuers and not namespace Issuers.
+
+> 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.
+
+## Usage
+
+### Enabling and configuring cert-manager
+
+To enable cert-manager, you'll need to configure it in the `kubernetes` provider configuration in your project `garden.yml` file:
+
+```yaml
+    kind: Project
+    name: cert-manager-example
+    environments:
+    - name: remote-dev
+      providers:
+      - name: kubernetes
+        context: your-remote-k8s-cluster-context
+        setupIngressController: nginx
+        ...
+        certManager:
+          install: true  # let garden install cert-manager
+          email: [email protected]  # 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 then install cert-manager for you under 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 for Let's Encrypt certificate requests.
+
+### Issuing your first certificate
+
+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).
+
+#### Example
+
+When you set `managedBy: cert-manager` on a certificate specified in the `tlsCertificates` field, Garden creates a corresponding Certificate resource:
+
+```yaml
+    kind: Project
+    name: cert-manager-example
+    environments:
+    - name: remote-dev
+      providers:
+      - name: kubernetes
+        context: your-remote-k8s-cluster-context
+        ...
+        certManager:
+          install: true
+          email: [email protected]
+          issuer: acme
+          acmeChallengeType: HTTP-01
+          acmeServer: letsencrypt-staging
+        tlsCertificates:
+          - name: example-certificate-staging-01
+            managedBy: cert-manager  # allow cert-manager to manage this certificate
+            hostnames:
+              - your-domain-name.com # the domain name(s) to be covered by the certificate
+            secretRef:
+              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. 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.
+
+For advanced configuration, please take a look at the official [cert-manager documentation](https://docs.cert-manager.io/en/latest/tasks/index.html).
+
+## Troubleshooting
+
+### The certificate creation timeouts and garden terminates
+
+> 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`.
+
+You can list all the `Certificate` resources with:
+
+```sh
+$: kubectl get Certificates -n your-namespace
+```
+
+and you can describe the failing Certificate with:
+
+```sh
+$: 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, 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/).

docs/reference/providers/kubernetes.md

@@ -764,6 +764,124 @@ The namespace where the secret is stored. If necessary, the secret may be copied
 | -------- | -------- | ----------- |
 | `string` | No       | `"default"` |
 
+### `providers[].tlsCertificates[].managedBy`
+
+[providers](#providers) > [tlsCertificates](#providerstlscertificates) > managedBy
+
+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 |
+| -------- | -------- |
+| `string` | No       |
+
+Example:
+
+```yaml
+providers:
+  - tlsCertificates:
+      - managedBy: "cert-manager"
+```
+
+### `providers[].certManager`
+
+[providers](#providers) > certManager
+
+cert-manager configuration, for creating and managing TLS certificates. See the
+[cert-manager guide](https://docs.garden.io/guides/cert-manager-integration) for details.
+
+| Type     | Required |
+| -------- | -------- |
+| `object` | No       |
+
+### `providers[].certManager.install`
+
+[providers](#providers) > [certManager](#providerscertmanager) > install
+
+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 |
+| --------- | -------- | ------- |
+| `boolean` | No       | `false` |
+
+### `providers[].certManager.email`
+
+[providers](#providers) > [certManager](#providerscertmanager) > email
+
+The email to use when requesting Let's Encrypt certificates.
+
+| Type     | Required |
+| -------- | -------- |
+| `string` | Yes      |
+
+Example:
+
+```yaml
+providers:
+  - certManager:
+      ...
+      email: "[email protected]"
+```
+
+### `providers[].certManager.issuer`
+
+[providers](#providers) > [certManager](#providerscertmanager) > issuer
+
+The type of issuer for the certificate (only ACME is supported for now).
+
+| Type     | Required | Default  |
+| -------- | -------- | -------- |
+| `string` | No       | `"acme"` |
+
+Example:
+
+```yaml
+providers:
+  - certManager:
+      ...
+      issuer: "acme"
+```
+
+### `providers[].certManager.acmeServer`
+
+[providers](#providers) > [certManager](#providerscertmanager) > acmeServer
+
+Specify which ACME server to request certificates from. Currently Let's Encrypt staging and prod servers are supported.
+
+| Type     | Required | Default                 |
+| -------- | -------- | ----------------------- |
+| `string` | No       | `"letsencrypt-staging"` |
+
+Example:
+
+```yaml
+providers:
+  - certManager:
+      ...
+      acmeServer: "letsencrypt-staging"
+```
+
+### `providers[].certManager.acmeChallengeType`
+
+[providers](#providers) > [certManager](#providerscertmanager) > acmeChallengeType
+
+The type of ACME challenge used to validate hostnames and generate the certificates (only HTTP-01 is supported for now).
+
+| Type     | Required | Default     |
+| -------- | -------- | ----------- |
+| `string` | No       | `"HTTP-01"` |
+
+Example:
+
+```yaml
+providers:
+  - certManager:
+      ...
+      acmeChallengeType: "HTTP-01"
+```
+
 ### `providers[].registryProxyTolerations[]`
 
 [providers](#providers) > registryProxyTolerations
@@ -1045,6 +1163,13 @@ providers:
         secretRef:
           name:
           namespace: default
+        managedBy:
+    certManager:
+      install: false
+      email:
+      issuer: acme
+      acmeServer: letsencrypt-staging
+      acmeChallengeType: HTTP-01
     registryProxyTolerations:
       - effect:
         key: