From a0045b670aae5f825e95699fd10f80476d9ea84c Mon Sep 17 00:00:00 2001 From: yaron2 Date: Thu, 3 Oct 2019 15:12:40 -0700 Subject: [PATCH 1/5] add how to for service discovery --- howto/invoke-and-discover-services/Readme.md | 101 +++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 howto/invoke-and-discover-services/Readme.md diff --git a/howto/invoke-and-discover-services/Readme.md b/howto/invoke-and-discover-services/Readme.md new file mode 100644 index 00000000000..ce27a6fff8d --- /dev/null +++ b/howto/invoke-and-discover-services/Readme.md @@ -0,0 +1,101 @@ +# Invoke remote services using well known IDs + +In many environments with multiple services that need to communicate with each other, developers often ask themselves the following questions: + +* How do I discover and invoke different services? +* How do I handle retries and transient errors? +* How do I use distributed tracing correctly to see a call graph? + +Dapr allows developers to overcome these challenges by providing an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling. + +## 1. Choose an ID for your service + +Dapr allows you to assign a global, unique identifier for your app.
+This ID will also encapsulate state for your app, regardless of the number of instances it may have. + +### Setting up an ID using Kubernetes + +In Kubernetes, set the `dapr.io/id` annotation on your pod: + +
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: python-app
+  labels:
+    app: python-app
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: python-app
+  template:
+    metadata:
+      labels:
+        app: python-app
+      annotations:
+        dapr.io/enabled: "true"
+        dapr.io/id: "cart"
+        dapr.io/port: "5000"
+...
+
+ +### Setting up an ID using the Dapr CLI + +In Standalone mode, set the `--app-id` flag: + +`dapr run --app-id cart --app-port 5000 python app.py` + +## Invoke a service + +Dapr embraces a sidecar based, decentralized architecture. +To invoke an app using Dapr, you can use the `invoke` endpoint on any Dapr instance in your cluster/environment. + +The sidecar programming model encourages each app to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another. + +*Note: The following is a Python example of a cart app. It can be written in any programming language* + +```python +from flask import Flask +app = Flask(__name__) + +@app.route('/add', methods=['POST']) +def add(): + return "Added!" + +if __name__ == '__main__': + app.run() +``` + +This Python app exposes an `add()` method via the `/add` endpoint. +Next we'll use Dapr to + +### Invoke with curl + +``` +curl http://localhost:3500/v1.0/invoke/cart/add -X POST +``` + +Since the aoo endpoint is a 'POST' method, we used `-X POST` in the curl command. + +To invoke a 'GET' endpoint: + +``` +curl http://localhost:3500/v1.0/invoke/cart/add +``` + +To invoke a 'DELETE' endpoint: + +``` +curl http://localhost:3500/v1.0/invoke/cart/add -X DELETE +``` + +Dapr will put any payload return by ther called service in the HTTP response's body. + + +## Overview + +The example above showed us how to directly invoke a different service running in our environment, locally or in Kubernetes. +Dapr will output metrics and tracing information allowing you to visualize a call graph between services, log errors and optionally log the payload body. + +For more information on tracing, visit [this link](../../best-practices/troubleshooting/tracing.md). From 6493c531b0ccb31388dc7607e3da2504e4984a7f Mon Sep 17 00:00:00 2001 From: yaron2 Date: Thu, 3 Oct 2019 15:15:44 -0700 Subject: [PATCH 2/5] fix links --- concepts/bindings/bindings.md | 2 +- howto/trigger-app-with-input-binding/Readme.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/concepts/bindings/bindings.md b/concepts/bindings/bindings.md index a9cc1938c8f..4adfc1dcba1 100644 --- a/concepts/bindings/bindings.md +++ b/concepts/bindings/bindings.md @@ -10,7 +10,7 @@ Bindings allow for on-demand, event-driven compute scenarios, and dapr bindings * Switch between bindings at runtime time * Enable portable applications where environment-specific bindings are set-up and no code changes are required -Bindings are developed independently of dapr runtime. You can view and contribute to the bindings [here](https://github.com/actionscore/components-contrib/tree/master/bindings). +Bindings are developed independently of dapr runtime. You can view and contribute to the bindings [here](https://github.com/dapr/components-contrib/tree/master/bindings). ## Supported Bindings and Specs diff --git a/howto/trigger-app-with-input-binding/Readme.md b/howto/trigger-app-with-input-binding/Readme.md index cde3904a6b5..9228fb65c17 100644 --- a/howto/trigger-app-with-input-binding/Readme.md +++ b/howto/trigger-app-with-input-binding/Readme.md @@ -10,14 +10,14 @@ Dapr bindings allow you to: * Replace bindings without changing your code * Focus on business logic and not the event resource implementation -For more info on bindings, read [this](../concepts/bindings/bindings.md) link.
+For more info on bindings, read [this](../../concepts/bindings/bindings.md) link.
For a complete sample showing bindings, visit this [link](). ## 1. Create a binding An input binding represents an event resource that Dapr uses to read events from and push to your application. -For the purpose of this HowTo, we'll use a Kafka binding. You can find a list of the different binding specs [here](../concepts/bindings/specs). +For the purpose of this HowTo, we'll use a Kafka binding. You can find a list of the different binding specs [here](../../concepts/bindings/specs). Create the following YAML file, named binding.yaml, and save this to the /components sub-folder in your application directory: From 6e3f054276a899edb02ec588a8aaa4ba15f40839 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Thu, 3 Oct 2019 16:12:00 -0700 Subject: [PATCH 3/5] MInor updates --- concepts/bindings/bindings.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/concepts/bindings/bindings.md b/concepts/bindings/bindings.md index 4adfc1dcba1..90cf192665c 100644 --- a/concepts/bindings/bindings.md +++ b/concepts/bindings/bindings.md @@ -10,7 +10,7 @@ Bindings allow for on-demand, event-driven compute scenarios, and dapr bindings * Switch between bindings at runtime time * Enable portable applications where environment-specific bindings are set-up and no code changes are required -Bindings are developed independently of dapr runtime. You can view and contribute to the bindings [here](https://github.com/dapr/components-contrib/tree/master/bindings). +Bindings are developed independently of Dapr runtime. You can view and contribute to the bindings [here](https://github.com/dapr/components-contrib/tree/master/bindings). ## Supported Bindings and Specs @@ -37,24 +37,24 @@ Every binding has its own unique set of properties. Click the name link to see t ## Input Bindings -Input bindings are used to trigger your app when an event from an external system has occured. +Input bindings are used to trigger your application when an event from an external resource has occured. An optional payload and metadata might be sent with the request. In order to receive events from an input binding: -1. Define the component YAML that describes the type of bindings and its metadata (connection info, etc.) +1. Define the component YAML that describes the type of binding and its metadata (connection info, etc.) 2. Listen on an HTTP endpoint for the incoming event, or use the gRPC proto library to get incoming events. Read the [How To](../../howto) section to get started with input bindings. ## Output Bindings -Output bindings allow users to invoke external systems +Output bindings allow users to invoke external resources An optional payload and metadata can be sent with the invocation request. In order to invoke an output binding: -1. Define the component YAML that describes the type of bindings and its metadata (connection info, etc.) +1. Define the component YAML that describes the type of binding and its metadata (connection info, etc.) 2. Use the HTTP endpoint or gRPC method to invoke the binding with an optional payload Read the [How To](../../howto) section to get started with output bindings. From 803dd060403f64edfb21cbe07f9a63d0171d0c63 Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Thu, 3 Oct 2019 16:41:43 -0700 Subject: [PATCH 4/5] Update Readme.md --- howto/invoke-and-discover-services/Readme.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/howto/invoke-and-discover-services/Readme.md b/howto/invoke-and-discover-services/Readme.md index ce27a6fff8d..ebfe3842f42 100644 --- a/howto/invoke-and-discover-services/Readme.md +++ b/howto/invoke-and-discover-services/Readme.md @@ -1,4 +1,4 @@ -# Invoke remote services using well known IDs +# Invoke remote services In many environments with multiple services that need to communicate with each other, developers often ask themselves the following questions: @@ -35,7 +35,7 @@ spec: app: python-app annotations: dapr.io/enabled: "true" - dapr.io/id: "cart" + dapr.io/id: "cart" dapr.io/port: "5000" ... @@ -68,7 +68,7 @@ if __name__ == '__main__': ``` This Python app exposes an `add()` method via the `/add` endpoint. -Next we'll use Dapr to +Next we'll use Dapr to invoke the service. ### Invoke with curl @@ -76,7 +76,7 @@ Next we'll use Dapr to curl http://localhost:3500/v1.0/invoke/cart/add -X POST ``` -Since the aoo endpoint is a 'POST' method, we used `-X POST` in the curl command. +Since the `/add` endpoint is a 'POST' method, we used `-X POST` in the curl command. To invoke a 'GET' endpoint: From 03e1d39b8f201009f2745863308a4a1ae9502833 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Thu, 3 Oct 2019 16:42:45 -0700 Subject: [PATCH 5/5] Changes to doc --- howto/invoke-and-discover-services/Readme.md | 34 +++++++++----------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/howto/invoke-and-discover-services/Readme.md b/howto/invoke-and-discover-services/Readme.md index ebfe3842f42..dc60c842527 100644 --- a/howto/invoke-and-discover-services/Readme.md +++ b/howto/invoke-and-discover-services/Readme.md @@ -10,10 +10,16 @@ Dapr allows developers to overcome these challenges by providing an endpoint tha ## 1. Choose an ID for your service -Dapr allows you to assign a global, unique identifier for your app.
-This ID will also encapsulate state for your app, regardless of the number of instances it may have. +Dapr allows you to assign a global, unique ID for your app.
+This ID encapsulates the state for your application, regardless of the number of instances it may have. -### Setting up an ID using Kubernetes +### Setup an ID using the Dapr CLI + +In Standalone mode, set the `--app-id` flag: + +`dapr run --app-id cart --app-port 5000 python app.py` + +### Setup an ID using Kubernetes In Kubernetes, set the `dapr.io/id` annotation on your pod: @@ -40,18 +46,11 @@ spec: ... -### Setting up an ID using the Dapr CLI - -In Standalone mode, set the `--app-id` flag: - -`dapr run --app-id cart --app-port 5000 python app.py` - -## Invoke a service +## Invoke a service in code -Dapr embraces a sidecar based, decentralized architecture. -To invoke an app using Dapr, you can use the `invoke` endpoint on any Dapr instance in your cluster/environment. +Dapr uses a sidecar, decentralized architecture. To invoke an applications using Dapr, you can use the `invoke` endpoint on any Dapr instance in your cluster/environment. -The sidecar programming model encourages each app to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another. +The sidecar programming model encourages each applications to talk to its own instance of Dapr. The Dapr instances discover and communicate with one another. *Note: The following is a Python example of a cart app. It can be written in any programming language* @@ -68,7 +67,6 @@ if __name__ == '__main__': ``` This Python app exposes an `add()` method via the `/add` endpoint. -Next we'll use Dapr to invoke the service. ### Invoke with curl @@ -76,7 +74,7 @@ Next we'll use Dapr to invoke the service. curl http://localhost:3500/v1.0/invoke/cart/add -X POST ``` -Since the `/add` endpoint is a 'POST' method, we used `-X POST` in the curl command. +Since the aoo endpoint is a 'POST' method, we used `-X POST` in the curl command. To invoke a 'GET' endpoint: @@ -90,12 +88,12 @@ To invoke a 'DELETE' endpoint: curl http://localhost:3500/v1.0/invoke/cart/add -X DELETE ``` -Dapr will put any payload return by ther called service in the HTTP response's body. +Dapr puts any payload return by ther called service in the HTTP response's body. ## Overview -The example above showed us how to directly invoke a different service running in our environment, locally or in Kubernetes. -Dapr will output metrics and tracing information allowing you to visualize a call graph between services, log errors and optionally log the payload body. +The example above showed you how to directly invoke a different service running in our environment, locally or in Kubernetes. +Dapr outputs metrics and tracing information allowing you to visualize a call graph between services, log errors and optionally log the payload body. For more information on tracing, visit [this link](../../best-practices/troubleshooting/tracing.md).