Support and versioning

• 1: Versioning policy
• 2: Supported runtime and SDK releases
• 3: Breaking changes and deprecations
• 4: Reporting security issues
• 5: Preview features
• 6: Alpha and Beta APIs

1 - Versioning policy

Introduction

Dapr is designed for future changes in the runtime, APIs and components with versioning schemes. This topic describes the versioning schemes and strategies for APIs, manifests such as components and Github repositories.

Versioning

Versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software.

• Versioning provides compatibility, explicit change control and handling changes, in particular breaking changes.
• Dapr strives to be backwards compatible. If a breaking change is needed it’ll be announced in advance.
• Deprecated features are done over multiple releases with both new and deprecated features working side-by-side.

Versioning refers to the following Dapr repos: dapr, CLI, stable language SDKs, dashboard, components-contrib, quickstarts, helm-charts and documentation.

Dapr has the following versioning schemes:

• Dapr HTTP API versioned with MAJOR.MINOR
• Dapr GRPC API with MAJOR
• Releases (GitHub repositories including dapr, CLI, SDKs and Helm Chart) with MAJOR.MINOR.PATCH
• Documentation and Quickstarts repositories are versioned with the Dapr runtime repository versioning.
• Dapr Components with MAJOR in components-contrib GitHub repositories.
• Dapr Manifests with MAJOR.MINOR. These include subscriptions and configurations.

Note that the Dapr APIs, binaries releases (runtime, CLI, SDKs) and components are all independent from one another.

Dapr HTTP API

The Dapr HTTP API is versioned according to these REST API guidelines.

Based to the these guidelines;

• A MAJOR version of the API is incremented when a deprecation is expected of the older version. Any such deprecation will be communicated and an upgrade path made available.
• A MINOR versions may be incremented for any other changes. For example a change to the JSON schema of the message sent to the API. The definition of a breaking change to the API can be viewed here.
• Experimental APIs include an “alpha” suffix to denote for their alpha status. For example v1.0alpha, v2.0alpha, etc.

Dapr runtime

Dapr releases use MAJOR.MINOR.PATCH versioning. For example 1.0.0. Read Supported releases for more on the versioning of releases.

Helm Charts

Helm charts in the helm-charts repo are versioned with the Dapr runtime. The Helm charts are used in the Kubernetes deployment

Language SDKs, CLI and dashboard

The Dapr language SDKs, CLI and dashboard are versioned independently from the Dapr runtime and can be released at different schedules. See this table to show the compatibility between versions of the SDKs, CLI, dashboard and runtime. Each new release on the runtime lists the corresponding supported SDKs, CLI and Dashboard.

SDKs, CLIs and Dashboard are versioning follows a MAJOR.MINOR.PATCH format. A major version is incremented when there’s a non-backwards compatible change in an SDK (for example, changing a parameter on a client method. A minor version is updated for new features and bug fixes and the patch version is incremented in case of bug or security hot fixes.

Samples and examples in SDKs version with that repo.

Components

Components are implemented in the components-contrib repository and follow a MAJOR versioning scheme. The version for components adheres to major versions (vX), as patches and non-breaking changes are added to the latest major version. The version is incremented when there’s a non-backwards compatible change in a component interface, for example, changing an existing method in the State Store interface.

The components-contrib repo release is a flat version across all components inside. That is, a version for the components-contrib repo release is made up of all the schemas for the components inside it. A new version of Dapr does not mean there is a new release of components-contrib if there are no component changes.

Note: Components have a production usage lifecycle status: Alpha, Beta and Stable. These statuses are not related to their versioning. The tables of supported components shows both their versions and their status.

• List of state store components
• List of pub/sub components
• List of binding components
• List of secret store components
• List of configuration store components
• List of lock components
• List of crytpography components
• List of middleware components

For more information on component versioning read Version 2 and beyond of a component

Component schemas

Versioning for component YAMLs comes in two forms:

• Versioning for the component manifest. The apiVersion
• Version for the component implementation. The .spec.version

A component manifest includes the schema for an implementation in the .spec.metadata field, with the .type field denoting the implementation

See the comments in the example below:

apiVersion: dapr.io/v1alpha1 # <-- This is the version of the component manifest
kind: Component
metadata:
  name: pubsub
spec:
  version: v1 # <-- This is the version of the pubsub.redis schema implementation
  type: pubsub.redis
  metadata:
  - name: redisHost
    value: redis-master:6379
  - name: redisPassword
    value: general-kenobi

Component manifest version

The Component YAML manifest is versioned with dapr.io/v1alpha1.

Component implementation version

The version for a component implementation is determined by the .spec.version field as can be seen in the example above. The .spec.version field is mandatory in a schema instance and the component fails to load if this is not present. For the release of Dapr 1.0.0 all components are marked as v1.The component implementation version is incremented only for non-backward compatible changes.

Component deprecations

Deprecations of components will be announced two (2) releases ahead. Deprecation of a component, results in major version update of the component version. After 2 releases, the component is unregistered from the Dapr runtime, and trying to load it will throw a fatal exception.

Component deprecations and removal are announced in the release notes.

Quickstarts and Samples

Quickstarts in the Quickstarts repo are versioned with the runtime, where a table of corresponding versions is on the front page of the samples repo. Users should only use Quickstarts corresponding to the version of the runtime being run.

Samples in the Samples repo are each versioned on a case by case basis depending on the sample maintainer. Samples that become very out of date with the runtime releases (many versions behind) or have not been maintained for more than 1 year will be removed.

Related links

• Read the Supported releases
• Read the Breaking Changes and Deprecation Policy

2 - Supported runtime and SDK releases

Introduction

This topic details the supported versions of Dapr releases, the upgrade policies and how deprecations and breaking changes are communicated in all Dapr repositories (runtime, CLI, SDKs, etc) at versions 1.x and above.

Dapr releases use MAJOR.MINOR.PATCH versioning. For example, 1.0.0.

A supported release means:

• A hoxfix patch is released if the release has a critical issue such as a mainline broken scenario or a security issue. Each of these are reviewed on a case by case basis.
• Issues are investigated for the supported releases. If a release is no longer supported, you need to upgrade to a newer release and determine if the issue is still relevant.

From the 1.8.0 release onwards three (3) versions of Dapr are supported; the current and previous two (2) versions. Typically these are MINORrelease updates. This means that there is a rolling window that moves forward for supported releases and it is your operational responsibility to remain up to date with these supported versions. If you have an older version of Dapr you may have to do intermediate upgrades to get to a supported version.

There will be at least 13 weeks (3 months) between major.minor version releases giving users at least a 9 month rolling window for upgrading from a non-supported version. For more details on the release process read release cycle and cadence

Patch support is for supported versions (current and previous).

Build variations

The Dapr’s sidecar image is published to both GitHub Container Registry and Docker Registry. The default image contains all components. From version 1.11, Dapr also offers a variation of the sidecar image, containing only stable components.

• Default sidecar images: daprio/daprd:<version> or ghcr.io/dapr/daprd:<version> (for example ghcr.io/dapr/daprd:1.11.1)
• Sidecar images for stable components: daprio/daprd:<version>-stablecomponents or ghcr.io/dapr/daprd:<version>-stablecomponents (for example ghcr.io/dapr/daprd:1.11.1-stablecomponents)

On Kubernetes, the sidecar image can be overwritten for the application Deployment resource with the dapr.io/sidecar-image annotation. See more about Dapr’s arguments and annotations. The default ‘daprio/daprd:latest’ image is used if not specified.

Learn more about Dapr components’ certification lifecycle.

Supported versions

The table below shows the versions of Dapr releases that have been tested together and form a “packaged” release. Any other combinations of releases are not supported.

SDK compatibility

The SDKs and runtime are committed to non-breaking changes other than those required for security issues. All breaking changes are announced if required in the release notes.

SDK and runtime forward compatibility
Newer Dapr SDKs support the latest version of Dapr runtime and two previous versions (N-2).

SDK and runtime backward compatibility
For a new Dapr runtime, the current SDK version and two previous versions (N-2) are supported.

Upgrade paths

After the 1.0 release of the runtime there may be situations where it is necessary to explicitly upgrade through an additional release to reach the desired target. For example, an upgrade from v1.0 to v1.2 may need to pass through v1.1.

The table below shows the tested upgrade paths for the Dapr runtime. Any other combinations of upgrades have not been tested.

General guidance on upgrading can be found for self hosted mode and Kubernetes deployments. It is best to review the target version release notes for specific guidance.

Upgrade on Hosting platforms

Dapr can support multiple hosting platforms for production. With the 1.0 release the two supported platforms are Kubernetes and physical machines. For Kubernetes upgrades see Production guidelines on Kubernetes

Supported versions of dependencies

Below is a list of software that the latest version of Dapr (v1.15.5) has been tested against.

Related links

• Read the Versioning Policy
• Read the Breaking Changes and Deprecation Policy

3 - Breaking changes and deprecations

Breaking changes

Breaking changes are defined as a change to any of the following that cause compilation errors or undesirable runtime behavior to an existing 3rd party consumer application or script after upgrading to the next stable minor version of a Dapr artifact (SDK, CLI, runtime, etc):

• Code behavior
• Schema
• Default configuration value
• Command line argument
• Published metric
• Kubernetes resource template
• Publicly accessible API
• Publicly visible SDK interface, method, class, or attribute

Breaking changes can be applied right away to the following cases:

• Projects that have not reached version 1.0.0 yet
• Preview feature
• Alpha API
• Preview or Alpha interface, class, method or attribute in SDK
• Dapr Component in Alpha or Beta
• Interfaces for github.com/dapr/components-contrib
• URLs in Docs and Blog
• An exceptional case where it is required to fix a critical bug or security vulnerability.

Process for applying breaking changes

There is a process for applying breaking changes:

1. A deprecation notice must be posted as part of a release.
2. The breaking changes are applied two (2) releases after the release in which the deprecation was announced.
   • For example, feature X is announced to be deprecated in the 1.0.0 release notes and will then be removed in 1.2.0.

Deprecations

Deprecations can apply to:

1. APIs, including alpha APIs
2. Preview features
3. Components
4. CLI
5. Features that could result in security vulnerabilities

Deprecations appear in release notes under a section named “Deprecations”, which indicates:

• The point in the future the now-deprecated feature will no longer be supported. For example release x.y.z. This is at least two (2) releases prior.
• Document any steps the user must take to modify their code, operations, etc if applicable in the release notes.

After announcing a future breaking change, the change will happen in 2 releases or 6 months, whichever is greater. Deprecated features should respond with warning but do nothing otherwise.

Announced deprecations

Related links

• Read the Versioning Policy
• Read the Supported Releases

4 - Reporting security issues

The Dapr project and maintainers make security a central focus of how we operate and design our software. From the Dapr binaries to the GitHub release processes, we take numerous steps to ensure user applications and data is secure. For more information on Dapr security features, visit the security page.

Repositories and issues covered

When we say “a security vulnerability in Dapr”, this means a security issue in any repository under the dapr GitHub organization.

This reporting process is intended only for security issues in the Dapr project itself, and doesn’t apply to applications using Dapr or to issues which do not affect security.

If the issue cannot be fixed by a change to one of the covered repositories above, then it’s recommended to create a GitHub issue in the appropriate repo or raise a question in Discord.

If you’re unsure, err on the side of caution and reach out using the reporting process before raising your issue through GitHub, Discord, or another channel.

Explicitly Not Covered: Vulnerability Scanner Reports

We do not accept reports which amount to copy and pasted output from a vulnerability scanning tool unless work has specifically been done to confirm that a vulnerability reported by the tool actually exists in Dapr, including the CLI, Dapr SDKs, the components-contrib repo, or any other repo under the Dapr org.

We make use of these tools ourselves and try to act on the output they produce. We tend to find, however, that when these reports are sent to our security mailing list they almost always represent false positives, since these tools tend to check for the presence of a library without considering how the library is used in context.

If we receive a report which seems to simply be a vulnerability list from a scanner, we reserve the right to ignore it.

This applies especially when tools produce vulnerability identifiers which are not publicly visible or which are proprietary in some way. We can look up CVEs or other publicly-available identifiers for further details, but cannot do the same for proprietary identifiers.

Security Contacts

The people who should have access to read your security report are listed in maintainers.md.

Reporting Process

1. Describe the issue in English, ideally with some example configuration or code which allows the issue to be reproduced. Explain why you believe this to be a security issue in Dapr.
2. Put that information into an email. Use a descriptive title.
3. Send an email to Security (security@dapr.io)

Response

Response times could be affected by weekends, holidays, breaks or time zone differences. That said, the maintainers team endeavours to reply as soon as possible, ideally within 3 working days.

If the team concludes that the reported issue is indeed a security vulnerability in a Dapr project, at least two members of the maintainers team discuss the next steps together as soon as possible, ideally within 24 hours.

As soon as the team decides that the report is of a genuine vulnerability, one of the team responds to the reporter acknowledging the issue and establishing a disclosure timeline, which should be as soon as possible.

Triage, response, patching and announcement should all happen within 30 days.

5 - Preview features

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 for more information.

For CLI there is no explicit opt-in, just the version that this was first made available.

Current preview features

6 - Alpha and Beta APIs

Alpha APIs

Beta APIs

No current beta APIs.

Related links

Learn more about the Alpha, Beta, and Stable lifecycle stages.