mirror of https://github.com/dapr/docs.git
Docs/pluggable components (#2875)
* Pluggable Components Docs and Overview Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Fix plural dapr configs Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Fix dapr links Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Link unix domain sockets Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-discovery.md Co-authored-by: Tiago Alves Macambira <macambira@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-discovery.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/concepts/components-concept.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Update daprdocs/content/en/operations/components/pluggable-components/pluggable-components-overview.md Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Rearrange protobuf text Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Add pluggable component as a preview feature Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Replace gRPC-based to pluggable Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Fix sections weight Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Added UNIX-like system prereq Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Tiago Alves Macambira <macambira@gmail.com> Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Mark Fussell <markfussell@gmail.com> Co-authored-by: Tiago Alves Macambira <macambira@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Tiago Alves Macambira <macambira@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Rename discovery to registration Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Add alert note on certification lifecycle Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Tiago Alves Macambira <tmacam@burocrata.org> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Reorder the text and adding Built-in Signed-off-by: Mark Fussell <markfussell@gmail.com> * Fixing link Signed-off-by: Mark Fussell <markfussell@gmail.com> * Edits Signed-off-by: Mark Fussell <markfussell@gmail.com> * edits Signed-off-by: Mark Fussell <markfussell@gmail.com> * Fixing up table Signed-off-by: Mark Fussell <markfussell@gmail.com> * revert package-lock change Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Apply suggestions from code review Co-authored-by: Tiago Alves Macambira <tmacam@burocrata.org> Co-authored-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Remove localization from url Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Add new grpc-components diagram Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Rename image Signed-off-by: Marcos Candeia <marrcooos@gmail.com> * Change exe to process Signed-off-by: Marcos Candeia <marrcooos@gmail.com> Signed-off-by: Marcos Candeia <marrcooos@gmail.com> Signed-off-by: Mark Fussell <markfussell@gmail.com> Signed-off-by: Tiago Alves Macambira <tmacam@burocrata.org> Co-authored-by: Mark Fussell <markfussell@gmail.com> Co-authored-by: Tiago Alves Macambira <macambira@gmail.com> Co-authored-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Co-authored-by: Tiago Alves Macambira <tmacam@burocrata.org>
This commit is contained in:
Marcos Candeia
GitHub
parent
4d860db7e1
commit
b3bdd51771
|
|
@ -6,21 +6,48 @@ weight: 300
|
|||
description: "Modular functionality used by building blocks and applications"
|
||||
---
|
||||
|
||||
Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are pluggable so that you can swap out one component with the same interface for another. The [components contrib repository](https://github.com/dapr/components-contrib) is where you can contribute implementations for the component interfaces and extend Dapr's capabilities.
|
||||
Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are interchangable so that you can swap out one component with the same interface for another.
|
||||
|
||||
A building block can use any combination of components. For example the [actors]({{<ref "actors-overview.md">}}) building block and the [state management]({{<ref "state-management-overview.md">}}) building block both use [state components](https://github.com/dapr/components-contrib/tree/master/state). As another example, the [pub/sub]({{<ref "pubsub-overview.md">}}) building block uses [pub/sub components](https://github.com/dapr/components-contrib/tree/master/pubsub).
|
||||
You can contribute implementations and extend Dapr's component interfaces capabilities via:
|
||||
|
||||
You can get a list of current components available in the hosting environment using the `dapr components` CLI command.
|
||||
- The [components-contrib repository](https://github.com/dapr/components-contrib)
|
||||
- [Pluggable components]({{<ref "components-concept.md#pluggable-components" >}}).
|
||||
|
||||
A building block can use any combination of components. For example, the [actors]({{<ref "actors-overview.md">}}) and the [state management]({{<ref "state-management-overview.md">}}) building blocks both use [state components](https://github.com/dapr/components-contrib/tree/master/state).
|
||||
|
||||
As another example, the [pub/sub]({{<ref "pubsub-overview.md">}}) building block uses [pub/sub components](https://github.com/dapr/components-contrib/tree/master/pubsub).
|
||||
|
||||
You can get a list of current components available in the hosting environment using the `dapr components` CLI command.
|
||||
|
||||
## Component specification
|
||||
|
||||
Each component has a specification (or spec) that it conforms to. Components are configured at design-time with a YAML file which is stored in either a `components/local` folder within your solution, or globally in the `.dapr` folder created when invoking `dapr init`. These YAML files adhere to the generic [Dapr component schema]({{<ref "component-schema.md">}}), but each is specific to the component specification.
|
||||
Each component has a specification (or spec) that it conforms to. Components are configured at design-time with a YAML file which is stored in either:
|
||||
|
||||
- A `components/local` folder within your solution, or
|
||||
- Globally in the `.dapr` folder created when invoking `dapr init`.
|
||||
|
||||
These YAML files adhere to the generic [Dapr component schema]({{<ref "component-schema.md">}}), but each is specific to the component specification.
|
||||
|
||||
It is important to understand that the component spec values, particularly the spec `metadata`, can change between components of the same component type, for example between different state stores, and that some design-time spec values can be overridden at runtime when making requests to a component's API. As a result, it is strongly recommended to review a [component's specs]({{<ref "components-reference">}}), paying particular attention to the sample payloads for requests to set the metadata used to interact with the component.
|
||||
|
||||
The diagram below shows some examples of the components for each component type
|
||||
<img src="/images/concepts-components.png" width=1200>
|
||||
|
||||
## Built-in and pluggable components
|
||||
|
||||
Dapr has built-in components that are included as part of the runtime. These are public components that are developed and donated by the community and are available to use in every release.
|
||||
|
||||
Dapr also allows for users to create their own private components called pluggable components. These are components that are self-hosted (process or container), do not need to be written in Go, exist outside the Dapr runtime, and are able to "plug" into Dapr to utilize the building block APIs.
|
||||
|
||||
Where possible, donating built-in components to the Dapr project and community is encouraged.
|
||||
|
||||
However, pluggable components are ideal for scenarios where you want to create your own private components that are not included into the Dapr project.
|
||||
For example:
|
||||
- Your component may be specific to your company or pose IP concerns, so it cannot be included in the Dapr component repo.
|
||||
- You want decouple your component updates from the Dapr release cycle.
|
||||
|
||||
For more information read [Pluggable components overview]({{<ref "pluggable-components-overview">}})
|
||||
|
||||
## Available component types
|
||||
|
||||
The following are the component types provided by Dapr:
|
||||
|
|
@ -76,7 +103,11 @@ Lock components are used as a distributed lock to provide mutually exclusive acc
|
|||
|
||||
### Middleware
|
||||
|
||||
Dapr allows custom [middleware]({{<ref "middleware.md">}}) to be plugged into the HTTP request processing pipeline. Middleware can perform additional actions on an HTTP request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the response is returned to the client. The middleware components are used with the [service invocation]({{<ref "service-invocation-overview.md">}}) building block.
|
||||
Dapr allows custom [middleware]({{<ref "middleware.md">}}) to be plugged into the HTTP request processing pipeline. Middleware can perform additional actions on an HTTP request (such as authentication, encryption, and message transformation) before the request is routed to the user code, or the response is returned to the client. The middleware components are used with the [service invocation]({{<ref "service-invocation-overview.md">}}) building block.
|
||||
|
||||
- [List of supported middleware components]({{< ref supported-middleware >}})
|
||||
- [Middleware implementations](https://github.com/dapr/components-contrib/tree/master/middleware)
|
||||
- [Middleware implementations](https://github.com/dapr/components-contrib/tree/master/middleware)
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Since pluggable components are not required to be written in Go, they follow a different implementation process than built-in Dapr components. For more information on developing built-in components, read [developing new components](https://github.com/dapr/components-contrib/blob/master/docs/developing-component.md).
|
||||
{{% /alert %}}
|
||||
|
|
|
|||
|
|
@ -6,20 +6,26 @@ weight: 200
|
|||
description: "The component certification lifecycle from submission to production ready"
|
||||
---
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Certification lifecycle only applies to built-in components and does not apply to [pluggable components]({{<ref "components-concept.md#Built-in-and-pluggable-components" >}}).
|
||||
{{% /alert %}}
|
||||
|
||||
## Overview
|
||||
|
||||
Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are pluggable so that in ideal scenarios, you can swap out one component with the same interface for another. Each component that is used in production, needs to maintain a certain set of technical requirements that ensure the functional compatibility and robustness of the component.
|
||||
Dapr uses a modular design where functionality is delivered as a component. Each component has an interface definition. All of the components are interchangable so that in ideal scenarios, you can swap out one component with the same interface for another. Each component that is used in production, needs to maintain a certain set of technical requirements that ensure the functional compatibility and robustness of the component.
|
||||
|
||||
In general a component needs to be:
|
||||
- compliant with the defined Dapr interfaces
|
||||
- functionally correct and robust
|
||||
- well documented and maintained
|
||||
|
||||
- Compliant with the defined Dapr interfaces
|
||||
- Functionally correct and robust
|
||||
- Well documented and maintained
|
||||
|
||||
To make sure a component conforms to the standards set by Dapr, there are a set of tests run against a component in a Dapr maintainers managed environment. Once the tests pass consistently, the maturity level can be determined for a component.
|
||||
|
||||
## Certification levels
|
||||
|
||||
The levels are as follows:
|
||||
|
||||
- [Alpha](#alpha)
|
||||
- [Beta](#beta)
|
||||
- [Stable](#stable)
|
||||
|
|
@ -90,7 +96,6 @@ The test plan must be approved by a Dapr maintainer and be published in a `READM
|
|||
- The tests should validate the functional behavior and robustness of the component based on the component specification, reflecting the scenarios from the test plan
|
||||
- The tests must run successfully as part of the continuous integration of the [components-contrib](https://github.com/dapr/components-contrib) repository
|
||||
|
||||
|
||||
## Component certification process
|
||||
|
||||
In order for a component to be certified, tests are run in an environment maintained by the Dapr project.
|
||||
|
|
@ -98,19 +103,21 @@ In order for a component to be certified, tests are run in an environment mainta
|
|||
### New component certification: Alpha->Beta
|
||||
|
||||
For a new component requiring a certification change from Alpha to Beta, a request for component certification follows these steps:
|
||||
|
||||
- Requestor creates an issue in the [components-contrib](https://github.com/dapr/components-contrib) repository for certification of the component with the current and the new certification levels
|
||||
- Requestor submits a PR to integrate the component with the defined conformance test suite, if not already included
|
||||
- The user details the environment setup in the issue created, so a Dapr maintainer can setup the service in a managed environment
|
||||
- After the environment setup is complete, Dapr maintainers review the PR and if approved merges that PR
|
||||
- The user details the environment setup in the issue created, so a Dapr maintainer can setup the service in a managed environment
|
||||
- After the environment setup is complete, Dapr maintainers review the PR and if approved merges that PR
|
||||
- Requestor submits a PR in the [docs](https://github.com/dapr/docs) repository, updating the component's certification level
|
||||
|
||||
### New component certification: Beta->Stable
|
||||
|
||||
For a new component requiring a certification change from Beta to Stable, a request for component certification follows these steps:
|
||||
|
||||
- Requestor creates an issue in the [components-contrib](https://github.com/dapr/components-contrib) repository for certification of the component with the current and the new certification levels
|
||||
- Requestor submits a PR for the test plan as a `README.md` file in the component's source code directory
|
||||
- The requestor details the test environment requirements in the created PR, including any manual steps or credentials needed
|
||||
- A Dapr maintainer reviews the test plan, provides feedback or approves it, and eventually merges the PR
|
||||
- The requestor details the test environment requirements in the created PR, including any manual steps or credentials needed
|
||||
- A Dapr maintainer reviews the test plan, provides feedback or approves it, and eventually merges the PR
|
||||
- Requestor submits a PR for the automated certification tests, including scripts to provision resources when applicable
|
||||
- After the test environment setup is completed and credentials provisioned, Dapr maintainers review the PR and, if approved, merges the PR
|
||||
- Requestor submits a PR in the [docs](https://github.com/dapr/docs) repository, updating the component's certification level
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Pluggable Components"
|
||||
linkTitle: "Pluggable Components"
|
||||
description: "Guidance on how to work with pluggable components"
|
||||
weight: 4000
|
||||
aliases:
|
||||
- "/operations/components/pluggable-components/pluggable-components-overview/"
|
||||
---
|
||||
|
|
@ -0,0 +1,134 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Pluggable components overview"
|
||||
linkTitle: "Overview"
|
||||
weight: 4400
|
||||
description: "Overview of pluggable component anatomy and supported component types"
|
||||
---
|
||||
|
||||
Pluggable components are components that are not included as part the runtime, as opposed to built-in ones that are included. You can configure Dapr to use pluggable components that leverage the building block APIs, but these are registered differently from the [built-in Dapr components](https://github.com/dapr/components-contrib). For example, you can configure a pluggable component for scenarios where you require a private component.
|
||||
|
||||
<img src="/images/concepts-building-blocks.png" width=400>
|
||||
|
||||
## Pluggable components vs. built-in components
|
||||
|
||||
Dapr provides two approaches for registering and creating components:
|
||||
|
||||
- The built-in components included in the runtime and found in the [components-contrib repository ](https://github.com/dapr/components-contrib).
|
||||
- Pluggable components which are deployed and registered independently.
|
||||
|
||||
While both registration options leverage Dapr's building block APIs, each has a different implementation processes.
|
||||
|
||||
| Component details | [Built-in Component](https://github.com/dapr/components-contrib/blob/master/docs/developing-component.md) | Pluggable Components |
|
||||
| ---------------------------- | :--------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Language** | Can only be written in Go | [Can be written in any gRPC-supported language](https://grpc.io/docs/what-is-grpc/introduction/#protocol-buffer-versions) |
|
||||
| **Where it runs** | As part of the Dapr runtime executable | As a distinct process or container in a pod. Runs separate from Dapr itself. |
|
||||
| **Registers with Dapr** | Included into the Dapr codebase | Registers with Dapr via Unix Domain Sockets (using gRPC ) |
|
||||
| **Distribution** | Distributed with Dapr release. New features added to component are aligned with Dapr releases | Distributed independently from Dapr itself. New features can be added when needed and follows its own release cycle. |
|
||||
| **How component is activated** | Dapr starts runs the component (automatic) | User starts component (manual) |
|
||||
|
||||
## When to create a pluggable component
|
||||
|
||||
- This is a private component.
|
||||
- You want to keep your component separate from the Dapr release process.
|
||||
- You are not as familiar with Go, or implementing your component in Go is not ideal.
|
||||
|
||||
## Implementing a pluggable component
|
||||
|
||||
In order to implement a pluggable component you need to implement a gRPC service in the component. Implementing the gRPC service requires three steps:
|
||||
|
||||
1. **Find the proto definition file.** Proto definitions are provided for each supported service interface (state store, pub/sub, bindings).
|
||||
|
||||
Currently, the following component APIs are supported:
|
||||
|
||||
- State stores
|
||||
- Pub/sub
|
||||
- Bindings
|
||||
|
||||
|
||||
| Component | Type | gRPC definition | Built-in Reference Implementation | Docs |
|
||||
| :---------: | :--------: | :--------------: | :----------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| State Store | `state` | [state.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/state/redis) | [concept]({{<ref "state-management-overview">}}), [howto]({{<ref "howto-get-save-state">}}), [api spec]({{<ref "state_api">}}) |
|
||||
| Pub/sub | `pubsub` | [pubsub.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/pubsub/redis) | [concept]({{<ref "pubsub-overview">}}), [howto]({{<ref "howto-publish-subscribe">}}), [api spec]({{<ref "pubsub_api">}}) |
|
||||
| Bindings | `bindings` | [bindings.proto] | [Kafka](https://github.com/dapr/components-contrib/tree/master/bindings/kafka) | [concept]({{<ref "bindings-overview">}}), [input howto]({{<ref "howto-triggers">}}), [output howto]({{<ref "howto-bindings">}}), [api spec]({{<ref "bindings_api">}}) |
|
||||
|
||||
Here's a snippet of the gRPC service definition for pluggable component state stores ([state.proto]).
|
||||
|
||||
```protobuf
|
||||
// StateStore service provides a gRPC interface for state store components.
|
||||
service StateStore {
|
||||
// Initializes the state store component with the given metadata.
|
||||
rpc Init(InitRequest) returns (InitResponse) {}
|
||||
// Returns a list of implemented state store features.
|
||||
rpc Features(FeaturesRequest) returns (FeaturesResponse) {}
|
||||
// Ping the state store. Used for liveness purposes.
|
||||
rpc Ping(PingRequest) returns (PingResponse) {}
|
||||
|
||||
// Deletes the specified key from the state store.
|
||||
rpc Delete(DeleteRequest) returns (DeleteResponse) {}
|
||||
// Get data from the given key.
|
||||
rpc Get(GetRequest) returns (GetResponse) {}
|
||||
// Sets the value of the specified key.
|
||||
rpc Set(SetRequest) returns (SetResponse) {}
|
||||
|
||||
|
||||
// Deletes many keys at once.
|
||||
rpc BulkDelete(BulkDeleteRequest) returns (BulkDeleteResponse) {}
|
||||
// Retrieves many keys at once.
|
||||
rpc BulkGet(BulkGetRequest) returns (BulkGetResponse) {}
|
||||
// Set the value of many keys at once.
|
||||
rpc BulkSet(BulkSetRequest) returns (BulkSetResponse) {}
|
||||
}
|
||||
```
|
||||
|
||||
The interface for the `StateStore` service exposes 9 methods:
|
||||
|
||||
- 2 methods for initialization and components capability advertisement (Init and Features)
|
||||
- 1 method for health-ness or liveness check (Ping)
|
||||
- 3 methods for CRUD (Get, Set, Delete)
|
||||
- 3 methods for bulk CRUD operations (BulkGet, BulkSet, BulkDelete)
|
||||
|
||||
2. **Create service scaffolding.** Use [protocol buffers and gRPC tools](https://grpc.io) to create the necessary scaffolding for the service. You may want to get acquainted with [the gRPC concepts documentation](https://grpc.io/docs/what-is-grpc/core-concepts/).
|
||||
|
||||
The tools can generate code targeting [any gRPC-supported language](https://grpc.io/docs/what-is-grpc/introduction/#protocol-buffer-versions). This code serves as the base for your server and it provides functionality to handle client calls along with infrastructure to decode incoming requests, execute service methods, and encode service responses.
|
||||
|
||||
The generated code is not complete. It is missing a concrete implementation for the methods your target service defines, i.e., the core of your pluggable component. This is further explored in the next topic. Additionally, you also have to provide code on how to handle Unix Socket Domain integration, which is Dapr specific, and code handling integration with your downstream services.
|
||||
|
||||
3. **Define the service.** Provide a concrete implementation of the desired service.
|
||||
|
||||
As a first step, [protocol buffers](https://developers.google.com/protocol-buffers/docs/overview) and [gRPC](https://grpc.io/docs/what-is-grpc/introduction/) tools are used to create the server code for this service. After that, the next step is to define concrete implementations for these 9 methods.
|
||||
|
||||
Each component has a gRPC service definition for its core functionality which is the same as the core component interface. For example:
|
||||
|
||||
- **State stores**
|
||||
A pluggable state store **must** provide an implementation of the `StateStore` service interface. In addition to this core functionality, some components might also expose functionality under other **optional** services. For example, you can add extra functionality by defining the implementation for a `QueriableStateStore` service and a `TransactionalStateStore` service.
|
||||
|
||||
- **Pub/sub**
|
||||
Pluggable pub/sub components only have a single core service interface defined ([pubsub.proto]). They have no optional service interfaces.
|
||||
|
||||
- **Bindings**
|
||||
Pluggable input and output bindings have a single core service definition on [bindings.proto]. They have no optional service interfaces.
|
||||
|
||||
Following the State Store example from step 1, after generating its service scaffolding code using gRPC and protocol buffers tools (step 2),
|
||||
the next step is to define concrete implementations for the 9 methods defined under `service StateStore`, along with code to initialize and communicate with your dependencies.
|
||||
This concrete implementation and auxiliary code are the core of your pluggable component: they define how your component behaves when handling gRPC requests from Dapr.
|
||||
|
||||
### Leveraging multiple building blocks for a component
|
||||
|
||||
In addition to implementing multiple gRPC services from the same component (for example `StateStore`, `QueriableStateStore`, `TransactionalStateStore` etc.), a pluggable component can also expose implementations for other component interfaces. This means that a single pluggable component can function as a state store, pub/sub, and input or output binding, all at the same time. In other words, you can implement multiple component interfaces into a pluggable component and exposes these as gRPC services.
|
||||
|
||||
While exposing multiple component interfaces on the same pluggable component lowers the operational burden of deploying multiple components, it makes implementing and debugging your component harder. If in doubt, stick to a "separation of concerns" by merging multiple components interfaces into the same pluggable component only when necessary.
|
||||
|
||||
## Operationalizing a pluggable component
|
||||
|
||||
Built-in components and pluggable components share one thing in common: both need a [component specification]({{<ref "components-concept.md#component-specification">}}). Built-in components do not require any extra steps to be used: Dapr is ready to use them automatically.
|
||||
|
||||
In contrast, pluggable components require additional steps before they can communicate with Dapr. You need to first run the component and facilitate Dapr-component communication to kick off the registration process.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Pluggable component registration]({{<ref "pluggable-components-registration">}})
|
||||
|
||||
[state.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/state.proto
|
||||
[pubsub.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/pubsub.proto
|
||||
[bindings.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/bindings.proto
|
||||
|
|
@ -0,0 +1,229 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How-To: Register a pluggable component"
|
||||
linkTitle: "How To: Register a pluggable component"
|
||||
weight: 4500
|
||||
description: "Learn how to register a pluggable component"
|
||||
---
|
||||
|
||||
[uds]: https://en.wikipedia.org/wiki/Unix_domain_socket
|
||||
|
||||
## Component registration process
|
||||
|
||||
Pluggable, [gRPC-based](https://grpc.io/) components 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:
|
||||
|
||||
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.
|
||||
3. The Dapr runtime connects with each socket and uses gRPC reflection to discover all proto services from a given building block API that the component implements.
|
||||
|
||||
A single component can implement multiple component interfaces at once.
|
||||
|
||||
<img src="/images/components-pluggable-register-grpc.png" width=50%>
|
||||
|
||||
While Dapr's built-in components come [included with the runtime](https://github.com/dapr/components-contrib/blob/master/docs/developing-component.md), pluggable components require a few setup steps before they can be used with Dapr.
|
||||
|
||||
1. Pluggable components need to be started and ready to take requests _before_ Dapr itself is started.
|
||||
2. The [Unix Domain Socket][uds] file used for the pluggable component communication need to be made accessible to both Dapr and pluggable component.
|
||||
|
||||
Dapr does not launch any pluggable components processes or containers. This is something that you need to do, and it is different depending on how Dapr and your components are run:
|
||||
|
||||
- In self-hosted mode as processes or containers.
|
||||
- In Kubernetes, as containers.
|
||||
|
||||
This also changes the approach to share [Unix Domain Socket][uds] files between Dapr and pluggable components.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
As a prerequisite the operating system must supports Unix Domain Sockets, any UNIX or UNIX-like system (Mac, Linux, or for local development [WSL](https://learn.microsoft.com/windows/wsl/install) for Windows users) should be sufficient.
|
||||
{{% /alert %}}
|
||||
|
||||
Select your environment to begin making your component discoverable.
|
||||
|
||||
{{< tabs "Standalone" "Kubernetes" >}}
|
||||
|
||||
{{% codetab %}}
|
||||
[uds]: https://en.wikipedia.org/wiki/Unix_domain_socket
|
||||
|
||||
## Run the component
|
||||
|
||||
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`.
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
Save the component YAML file in the components-path, replacing:
|
||||
|
||||
- `your_socket_goes_here` with your component socket name (no extension)
|
||||
- `your_component_type` with your component type
|
||||
|
||||
```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
|
||||
spec:
|
||||
type: state.my-component
|
||||
version: v1
|
||||
metadata:
|
||||
```
|
||||
|
||||
Save this file as `component.yaml` in Dapr's component configuration folder.
|
||||
|
||||
## Run Dapr
|
||||
|
||||
[Initialize Dapr]({{< ref get-started-api.md >}}), and make sure that your component file is placed in the right folder.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Dapr v1.9.0 is the minimum version that supports pluggable components.
|
||||
Run the following command specify the runtime version: `dapr init --runtime-version 1.9.0`
|
||||
{{% /alert %}}
|
||||
|
||||
<!-- We should list the actual command line the user will be typing here -->
|
||||
|
||||
That's it! Now you're able to call the state store APIs via Dapr API. See it in action by running the following. Replace `$PORT` with the Dapr HTTP port:
|
||||
|
||||
```shell
|
||||
curl -X POST -H "Content-Type: application/json" -d '[{ "key": "name", "value": "Bruce Wayne", "metadata": {}}]' http://localhost:$PORT/v1.0/state/prod-mystore
|
||||
```
|
||||
|
||||
Retrieve the value, replacing `$PORT` with the Dapr HTTP port:
|
||||
|
||||
```shell
|
||||
curl http://localhost:$PORT/v1.0/state/prod-mystore/name
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
[uds]: https://en.wikipedia.org/wiki/Unix_domain_socket
|
||||
|
||||
## Build and publish a container for your pluggable component
|
||||
|
||||
Make sure your component is running as a container, published first and accessible to your Kubernetes cluster.
|
||||
|
||||
## Deploy Dapr on a Kubernetes cluster
|
||||
|
||||
Follow the steps provided in the [Deploy Dapr on a Kubernetes cluster]({{< ref kubernetes-deploy.md >}}) docs.
|
||||
|
||||
## Add the pluggable component container in your deployments
|
||||
|
||||
When running in Kubernetes mode, pluggable components are deployed as containers in the same pod as your application.
|
||||
|
||||
Since pluggable components are backed by [Unix Domain Sockets][uds], make the socket created by your pluggable component accessible by Dapr runtime. Configure the deployment spec to:
|
||||
|
||||
1. Mount volumes
|
||||
2. Hint to Dapr the mounted Unix socket volume location
|
||||
3. Attach volume to your pluggable component container
|
||||
|
||||
Below is an example of a deployment that configures a pluggable component:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: app
|
||||
labels:
|
||||
app: app
|
||||
spec:
|
||||
replicas: 1
|
||||
selector:
|
||||
matchLabels:
|
||||
app: app
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: app
|
||||
annotations:
|
||||
dapr.io/unix-domain-socket-path: "/tmp/dapr-components-sockets" ## required, the default path where Dapr uses for registering components.
|
||||
dapr.io/app-id: "my-app"
|
||||
dapr.io/enabled: "true"
|
||||
spec:
|
||||
volumes: ## required, the sockets volume
|
||||
- name: dapr-unix-domain-socket
|
||||
emptyDir: {}
|
||||
containers:
|
||||
### --------------------- YOUR APPLICATION CONTAINER GOES HERE -----------
|
||||
##
|
||||
### --------------------- YOUR APPLICATION CONTAINER GOES HERE -----------
|
||||
### This is the pluggable component container.
|
||||
- name: component
|
||||
volumeMounts: # required, the sockets volume mount
|
||||
- name: dapr-unix-domain-socket
|
||||
mountPath: /dapr-unix-domain-sockets
|
||||
image: YOUR_IMAGE_GOES_HERE:YOUR_IMAGE_VERSION
|
||||
env:
|
||||
- name: DAPR_COMPONENTS_SOCKETS_FOLDER # Tells the component where the sockets should be created.
|
||||
value: /dapr-unix-domain-sockets
|
||||
```
|
||||
|
||||
Before applying the deployment, let's add one more configuration: the component spec.
|
||||
|
||||
## Define a component
|
||||
|
||||
Pluggable components are defined using a [component spec]({{< ref component-schema.md >}}). The component `type` is derived from the socket name (without the file extension). In the following example YAML, replace:
|
||||
|
||||
- `your_socket_goes_here` with your component socket name (no extension)
|
||||
- `your_component_type` with your component type
|
||||
|
||||
```yaml
|
||||
apiVersion: dapr.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: prod-mystore
|
||||
spec:
|
||||
type: your_component_type.your_socket_goes_here
|
||||
version: v1
|
||||
metadata:
|
||||
scopes:
|
||||
- backend
|
||||
```
|
||||
|
||||
[Scope]({{< ref component-scopes >}}) your component to make sure that only the target application can connect with the pluggable component, since it will only be running in its deployment. Otherwise the runtime fails when initializing the component.
|
||||
|
||||
That's it! **[Apply the created manifests to your Kubernetes cluster](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-apply)**, and call the state store APIs via Dapr API.
|
||||
|
||||
Use [Kubernetes pod forwarder](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/) to access the `daprd` runtime.
|
||||
|
||||
See it in action by running the following. Replace `$PORT` with the Dapr HTTP port:
|
||||
|
||||
```shell
|
||||
curl -X POST -H "Content-Type: application/json" -d '[{ "key": "name", "value": "Bruce Wayne", "metadata": {}}]' http://localhost:$PORT/v1.0/state/prod-mystore
|
||||
```
|
||||
|
||||
Retrieve the value, replacing `$PORT` with the Dapr HTTP port:
|
||||
|
||||
```shell
|
||||
curl http://localhost:$PORT/v1.0/state/prod-mystore/name
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next Steps
|
||||
|
||||
Get started with developing .NET pluggable component using this [sample code](https://github.com/dapr/samples/tree/master/pluggable-components-dotnet-template)
|
||||
|
|
@ -5,7 +5,7 @@ linkTitle: "Preview features"
|
|||
weight: 4000
|
||||
description: "List of current preview features"
|
||||
---
|
||||
Preview features in Dapr are considered experimental when they are first released.
|
||||
Preview features in Dapr are considered experimental when they are first released.
|
||||
|
||||
Runtime preview features require explicit opt-in in order to be used. The runtime opt-in is specified in a preview setting feature in Dapr's application configuration. See [How-To: Enable preview features]({{<ref preview-features>}}) for more information.
|
||||
|
||||
|
|
@ -19,3 +19,4 @@ For CLI there is no explicit opt-in, just the version that this was first made a
|
|||
| **Resiliency** | Allows configuring of fine-grained policies for retries, timeouts and circuitbreaking. | `Resiliency` | [Configure Resiliency Policies]({{<ref "resiliency-overview">}}) | v1.7|
|
||||
| **Service invocation without default `content-type`** | When enabled removes the default service invocation content-type header value `application/json` when no content-type is provided. This will become the default behavior in release v1.9.0. This requires you to explicitly set content-type headers where required for your apps. | `ServiceInvocation.NoDefaultContentType` | [Service Invocation]({{<ref "service_invocation_api.md#request-contents" >}}) | v1.7 |
|
||||
| **App Middleware** | Allow middleware components to be executed when making service-to-service calls | N/A | [App Middleware]({{<ref "middleware.md#app-middleware" >}}) | v1.9 |
|
||||
| **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]({{<ref "components-concept#pluggable-components" >}})| v1.9 |
|
||||
|
|
|
|||
|
|
@ -879,4 +879,4 @@
|
|||
"dev": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 245 KiB |
Loading…
Reference in New Issue