diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md new file mode 100644 index 0000000..b934ec3 --- /dev/null +++ b/docs/tutorial/README.md @@ -0,0 +1,121 @@ +# Dapr Shared Getting Started Tutorial + +This tutorial follows up on the Dapr Hello Kubernetes tutorial that can be found here in the Dapr Quickstart repo: + +https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes + +Instead of deploying Dapr as a sidecar we are going to use Dapr Shared instances. + + +## Prerequisites and Installation + +Before proceeding make sure that you have the necessary tools installed on your system. We will create a local KinD cluster to install Dapr, some applications, and an instance of Dapr Shared. + +To get started, make sure you have the following CLIs installed: + +- [Docker](https://www.docker.com/) + +- [KinD (Kubernetes in Docker)](https://kind.sigs.k8s.io/docs/user/quick-start/) + +- [kubectl](https://kubernetes.io/docs/tasks/tools/) + +- [Helm](https://helm.sh/docs/intro/install/) + + +## Creating a local Kubernetes cluster with KinD: + +Create a Kubernetes cluster with KinD defaults by running the following command: + +```bash +kind create cluster +``` + +Next install a version of the Dapr control plane into the cluster: + +``` +helm repo add dapr https://dapr.github.io/helm-charts/ +helm repo update +helm upgrade --install dapr dapr/dapr \ +--version=1.13.2 \ +--namespace dapr-system \ +--create-namespace \ +--wait +``` +Or use the Dapr CLI to install the latest version with the following command + +`dapr init -k` +## Running the Hello Kubernetes example + +Next install a Redis instance into the cluster using Helm + +```shell +helm install redis oci://registry-1.docker.io/bitnamicharts/redis --version 17.11.3 --set "architecture=standalone" --set "master.persistence.size=1Gi" +``` + +Once Redis is installed you can deploy our application workloads, including a statestore component by running: + +```shell +kubectl apply -f deploy/ +``` + +This creates a statestore component, a Node application and a Python application. + +If you inspect the `deploy/node.yaml` and `deploy/python.yaml` files you see that both are define two environment variables: + +```yaml + - name: DAPR_HTTP_ENDPOINT + value: http://nodeapp-dapr.default.svc.cluster.local:3500 + - name: DAPR_GRPC_ENDPOINT + value: http://nodeapp-dapr.default.svc.cluster.local:50001 +``` + +These two environment variables let the Dapr SDK know where the Dapr endpoints are hosted (usually for the sidecar these are located on `localhost`). + +Because these workloads are not annotated with Dapr annotations, the Dapr Control Plane will not inject a Dapr sidecar, instead we will create two instances of the Dapr runtime using Dapr Shared for our services to use. + + +## Creating two Dapr Shared instances for our services + +For each application service that needs to talk to the Dapr APIs we need to deploy a new Dapr Shared instance. Each instance have a one to one relationship with Dapr Application Ids. + +Let's create a new Dapr Shared instance for the Node (`nodeapp`) application: + +```sh +helm install nodeapp-shared oci://docker.io/daprio/dapr-shared-chart --set shared.appId=nodeapp +``` + +Notice that the `shared.appId` is the name used for the endpoint variables defined in the previous section. + +Let's do the same for the Python application: + +```sh +helm install pythonapp-shared oci://docker.io/daprio/dapr-shared-chart --set shared.appId=pythonapp +``` + +Once both Dapr Shared instances are up, the application can connect to the Dapr APIs on the shared instance for the particular application. You can validate this by interacting with the `nodeapp` by running: + +``` +kubectl port-forward service/nodeapp 8080:80 +``` + +And then sending a request to place a new order: + +```shell +curl --request POST --data "@sample.json" --header Content-Type:application/json http://localhost:8080/neworder +``` + +Validate the order has been persisted: + +```shell +curl http://localhost:8080/order +``` + +Expected Output: +``` +{ "orderId": "42" } +``` + +## Get involved + +If you want to contribute to Dapr Shared, please get in touch, create an issue, or submit a Pull Request. +You can also check the Project Roadmap to see what is coming or to find out how you can help us get the next version done. diff --git a/docs/tutorial/deploy/node.yaml b/docs/tutorial/deploy/node.yaml new file mode 100644 index 0000000..e8532ac --- /dev/null +++ b/docs/tutorial/deploy/node.yaml @@ -0,0 +1,45 @@ +kind: Service +apiVersion: v1 +metadata: + name: nodeapp + labels: + app: node +spec: + selector: + app: node + ports: + - protocol: TCP + port: 80 + targetPort: 3000 + type: LoadBalancer + +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: nodeapp + labels: + app: node +spec: + replicas: 1 + selector: + matchLabels: + app: node + template: + metadata: + labels: + app: node + spec: + containers: + - name: node + image: ghcr.io/dapr/samples/hello-k8s-node:latest + env: + - name: APP_PORT + value: "3000" + - name: DAPR_HTTP_ENDPOINT + value: http://nodeapp-dapr.default.svc.cluster.local:3500 + - name: DAPR_GRPC_ENDPOINT + value: http://nodeapp-dapr.default.svc.cluster.local:50001 + ports: + - containerPort: 3000 + imagePullPolicy: Always \ No newline at end of file diff --git a/docs/tutorial/deploy/python.yaml b/docs/tutorial/deploy/python.yaml new file mode 100644 index 0000000..8d26069 --- /dev/null +++ b/docs/tutorial/deploy/python.yaml @@ -0,0 +1,24 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: pythonapp + labels: + app: python +spec: + replicas: 1 + selector: + matchLabels: + app: python + template: + metadata: + labels: + app: python + spec: + containers: + - name: python + image: ghcr.io/dapr/samples/hello-k8s-python:latest + env: + - name: DAPR_HTTP_ENDPOINT + value: http://pythonapp-dapr.default.svc.cluster.local:3500 + - name: DAPR_GRPC_ENDPOINT + value: http://pythonapp-dapr.default.svc.cluster.local:50001 \ No newline at end of file diff --git a/docs/tutorial/deploy/redis.yaml b/docs/tutorial/deploy/redis.yaml new file mode 100644 index 0000000..c565c03 --- /dev/null +++ b/docs/tutorial/deploy/redis.yaml @@ -0,0 +1,21 @@ +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: statestore +spec: + type: state.redis + version: v1 + metadata: + # These settings will work out of the box if you use `helm install + # bitnami/redis`. If you have your own setup, replace + # `redis-master:6379` with your own Redis master address, and the + # Redis password with your own Secret's name. For more information, + # see https://docs.dapr.io/operations/components/component-secrets . + - name: redisHost + value: redis-master:6379 + - name: redisPassword + secretKeyRef: + name: redis + key: redis-password +auth: + secretStore: kubernetes \ No newline at end of file diff --git a/docs/tutorial/sample.json b/docs/tutorial/sample.json new file mode 100644 index 0000000..a1f7f05 --- /dev/null +++ b/docs/tutorial/sample.json @@ -0,0 +1,5 @@ +{ + "data": { + "orderId": "42" + } +} diff --git a/tutorial/README.md b/tutorial/README.md deleted file mode 100644 index 5f3f8c2..0000000 --- a/tutorial/README.md +++ /dev/null @@ -1,134 +0,0 @@ -# Dapr Shared with KinD - -This tutorial provides step-by-step instructions for installing Dapr Shared for a simple application composed with 3 services. - -## Prerequisites and Installation - -Before proceeding, please make sure that you have the necessary tools installed on your system. We will create a local KinD cluster to install Dapr, some applications, and an instance of Dapr Shared. - -To get started, make sure you have the following CLIs installed: - -- [Docker](https://www.docker.com/) - -- [KinD (Kubernetes in Docker)](https://kind.sigs.k8s.io/docs/user/quick-start/) - -- [kubectl](https://kubernetes.io/docs/tasks/tools/) - -- [Helm](https://helm.sh/docs/intro/install/) - - -## Creating a local Kubernetes cluster with KinD: - -Here, you will create a simple Kubernetes cluster with KinD defaults running the following command: - -```bash - kind create cluster -``` - -Make sure to install the Dapr Control Plane into the cluster with: - -``` -helm repo add dapr https://dapr.github.io/helm-charts/ -helm repo update -helm upgrade --install dapr dapr/dapr \ ---version=1.12.3 \ ---namespace dapr-system \ ---create-namespace \ ---wait -``` - -## Installing application-infrastructure (PostgreSQL and Kafka): - -We will be using Kafka for sending messages between services: - -``` -helm install kafka oci://registry-1.docker.io/bitnamicharts/kafka --version 22.1.5 --set "provisioning.topics[0].name=events-topic" --set "provisioning.topics[0].partitions=1" --set "persistence.size=1Gi" -``` - -We will be using PostgreSQL as our persistent store, but before installing the PostgreSQL Chart run: - -``` -kubectl apply -f k8s/pizza-init-sql-cm.yaml -``` - -Then: - -``` -helm install postgresql oci://registry-1.docker.io/bitnamicharts/postgresql --version 12.5.7 --set "image.debug=true" --set "primary.initdb.user=postgres" --set "primary.initdb.password=postgres" --set "primary.initdb.scriptsConfigMap=pizza-init-sql" --set "global.postgresql.auth.postgresPassword=postgres" --set "primary.persistence.size=1Gi" -``` - -## Installing Dapr Components - -In this section, we will be configure two Dapr Components: [PubSub](https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-overview/) and [StateStore](https://docs.dapr.io/developing-applications/building-blocks/state-management/state-management-overview/). - -So before deploying our applications, let's configure the Statestore component to connect to PostgreSQL. - -Create the StateStore component by running: - -```sh -kubectl apply -f k8s/statestore.yaml - -``` - -Now we can create and configure the PubSub component to connect to Kafka. We can do this by applying this resource: - -```sh -kubectl apply -f k8s/pubsub.yaml -``` - -Once configured, the PubSub component can register Subscriptions to define who and where notifications will be sent when new messages arrive at the `notification` topic. - -Create the Subscription resource by applying this file to Kubernetes by running: - -```sh -kubectl apply -f k8s/subscription.yaml -``` - -## Installing Dapr Shared and all applications - -For each application service that needs to talk to the Dapr APIs we need to deploy a new Dapr Shared instance. Each instance have a one to one relationship with Dapr Application Ids. - -Let's create a new Dapr Shared instance for the Pizza Store service: - -```sh -helm install pizza-store-shared oci://docker.io/daprio/dapr-shared-chart --set shared.appId=pizza-store --set shared.remoteURL=pizza-store --set shared.remotePort=80 -``` - -Let's do the same for the Kitchen Service: - -```sh -helm install pizza-kitchen-shared oci://docker.io/daprio/dapr-shared-chart --set shared.appId=kitchen-service --set shared.remoteURL=kitchen-service --set shared.remotePort=80 -``` - - -Finally, let's do the same for the Delivery Service: - -```sh -helm install pizza-delivery-shared oci://docker.io/daprio/dapr-shared-chart --set shared.appId=delivery-service --set shared.remoteURL=delivery-service --set shared.remotePort=80 -``` - - -Now that we have our 3 Dapr Shared instances for our application services, we can install the application Services. - -These are standard Kubernetes applications using `Deployments` and `Services`: - -```sh - kubectl apply -f k8s/pizza-app.yaml -``` - -This installs all the application services. To avoid dealing with Ingresses, you can access the application by using `kubectl port-forward` to access the application on port `8080`: - -``` -kubectl port-forward svc/pizza-store 8080:80 -``` - -Then you can point your browser to [`http://localhost:8080`](http://localhost:8080) and you should see: - -![Pizza Store](imgs/pizza-store.png) - -If you want to see the implementation's details, you [can access this repository](https://github.com/salaboy/pizza). - -## Get involved - -If you want to contribute to Dapr Shared, please get in touch, create an issue, or submit a Pull Request. -You can also check the Project Roadmap to see what is coming or to find out how you can help us get the next version done. diff --git a/tutorial/imgs/pizza-store.png b/tutorial/imgs/pizza-store.png deleted file mode 100644 index 16237df..0000000 Binary files a/tutorial/imgs/pizza-store.png and /dev/null differ diff --git a/tutorial/k8s/pizza-app.yaml b/tutorial/k8s/pizza-app.yaml deleted file mode 100644 index 35ce1cc..0000000 --- a/tutorial/k8s/pizza-app.yaml +++ /dev/null @@ -1,200 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: pizza-delivery-deployment -spec: - selector: - matchLabels: - app: pizza-delivery-service - template: - metadata: - annotations: - # dapr.io/app-id: delivery-service - # dapr.io/app-port: "8080" - # dapr.io/enabled: "true" - # dapr.io/log-level: "debug" - labels: - app: pizza-delivery-service - app.kubernetes.io/name: pizza-delivery-service - app.kubernetes.io/part-of: pizza-delivery-service - app.kubernetes.io/version: 0.1.0 - spec: - containers: - - name: pizza-delivery-service - image: salaboy/pizza-delivery:0.1.0 - imagePullPolicy: Always - env: - - name: JAVA_OPTS - value: "-XX:+UseParallelGC -XX:ActiveProcessorCount=1 -XX:MaxRAMPercentage=75 -XX:TieredStopAtLevel=1" - - name: DAPR_HTTP_ENDPOINT - value: http://delivery-service-dapr.default.svc.cluster.local:3500 - - name: DAPR_GRPC_ENDPOINT - value: http://delivery-service-dapr.default.svc.cluster.local:50001 - - name: PUB_SUB_NAME - value: pubsub - - name: PUB_SUB_TOPIC - value: topic - livenessProbe: - httpGet: - path: /actuator/health - port: 8080 - readinessProbe: - httpGet: - path: /actuator/health - port: 8080 - resources: - limits: - cpu: "1" - memory: "2Gi" - requests: - cpu: "1" - memory: "2Gi" - ports: - - containerPort: 8080 - ---- -apiVersion: v1 -kind: Service -metadata: - name: delivery-service -spec: - selector: - app: pizza-delivery-service - ports: - - port: 80 - targetPort: 8080 - ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: pizza-kitchen-deployment -spec: - selector: - matchLabels: - app: pizza-kitchen-service - template: - metadata: - annotations: - # dapr.io/app-id: kitchen-service - # dapr.io/app-port: "8080" - # dapr.io/enabled: "true" - # dapr.io/log-level: "debug" - labels: - app: pizza-kitchen-service - app.kubernetes.io/name: pizza-kitchen-service - app.kubernetes.io/part-of: pizza-kitchen-service - app.kubernetes.io/version: 0.1.0 - spec: - containers: - - name: pizza-kitchen-service - image: salaboy/pizza-kitchen:0.1.0 - imagePullPolicy: Always - env: - - name: JAVA_OPTS - value: "-XX:+UseParallelGC -XX:ActiveProcessorCount=1 -XX:MaxRAMPercentage=75 -XX:TieredStopAtLevel=1" - - name: PUB_SUB_NAME - value: pubsub - - name: PUB_SUB_TOPIC - value: topic - - name: DAPR_HTTP_ENDPOINT - value: http://kitchen-service-dapr.default.svc.cluster.local:3500 - - name: DAPR_GRPC_ENDPOINT - value: http://kitchen-service-dapr.default.svc.cluster.local:50001 - livenessProbe: - httpGet: - path: /actuator/health - port: 8080 - readinessProbe: - httpGet: - path: /actuator/health - port: 8080 - resources: - limits: - cpu: "1" - memory: "2Gi" - requests: - cpu: "1" - memory: "2Gi" - ports: - - containerPort: 8080 - ---- -apiVersion: v1 -kind: Service -metadata: - name: kitchen-service -spec: - selector: - app: pizza-kitchen-service - ports: - - port: 80 - targetPort: 8080 - ---- - - -apiVersion: apps/v1 -kind: Deployment -metadata: - name: pizza-store-deployment -spec: - selector: - matchLabels: - app: pizza-store-service - template: - metadata: - annotations: - # dapr.io/app-id: pizza-store - # dapr.io/app-port: "8080" - # dapr.io/enabled: "true" - # dapr.io/log-level: "debug" - labels: - app: pizza-store-service - app.kubernetes.io/name: pizza-store-service - app.kubernetes.io/part-of: pizza-store-service - app.kubernetes.io/version: 0.1.0 - spec: - containers: - - name: pizza-store-service - image: salaboy/pizza-store:0.1.0 - imagePullPolicy: Always - env: - - name: JAVA_OPTS - value: "-XX:+UseParallelGC -XX:ActiveProcessorCount=1 -XX:MaxRAMPercentage=75 -XX:TieredStopAtLevel=1" - - name: PUBLIC_IP - value: localhost:8080 - - name: DAPR_HTTP_ENDPOINT - value: http://pizza-store-dapr.default.svc.cluster.local:3500 - - name: DAPR_GRPC_ENDPOINT - value: http://pizza-store-dapr.default.svc.cluster.local:50001 - - name: STATESTORE_NAME - value: kvstore - livenessProbe: - httpGet: - path: /actuator/health - port: 8080 - readinessProbe: - httpGet: - path: /actuator/health - port: 8080 - resources: - limits: - cpu: "1" - memory: "2Gi" - requests: - cpu: "1" - memory: "2Gi" - ports: - - containerPort: 8080 ---- -apiVersion: v1 -kind: Service -metadata: - name: pizza-store -spec: - selector: - app: pizza-store-service - ports: - - port: 80 - targetPort: 8080 \ No newline at end of file diff --git a/tutorial/k8s/pizza-init-sql-cm.yaml b/tutorial/k8s/pizza-init-sql-cm.yaml deleted file mode 100644 index 7425825..0000000 --- a/tutorial/k8s/pizza-init-sql-cm.yaml +++ /dev/null @@ -1,7 +0,0 @@ -apiVersion: v1 -kind: ConfigMap -metadata: - name: pizza-init-sql -data: - init.sql: |- - CREATE DATABASE dapr; \ No newline at end of file diff --git a/tutorial/k8s/pubsub.yaml b/tutorial/k8s/pubsub.yaml deleted file mode 100644 index 579d308..0000000 --- a/tutorial/k8s/pubsub.yaml +++ /dev/null @@ -1,12 +0,0 @@ -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: pubsub -spec: - type: pubsub.kafka - version: v1 - metadata: - - name: brokers # Required. Kafka broker connection setting - value: kafka.default.svc.cluster.local:9092 - - name: authType - value: "none" \ No newline at end of file diff --git a/tutorial/k8s/statestore.yaml b/tutorial/k8s/statestore.yaml deleted file mode 100644 index ab94315..0000000 --- a/tutorial/k8s/statestore.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: kvstore -spec: - type: state.postgresql - version: v1 - metadata: - - name: connectionString - value: "host=postgresql.default.svc.cluster.local user=postgres password=postgres port=5432 connect_timeout=10 database=dapr" diff --git a/tutorial/k8s/subscription.yaml b/tutorial/k8s/subscription.yaml deleted file mode 100644 index 8277c7c..0000000 --- a/tutorial/k8s/subscription.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dapr.io/v1alpha1 -kind: Subscription -metadata: - name: pizza-store-subscritpion -spec: - topic: topic - route: /events - pubsubname: pubsub -scopes: -- pizza-store \ No newline at end of file