diff --git a/daprdocs/content/en/concepts/terminology.md b/daprdocs/content/en/concepts/terminology.md index a9bd4f54e..80d5c89d7 100644 --- a/daprdocs/content/en/concepts/terminology.md +++ b/daprdocs/content/en/concepts/terminology.md @@ -16,6 +16,7 @@ This page details all of the common terms you may come across in the Dapr docs. | Configuration | A YAML file declaring all of the settings for Dapr sidecars or the Dapr control plane. This is where you can configure control plane mTLS settings, or the tracing and middleware settings for an application instance. | [Dapr configuration]({{< ref configuration-concept.md >}}) | Dapr | Distributed Application Runtime. | [Dapr overview]({{< ref overview.md >}}) | Dapr control plane | A collection of services that are part of a Dapr installation on a hosting platform such as a Kubernetes cluster. This allows Dapr-enabled applications to run on the platform and handles Dapr capabilities such as actor placement, Dapr sidecar injection, or certificate issuance/rollover. | [Self-hosted overview]({{< ref self-hosted-overview >}})
[Kubernetes overview]({{< ref kubernetes-overview >}}) +| HTTPEndpoint | HTTPEndpoint is a Dapr resource use to identify non-Dapr endpoints to invoke via the service invocation API. | [Service invocation API]({{< ref service_invocation_api.md >}}) | Self-hosted | Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides the capability to run on machines in "self-hosted" mode. | [Self-hosted mode]({{< ref self-hosted-overview.md >}}) | Service | A running application or binary. This can refer to your application or to a Dapr application. | Sidecar | A program that runs alongside your application as a separate process or container. | [Sidecar pattern](https://docs.microsoft.com/azure/architecture/patterns/sidecar) diff --git a/daprdocs/content/en/developing-applications/building-blocks/bindings/bindings-overview.md b/daprdocs/content/en/developing-applications/building-blocks/bindings/bindings-overview.md index ccc1007d2..e98b5440e 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/bindings/bindings-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/bindings/bindings-overview.md @@ -24,6 +24,10 @@ For example, with bindings, your microservice can respond to incoming Twilio/SMS Bindings are developed independently of Dapr runtime. You can [view and contribute to the bindings](https://github.com/dapr/components-contrib/tree/master/bindings). {{% /alert %}} +{{% alert title="Note" color="primary" %}} +If you are using the HTTP Binding, then it is preferable to use [service invocation]({{< ref service_invocation_api.md >}}) instead. Read [How-To: Invoke Non-Dapr Endpoints using HTTP]({{< ref "howto-invoke-non-dapr-endpoints.md" >}}) for more information. +{{% /alert %}} + ## Input bindings With input bindings, you can trigger your application when an event from an external resource occurs. An optional payload and metadata may be sent with the request. diff --git a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md index a73fc8630..7a2610354 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md +++ b/daprdocs/content/en/developing-applications/building-blocks/bindings/howto-bindings.md @@ -6,6 +6,7 @@ description: "Invoke external systems with output bindings" weight: 300 --- + With output bindings, you can invoke external resources. An optional payload and metadata can be sent with the invocation request. Diagram showing bindings of example service diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md new file mode 100644 index 000000000..8196bd0b1 --- /dev/null +++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/howto-invoke-non-dapr-endpoints.md @@ -0,0 +1,92 @@ +--- +type: docs +title: "How-To: Invoke Non-Dapr Endpoints using HTTP" +linkTitle: "How-To: Invoke Non-Dapr Endpoints" +description: "Call Non-Dapr endpoints from Dapr applications using service invocation" +weight: 2000 +--- + +This article demonstrates how to call a non-Dapr endpoint using Dapr over HTTP. + +Using Dapr's service invocation API, you can communicate with endpoints that either use or do not use Dapr. Using Dapr to call endpoints that do not use Dapr not only provides a consistent API, but also the following [Dapr service invocation]({{< ref service-invocation-overview.md >}}) benefits: + +- Ability to apply resiliency policies +- Call observability with tracing & metrics +- Security access control through scoping +- Ability to utilize middleware pipeline components +- Service discovery +- Authentication through the use of headers + +## HTTP service invocation to external services or non-Dapr endpoints +Sometimes you need to call a non-Dapr HTTP endpoint. For example: +- You may choose to only use Dapr in part of your overall application, including brownfield development +- You may not have access to the code to migrate an existing application to use Dapr +- You need to call an external HTTP service. + +By defining an `HTTPEndpoint` resource, you declaratively define a way to interact with a non-Dapr endpoint. You then use the service invocation URL to invoke non-Dapr endpoints. Alternatively, you can place a non-Dapr Fully Qualified Domain Name (FQDN) endpoint URL directly into the service invocation URL. + +### Order of precedence between HttpEndpoint, FQDN URL, and appId +When using service invocation, the Dapr runtime follows a precedence order: + +1. Is this a named `HTTPEndpoint` resource? +2. Is this an FQDN URL with an`http://` or `https://` prefix? +3. Is this an `appID`? + +## Service invocation and non-Dapr HTTP endpoint +The diagram below is an overview of how Dapr's service invocation works when invoking non-Dapr endpoints. + +Diagram showing the steps of service invocation to non-Dapr endpoints + +1. Service A makes an HTTP call targeting Service B, a non-Dapr endpoint. The call goes to the local Dapr sidecar. +2. Dapr discovers Service B's location using the `HTTPEndpoint` or FQDN URL. +3. Dapr forwards the message to Service B. +4. Service B runs its business logic code. +5. Service B sends a response to Service A's Dapr sidecar. +6. Service A receives the response. + +## Using an HTTPEndpoint resource or FQDN URL for non-Dapr endpoints +There are two ways to invoke a non-Dapr endpoint when communicating either to Dapr applications or non-Dapr applications. A Dapr application can invoke a non-Dapr endpoint by providing one of the following: + +- A named `HTTPEndpoint` resource, including defining an `HTTPEndpoint` resource type. See the [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}}) guide for an example. + + ```sh + localhost:3500/v1.0/invoke//method/ + ``` + + For example, with an `HTTPEndpoint` resource called "palpatine" and a method called "Order66", this would be: + ```sh + curl http://localhost:3500/v1.0/invoke/palpatine/method/order66 + ``` + +- A FQDN URL to the non-Dapr endpoint. + + ```sh + localhost:3500/v1.0/invoke//method/ + ``` + + For example, with an FQDN resource called `https://darthsidious.starwars`, this would be: + ```sh + curl http://localhost:3500/v1.0/invoke/https://darthsidious.starwars/method/order66 + ``` + +### Using appId when calling Dapr enabled applications +AppIDs are always used to call Dapr applications with the `appID` and `my-method. Read the [How-To: Invoke services using HTTP]({{< ref howto-invoke-discover-services.md >}}) guide for more information. For example: + +```sh +localhost:3500/v1.0/invoke//method/ +``` +```sh +curl http://localhost:3602/v1.0/invoke/orderprocessor/method/checkout +``` + +## Related Links + +- [HTTPEndpoint reference]({{< ref httpendpoints-reference.md >}}) +- [Service invocation overview]({{< ref service-invocation-overview.md >}}) +- [Service invocation API specification]({{< ref service_invocation_api.md >}}) + +## Community call demo +Watch this [video](https://youtu.be/BEXJgLsO4hA?t=364) on how to use service invocation to call non-Dapr endpoints. +
+ +
diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md index 0c4d3bc41..4d2ce7a2c 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md @@ -25,7 +25,7 @@ Dapr uses a sidecar architecture. To invoke an application using Dapr: - Each application communicates with its own instance of Dapr. - The Dapr instances discover and communicate with each other. -The diagram below is an overview of how Dapr's service invocation works. +The diagram below is an overview of how Dapr's service invocation works between two Dapr-ized applications. Diagram showing the steps of service invocation @@ -38,8 +38,10 @@ The diagram below is an overview of how Dapr's service invocation works. 6. Dapr forwards the response to Service A's Dapr sidecar. 7. Service A receives the response. +You can also call non-Dapr HTTP endpoints using the service invocation API. For example, you may only use Dapr in part of an overall application, may not have access to the code to migrate an existing application to use Dapr, or simply need to call an external HTTP service. Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. + ## Features -Service invocation provides several features to make it easy for you to call methods between applications. +Service invocation provides several features to make it easy for you to call methods between applications or to call external HTTP endpoints. ### HTTP and gRPC service invocation - **HTTP**: If you're already using HTTP protocols in your application, using the Dapr HTTP header might be the easiest way to get started. You don't need to change your existing endpoint URLs; just add the `dapr-app-id` header and you're ready to go. For more information, see [Invoke Services using HTTP]({{< ref howto-invoke-discover-services.md >}}). diff --git a/daprdocs/content/en/operations/support/support-preview-features.md b/daprdocs/content/en/operations/support/support-preview-features.md index 3b4cdc2e5..92522d496 100644 --- a/daprdocs/content/en/operations/support/support-preview-features.md +++ b/daprdocs/content/en/operations/support/support-preview-features.md @@ -20,6 +20,7 @@ For CLI there is no explicit opt-in, just the version that this was first made a | **Pluggable components** | Allows creating self-hosted gRPC-based components written in any language that supports gRPC. The following component APIs are supported: State stores, Pub/sub, Bindings | N/A | [Pluggable components concept]({{}})| v1.9 | | **Multi-App Run** | Configure multiple Dapr applications from a single configuration file and run from a single command | `dapr run -f` | [Multi-App Run]({{< ref multi-app-dapr-run.md >}}) | v1.10 | | **Workflows** | Author workflows as code to automate and orchestrate tasks within your application, like messaging, state management, and failure handling | N/A | [Workflows concept]({{< ref "components-concept#workflows" >}})| v1.10 | +| **Service invocation for non-Dapr endpoints** | Allow the invocation of non-Dapr endpoints by Dapr using the [Service invocation API]({{< ref service_invocation_api.md >}}). Read ["How-To: Invoke Non-Dapr Endpoints using HTTP"]({{< ref howto-invoke-non-dapr-endpoints.md >}}) for more information. | N/A | [Service invocation API]({{< ref service_invocation_api.md >}}) | v1.11 | ### Streaming for HTTP service invocation diff --git a/daprdocs/content/en/reference/api/metadata_api.md b/daprdocs/content/en/reference/api/metadata_api.md index 336711013..b0c39c855 100644 --- a/daprdocs/content/en/reference/api/metadata_api.md +++ b/daprdocs/content/en/reference/api/metadata_api.md @@ -6,7 +6,7 @@ description: "Detailed documentation on the Metadata API" weight: 1100 --- -Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns a list of the components loaded, the activated actors (if present) and attributes with information attached. +Dapr has a metadata API that returns information about the sidecar allowing runtime discoverability. The metadata endpoint returns a list of the resources (components and HttpEndpoints loaded), the activated actors (if present), and attributes with information attached. ## Components Each loaded component provides its name, type and version and also information about supported features in the form of component capabilities. @@ -17,6 +17,9 @@ Component type | Capabilities State Store | ETAG, TRANSACTION, ACTOR, QUERY_API Binding | INPUT_BINDING, OUTPUT_BINDING +## HTTPEndpoints +Each loaded `HttpEndpoint` provides a name to easily identify the Dapr resource associated with the runtime. + ## Attributes The metadata API allows you to store additional attribute information in the format of key-value pairs. These are ephemeral in-memory and are not persisted if a sidecar is reloaded. This information should be added at the time of a sidecar creation, for example, after the application has started. diff --git a/daprdocs/content/en/reference/api/service_invocation_api.md b/daprdocs/content/en/reference/api/service_invocation_api.md index 15de82351..8ecd243ef 100644 --- a/daprdocs/content/en/reference/api/service_invocation_api.md +++ b/daprdocs/content/en/reference/api/service_invocation_api.md @@ -6,17 +6,29 @@ description: "Detailed documentation on the service invocation API" weight: 100 --- -Dapr provides users with the ability to call other applications that have unique ids. -This functionality allows apps to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime. +Dapr provides users with the ability to call other applications that are using Dapr with a unique named identifier (appId), or HTTP endpoints that are not using Dapr. +This allows applications to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime. -## Invoke a method on a remote dapr app +## Invoke a method on a remote Dapr app This endpoint lets you invoke a method in another Dapr enabled app. ### HTTP Request ``` -PATCH/POST/GET/PUT/DELETE http://localhost:/v1.0/invoke//method/ +PATCH/POST/GET/PUT/DELETE http://localhost:/v1.0/invoke//method/ +``` + +## Invoke a method on a non-Dapr endpoint + +This endpoint lets you invoke a method on a non-Dapr endpoint using an `HTTPEndpoint` resource name, or a Fully Qualified Domain Name (FQDN) URL. + +### HTTP Request + +``` +PATCH/POST/GET/PUT/DELETE http://localhost:/v1.0/invoke//method/ + +PATCH/POST/GET/PUT/DELETE http://localhost:/v1.0/invoke//method/ ``` ### HTTP Response codes @@ -38,7 +50,9 @@ XXX | Upstream status returned Parameter | Description --------- | ----------- daprPort | the Dapr port -appId | the App ID associated with the remote app +appID | the App ID associated with the remote app +HTTPEndpoint name | the HTTPEndpoint resource associated with the external endpoint +FQDN URL | Fully Qualified Domain Name URL to invoke on the external endpoint method-name | the name of the method or url to invoke on the remote app > Note, all URL parameters are case-sensitive. @@ -65,9 +79,9 @@ Within the body of the request place the data you want to send to the service: ### Request received by invoked service -Once your service code invokes a method in another Dapr enabled app, Dapr will send the request, along with the headers and body, to the app on the `` endpoint. +Once your service code invokes a method in another Dapr enabled app or non-Dapr endpoint, Dapr sends the request, along with the headers and body, on the `` endpoint. -The Dapr app being invoked will need to be listening for and responding to requests on that endpoint. +The Dapr app or non-Dapr endpoint being invoked will need to be listening for and responding to requests on that endpoint. ### Cross namespace invocation @@ -120,5 +134,19 @@ In case you are invoking `mathService` on a different namespace, you can use the In this URL, `testing` is the namespace that `mathService` is running in. +#### Non-Dapr Endpoint Example + +If the `mathService` service was a non-Dapr application, then it could be invoked using service invocation via an `HTTPEndpoint`, as well as a Fully Qualified Domain Name (FQDN) URL. + +```shell +curl http://localhost:3500/v1.0/invoke/mathHTTPEndpoint/method/add \ + -H "Content-Type: application/json" + -d '{ "arg1": 10, "arg2": 23}' + +curl http://localhost:3500/v1.0/invoke/http://mathServiceURL.com/method/add \ + -H "Content-Type: application/json" + -d '{ "arg1": 10, "arg2": 23}' +``` + ## Next Steps - [How-To: Invoke and discover services]({{< ref howto-invoke-discover-services.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 b95099430..30de16705 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/http.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/http.md @@ -7,6 +7,10 @@ aliases: - "/operations/components/setup-bindings/supported-bindings/http/" --- +## 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. + ## Setup Dapr component ```yaml diff --git a/daprdocs/content/en/reference/resource-specs/_index.md b/daprdocs/content/en/reference/resource-specs/_index.md new file mode 100644 index 000000000..fa7ba8fc8 --- /dev/null +++ b/daprdocs/content/en/reference/resource-specs/_index.md @@ -0,0 +1,7 @@ +--- +type: docs +title: "Dapr resource specs" +linkTitle: "Resource specs" +description: "Detailed information and specifications on Dapr resources" +weight: 500 +--- diff --git a/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md new file mode 100644 index 000000000..66d4f5606 --- /dev/null +++ b/daprdocs/content/en/reference/resource-specs/httpendpoints-reference.md @@ -0,0 +1,41 @@ +--- +type: docs +title: "HTTPEndpoint spec" +linkTitle: "HTTPEndpoint spec" +description: "The HTTPEndpoint resource spec" +weight: 300 +aliases: + - "/operations/httpEndpoints/" +--- + +The `HTTPEndpoint` is a Dapr resource that is used to enable the invocation of non-Dapr endpoints from a Dapr application. + +## HTTPEndpoint format + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: HTTPEndpoint +metadata: + name: +spec: + version: v1alpha1 + baseUrl: # Required. Use "http://" or "https://" prefix. + headers: # Optional + - name: + value: + - name: + secretKeyRef: + name: + key: +scopes: # Optional + - +auth: # Optional + secretStore: +``` + +## Spec fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| baseUrl | Y | Base URL of the non-Dapr endpoint | `"https://api.github.com"`, `"http://api.github.com"` +| headers | N | HTTP request headers for service invocation | `name: "Accept-Language" value: "en-US"`
`name: "Authorization" secretKeyRef.name: "my-secret" secretKeyRef.key: "myGithubToken" ` \ No newline at end of file diff --git a/daprdocs/static/images/service-invocation-overview-non-dapr-endpoint.png b/daprdocs/static/images/service-invocation-overview-non-dapr-endpoint.png new file mode 100644 index 000000000..28873f84c Binary files /dev/null and b/daprdocs/static/images/service-invocation-overview-non-dapr-endpoint.png differ diff --git a/daprdocs/static/presentations/Dapr-Diagrams.pptx.zip b/daprdocs/static/presentations/Dapr-Diagrams.pptx.zip index 21bc81f93..947ddb476 100644 Binary files a/daprdocs/static/presentations/Dapr-Diagrams.pptx.zip and b/daprdocs/static/presentations/Dapr-Diagrams.pptx.zip differ