From 351453c76a5bf6952513c37e91ff1476df71752e Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Date: Thu, 1 Jun 2023 07:48:42 +0530 Subject: [PATCH 1/5] add app channel address flag for run and multi app run template. (#3473) * add app channel address flag for run and multi app run template. fix tags issue during compile Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> * Update daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md Signed-off-by: Mark Fussell --------- Signed-off-by: Mukundan Sundararajan <65565396+mukundansundar@users.noreply.github.com> Signed-off-by: Mark Fussell Co-authored-by: Mark Fussell --- .../howto-manage-configuration.md | 18 ++++++++------- .../multi-app-dapr-run/multi-app-template.md | 22 ++++++++++--------- daprdocs/content/en/reference/cli/dapr-run.md | 1 + 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md b/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md index d09e5337c..6fba434ad 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md +++ b/daprdocs/content/en/developing-applications/building-blocks/configuration/howto-manage-configuration.md @@ -26,12 +26,12 @@ Create a configuration item in a supported configuration store. This can be a si docker run --name my-redis -p 6379:6379 -d redis:6 ``` -### Save an item +### Save an item Using the [Redis CLI](https://redis.com/blog/get-redis-cli-without-installing-redis-server/), connect to the Redis instance: ``` -redis-cli -p 6379 +redis-cli -p 6379 ``` Save a configuration item: @@ -45,10 +45,10 @@ MSET orderId1 "101||1" orderId2 "102||1" Save the following component file to the [default components folder]({{< ref "install-dapr-selfhost.md#step-5-verify-components-directory-has-been-initialized" >}}) on your machine. You can use this as the Dapr component YAML: - For Kubernetes using `kubectl`. -- When running with the Dapr CLI. +- When running with the Dapr CLI. {{% alert title="Note" color="primary" %}} - Since the Redis configuration component has identical metadata to the Redis `statestore.yaml` component, you can simply copy/change the Redis state store component type if you already have a Redis `statestore.yaml`. + Since the Redis configuration component has identical metadata to the Redis `statestore.yaml` component, you can simply copy/change the Redis state store component type if you already have a Redis `statestore.yaml`. {{% /alert %}} @@ -250,7 +250,7 @@ Invoke-RestMethod -Uri 'http://localhost:3601/v1.0/configuration/configstore?key ### Subscribe to configuration item updates -Below are code examples that leverage SDKs to subscribe to keys `[orderId1, orderId2]` using `configstore` store component. +Below are code examples that leverage SDKs to subscribe to keys `[orderId1, orderId2]` using `configstore` store component. {{< tabs ".NET" "ASP.NET Core" Java Python Go Javascript>}} @@ -328,7 +328,7 @@ namespace ConfigurationApi // Get the initial value and continue to watch it for changes. config.AddDaprConfigurationStore("configstore", new List() { "orderId1","orderId2" }, client, TimeSpan.FromSeconds(20)); config.AddStreamingDaprConfigurationStore("configstore", new List() { "orderId1","orderId2" }, client, TimeSpan.FromSeconds(20)); - + }) .ConfigureWebHostDefaults(webBuilder => { @@ -429,7 +429,7 @@ dapr run --app-id orderprocessing -- python3 OrderProcessingService.py {{% codetab %}} -```go +```go package main import ( @@ -653,7 +653,7 @@ async function main() { ); setTimeout(() => { // Unsubscribe to config updates - stream.stop(); + stream.stop(); console.log("App unsubscribed to config changes"); process.exit(0); }, 20000); @@ -679,6 +679,8 @@ Invoke-RestMethod -Uri 'http://localhost:/v1.0/configuration/con ``` {{% /codetab %}} +{{< /tabs >}} + ## Next steps * Read [configuration API overview]({{< ref configuration-api-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md index e3b762925..6dad64c9f 100644 --- a/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md +++ b/daprdocs/content/en/developing-applications/local-development/multi-app-dapr-run/multi-app-template.md @@ -7,13 +7,13 @@ description: Unpack the Multi-App Run template file and its properties --- {{% alert title="Note" color="primary" %}} - Multi-App Run is currently a preview feature only supported in Linux/MacOS. + Multi-App Run is currently a preview feature only supported in Linux/MacOS. {{% /alert %}} The Multi-App Run template file is a YAML file that you can use to run multiple applications at once. In this guide, you'll learn how to: -- Use the multi-app template +- Use the multi-app template - View started applications -- Stop the multi-app template +- Stop the multi-app template - Stucture the multi-app template file ## Use the multi-app template @@ -65,7 +65,7 @@ dapr stop -f ./path/to/.yaml ## Template file structure -The Multi-App Run template file can include the following properties. Below is an example template showing two applications that are configured with some of the properties. +The Multi-App Run template file can include the following properties. Below is an example template showing two applications that are configured with some of the properties. ```yaml version: 1 @@ -77,15 +77,16 @@ apps: - appID: webapp # optional appDirPath: .dapr/webapp/ # REQUIRED resourcesPath: .dapr/resources # deprecated - resourcesPaths: .dapr/resources # comman separated resources paths. (optional) can be default by convention + resourcesPaths: .dapr/resources # comma separated resources paths. (optional) can be left to default value by convention. + appChannelAddress: 127.0.0.1 # network address where the app listens on. (optional) can be left to default value by convention. configFilePath: .dapr/config.yaml # (optional) can be default by convention too, ignore if file is not found. appProtocol: http appPort: 8080 - appHealthCheckPath: "/healthz" + appHealthCheckPath: "/healthz" command: ["python3" "app.py"] appLogDestination: file # (optional), can be file, console or fileAndConsole. default is fileAndConsole. daprdLogDestination: file # (optional), can be file, console or fileAndConsole. default is file. - - appID: backend # optional + - appID: backend # optional appDirPath: .dapr/backend/ # REQUIRED appProtocol: grpc appPort: 3000 @@ -106,15 +107,16 @@ The following rules apply for all the paths present in the template file: ## Template properties -The properties for the Multi-App Run template align with the `dapr run` CLI flags, [listed in the CLI reference documentation]({{< ref "dapr-run.md#flags" >}}). +The properties for the Multi-App Run template align with the `dapr run` CLI flags, [listed in the CLI reference documentation]({{< ref "dapr-run.md#flags" >}}). | Properties | Required | Details | Example | |--------------------------|:--------:|--------|---------| | `appDirPath` | Y | Path to the your application code | `./webapp/`, `./backend/` | | `appID` | N | Application's app ID. If not provided, will be derived from `appDirPath` | `webapp`, `backend` | -| `resourcesPath` | N | **Deprecated**. Path to your Dapr resources. Can be default by convention| `./app/components`, `./webapp/components` | -| `resourcesPaths` | N | Comma separated paths to your Dapr resources. Can be default by convention | `./app/components`, `./webapp/components` | +| `resourcesPath` | N | **Deprecated**. Path to your Dapr resources. Can be default value by convention| `./app/components`, `./webapp/components` | +| `resourcesPaths` | N | Comma separated paths to your Dapr resources. Can be default value by convention | `./app/components`, `./webapp/components` | +| `appChannelAddress` | N | The network address the application listens on. Can be left to the default value by convention. | `127.0.0.1` | `localhost` | | `configFilePath` | N | Path to your application's configuration file | `./webapp/config.yaml` | | `appProtocol` | N | The protocol Dapr uses to talk to the application. | `http`, `grpc` | | `appPort` | N | The port your application is listening on | `8080`, `3000` | diff --git a/daprdocs/content/en/reference/cli/dapr-run.md b/daprdocs/content/en/reference/cli/dapr-run.md index ee16027b2..5587fc21f 100644 --- a/daprdocs/content/en/reference/cli/dapr-run.md +++ b/daprdocs/content/en/reference/cli/dapr-run.md @@ -28,6 +28,7 @@ dapr run [flags] [command] | `--app-port`, `-p` | `APP_PORT` | | The port your application is listening on | | `--app-protocol`, `-P` | | `http` | The protocol Dapr uses to talk to the application. Valid values are: `http`, `grpc`, `https` (HTTP with TLS), `grpcs` (gRPC with TLS), `h2c` (HTTP/2 Cleartext) | | `--resources-path`, `-d` | | Linux/Mac: `$HOME/.dapr/components`
Windows: `%USERPROFILE%\.dapr\components` | The path for components directory | +| `--app-channel-address` | | `127.0.0.1` | The network address the application listens on | | `--runtime-path` | | | Dapr runtime install path | | `--config`, `-c` | | Linux/Mac: `$HOME/.dapr/config.yaml`
Windows: `%USERPROFILE%\.dapr\config.yaml` | Dapr configuration file | | `--dapr-grpc-port`, `-G` | `DAPR_GRPC_PORT` | `50001` | The gRPC port for Dapr to listen on | From 44baf48b7a9f794ac2da8946ef30bfcabec4fbda Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Fri, 2 Jun 2023 06:18:17 +0100 Subject: [PATCH 2/5] Adds TTL documentation to CosmosDB and MySQL (#3471) * Adds TTL documentation to CosmosDB and MySQL Signed-off-by: joshvanl * Remove Microsoft link localization form the CosmosDB MySQL reference docs Signed-off-by: joshvanl * Update daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-cosmosdb.md Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen * Update daprdocs/content/en/reference/components-reference/supported-state-stores/setup-mysql.md Co-authored-by: Mark Fussell Signed-off-by: Josh van Leeuwen --------- Signed-off-by: joshvanl Signed-off-by: Josh van Leeuwen Co-authored-by: Mark Fussell --- .../supported-state-stores/setup-azure-cosmosdb.md | 4 ++++ .../supported-state-stores/setup-mysql.md | 12 ++++++++++++ .../supported-state-stores/setup-postgresql.md | 2 +- 3 files changed, 17 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-cosmosdb.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-cosmosdb.md index 2c7a4651c..a1f4f59b9 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-cosmosdb.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-azure-cosmosdb.md @@ -70,6 +70,10 @@ In order to setup Cosmos DB as a state store, you need the following properties - **Database**: The name of the database - **Collection**: The name of the collection (or container) +### TTLs and cleanups + +This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to override the default TTL on the CosmodDB container, indicating when the data should be considered "expired". Note that this value _only_ takes effect if the container's `DefaultTimeToLive` field has a non-NULL value. See the [CosmosDB documentation](https://docs.microsoft.com/azure/cosmos-db/nosql/time-to-live) for more information. + ## Best Practices for Production Use Azure Cosmos DB shares a strict metadata request rate limit across all databases in a single Azure Cosmos DB account. New connections to Azure Cosmos DB assume a large percentage of the allowable request rate limit. (See the [Cosmos DB documentation](https://docs.microsoft.com/azure/cosmos-db/sql/troubleshoot-request-rate-too-large#recommended-solution-3)) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-mysql.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-mysql.md index 62c3a430f..65000b4d1 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-mysql.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-mysql.md @@ -58,6 +58,7 @@ If you wish to use MySQL as an actor store, append the following to the yaml. | `timeoutInSeconds` | N | Timeout for all database operations. Defaults to `20` | `30` | | `pemPath` | N | Full path to the PEM file to use for [enforced SSL Connection](#enforced-ssl-connection) required if pemContents is not provided. Cannot be used in K8s environment | `"/path/to/file.pem"`, `"C:\path\to\file.pem"` | | `pemContents` | N | Contents of PEM file to use for [enforced SSL Connection](#enforced-ssl-connection) required if pemPath is not provided. Can be used in K8s environment | `"pem value"` | +| `cleanupIntervalInSeconds` | N | Interval, in seconds, to clean up rows with an expired TTL. Default: `3600` (that is 1 hour). Setting this to values <=0 disables the periodic cleanup. | `1800`, `-1` ## Setup MySQL @@ -134,6 +135,17 @@ Replace the `` value with your connection string. The connect If your server requires SSL your connection string must end with `&tls=custom` for example, `":@tcp(:3306)/?allowNativePasswords=true&tls=custom"`. You must replace the `` with a full path to the PEM file. The connection to MySQL will require a minimum TLS version of 1.2. +### TTLs and cleanups + +This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate when the data should be considered "expired". + +Because MySQL doesn't have built-in support for TTLs, this is implemented in Dapr by adding a column in the state table indicating when the data is to be considered "expired". Records that are "expired" are not returned to the caller, even if they're still physically stored in the database. A background "garbage collector" periodically scans the state table for expired rows and deletes them. + +The interval at which the deletion of expired records happens is set with the `cleanupIntervalInSeconds` metadata property, which defaults to 3600 seconds (that is, 1 hour). + +- Longer intervals require less frequent scans for expired rows, but can require storing expired records for longer, potentially requiring more storage space. If you plan to store many records in your state table, with short TTLs, consider setting `cleanupIntervalInSeconds` to a smaller value, for example `300` (300 seconds, or 5 minutes). +- If you do not plan to use TTLs with Dapr and the MySQL state store, you should consider setting `cleanupIntervalInSeconds` to a value <= 0 (e.g. `0` or `-1`) to disable the periodic cleanup and reduce the load on the database. + ## Related links - [Basic schema for a Dapr component]({{< ref component-schema >}}) - Read [this guide]({{< ref "howto-get-save-state.md#step-2-save-and-retrieve-a-single-state" >}}) for instructions on configuring state store components diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md index d8472e840..6e1bfad92 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-postgresql.md @@ -92,7 +92,7 @@ Either the default "postgres" database can be used, or create a new database for ### TTLs and cleanups -This state store supports [Time-To-Live (TTL)](https://docs.dapr.io/developing-applications/building-blocks/state-management/state-store-ttl/) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate after how many seconds the data should be considered "expired". +This state store supports [Time-To-Live (TTL)]({{< ref state-store-ttl.md >}}) for records stored with Dapr. When storing data using Dapr, you can set the `ttlInSeconds` metadata property to indicate after how many seconds the data should be considered "expired". Because PostgreSQL doesn't have built-in support for TTLs, this is implemented in Dapr by adding a column in the state table indicating when the data is to be considered "expired". Records that are "expired" are not returned to the caller, even if they're still physically stored in the database. A background "garbage collector" periodically scans the state table for expired rows and deletes them. From 5adf7173e2cdea088429fe8503487b320e32df25 Mon Sep 17 00:00:00 2001 From: Josh van Leeuwen Date: Fri, 2 Jun 2023 19:41:19 +0100 Subject: [PATCH 3/5] Show same dapr version in quickstart CLI version (#3479) Signed-off-by: joshvanl --- .../content/en/getting-started/install-dapr-cli.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/daprdocs/content/en/getting-started/install-dapr-cli.md b/daprdocs/content/en/getting-started/install-dapr-cli.md index 82474d9ae..df9b25d69 100644 --- a/daprdocs/content/en/getting-started/install-dapr-cli.md +++ b/daprdocs/content/en/getting-started/install-dapr-cli.md @@ -34,7 +34,7 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`). ```bash -wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash -s 1.9.1 +wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash -s {{% dapr-latest-version cli="true" %}} ``` @@ -51,7 +51,7 @@ wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`). ```bash -wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash -s 1.9.1 +wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | DAPR_INSTALL_DIR="$HOME/dapr" /bin/bash -s {{% dapr-latest-version cli="true" %}} ``` {{% /codetab %}} @@ -73,7 +73,7 @@ powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`). ```powershell -powershell -Command "$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList 1.9.1" +powershell -Command "$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList {{% dapr-latest-version cli="true" %}}" ``` #### Install without administrative rights @@ -91,7 +91,7 @@ The following example shows how to install CLI version `{{% dapr-latest-version ```powershell $Env:DAPR_INSTALL_DIR = "" -$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList "1.9.1", "$Env:DAPR_INSTALL_DIR" +$script=iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1; $block=[ScriptBlock]::Create($script); invoke-command -ScriptBlock $block -ArgumentList "{{% dapr-latest-version cli="true" %}}", "$Env:DAPR_INSTALL_DIR" ``` #### Install using winget @@ -136,7 +136,7 @@ curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`). ```bash -curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash -s 1.9.1 +curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | /bin/bash -s {{% dapr-latest-version cli="true" %}} ``` **For ARM64 Macs:** @@ -177,7 +177,7 @@ curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh The following example shows how to install CLI version `{{% dapr-latest-version cli="true" %}}`. You can also install release candidates by specifying the version (for example, `1.10.0-rc.3`). ```bash -curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | DAPR_INSTALL_DIR="$HOME/dapr" -s 1.9.1 +curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | DAPR_INSTALL_DIR="$HOME/dapr" -s {{% dapr-latest-version cli="true" %}} ``` {{% /codetab %}} From 70537df6689d7633655408a4433998a4574d493d Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Fri, 2 Jun 2023 20:56:19 -0400 Subject: [PATCH 4/5] Add `consumerID` to Pulsar pub/sub (#3437) * add consumerID Signed-off-by: Hannah Hunter * Update daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md Signed-off-by: Mark Fussell --------- Signed-off-by: Hannah Hunter Signed-off-by: Mark Fussell Co-authored-by: Mark Fussell --- .../components-reference/supported-pubsub/setup-pulsar.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md index e57c2aa26..6097cba71 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-pulsar.md @@ -28,6 +28,8 @@ spec: value: "public" - name: token value: "eyJrZXlJZCI6InB1bHNhci1wajU0cXd3ZHB6NGIiLCJhbGciOiJIUzI1NiJ9.eyJzd" + - name: consumerID + value: "topic1" - name: namespace value: "default" - name: persistent @@ -66,6 +68,7 @@ spec: | enableTLS | N | Enable TLS. Default: `"false"` | `"true"`, `"false"` | | token | N | Enable Authentication. | [How to create pulsar token](https://pulsar.apache.org/docs/en/security-jwt/#generate-tokens)| | tenant | N | The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. Default: `"public"` | `"public"` | +| consumerID | N | Used to set the subscription name or consumer ID. | `"topic1"` | namespace | N | The administrative unit of the topic, which acts as a grouping mechanism for related topics. Default: `"default"` | `"default"` | persistent | N | Pulsar supports two kinds of topics: [persistent](https://pulsar.apache.org/docs/en/concepts-architecture-overview#persistent-storage) and [non-persistent](https://pulsar.apache.org/docs/en/concepts-messaging/#non-persistent-topics). With persistent topics, all messages are durably persisted on disks (if the broker is not standalone, messages are durably persisted on multiple disks), whereas data for non-persistent topics is not persisted to storage disks. | disableBatching | N | disable batching.When batching enabled default batch delay is set to 10 ms and default batch size is 1000 messages,Setting `disableBatching: true` will make the producer to send messages individually. Default: `"false"` | `"true"`, `"false"`| From 3ba10e7d5bcf794eeacd36ab29fadb946c9d0e7b Mon Sep 17 00:00:00 2001 From: Artur Souza Date: Fri, 2 Jun 2023 18:05:59 -0700 Subject: [PATCH 5/5] Add build variations + refactor breaking-changes. (#3478) * Add build variations + refactor breaking-changes. Signed-off-by: Artur Souza * Update daprdocs/content/en/operations/support/support-release-policy.md Co-authored-by: Mark Fussell Signed-off-by: Artur Souza * Add example and reference to build variants. Signed-off-by: Artur Souza * Update daprdocs/content/en/reference/arguments-annotations-overview.md Signed-off-by: Mark Fussell * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell * Update daprdocs/content/en/operations/support/support-release-policy.md Signed-off-by: Mark Fussell * Update daprdocs/content/en/reference/arguments-annotations-overview.md Signed-off-by: Mark Fussell --------- Signed-off-by: Artur Souza Signed-off-by: Mark Fussell Co-authored-by: Mark Fussell --- .../breaking-changes-and-deprecations.md | 63 +++++++++++++++++ .../support/support-release-policy.md | 67 ++++--------------- .../arguments-annotations-overview.md | 2 +- 3 files changed, 77 insertions(+), 55 deletions(-) create mode 100644 daprdocs/content/en/operations/support/breaking-changes-and-deprecations.md diff --git a/daprdocs/content/en/operations/support/breaking-changes-and-deprecations.md b/daprdocs/content/en/operations/support/breaking-changes-and-deprecations.md new file mode 100644 index 000000000..3d2893576 --- /dev/null +++ b/daprdocs/content/en/operations/support/breaking-changes-and-deprecations.md @@ -0,0 +1,63 @@ +--- +type: docs +title: "Breaking changes and deprecations" +linkTitle: "Breaking changes and deprecations" +weight: 2500 +description: "Handling of 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 CRD template +- Publicly accessible API +- Publicly visible SDK interface, method, class, or attribute + +Breaking changes can be applied right away to the following cases: + +- Projects versioned at 0.x.y +- Preview feature +- Alpha API +- Preview or Alpha interface, class, method or attribute in SDK +- Dapr Component in Alpha or Beta +- Components-Contrib interface +- 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. +1. 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 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 + +| Feature | Deprecation announcement | Removal | +|-----------------------|-----------------------|------------------------- | +| GET /v1.0/shutdown API (Users should use [POST API]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 | +| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) instead) | Java SDK 1.3.0 | Java SDK 1.5.0 | +| Service invocation will no longer provide a default content type header of `application/json` when no content-type is specified. You must explicitly [set a content-type header]({{< ref "service_invocation_api.md#request-contents" >}}) for service invocation if your invoked apps rely on this header. | 1.7.0 | 1.9.0 | +| gRPC service invocation using `invoke` method is deprecated. Use proxy mode service invocation instead. See [How-To: Invoke services using gRPC ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 | + +## Related links + +- Read the [Versioning Policy]({{< ref support-versioning.md >}}) +- Read the [Supported Releases]({{< ref support-release-policy.md >}}) diff --git a/daprdocs/content/en/operations/support/support-release-policy.md b/daprdocs/content/en/operations/support/support-release-policy.md index d32034737..266321178 100644 --- a/daprdocs/content/en/operations/support/support-release-policy.md +++ b/daprdocs/content/en/operations/support/support-release-policy.md @@ -28,6 +28,17 @@ There will be at least 6 weeks between major.minor version releases giving users Patch support is for supported versions (current and previous). +## Build variations + +The Dapr's sidecar image is published to both [GitHub Container Registry](https://github.com/dapr/dapr/pkgs/container/daprd) and [Docker Registry](https://hub.docker.com/r/daprio/daprd/tags). 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:` or `ghcr.io/dapr/daprd:` (for example `ghcr.io/dapr/daprd:1.11.0`) +* Sidecar images for stable components: `daprio/daprd:-stable` or `ghcr.io/dapr/daprd:-stable` (for example `ghcr.io/dapr/daprd:1.11.0-stable`) + +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. @@ -106,59 +117,6 @@ General guidance on upgrading can be found for [self hosted mode]({{< ref self-h | 1.9.0 | N/A | 1.9.6 | | 1.10.0 | N/A | 1.10.7 | -## 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 CRD template -- Publicly accessible API -- Publicly visible SDK interface, method, class, or attribute - -Breaking changes can be applied right away to the following cases: - -- Projects versioned at 0.x.y -- Preview feature -- Alpha API -- Preview or Alpha interface, class, method or attribute in SDK -- Dapr Component in Alpha or Beta -- Components-Contrib interface -- 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. -1. 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. - -### Depreciations - -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 - -| Feature | Deprecation announcement | Removal | -|-----------------------|-----------------------|------------------------- | -| GET /v1.0/shutdown API (Users should use [POST API]({{< ref kubernetes-job.md >}}) instead) | 1.2.0 | 1.4.0 | -| Java domain builder classes deprecated (Users should use [setters](https://github.com/dapr/java-sdk/issues/587) instead) | Java SDK 1.3.0 | Java SDK 1.5.0 | -| Service invocation will no longer provide a default content type header of `application/json` when no content-type is specified. You must explicitly [set a content-type header]({{< ref "service_invocation_api.md#request-contents" >}}) for service invocation if your invoked apps rely on this header. | 1.7.0 | 1.9.0 | -| gRPC service invocation using `invoke` method is deprecated. Use proxy mode service invocation instead. See [How-To: Invoke services using gRPC ]({{< ref howto-invoke-services-grpc.md >}}) to use the proxy mode.| 1.9.0 | 1.10.0 | - ## 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]({{< ref kubernetes-production.md >}}) @@ -175,4 +133,5 @@ Below is a list of software that the latest version of Dapr (v{{% dapr-latest-ve ## Related links -- Read the [Versioning policy]({{< ref support-versioning.md >}}) +- Read the [Versioning Policy]({{< ref support-versioning.md >}}) +- Read the [Breaking Changes and Deprecation Policy]({{< ref breaking-changes-and-deprecations.md >}}) diff --git a/daprdocs/content/en/reference/arguments-annotations-overview.md b/daprdocs/content/en/reference/arguments-annotations-overview.md index 5cac39e18..1ddf57582 100644 --- a/daprdocs/content/en/reference/arguments-annotations-overview.md +++ b/daprdocs/content/en/reference/arguments-annotations-overview.md @@ -23,7 +23,7 @@ This table is meant to help users understand the equivalent options for running | `--dapr-http-port` | `--dapr-http-port` | | not supported | The HTTP port for the Dapr API | | `--dapr-http-max-request-size` | --dapr-http-max-request-size | | `dapr.io/http-max-request-size` | Increasing max size of request body http and grpc servers parameter in MB to handle uploading of big files. Default is `4` MB | | `--dapr-http-read-buffer-size` | --dapr-http-read-buffer-size | | `dapr.io/http-read-buffer-size` | Increasing max size of http header read buffer in KB to handle when sending multi-KB headers. The default 4 KB. When sending bigger than default 4KB http headers, you should set this to a larger value, for example 16 (for 16KB) | -| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is `daprio/daprd:latest`. Use this when building your own custom image of Dapr and the Dapr sidecar will use this image instead of the default image of Dapr | +| not supported | `--image` | | `dapr.io/sidecar-image` | Dapr sidecar image. Default is daprio/daprd:latest. The Dapr sidecar uses this image instead of the latest default image. Use this when building your own custom image of Dapr and or [using an alternative stable Dapr image]({{}}) | | `--internal-grpc-port` | not supported | | not supported | gRPC port for the Dapr Internal API to listen on | | `--enable-metrics` | not supported | | configuration spec | Enable prometheus metric (default true) | | `--enable-mtls` | not supported | | configuration spec | Enables automatic mTLS for daprd to daprd communication channels |