HTTP binding spec

Detailed documentation on the HTTP binding component

Alternative

The service invocation API allows invoking non-Dapr HTTP endpoints and is the recommended approach. Read “How-To: Invoke Non-Dapr Endpoints using HTTP” for more information.

Setup Dapr component

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: bindings.http
  7.   version: v1
  8.   metadata:
  9.     - name: url
  10.       value: "http://something.com"
  11.     #- name: maxResponseBodySize
  12.     #  value: "100Mi" # OPTIONAL maximum amount of data to read from a response
  13.     #- name: MTLSRootCA
  14.     #  value: "/Users/somepath/root.pem" # OPTIONAL path to root CA or PEM-encoded string
  15.     #- name: MTLSClientCert
  16.     #  value: "/Users/somepath/client.pem" # OPTIONAL path to client cert or PEM-encoded string
  17.     #- name: MTLSClientKey
  18.     #  value: "/Users/somepath/client.key" # OPTIONAL path to client key or PEM-encoded string
  19.     #- name: MTLSRenegotiation
  20.     #  value: "RenegotiateOnceAsClient" # OPTIONAL one of: RenegotiateNever, RenegotiateOnceAsClient, RenegotiateFreelyAsClient
  21.     #- name: securityToken # OPTIONAL <token to include as a header on HTTP requests>
  22.     #  secretKeyRef:
  23.     #    name: mysecret
  24.     #    key: "mytoken"
  25.     #- name: securityTokenHeader
  26.     #  value: "Authorization: Bearer" # OPTIONAL <header name for the security token>
  27.     #- name: errorIfNot2XX
  28.     #  value: "false" # OPTIONAL

Spec metadata fields

FieldRequiredBinding supportDetailsExample
urlYOutputThe base URL of the HTTP endpoint to invokehttp://host:port/path, http://myservice:8000/customers
maxResponseBodySizeNOutputMaximum length of the response to read. A whole number is interpreted as bytes; units such as Ki, Mi, Gi (SI) or `kM
MTLSRootCANOutputPath to root CA certificate or PEM-encoded string
MTLSClientCertNOutputPath to client certificate or PEM-encoded string
MTLSClientKeyNOutputPath client private key or PEM-encoded string
MTLSRenegotiationNOutputType of mTLS renegotiation to be usedRenegotiateOnceAsClient
securityTokenNOutputThe value of a token to be added to a HTTP request as a header. Used together with securityTokenHeader
securityTokenHeaderNOutputThe name of the header for securityToken on a HTTP request
errorIfNot2XXNOutputIf a binding error should be thrown when the response is not in the 2xx range. Defaults to true

The values for MTLSRootCA, MTLSClientCert and MTLSClientKey can be provided in three ways:

  • Secret store reference:

    1. apiVersion: dapr.io/v1alpha1
    2. kind: Component
    3. metadata:
    4.   name: <NAME>
    5. spec:
    6.   type: bindings.http
    7.   version: v1
    8.   metadata:
    9.   - name: url
    10.     value: http://something.com
    11.   - name: MTLSRootCA
    12.     secretKeyRef:
    13.       name: mysecret
    14.       key: myrootca
    15. auth:
    16.   secretStore: <NAME_OF_SECRET_STORE_COMPONENT>

  • 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.

Note

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 for more details. You can also provide only MTLSRootCA, to enable HTTPS connection with a certificate signed by a custom CA. See HTTPS section for more details.

Binding support

This component supports output binding with the following HTTP methods/verbs:

  • create : For backward compatibility and treated like a post
  • get : Read data/records
  • head : Identical to get except that the server does not return a response body
  • post : Typically used to create records or send commands
  • put : Update data/records
  • patch : Sometimes used to update a subset of fields of a record
  • delete : Delete a data/record
  • options : Requests for information about the communication options available (not commonly used)
  • trace : Used to invoke a remote, application-layer loop- back of the request message (not commonly used)

Request

Operation metadata fields

All of the operations above support the following metadata fields

FieldRequiredDetailsExample
pathNThe path to append to the base URL. Used for accessing specific URIs.“/1234”, “/search?lastName=Jones”
Field with a capitalized first letterNAny fields that have a capital first letter are sent as request headers“Content-Type”, “Accept”

Retrieving data

To retrieve data from the HTTP endpoint, invoke the HTTP binding with a GET method and the following JSON body:

  1. {
  2.   "operation": "get"
  3. }

Optionally, a path can be specified to interact with resource URIs:

  1. {
  2.   "operation": "get",
  3.   "metadata": {
  4.     "path": "/things/1234"
  5.   }
  6. }

Response

The response body contains the data returned by the HTTP endpoint. The data field contains the HTTP response body as a byte slice (Base64 encoded via curl). The metadata field contains:

FieldRequiredDetailsExample
statusCodeYThe HTTP status code200, 404, 503
statusYThe status description“200 OK”, “201 Created”
Field with a capitalized first letterNAny fields that have a capital first letter are sent as request headers“Content-Type”

Example

Requesting the base URL

  1. curl -d "{ \"operation\": \"get\" }" \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "get" }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Requesting a specific path

  1. curl -d "{ \"operation\": \"get\", \"metadata\": { \"path\": \"/things/1234\" } }" \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "get", "metadata": { "path": "/things/1234" } }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Sending and updating data

To send data to the HTTP endpoint, invoke the HTTP binding with a POST, PUT, or PATCH method and the following JSON body:

Note

Any metadata field that starts with a capital letter is passed as a request header. For example, the default content type is application/json; charset=utf-8. This can be overridden be setting the Content-Type metadata field.

  1. {
  2.   "operation": "post",
  3.   "data": "content (default is JSON)",
  4.   "metadata": {
  5.     "path": "/things",
  6.     "Content-Type": "application/json; charset=utf-8"
  7.   }
  8. }

Example

Posting a new record

  1. curl -d "{ \"operation\": \"post\", \"data\": \"YOUR_BASE_64_CONTENT\", \"metadata\": { \"path\": \"/things\" } }" \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "post", "data": "YOUR_BASE_64_CONTENT", "metadata": { "path": "/things" } }' \
  2.       http://localhost:<dapr-port>/v1.0/bindings/<binding-name>

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 URL to use https instead of http.
  2. If you need to add a custom TLS certificate, refer How-To: Install certificates in the Dapr sidecar, to install the TLS certificates in the sidecar.

Example

Update the binding component

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5.   namespace: <NAMESPACE>
  6. spec:
  7.   type: bindings.http
  8.   version: v1
  9.   metadata:
  10.   - name: url
  11.     value: https://my-secured-website.com # Use HTTPS

Install the TLS certificate in the sidecar

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.

  1. version: '3'
  2. services:
  3.   my-app:
  4.     # ...
  5.   dapr-sidecar:
  6.     image: "daprio/daprd:1.8.0"
  7.     command: [
  8.       "./daprd",
  9.      "-app-id", "myapp",
  10.      "-app-port", "3000",
  11.      ]
  12.     volumes:
  13.         - "./components/:/components"
  14.         - "/tmp/ssl/:/certificates" # Mount the certificates folder to the sidecar container at /certificates
  15.     environment:
  16.       - "SSL_CERT_DIR=/certificates" # Set the environment variable to the path of the certificates folder
  17.     depends_on:
  18.       - my-app

The sidecar can read the TLS certificate from a variety of sources. See How-to: Mount Pod volumes to the Dapr sidecar for more. In this example, we store the TLS certificate as a Kubernetes secret.

  1. kubectl create secret generic myapp-cert --from-file /tmp/ssl/cert.pem

The YAML below is an example of the Kubernetes deployment that mounts the above secret to the sidecar and sets SSL_CERT_DIR to install the certificates.

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: myapp
  5.   namespace: default
  6.   labels:
  7.     app: myapp
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     matchLabels:
  12.       app: myapp
  13.   template:
  14.     metadata:
  15.       labels:
  16.         app: myapp
  17.       annotations:
  18.         dapr.io/enabled: "true"
  19.         dapr.io/app-id: "myapp"
  20.         dapr.io/app-port: "8000"
  21.         dapr.io/volume-mounts: "cert-vol:/certificates" # Mount the certificates folder to the sidecar container at /certificates
  22.         dapr.io/env: "SSL_CERT_DIR=/certificates" # Set the environment variable to the path of the certificates folder
  23.     spec:
  24.       volumes:
  25.         - name: cert-vol
  26.           secret:
  27.             secretName: myapp-cert
  28. ...

Invoke the binding securely

  1. curl -d "{ \"operation\": \"get\" }" \
  2.       https://localhost:<dapr-port>/v1.0/bindings/<binding-name>
  1. curl -d '{ "operation": "get" }' \
  2.       https://localhost:<dapr-port>/v1.0/bindings/<binding-name>

Note

HTTPS binding support can also be configured using the MTLSRootCA metadata option. This will add the specified certificate to the list of trusted certificates for the binding. There’s no specific preference for either method. While the MTLSRootCA option is easy to use and doesn’t require any changes to the sidecar, it accepts only one certificate. If you need to trust multiple certificates, you need to install them in the sidecar by following the steps above.

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.

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 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.

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
  • RenegotiateOnceAsClient
  • RenegotiateFreelyAsClient

For more details see the Go RenegotiationSupport documentation.

You can use this when the server with which the HTTP binding is configured to communicate requires mTLS or client TLS authentication.

Last modified March 21, 2024: Merge pull request #4082 from newbe36524/v1.13 (f4b0938)