dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs for HTTP binding 

Fixes #3664

Signed-off-by: ItalyPaleAle <43508+ItalyPaleAle@users.noreply.github.com>
This commit is contained in:
ItalyPaleAle 2023-10-11 12:32:16 -07:00
parent 6d1e6c4f96
commit f9d5a1b89b
1 changed files with 76 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
daprdocs/content/en/reference/components-reference/supported-bindings/http.md
View File

@ -9,7 +9,7 @@ aliases:
## Alternative ## Alternative
The [service invocation API]({{< ref service_invocation_api.md >}}) allows for the invocation of non-Dapr HTTP endpoints and is the recommended approach. Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. The [service invocation API]({{< ref service_invocation_api.md >}}) allows invoking non-Dapr HTTP endpoints and is the recommended approach. Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information.
## Setup Dapr component ## Setup Dapr component
@ -22,66 +22,70 @@ spec:
type: bindings.http type: bindings.http
version: v1 version: v1
metadata: metadata:
- name: url - name: url
value: "http://something.com" value: "http://something.com"
- name: MTLSRootCA #- name: maxResponseBodySize
value: "/Users/somepath/root.pem" # OPTIONAL Secret store ref, <path to root CA>, or <pem encoded string> # value: "100Mi" # OPTIONAL maximum amount of data to read from a response
- name: MTLSClientCert #- name: MTLSRootCA
value: "/Users/somepath/client.pem" # OPTIONAL Secret store ref, <path to client cert>, or <pem encoded string> # value: "/Users/somepath/root.pem" # OPTIONAL path to root CA or PEM-encoded string
- name: MTLSClientKey #- name: MTLSClientCert
value: "/Users/somepath/client.key" # OPTIONAL Secret store ref, <path to client key>, or <pem encoded string> # value: "/Users/somepath/client.pem" # OPTIONAL path to client cert or PEM-encoded string
- name: MTLSRenegotiation #- name: MTLSClientKey
value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient # value: "/Users/somepath/client.key" # OPTIONAL path to client key or PEM-encoded string
- name: securityToken # OPTIONAL <token to include as a header on HTTP requests> #- name: MTLSRenegotiation
secretKeyRef: # value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
name: mysecret #- name: securityToken # OPTIONAL <token to include as a header on HTTP requests>
key: "mytoken" # secretKeyRef:
- name: securityTokenHeader # name: mysecret
value: "Authorization: Bearer" # OPTIONAL <header name for the security token> # key: "mytoken"
- name: direction #- name: securityTokenHeader
value: "output" # value: "Authorization: Bearer" # OPTIONAL <header name for the security token>
``` ```
## Spec metadata fields ## Spec metadata fields
| Field | Required | Binding support | Details | Example | | Field | Required | Binding support | Details | Example |
|--------------------|:--------:|--------|--------|---------| |--------------------|:--------:|--------|--------|---------|
| `url` | Y | Output |The base URL of the HTTP endpoint to invoke | `http://host:port/path`, `http://myservice:8000/customers` | `url` | Y | Output | The base URL of the HTTP endpoint to invoke | `http://host:port/path`, `http://myservice:8000/customers` |
| `MTLSRootCA` | N | Output |Secret store reference, path to root ca certificate, or pem encoded string | | `maxResponseBodySize`| N | Output | Maximum length of the response to read. A whole number is interpreted as bytes; units such as `Ki, Mi, Gi` (SI) or `k | M | G` (decimal) can be added for convenience. The default value is `100Mi` | "1Gi", "100Mi", "20Ki", "200" (bytes) |
| `MTLSClientCert` | N | Output |Secret store reference, path to client certificate, or pem encoded string | | `MTLSRootCA` | N | Output | Path to root CA certificate or PEM-encoded string |
| `MTLSClientKey` | N | Output |Secret store reference, path client private key, or pem encoded string | | `MTLSClientCert` | N | Output | Path to client certificate or PEM-encoded string |
| `MTLSRenegotiation` | N | Output |Type of TLS renegotiation to be used | `RenegotiateOnceAsClient` | `MTLSClientKey` | N | Output | Path client private key or PEM-encoded string |
| `securityToken` | N | Output |The value of a token to be added to an HTTP request as a header. Used together with `securityTokenHeader` | | `MTLSRenegotiation` | N | Output | Type of mTLS renegotiation to be used | `RenegotiateOnceAsClient`
| `securityTokenHeader`| N | Output |The name of the header for `securityToken` on an HTTP request that | | `securityToken` | N | Output | The value of a token to be added to a HTTP request as a header. Used together with `securityTokenHeader` |
| `direction`| N | Output |The direction of the binding | `"output"` | `securityTokenHeader` | N | Output | The name of the header for `securityToken` on a HTTP request |
### How to configure mTLS-related fields in metadata
### How to configure MTLS related fields in Metadata
The values for **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** can be provided in three ways: The values for **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** can be provided in three ways:
1. Secret store reference
```yaml - Secret store reference:
apiVersion: dapr.io/v1alpha1
kind: Component ```yaml
metadata: apiVersion: dapr.io/v1alpha1
name: <NAME> kind: Component
spec: metadata:
type: bindings.http name: <NAME>
version: v1 spec:
metadata: type: bindings.http
- name: url version: v1
value: http://something.com metadata:
- name: MTLSRootCA - name: url
secretKeyRef: value: http://something.com
name: mysecret - name: MTLSRootCA
key: myrootca secretKeyRef:
auth: name: mysecret
secretStore: <NAME_OF_SECRET_STORE_COMPONENT> key: myrootca
``` auth:
2. Path to the file: The absolute path to the file can be provided as a value for the field. secretStore: <NAME_OF_SECRET_STORE_COMPONENT>
3. PEM encoded string: The PEM encoded string can also be provided as a value for the field. ```
- Path to the file: the absolute path to the file can be provided as a value for the field.
- PEM encoded string: the PEM-encoded string can also be provided as a value for the field.
{{% alert title="Note" color="primary" %}} {{% alert title="Note" color="primary" %}}
Metadata fields **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** are used to configure TLS(m) authentication. Metadata fields **MTLSRootCA**, **MTLSClientCert** and **MTLSClientKey** are used to configure (m)TLS authentication.
To use mTLS authentication, you must provide all three fields. See [mTLS]({{< ref "#using-mtls-or-enabling-client-tls-authentication-along-with-https" >}}) for more details. You can also provide only **MTLSRootCA**, to enable **HTTPS** connection. See [HTTPS]({{< ref "#install-the-ssl-certificate-in-the-sidecar" >}}) section for more details. To use mTLS authentication, you must provide all three fields. See [mTLS]({{< ref "#using-mtls-or-enabling-client-tls-authentication-along-with-https" >}}) for more details. You can also provide only **MTLSRootCA**, to enable **HTTPS** connection with a certificate signed by a custom CA. See [HTTPS]({{< ref "#install-the-ssl-certificate-in-the-sidecar" >}}) section for more details.
{{% /alert %}} {{% /alert %}}
@ -107,8 +111,8 @@ All of the operations above support the following metadata fields
| Field | Required | Details | Example | | Field | Required | Details | Example |
|--------------------|:--------:|---------|---------| |--------------------|:--------:|---------|---------|
| path | N | The path to append to the base URL. Used for accessing specific URIs | `"/1234"`, `"/search?lastName=Jones"` | `path` | N | The path to append to the base URL. Used for accessing specific URIs. | `"/1234"`, `"/search?lastName=Jones"`
| Headers* | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`, `"Accept"` | Field with a capitalized first letter | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"`, `"Accept"`
#### Retrieving data #### Retrieving data
@ -137,9 +141,9 @@ The response body contains the data returned by the HTTP endpoint. The `data` f
| Field | Required | Details | Example | | Field | Required | Details | Example |
|--------------------|:--------:|---------|---------| |--------------------|:--------:|---------|---------|
| statusCode | Y | The [HTTP status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) | `200`, `404`, `503` | `statusCode` | Y | The [HTTP status code](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) | `200`, `404`, `503` |
| status | Y | The status description | `"200 OK"`, `"201 Created"` | `status` | Y | The status description | `"200 OK"`, `"201 Created"` |
| Headers* | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"` | Field with a capitalized first letter | N | Any fields that have a capital first letter are sent as request headers | `"Content-Type"` |
#### Example #### Example
@ -168,14 +172,14 @@ curl -d '{ "operation": "get" }' \
{{< tabs Windows Linux >}} {{< tabs Windows Linux >}}
{{% codetab %}} {{% codetab %}}
```bash ```sh
curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \ curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name> http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
``` ```
{{% /codetab %}} {{% /codetab %}}
{{% codetab %}} {{% codetab %}}
```bash ```sh
curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \ curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name> http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
``` ```
@ -210,14 +214,14 @@ For example, the default content type is `application/json; charset=utf-8`. This
{{< tabs Windows Linux >}} {{< tabs Windows Linux >}}
{{% codetab %}} {{% codetab %}}
```bash ```sh
curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \ curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name> http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
``` ```
{{% /codetab %}} {{% /codetab %}}
{{% codetab %}} {{% codetab %}}
```bash ```sh
curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
http://localhost:<dapr-port>/v1.0/bindings/<binding-name> http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
``` ```
@ -229,9 +233,8 @@ curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "p
The HTTP binding can also be used with HTTPS endpoints by configuring the Dapr sidecar to trust the server's SSL certificate. 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 URL to use `https` instead of `http`. 1. Update the binding URL 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. 1. If you need to add a custom TLS certificate, refer [How-To: Install certificates in the Dapr sidecar]({{< ref install-certificates >}}), to install the TLS certificates in the sidecar.
### Example ### Example
@ -251,13 +254,12 @@ spec:
value: https://my-secured-website.com # Use HTTPS value: https://my-secured-website.com # Use HTTPS
``` ```
#### Install the SSL certificate in the sidecar #### Install the TLS certificate in the sidecar
{{< tabs Self-Hosted Kubernetes >}} {{< tabs Self-Hosted Kubernetes >}}
{{% codetab %}} {{% codetab %}}
When the sidecar is not running inside a container, the SSL certificate can be directly installed on the host operating system. When the sidecar is not running inside a container, the TLS certificate can be directly installed on the host operating system.
Below is an example when the sidecar is running as a container. The SSL certificate is located on the host computer at `/tmp/ssl/cert.pem`. Below is an example when the sidecar is running as a container. The SSL certificate is located on the host computer at `/tmp/ssl/cert.pem`.
@ -286,7 +288,7 @@ services:
{{% codetab %}} {{% codetab %}}
The sidecar can read the SSL certificate from a variety of sources. See [How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts >}}) for more. In this example, we store the SSL certificate as a Kubernetes secret. The sidecar can read the TLS certificate from a variety of sources. See [How-to: Mount Pod volumes to the Dapr sidecar]({{< ref kubernetes-volume-mounts >}}) for more. In this example, we store the TLS certificate as a Kubernetes secret.
```bash ```bash
kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem
@ -354,24 +356,26 @@ HTTPS binding support can also be configured using the **MTLSRootCA** metadata o
{{% /alert %}} {{% /alert %}}
## Using mTLS or enabling client TLS authentication along with HTTPS ## Using mTLS or enabling client TLS authentication along with HTTPS
You can configure the HTTP binding to use mTLS or client TLS authentication along with HTTPS by providing the `MTLSRootCA`, `MTLSClientCert`, and `MTLSClientKey` metadata fields in the binding component. You can configure the HTTP binding to use mTLS or client TLS authentication along with HTTPS by providing the `MTLSRootCA`, `MTLSClientCert`, and `MTLSClientKey` metadata fields in the binding component.
These fields can be passed as a file path or as a pem encoded string. These fields can be passed as a file path or as a pem encoded string:
- If the file path is provided, the file is read and the contents are used. - If the file path is provided, the file is read and the contents are used.
- If the pem encoded string is provided, the string is used as is. - If the PEM-encoded string is provided, the string is used as is.
When these fields are configured, the Dapr sidecar uses the provided certificate to authenticate itself with the server during the TLS handshake process. When these fields are configured, the Dapr sidecar uses the provided certificate to authenticate itself with the server during the TLS handshake process.
If the remote server is enforcing TLS renegotiation, you also need to set the metadata field `MTLSRenegotiation`. This field accepts one of following options: If the remote server is enforcing TLS renegotiation, you also need to set the metadata field `MTLSRenegotiation`. This field accepts one of following options:
- `RenegotiateNever` - `RenegotiateNever`
- `RenegotiateOnceAsClient` - `RenegotiateOnceAsClient`
- `RenegotiateFreelyAsClient`. - `RenegotiateFreelyAsClient`
For more details see [the Go `RenegotiationSupport` documentation](https://pkg.go.dev/crypto/tls#RenegotiationSupport). For more details see [the Go `RenegotiationSupport` documentation](https://pkg.go.dev/crypto/tls#RenegotiationSupport).
### When to use:
You can use this when the server with which the HTTP binding is configured to communicate requires mTLS or client TLS authentication. You can use this when the server with which the HTTP binding is configured to communicate requires mTLS or client TLS authentication.
## Related links ## Related links
- [Basic schema for a Dapr component]({{< ref component-schema >}}) - [Basic schema for a Dapr component]({{< ref component-schema >}})