Skip to content

Latest commit

 

History

History
112 lines (87 loc) · 7.85 KB

developing-component.md

File metadata and controls

112 lines (87 loc) · 7.85 KB
Raw

Developing new component

This document describes how to build and test new component. 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

cd $GOPATH/src

# Clone dapr
mkdir -p github.com/dapr/dapr
git clone https://github.com/dapr/dapr.git github.com/dapr/dapr

# Clone component-contrib
mkdir -p github.com/dapr/components-contrib
git clone https://github.com/dapr/components-contrib.git github.com/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 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 Dapr and component-contrib repos under $GOPATH/src/github.com/dapr
  2. Replace github.com/dapr/components-contrib reference to the local component-contrib
go mod edit -replace github.com/dapr/components-contrib=../components-contrib
  1. Import your component to dapr main.go
  2. Register your component in dapr main.go(e.g. binding)
  3. Build debuggable dapr binary
go mod tidy
make DEBUG=1 build
  1. Replace the installed daprd with the test binary (then dapr cli will 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

  1. Prepare your test app (e.g. kafka sample app: https://github.com/dapr/quickstarts/tree/master/bindings/nodeapp/)
  2. Create yaml for bindings in './components' under app’s directory (e.g. kafka example : https://github.com/dapr/quickstarts/blob/master/bindings/components/kafka_bindings.yaml)
  3. Run your test app using dapr cli
  4. Make sure your component is loaded successfully in daprd log

Submit your component

  1. Create a pullrequest to add your component in component-contrib repo
  2. Get the approval from maintainers
  3. Fetch the latest dapr/dapr repo
  4. Update component-contrib go mod and ensure that component-contrib is updated to the latest version
go get -u github.com/dapr/components-contrib@master
make modtidy-all
  1. Import your component to Dapr main.go
  2. Register your component in Dapr main.go
  3. Create a pullrequest in 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 backward 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. Import your component to Dapr main.go without removing the package for the previous version
  5. Register your component in dapr main.go like before, but append its new major version to the name (e.g. redis/v2)
  6. Validate your component as described previously