Skip to content

Latest commit

 

History

History
113 lines (87 loc) · 8.12 KB

developing-component.md

File metadata and controls

113 lines (87 loc) · 8.12 KB
Raw

Developing new component

This document describes how to build and test new components. The Dapr runtime and all of its components are written in Go. If you are completely new to the language you can take a tour of its features. For building your first component, using an existing one as a template is as a great way to get started.

Prerequisites

  1. Dapr development environment setup
  2. golangci-lint

Clone dapr and component-contrib

We recommend creating a folder for Dapr and clone all repositories in that folder.

mkdir dapr

# Clone dapr
git clone https://github.com/dapr/dapr.git dapr/dapr

# Clone component-contrib
git clone https://github.com/dapr/components-contrib.git dapr/components-contrib

Writing new component

Write new component

  1. Create your component directory in the right component directory.
  2. Copy component files from the reference component to your component directory.
  3. Add Go unit test files for your component.
  4. Add conformance tests for your component.
Type Directory Reference Docs
State components-contrib/state Redis concept, howto, api spec
Pubsub components-contrib/pubsub Redis concept, howto, api spec
Bindings components-contrib/bindings Kafka concept, input howto, output howto, api spec
Secret Store components-contrib/secretstore Kubernetes, Azure Keyvault concept, howto
Middleware components-contrib/middleware Oauth2 concept, howto
Name Resolution components-contrib/nameresolution mdns howto

Running unit-test

make test

Running linting

make lint

Validating with Dapr core

  1. Make sure you clone the dapr/dapr and dapr/components-contrib repositories side-by-side, within the same folder.
  2. In case of compatibility issues between dapr/dapr and dapr/compoments-contrib go.mod files during build, checkout the latest released version of dapr/dapr.
  3. Replace github.com/dapr/components-contrib with a reference to the locally-cloned components-contrib: 
    go mod edit -replace github.com/dapr/components-contrib=../components-contrib
  4. Register your components by creating a file (in the dapr/dapr repo) in cmd/daprd/components, similar to the ones in the folder (one file per component).
  5. Build debuggable dapr binary 
    make modtidy-all
make DEBUG=1 build
  6. Replace the installed daprd with the test binary (the Dapr CLI will then use the test binary): 
    # Back up the current daprd
cp ~/.dapr/bin/daprd ~/.dapr/bin/daprd.bak
cp ./dist/darwin_amd64/debug/daprd ~/.dapr/bin

    Linux debuggable binary: ./dist/linux_amd64/debug/daprd Windows debuggable binary: .\dist\windows_amd64\debug\daprd macOS (Intel) debuggable binary: ./dist/darwin_amd64/debug/daprd macOS (Apple Silicon) debuggable binary: ./dist/darwin_arm64/debug/daprd

  7. Prepare your test app (e.g. see the binding tutorial sample apps: https://github.com/dapr/quickstarts/tree/master/tutorials/bindings/)
  8. Create a YAML for the component in './components' under app's directory (e.g. bindings tutorial: https://github.com/dapr/quickstarts/blob/master/tutorials/bindings/components)
  9. Run your test app using Dapr CLI.
  10. Make sure your component is loaded successfully in the daprd log.

Submit your component

  1. Create a Pull Request to add your component in component-contrib repo
  2. Get the approval from maintainers
  3. Fetch the latest dapr/dapr repo
  4. Update components-contrib in dapr/dapr's go.mod and ensure that components-contrib is updated to the latest version 
    # In the folder where the dapr/dapr repo was cloned
go get -u github.com/dapr/components-contrib@master
make modtidy-all
  5. Register your components by creating a file (in the dapr/dapr repo) in cmd/daprd/components, similar to the ones in the folder (one file per component).
  6. Create a pull request in dapr/dapr.

Version 2 and beyond of a component

API versioning of Dapr components follows the same approach as Go modules where the unstable version (v0) and first stable version (v1) are contained in the root directory of the component package. For example v1 of the Redis binding component is located in bindings/redis. Code changes may continue in this package provided there are no breaking changes. Breaking changes include:

  • Renaming or removing a metadata field that the component is currently using
  • Adding a required metadata field
  • Adding an optional field that does not have a backwards-compatible default value
  • Making significant changes to the component's behavior that would adversely affect existing users

In most cases, breaking changes can be avoided by using backward compatible metadata fields. When breaking changes cannot be avoided, here are the steps for creating the next major version of a component:

  1. Create a version subdirectory for the next major version (e.g. bindings/redis/v2, bindings/redis/v3, etc.)
  2. Copy any code into the new subdirectory that should be preserved from the previous version
  3. Submit your component as described in the previous section
  4. Register your components by creating a new file (in the dapr/dapr repo) in cmd/daprd/components, without removing the file for the previous version. This time, append the new major version to the name, e.g. redis/v2.
  5. Validate your component as described previously