diff --git a/daprdocs/content/en/operations/configuration/install-certificates.md b/daprdocs/content/en/operations/configuration/install-certificates.md new file mode 100644 index 000000000..302565f7f --- /dev/null +++ b/daprdocs/content/en/operations/configuration/install-certificates.md @@ -0,0 +1,97 @@ +--- +type: docs +title: "How-To: Install certificates in the Dapr sidecar" +linkTitle: "install certificates" +weight: 6500 +description: "Configure the Dapr sidecar container to trust certificates" +--- + +The Dapr sidecar can be configured to trust certificates for communicating with external services. This is useful in scenarios where a self-signed certificate needs to be trusted. For example, using an HTTP binding or configuring an outbound proxy for the sidecar. Both certificate authority (CA) certificates and leaf certificates are supported. + +{{< tabs Self-hosted Kubernetes >}} + +{{% codetab %}} + +When the sidecar is not running inside a container, certificates must be directly installed on the host operating system. + +When the sidecar is running as a container: +1. Certificates must be available to the sidecar container. This can be configured using volume mounts. +1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates. +1. For Windows containers, the container needs to run with administrator privileges to be able to install the certificates. + +Below is an example that uses Docker Compose to install certificates (present locally in the `./certificates` directory) in the sidecar container: +```yaml +version: '3' +services: + dapr-sidecar: + image: "daprio/daprd:edge" # dapr version must be at least v1.8 + command: [ + "./daprd", + "-app-id", "myapp", + "-app-port", "3000", + ] + volumes: + - "./components/:/components" + - "./certificates:/certificates" # (STEP 1) Mount the certificates folder to the sidecar container + environment: + - "SSL_CERT_DIR=/certificates" # (STEP 2) Set the environment variable to the path of the certificates folder + # Uncomment the line below for Windows containers + # user: ContainerAdministrator +``` + +{{% /codetab %}} + + +{{% codetab %}} + +On Kubernetes: +1. Certificates must be available to the sidecar container using a volume mount. +1. The environment variable `SSL_CERT_DIR` must be set in the sidecar container, pointing to the directory containing the certificates. + +The YAML below is an example of a deployment that attaches a pod volume to the sidecar, and sets `SSL_CERT_DIR` to install the certificates. +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: myapp + namespace: default + labels: + app: myapp +spec: + replicas: 1 + selector: + matchLabels: + app: myapp + template: + metadata: + labels: + app: myapp + annotations: + dapr.io/enabled: "true" + dapr.io/app-id: "myapp" + dapr.io/app-port: "8000" + dapr.io/volume-mounts: "certificates-vol:/tmp/certificates" # (STEP 1) Mount the certificates folder to the sidecar container + dapr.io/env: "SSL_CERT_DIR=/tmp/certificates" # (STEP 2) Set the environment variable to the path of the certificates folder + spec: + volumes: + - name: certificates-vol + hostPath: + path: /certificates +... +``` + +{{% alert title="Note" color="primary" %}} +When using Windows containers, the sidecar container is started with admin privileges, which is required to install the certificates. This does not apply to Linux containers. +{{% /alert %}} + +Note, all the certificates in the directory pointed by `SSL_CERT_DIR` are installed. +1. On Linux containers, all the certificate extensions supported by OpenSSL are supported. For more information, see https://www.openssl.org/docs/man1.1.1/man1/openssl-rehash.html +1. On Windows container, all the certificate extensions supported by certoc.exe are supported. For more information, see certoc.exe present in [Windows Server Core](https://hub.docker.com/_/microsoft-windows-servercore) + +{{% /codetab %}} + +{{< /tabs >}} + +## Related links +- [(Kubernetes) How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts.md >}}) +- [Dapr Kubernetes pod annotations spec]({{< ref arguments-annotations-overview.md >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/http.md b/daprdocs/content/en/reference/components-reference/supported-bindings/http.md index f1d32550f..dea2e468c 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/http.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/http.md @@ -169,6 +169,14 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p {{< /tabs >}} +## Using HTTPS + +The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server's SSL certificate. + +1. Update the binding component's YAML to use `https` instead of `http` +1. Refer [How-To: Install certificates in the Dapr sidecar]({{ ref install-certificates }}), to install the SSL certificate in the sidecar. + + ## Related links - [Basic schema for a Dapr component]({{< ref component-schema >}}) @@ -176,3 +184,4 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p - [How-To: Trigger application with input binding]({{< ref howto-triggers.md >}}) - [How-To: Use bindings to interface with external resources]({{< ref howto-bindings.md >}}) - [Bindings API reference]({{< ref bindings_api.md >}}) +- [How-To: Install certificates in the Dapr sidecar]({{ ref install-certificates }}) diff --git a/daprdocs/content/en/reference/environment/_index.md b/daprdocs/content/en/reference/environment/_index.md index 8e88cdc44..2ddbc480f 100644 --- a/daprdocs/content/en/reference/environment/_index.md +++ b/daprdocs/content/en/reference/environment/_index.md @@ -20,3 +20,4 @@ The following table lists the environment variables used by the Dapr runtime, CL | DAPR_API_TOKEN | Dapr sidecar | The token used for Dapr API authentication for requests from the application. [Enable API token authentication in Dapr]({{< ref api-token >}}). | | NAMESPACE | Dapr sidecar | Used to specify a component's [namespace in self-hosted mode]({{< ref component-scopes >}}). | | DAPR_DEFAULT_IMAGE_REGISTRY | Dapr CLI | In self-hosted mode, it is used to specify the default container registry to pull images from. When its value is set to `GHCR` or `ghcr`, it pulls the required images from Github container registry. To default to Docker hub, unset this environment variable. | +| SSL_CERT_DIR | Dapr sidecar | Specifies the location where the public certificates for all the trusted certificate authorities (CA) are located. Not applicable when the sidecar is running as a process in self-hosted mode.