From 41fd252e76a41e120b22653f9ef0cbc81354157e Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Wed, 8 Feb 2023 15:10:19 -0800 Subject: [PATCH 1/7] How to define spec.type for pluggable components. Expands on multiple building blocks behind a single pluggable components and how how to define the contents of the field `spec.type` in a component spec. Addresses #2985 Signed-off-by: Tiago Alves Macambira --- .../pluggable-components-registration.md | 44 ++++++++----------- 1 file changed, 19 insertions(+), 25 deletions(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index 15e7fdbc8..d581414f5 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -49,49 +49,43 @@ Both your component and the Unix Socket must be running before Dapr starts. By default, Dapr looks for [Unix Domain Socket][uds] files in the folder in `/tmp/dapr-components-sockets`. -Filenames in this folder are significant for component registration. They must be formed by appending the component's name with a file extension of your choice, more commonly `.sock`. For example, the filename `my-component.sock` is a valid UDS file name for a component named `my-component`. +Filenames in this folder are significant for component registration. They must be formed by appending the component's **name** with a file extension of your choice, more commonly `.sock`. For example, the filename `my-component.sock` is a valid UDS file name for a component named `my-component`. Since you are running Dapr in the same host as the component, verify this folder and the files within it are accessible and writable by both your component and Dapr. +### Building-blocks discovery from behind the same component + +A pluggable component accessible through a [Unix Domain Socket][uds] can host multiple distinct bulding blocks. During the components initial discovery process, Dapr will use reflection to enumerate all building blocks behind a UDS. The `my-component` pluggable component from the example above could contain both a state store (`state`) and a Pub/Sub (`pubsub`) building-blocks. + +The most common use-case is for a 1:1 mapping between pluggable components and building blocks they expose. That said, having the possibility of consolidating multiple building blocks under the same pluggable components might be healpful, specially to ease DevOps burden at the expense of fault tolerance and security. Please weight the pros and cons and, if in doubt, stick to a 1:1 approach. + + ## Define the component -Define your component using a [component spec]({{< ref component-schema.md >}}). Your component's `type` is derived from the socket name, without the file extension. +Define your component using a [component spec]({{< ref component-schema.md >}}). Your component's `spec.type` value is made by concatenating the following 2 parts with a `.`: +1. the component's **building block type** (`state`, `pubsub` etc) +2. its **name**, which is derived from the socket name, without the file extension. -Save the component YAML file in the resources-path, replacing: +You will need to define one [component spec]({{< ref component-schema.md >}}) for each building block exposed by your pluggable component's [Unix Domain Socket][uds]. From the example above, the UDS `my-component.sock` from the previous example, exposes a pluggable component named `my-component` with both a `state` and a `pubsub` building blocks. Two components specs, each in their own YAML file placed in the resouces-path, will be required, one for `state.my-component` and another for `pubsub.my-component`. -- `your_socket_goes_here` with your component socket name (no extension) -- `your_component_type` with your component type +For instance, the component spec for `state.my-component` could be as follow ```yaml apiVersion: dapr.io/v1alpha1 kind: Component metadata: - name: prod-mystore -spec: - type: your_component_type.your_socket_goes_here - version: v1 - metadata: -``` - -Using the previous `my-component.sock` example: - -- `your_component_type` would be replaced by `state`, as it is a state store. -- `your_socket_goes_here` would be replaced by `my-component`. - -The configuration example for `my-component` is below: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: prod-mystore + name: my-production-state-store spec: type: state.my-component version: v1 metadata: ``` -Save this file as `component.yaml` in Dapr's component configuration folder. +In this sample above, notice the following: +* The contents of the field `spec.type` is `state.my-component`: this refers to a State Store being exposed as a pluggable component named `my-component`. +* The field `metadata.name`, which is the name of the state store beging defined here, is not related with the pluggable component name. + +Save this file as `component.yaml` in Dapr's component configuration folder. Just like the contents of `metadata.name` field, the filename for this YAML file has no impact and does not depend on the pluggable component name. ## Run Dapr From e5b36e2c1c410fe2a7ba1747ebf33f0fbd306cbe Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Wed, 8 Feb 2023 15:27:53 -0800 Subject: [PATCH 2/7] Update daprdocs/content/en/operations/components/pluggable-components-registration.md Co-authored-by: Phillip Hoff Signed-off-by: Tiago Alves Macambira --- .../operations/components/pluggable-components-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index d581414f5..f44077399 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -68,7 +68,7 @@ Define your component using a [component spec]({{< ref component-schema.md >}}). You will need to define one [component spec]({{< ref component-schema.md >}}) for each building block exposed by your pluggable component's [Unix Domain Socket][uds]. From the example above, the UDS `my-component.sock` from the previous example, exposes a pluggable component named `my-component` with both a `state` and a `pubsub` building blocks. Two components specs, each in their own YAML file placed in the resouces-path, will be required, one for `state.my-component` and another for `pubsub.my-component`. -For instance, the component spec for `state.my-component` could be as follow +For instance, the component spec for `state.my-component` could be: ```yaml apiVersion: dapr.io/v1alpha1 From a289c83faa2aa393b9028b7d524d18ca1133364e Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Wed, 8 Feb 2023 15:49:26 -0800 Subject: [PATCH 3/7] Update daprdocs/content/en/operations/components/pluggable-components-registration.md Signed-off-by: Tiago Alves Macambira --- .../operations/components/pluggable-components-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index f44077399..4f57236d5 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -53,7 +53,7 @@ Filenames in this folder are significant for component registration. They must b Since you are running Dapr in the same host as the component, verify this folder and the files within it are accessible and writable by both your component and Dapr. -### Building-blocks discovery from behind the same component +### Component discovery and multiplexing A pluggable component accessible through a [Unix Domain Socket][uds] can host multiple distinct bulding blocks. During the components initial discovery process, Dapr will use reflection to enumerate all building blocks behind a UDS. The `my-component` pluggable component from the example above could contain both a state store (`state`) and a Pub/Sub (`pubsub`) building-blocks. From b9b58d8cfa2333ab75c75ff0b4dd232c3fe69b44 Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Wed, 8 Feb 2023 21:07:28 -0800 Subject: [PATCH 4/7] Update daprdocs/content/en/operations/components/pluggable-components-registration.md Co-authored-by: Mark Fussell Signed-off-by: Tiago Alves Macambira --- .../operations/components/pluggable-components-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index 4f57236d5..85a9be8a6 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -55,7 +55,7 @@ Since you are running Dapr in the same host as the component, verify this folder ### Component discovery and multiplexing -A pluggable component accessible through a [Unix Domain Socket][uds] can host multiple distinct bulding blocks. During the components initial discovery process, Dapr will use reflection to enumerate all building blocks behind a UDS. The `my-component` pluggable component from the example above could contain both a state store (`state`) and a Pub/Sub (`pubsub`) building-blocks. +A pluggable component accessible through a [Unix Domain Socket][UDS] can host multiple distinct component APIs . During the components' initial discovery process, Dapr uses reflection to enumerate all the component APIs behind a UDS. The `my-component` pluggable component in the example above can contain both state store (`state`) and a pub/sub (`pubsub`) component APIs. The most common use-case is for a 1:1 mapping between pluggable components and building blocks they expose. That said, having the possibility of consolidating multiple building blocks under the same pluggable components might be healpful, specially to ease DevOps burden at the expense of fault tolerance and security. Please weight the pros and cons and, if in doubt, stick to a 1:1 approach. From 8da777f8e83781816e68cf9c17277615703ba09a Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Thu, 9 Feb 2023 19:26:34 -0800 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Tiago Alves Macambira --- .../pluggable-components-registration.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index 85a9be8a6..a4dda6ddf 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -49,7 +49,7 @@ Both your component and the Unix Socket must be running before Dapr starts. By default, Dapr looks for [Unix Domain Socket][uds] files in the folder in `/tmp/dapr-components-sockets`. -Filenames in this folder are significant for component registration. They must be formed by appending the component's **name** with a file extension of your choice, more commonly `.sock`. For example, the filename `my-component.sock` is a valid UDS file name for a component named `my-component`. +Filenames in this folder are significant for component registration. They must be formed by appending the component's **name** with a file extension of your choice, more commonly `.sock`. For example, the filename `my-component.sock` is a valid Unix Domain Socket file name for a component named `my-component`. Since you are running Dapr in the same host as the component, verify this folder and the files within it are accessible and writable by both your component and Dapr. @@ -57,16 +57,16 @@ Since you are running Dapr in the same host as the component, verify this folder A pluggable component accessible through a [Unix Domain Socket][UDS] can host multiple distinct component APIs . During the components' initial discovery process, Dapr uses reflection to enumerate all the component APIs behind a UDS. The `my-component` pluggable component in the example above can contain both state store (`state`) and a pub/sub (`pubsub`) component APIs. -The most common use-case is for a 1:1 mapping between pluggable components and building blocks they expose. That said, having the possibility of consolidating multiple building blocks under the same pluggable components might be healpful, specially to ease DevOps burden at the expense of fault tolerance and security. Please weight the pros and cons and, if in doubt, stick to a 1:1 approach. +Typically, a pluggable component implements a single component API for packaging and deployment. However, at the expense of having dependencies and security, a pluggable component can have multiple component APIs implemented to ease the deployment burden. Best practice for isolation, fault tolerance, and security is a single component API implementation for each pluggable component. ## Define the component Define your component using a [component spec]({{< ref component-schema.md >}}). Your component's `spec.type` value is made by concatenating the following 2 parts with a `.`: -1. the component's **building block type** (`state`, `pubsub` etc) -2. its **name**, which is derived from the socket name, without the file extension. +1. The component's API (`state`, `pubsub`, `bindings`, etc) +2. The component's **name**, which is derived from the socket name, without the file extension. -You will need to define one [component spec]({{< ref component-schema.md >}}) for each building block exposed by your pluggable component's [Unix Domain Socket][uds]. From the example above, the UDS `my-component.sock` from the previous example, exposes a pluggable component named `my-component` with both a `state` and a `pubsub` building blocks. Two components specs, each in their own YAML file placed in the resouces-path, will be required, one for `state.my-component` and another for `pubsub.my-component`. +You will need to define one [component spec]({{< ref component-schema.md >}}) for each API exposed by your pluggable component's [Unix Domain Socket][uds]. The Unix Domain Socket `my-component.sock` from the previous example exposes a pluggable component named `my-component` with both a `state` and a `pubsub` API. Two components specs, each in their own YAML file, placed in the `resources-path`, will be required: one for `state.my-component` and another for `pubsub.my-component`. For instance, the component spec for `state.my-component` could be: @@ -81,9 +81,9 @@ spec: metadata: ``` -In this sample above, notice the following: -* The contents of the field `spec.type` is `state.my-component`: this refers to a State Store being exposed as a pluggable component named `my-component`. -* The field `metadata.name`, which is the name of the state store beging defined here, is not related with the pluggable component name. +In the sample above, notice the following: +* The contents of the field `spec.type` is `state.my-component`, referring to a state store being exposed as a pluggable component named `my-component`. +* The field `metadata.name`, which is the name of the state store being defined here, is not related to the pluggable component name. Save this file as `component.yaml` in Dapr's component configuration folder. Just like the contents of `metadata.name` field, the filename for this YAML file has no impact and does not depend on the pluggable component name. From 40ecf2894a4be5e542fee7dbc4124c9bfcd9d0d2 Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Fri, 10 Feb 2023 09:41:11 -0800 Subject: [PATCH 6/7] Update daprdocs/content/en/operations/components/pluggable-components-registration.md Signed-off-by: Tiago Alves Macambira --- .../operations/components/pluggable-components-registration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index a4dda6ddf..5454c30c6 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -57,7 +57,7 @@ Since you are running Dapr in the same host as the component, verify this folder A pluggable component accessible through a [Unix Domain Socket][UDS] can host multiple distinct component APIs . During the components' initial discovery process, Dapr uses reflection to enumerate all the component APIs behind a UDS. The `my-component` pluggable component in the example above can contain both state store (`state`) and a pub/sub (`pubsub`) component APIs. -Typically, a pluggable component implements a single component API for packaging and deployment. However, at the expense of having dependencies and security, a pluggable component can have multiple component APIs implemented to ease the deployment burden. Best practice for isolation, fault tolerance, and security is a single component API implementation for each pluggable component. +Typically, a pluggable component implements a single component API for packaging and deployment. However, at the expense of increasing its dependencies and broadening its security attack surface, a pluggable component can have multiple component APIs implemented. This could be done to ease the deployment and monitoring burden. Best practice for isolation, fault tolerance, and security is a single component API implementation for each pluggable component. ## Define the component From 8f21d81643c7c7670da50064791dd9f1bf63f020 Mon Sep 17 00:00:00 2001 From: Tiago Alves Macambira Date: Fri, 10 Feb 2023 09:50:08 -0800 Subject: [PATCH 7/7] Some nitpicking fixes * define acronym UDS right at the top of the document so we can use it later on * no comma before etc. * socket -> UDS filename Signed-off-by: Tiago Alves Macambira --- .../components/pluggable-components-registration.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/daprdocs/content/en/operations/components/pluggable-components-registration.md b/daprdocs/content/en/operations/components/pluggable-components-registration.md index 5454c30c6..97d27e3db 100644 --- a/daprdocs/content/en/operations/components/pluggable-components-registration.md +++ b/daprdocs/content/en/operations/components/pluggable-components-registration.md @@ -10,7 +10,7 @@ description: "Learn how to register a pluggable component" ## Component registration process -[Pluggable, gRPC-based components]({{< ref pluggable-components-overview >}}) are typically run as containers or processes that need to communicate with the Dapr runtime via [Unix Domain Sockets][uds]. They are automatically discovered and registered in the runtime with the following steps: +[Pluggable, gRPC-based components]({{< ref pluggable-components-overview >}}) are typically run as containers or processes that need to communicate with the Dapr runtime via [Unix Domain Sockets][uds] (or UDS for short). They are automatically discovered and registered in the runtime with the following steps: 1. The component listens to an [Unix Domain Socket][uds] placed on the shared volume. 2. The Dapr runtime lists all [Unix Domain Socket][uds] in the shared volume. @@ -55,7 +55,7 @@ Since you are running Dapr in the same host as the component, verify this folder ### Component discovery and multiplexing -A pluggable component accessible through a [Unix Domain Socket][UDS] can host multiple distinct component APIs . During the components' initial discovery process, Dapr uses reflection to enumerate all the component APIs behind a UDS. The `my-component` pluggable component in the example above can contain both state store (`state`) and a pub/sub (`pubsub`) component APIs. +A pluggable component accessible through a [Unix Domain Socket][UDS] (UDS) can host multiple distinct component APIs . During the components' initial discovery process, Dapr uses reflection to enumerate all the component APIs behind a UDS. The `my-component` pluggable component in the example above can contain both state store (`state`) and a pub/sub (`pubsub`) component APIs. Typically, a pluggable component implements a single component API for packaging and deployment. However, at the expense of increasing its dependencies and broadening its security attack surface, a pluggable component can have multiple component APIs implemented. This could be done to ease the deployment and monitoring burden. Best practice for isolation, fault tolerance, and security is a single component API implementation for each pluggable component. @@ -63,8 +63,8 @@ Typically, a pluggable component implements a single component API for packaging ## Define the component Define your component using a [component spec]({{< ref component-schema.md >}}). Your component's `spec.type` value is made by concatenating the following 2 parts with a `.`: -1. The component's API (`state`, `pubsub`, `bindings`, etc) -2. The component's **name**, which is derived from the socket name, without the file extension. +1. The component's API (`state`, `pubsub`, `bindings` etc) +2. The component's **name**, which is derived from the [Unix Domain Socket][uds] filename, without the file extension. You will need to define one [component spec]({{< ref component-schema.md >}}) for each API exposed by your pluggable component's [Unix Domain Socket][uds]. The Unix Domain Socket `my-component.sock` from the previous example exposes a pluggable component named `my-component` with both a `state` and a `pubsub` API. Two components specs, each in their own YAML file, placed in the `resources-path`, will be required: one for `state.my-component` and another for `pubsub.my-component`.