From 581a7f5aeae289974e72da5a62dbb3adaea9bfa9 Mon Sep 17 00:00:00 2001 From: Scott Hussey Date: Tue, 28 Dec 2021 14:53:18 -0600 Subject: [PATCH 01/15] Document Kafka pub/sub OIDC authentication - Add documentation to configure Kafka pub/sub component for OIDC authentication - Update documentation on the Kafka pub/sub component TLS configuration to clarify a separation of TLS for transport and authentication. Signed-off-by: Scott Hussey --- .../supported-pubsub/setup-apache-kafka.md | 229 +++++++++++++++--- 1 file changed, 201 insertions(+), 28 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md index e0e4167c9..616bd31d6 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md @@ -27,11 +27,11 @@ spec: value: "group1" - name: clientID # Optional. Used as client tracing ID by Kafka brokers. value: "my-dapr-app-id" - - name: authRequired # Required. - value: "true" - - name: saslUsername # Required if authRequired is `true`. + - name: authType # Required. + value: "password" + - name: saslUsername # Required if authType is `password`. value: "adminuser" - - name: saslPassword # Required if authRequired is `true`. + - name: saslPassword # Required if authType is `password`. secretKeyRef: name: kafka-secrets key: saslPasswordSecret @@ -50,22 +50,158 @@ spec: | brokers | Y | A comma-separated list of Kafka brokers. | `"localhost:9092,dapr-kafka.myapp.svc.cluster.local:9093"` | consumerGroup | N | A kafka consumer group to listen on. Each record published to a topic is delivered to one consumer within each consumer group subscribed to the topic. | `"group1"` | clientID | N | A user-provided string sent with every request to the Kafka brokers for logging, debugging, and auditing purposes. Defaults to `"sarama"`. | `"my-dapr-app"` -| authRequired | Y | Enable [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication with the Kafka brokers. | `"true"`, `"false"` -| saslUsername | N | The SASL username used for authentication. Only required if `authRequired` is set to `"true"`. | `"adminuser"` -| saslPassword | N | The SASL password used for authentication. Can be `secretKeyRef` to use a [secret reference]({{< ref component-secrets.md >}}). Only required if `authRequired` is set to `"true"`. | `""`, `"KeFg23!"` +| authRequired | N | *Deprecated* Enable [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication with the Kafka brokers. | `"true"`, `"false"` +| authType | Y | Configure or disable authentication. Supported values: `none`, `password`, `mtls`, or `oidc` | `"password"`, `"none"` +| saslUsername | N | The SASL username used for authentication. Only required if `authType` is set to `"password"`. | `"adminuser"` +| saslPassword | N | The SASL password used for authentication. Can be `secretKeyRef` to use a [secret reference]({{< ref component-secrets.md >}}). Only required if `authType is set to `"password"`. | `""`, `"KeFg23!"` | initialOffset | N | The initial offset to use if no offset was previously committed. Should be "newest" or "oldest". Defaults to "newest". | `"oldest"` | maxMessageBytes | N | The maximum size in bytes allowed for a single Kafka message. Defaults to 1024. | `2048` | consumeRetryInterval | N | The interval between retries when attempting to consume topics. Treats numbers without suffix as milliseconds. Defaults to 100ms. | `200ms` | version | N | Kafka cluster version. Defaults to 2.0.0.0 | `0.10.2.0` | caCert | N | Certificate authority certificate, required for using TLS. Can be `secretKeyRef` to use a secret reference | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"` -| clientCert | N | Client certificate, required for using TLS. Can be `secretKeyRef` to use a secret reference | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"` -| clientKey | N | Client key, required for using TLS. Can be `secretKeyRef` to use a secret reference | `"-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----"` +| clientCert | N | Client certificate, required for `authType` `mtls`. Can be `secretKeyRef` to use a secret reference | `"-----BEGIN CERTIFICATE-----\n\n-----END CERTIFICATE-----"` +| clientKey | N | Client key, required for `authType` `mtls` Can be `secretKeyRef` to use a secret reference | `"-----BEGIN RSA PRIVATE KEY-----\n\n-----END RSA PRIVATE KEY-----"` | skipVerify | N | Skip TLS verification, this is not recommended for use in production. Defaults to `"false"` | `"true"`, `"false"` | +| disableTls | N | Disable TLS for transport security. This is not recommended for use in production. Defaults to `"false"` | `"true"`, `"false"` | +| oidcTokenEndpoint | N | Full URL to an OAuth2 identity provider access token endpoint. Required when `authType` is set to `oidc` | "https://identity.example.com/v1/token" | +| oidcClientID | N | The OAuth2 client ID that has been provisioned in the identity provider. Required when `authType is set to `oidc` | `dapr-kafka` | +| oidcClientSecret | N | The OAuth2 client secret that has been provisioned in the identity provider: Required when `authType` is set to `oidc` | `"KeFg23!"` | +| oidcScopes | N | Comma-delimited list of OAuth2/OIDC scopes to request with the access token. Recommended when `authType` is set to `oidc`. Defaults to `"openid"` | '"openid,kafka-prod"` | -### Communication using TLS -To configure communication using TLS, ensure the Kafka broker is configured to support certificates. -Pre-requisite includes `certficate authority certificate`, `ca issued client certificate`, `client private key`. -Below is an example of a Kafka pubsub component configured to use TLS: + +The `secretKeyRef` above is referencing a [kubernetes secrets store]({{< ref kubernetes-secret-store.md >}}) to access the tls information. Visit [here]({{< ref setup-secret-store.md >}}) to learn more about how to configure a secret store component. + +### Authentication + +Kafka supports a variety of authentication schemes and Dapr supports several: SASL password, mTLS, OIDC/OAuth2. With the added authentication methods, the `authRequired` field has been deprecated +and instead the `authType` field should be used. If `authRequired` is set to `true`, Dapr will attempt to configure `authType` correctly based on the value of `saslPassword`. There are four valid values for `authType`: `none`, `password`, `mtls`, and `oidc`. Note this is authentication only; authorization is still configured within Kafka. + +#### None + +Setting `authType` to `none` will disable any authentication. This is *NOT* recommended in production. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: kafka-pubsub-noauth + namespace: default +spec: + type: pubsub.kafka + version: v1 + metadata: + - name: brokers # Required. Kafka broker connection setting + value: "dapr-kafka.myapp.svc.cluster.local:9092" + - name: consumerGroup # Optional. Used for input bindings. + value: "group1" + - name: clientID # Optional. Used as client tracing ID by Kafka brokers. + value: "my-dapr-app-id" + - name: authType # Required. + value: "none" + - name: maxMessageBytes # Optional. + value: 1024 + - name: consumeRetryInterval # Optional. + value: 200ms + - name: version # Optional. + value: 0.10.2.0 + - name: disableTls + value: "true" +``` + +#### SASL Password + +Setting `authType` to `password` will enable [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication using the **PLAIN** mechanism. This requires setting +the `saslUsername` and `saslPassword` fields. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: kafka-pubsub-sasl + namespace: default +spec: + type: pubsub.kafka + version: v1 + metadata: + - name: brokers # Required. Kafka broker connection setting + value: "dapr-kafka.myapp.svc.cluster.local:9092" + - name: consumerGroup # Optional. Used for input bindings. + value: "group1" + - name: clientID # Optional. Used as client tracing ID by Kafka brokers. + value: "my-dapr-app-id" + - name: authType # Required. + value: "password" + - name: saslUsername # Required if authType is `password`. + value: "adminuser" + - name: saslPassword # Required if authType is `password`. + secretKeyRef: + name: kafka-secrets + key: saslPasswordSecret + - name: maxMessageBytes # Optional. + value: 1024 + - name: consumeRetryInterval # Optional. + value: 200ms + - name: version # Optional. + value: 0.10.2.0 + - name: caCert + secretKeyRef: + name: kafka-tls + key: caCert +``` + +#### Mutual TLS + +Setting `authType` to `mtls` will use a x509 client certificate (the `clientCert` field) and key (the `clientKey` field) to authenticate. Note that mTLS as an +authentication mechanism is distinct from using TLS to secure the transport layer via encryption. mTLS requires TLS transport (meaning `disableTls` must be `false`), but securing +the transport layer does not require using mTLS. See _Communication using TLS_ for configuring underlying TLS transport. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: kafka-pubsub-mtls + namespace: default +spec: + type: pubsub.kafka + version: v1 + metadata: + - name: brokers # Required. Kafka broker connection setting + value: "dapr-kafka.myapp.svc.cluster.local:9092" + - name: consumerGroup # Optional. Used for input bindings. + value: "group1" + - name: clientID # Optional. Used as client tracing ID by Kafka brokers. + value: "my-dapr-app-id" + - name: authType # Required. + value: "mtls" + - name: caCert + secretKeyRef: + name: kafka-tls + key: caCert + - name: clientCert + secretKeyRef: + name: kafka-tls + key: clientCert + - name: clientKey + secretKeyRef: + name: kafka-tls + key: clientKey + - name: maxMessageBytes # Optional. + value: 1024 + - name: consumeRetryInterval # Optional. + value: 200ms + - name: version # Optional. + value: 0.10.2.0 +``` + +#### OAuth2 or OpenID Connect + +Setting `authType` to `oidc` will enable SASL authentication via the **OAUTHBEARER** mechanism. This supports specifying a bearer +token from an external OAuth2 or [OIDC](https://en.wikipedia.org/wiki/OpenID) identity provider. Currenly only the **client_credentials** grant is supported. Configure `oidcTokenEndpoint` to +the full URL for the identity provider access token endpoint. Set `oidcClientID` and `oidcClientSecret` to the client credentials provisioned in the identity provider. If `caCert` +is specified in the component configuration, the certificate will be appended to the system CA trust for verifying the identity provider certificate. Similarly, if `skipVerify` +is specified in the component configuration, it will also be applied when accessing the identity provider. By default, the only scope requested for the token is `openid` but it is highly recommended +that additional scopes be specified via `oidcScopes` in a comma-separated list and validated by the Kafka broken. If additional scopes are not used to narrow the validity of the access token, +a compromised Kafka broker could replay the token to access other services as the Dapr clientID. ```yaml apiVersion: dapr.io/v1alpha1 @@ -83,9 +219,57 @@ spec: value: "group1" - name: clientID # Optional. Used as client tracing ID by Kafka brokers. value: "my-dapr-app-id" - - name: authRequired # Required. - value: "true" - - name: saslUsername # Required if authRequired is `true`. + - name: authType # Required. + value: "oidc" + - name: oidcTokenEndpoint # Required if authType is `oidc`. + value: "https://identity.example.com/v1/token" + - name: oidcClientID # Required if authType is `oidc`. + value: "dapr-myapp" + - name: oidcClientSecret # Required if authType is `oidc`. + secretKeyRef: + name: kafka-secrets + key: oidcClientSecret + - name: oidcScopes # Recommended if authType is `oidc`. + value: "openid,kafka-dev" + - name: caCert # Also applied to verifying OIDC provider certificate + secretKeyRef: + name: kafka-tls + key: caCert + - name: maxMessageBytes # Optional. + value: 1024 + - name: consumeRetryInterval # Optional. + value: 200ms + - name: version # Optional. + value: 0.10.2.0 +``` + +### Communication using TLS + +By default TLS is enabled to secure the transport layer to Kafka. To disable TLS, set `disableTls` to `true`. When TLS is enabled, you can +control server certificate verification using `skipVerify` to disable verificaiton (*NOT* recommended in production environments) and `caCert` to +specify a trusted TLS certificate authority (CA). If no `caCert` is specified, the system CA trust will be used. To also configure mTLS authentication, +see the section under _Authentication_. +Below is an example of a Kafka pubsub component configured to use transport layer TLS: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: kafka-pubsub + namespace: default +spec: + type: pubsub.kafka + version: v1 + metadata: + - name: brokers # Required. Kafka broker connection setting + value: "dapr-kafka.myapp.svc.cluster.local:9092" + - name: consumerGroup # Optional. Used for input bindings. + value: "group1" + - name: clientID # Optional. Used as client tracing ID by Kafka brokers. + value: "my-dapr-app-id" + - name: authType # Required. + value: "password" + - name: saslUsername # Required if authType is `password`. value: "adminuser" - name: consumeRetryInterval # Optional. value: 200ms @@ -101,21 +285,10 @@ spec: secretKeyRef: name: kafka-tls key: caCert - - name: clientCert # Client certificate. - secretKeyRef: - name: kafka-tls - key: clientCert - - name: clientKey # Client key. - secretKeyRef: - name: kafka-tls - key: clientKey auth: secretStore: ``` -The `secretKeyRef` above is referencing a [kubernetes secrets store]({{< ref kubernetes-secret-store.md >}}) to access the tls information. Visit [here]({{< ref setup-secret-store.md >}}) to learn more about how to configure a secret store component. - - ## Per-call metadata fields ### Partition Key @@ -154,4 +327,4 @@ To run Kafka on Kubernetes, you can use any Kafka operator, such as [Strimzi](ht ## Related links - [Basic schema for a Dapr component]({{< ref component-schema >}}) - Read [this guide]({{< ref "howto-publish-subscribe.md##step-1-setup-the-pubsub-component" >}}) for instructions on configuring pub/sub components -- [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file +- [Pub/Sub building block]({{< ref pubsub >}}) From d16b035c0e2ae746447a4c9032e6ed4477537c03 Mon Sep 17 00:00:00 2001 From: lucasjellema Date: Tue, 4 Jan 2022 12:05:12 +0100 Subject: [PATCH 02/15] Introducing documentation for OCI Object Storage state store component Signed-off-by: lucasjellema --- .../supported-state-stores/_index.md | 6 + .../setup-oci-objectstorage.md | 116 ++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md index b52fcdd01..b7c8644d3 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md @@ -60,3 +60,9 @@ The following stores are supported, at various levels, by the Dapr state managem | [Azure CosmosDB]({{< ref setup-azure-cosmosdb.md >}}) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Stable | v1 | 1.0 | | [Azure SQL Server]({{< ref setup-sqlserver.md >}}) | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | Stable | v1 | 1.5 | | [Azure Table Storage]({{< ref setup-azure-tablestorage.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.0 | + +### Oracle Cloud Infrastructure (OCI) + +| Name |CRUD|Transactional|ETag| [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | [Query]({{< ref howto-state-query-api.md >}}) | Status | Component version | Since | +|------------------------------------------------------------------|----|-------------|----|----|----|----|-------|----|-----| +| [OCI Object Storage]({{< ref setup-oci-objectstorage.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.6 | diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md new file mode 100644 index 000000000..b202a45bf --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -0,0 +1,116 @@ +--- +type: docs +title: "OCI Object Storage " +linkTitle: "OCI Object Storage " +description: Detailed information on the OCI Object Storage state store component +aliases: + - "/operations/components/setup-state-store/supported-state-stores/setup-oci-objectstorage/" +--- + +## Component format + +To setup OCI Object Storage state store create a component of type `state.oci.objectstorage`. See [this guide]({{< ref "howto-get-save-state.md#step-1-setup-a-state-store" >}}) on how to create and apply a state store configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: + namespace: +spec: + type: state.oci.objectstorage + version: v1 + metadata: + - name: tenancyOCID + value: + - name: userOCID + value: + - name: fingerPrint + value: + - name: privateKey + value: | + -----BEGIN RSA PRIVATE KEY----- + REPLACE-WIH-PRIVATE-KEY-AS-IN-PEM-FILE + -----END RSA PRIVATE KEY----- + - name: region + value: + - name: bucketName + value: + - name: compartmentOCID + value: + +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| tenancyOCID | Y | The OCI tenancy identifier. | `"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`. +| userOCID | Y | The OCID for an OCI account (this account requires permissions to access OCI Object Storage).| `"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"` +| fingerPrint | Y | Fingerprint of the public key. | `"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"` +| privateKey | Y | Private key of the RSA key pair | `"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"` +| region | Y | OCI Region | `"us-ashburn-1"` +| bucketName | Y | Name of the bucket written to and read from (and if necessary created) | `"application-state-store-bucket"` +| compartmentOCID | Y | The OCID for the compartment that contains the bucket | `"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"` + +## Setup OCI Object Storage +The OCI Object Storage state store needs to interact through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. + +If you wish to create the bucket for Dapr to use, you can do so beforehand. However, Object Storage state provider will create one - in the specified compartment - for you automatically if it doesn't exist. + +In order to setup OCI Object Storage as a state store, you will need the following properties: +- **tenancyOCID**: The identifier for the OCI cloud tenancy in which the state is to be stored. +- **userOCID**: The identifier for the account used by the state store component to connect to OCI; this must be an account with appropriate permissions on the OCI Object Storage service in the specified compartment and bucket +- **fingerPrint**: The fingerprint for the public key in the RSA key pair generated for the account indicated by **userOCID** +- **privateKey**: The private key in the RSA key pair generated for the account indicated by **userOCID** +- **region**: The OCI region - for example **us-ashburn-1**, **eu-amsterdam-1**, **ap-mumbai-1** +- **bucketName**: The name of the bucket on OCI Object Storage in which state will be created. This bucket can exist already when the state store is initialized or it will be created during initialization of the state store. Note that the name of buckets is unique within a namespace +- **compartmentOCID**: The identifier of the compartment within the tenancy in which the bucket exists or will be created. + + +## What Happens at Runtime? + +Every state entry is represented by an object in OCI Object Storage. The OCI Object Storage state store uses the `key` property provided in the requests to the Dapr API to determine the name of the object. The `value` is stored as the (literal) content of the object. Each object is assigned a unique ETag value - whenever it is created or updated (aka overwritten). + +For example, the following operation + +```shell +curl -X POST http://localhost:3500/v1.0/state \ + -H "Content-Type: application/json" + -d '[ + { + "key": "nihilus", + "value": "darth" + } + ]' +``` + +will create the following object: + +| Bucket | Object Name | Object Content | +| ------------ | ------- | ----- | +| as specified with **bucketName** in components.yaml | nihilus | darth | + +You will be able to inspect all state stored through the OCI Object Storage state store by inspecting the contents of the bucket through the console, the APIs, CLI or SDKs. By going directly to the bucket, you can prepare state that will be available as state to your application at runtime. + +## Concurrency + +OCI Object Storage state concurrency is achieved by using `ETag`s. Each object in OCI Object Storage is assigned a unique ETag when it is created or updated (aka replaced). When the Set and Delete requests for this state store specify the FirstWrite concurrency policy, then the request need to provide the actual ETag value for the state to be written or removed for the request to be successful. + +## Consistency + +OCI Object Storage state does not support Transactions. + +## Query + +OCI Object Storage state does not support the Query API. + + +## 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 +- [State management building block]({{< ref state-management >}}) From 4979af3abc9340ab18f0c683c99eb0cdb2e16eb0 Mon Sep 17 00:00:00 2001 From: Scott Hussey Date: Wed, 5 Jan 2022 20:09:06 -0600 Subject: [PATCH 03/15] Update some phrasing and links - Correctly link to subsection Signed-off-by: Scott Hussey --- .../supported-pubsub/setup-apache-kafka.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md index 616bd31d6..a7968be25 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-apache-kafka.md @@ -73,8 +73,9 @@ The `secretKeyRef` above is referencing a [kubernetes secrets store]({{< ref ku ### Authentication -Kafka supports a variety of authentication schemes and Dapr supports several: SASL password, mTLS, OIDC/OAuth2. With the added authentication methods, the `authRequired` field has been deprecated -and instead the `authType` field should be used. If `authRequired` is set to `true`, Dapr will attempt to configure `authType` correctly based on the value of `saslPassword`. There are four valid values for `authType`: `none`, `password`, `mtls`, and `oidc`. Note this is authentication only; authorization is still configured within Kafka. +Kafka supports a variety of authentication schemes and Dapr supports several: SASL password, mTLS, OIDC/OAuth2. With the added authentication methods, the `authRequired` field has +been deprecated from the v1.6 release and instead the `authType` field should be used. If `authRequired` is set to `true`, Dapr will attempt to configure `authType` correctly +based on the value of `saslPassword`. There are four valid values for `authType`: `none`, `password`, `mtls`, and `oidc`. Note this is authentication only; authorization is still configured within Kafka. #### None @@ -110,7 +111,7 @@ spec: #### SASL Password -Setting `authType` to `password` will enable [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication using the **PLAIN** mechanism. This requires setting +Setting `authType` to `password` enables [SASL](https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer) authentication using the **PLAIN** mechanism. This requires setting the `saslUsername` and `saslPassword` fields. ```yaml @@ -151,9 +152,9 @@ spec: #### Mutual TLS -Setting `authType` to `mtls` will use a x509 client certificate (the `clientCert` field) and key (the `clientKey` field) to authenticate. Note that mTLS as an +Setting `authType` to `mtls` uses a x509 client certificate (the `clientCert` field) and key (the `clientKey` field) to authenticate. Note that mTLS as an authentication mechanism is distinct from using TLS to secure the transport layer via encryption. mTLS requires TLS transport (meaning `disableTls` must be `false`), but securing -the transport layer does not require using mTLS. See _Communication using TLS_ for configuring underlying TLS transport. +the transport layer does not require using mTLS. See [Communication using TLS](#communication-using-tls) for configuring underlying TLS transport. ```yaml apiVersion: dapr.io/v1alpha1 @@ -195,12 +196,12 @@ spec: #### OAuth2 or OpenID Connect -Setting `authType` to `oidc` will enable SASL authentication via the **OAUTHBEARER** mechanism. This supports specifying a bearer +Setting `authType` to `oidc` enables SASL authentication via the **OAUTHBEARER** mechanism. This supports specifying a bearer token from an external OAuth2 or [OIDC](https://en.wikipedia.org/wiki/OpenID) identity provider. Currenly only the **client_credentials** grant is supported. Configure `oidcTokenEndpoint` to the full URL for the identity provider access token endpoint. Set `oidcClientID` and `oidcClientSecret` to the client credentials provisioned in the identity provider. If `caCert` -is specified in the component configuration, the certificate will be appended to the system CA trust for verifying the identity provider certificate. Similarly, if `skipVerify` -is specified in the component configuration, it will also be applied when accessing the identity provider. By default, the only scope requested for the token is `openid` but it is highly recommended -that additional scopes be specified via `oidcScopes` in a comma-separated list and validated by the Kafka broken. If additional scopes are not used to narrow the validity of the access token, +is specified in the component configuration, the certificate is appended to the system CA trust for verifying the identity provider certificate. Similarly, if `skipVerify` +is specified in the component configuration, verification will also be skipped when accessing the identity provider. By default, the only scope requested for the token is `openid`; it is **highly** recommended +that additional scopes be specified via `oidcScopes` in a comma-separated list and validated by the Kafka broker. If additional scopes are not used to narrow the validity of the access token, a compromised Kafka broker could replay the token to access other services as the Dapr clientID. ```yaml From 5826b150f48800b7b403cb3fc5e176c77891f463 Mon Sep 17 00:00:00 2001 From: lucasjellema Date: Thu, 6 Jan 2022 10:45:41 +0100 Subject: [PATCH 04/15] adding OCI ObjectStorage TTL and composite key support Signed-off-by: lucasjellema --- .../supported-state-stores/_index.md | 2 +- .../setup-oci-objectstorage.md | 63 +++++++++++++++++-- 2 files changed, 60 insertions(+), 5 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md index b7c8644d3..70c209e93 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/_index.md @@ -65,4 +65,4 @@ The following stores are supported, at various levels, by the Dapr state managem | Name |CRUD|Transactional|ETag| [TTL]({{< ref state-store-ttl.md >}}) | [Actors]({{< ref howto-actors.md >}}) | [Query]({{< ref howto-state-query-api.md >}}) | Status | Component version | Since | |------------------------------------------------------------------|----|-------------|----|----|----|----|-------|----|-----| -| [OCI Object Storage]({{< ref setup-oci-objectstorage.md >}}) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | Alpha | v1 | 1.6 | +| [OCI Object Storage]({{< ref setup-oci-objectstorage.md >}}) | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | Alpha | v1 | 1.6 | diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md index b202a45bf..cd8345b71 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -74,7 +74,7 @@ In order to setup OCI Object Storage as a state store, you will need the followi ## What Happens at Runtime? -Every state entry is represented by an object in OCI Object Storage. The OCI Object Storage state store uses the `key` property provided in the requests to the Dapr API to determine the name of the object. The `value` is stored as the (literal) content of the object. Each object is assigned a unique ETag value - whenever it is created or updated (aka overwritten). +Every state entry is represented by an object in OCI Object Storage. The OCI Object Storage state store uses the `key` property provided in the requests to the Dapr API to determine the name of the object. The `value` is stored as the (literal) content of the object. Each object is assigned a unique ETag value - whenever it is created or updated (aka overwritten); this is native behavior of OCI Object Storage. The state store assigns a meta data tag to every object it writes; the tag is __category__ and its value is __dapr-state-store__. This allows the objects created as state for Daprized applications to be identified. For example, the following operation @@ -91,12 +91,67 @@ curl -X POST http://localhost:3500/v1.0/state \ will create the following object: -| Bucket | Object Name | Object Content | -| ------------ | ------- | ----- | -| as specified with **bucketName** in components.yaml | nihilus | darth | +| Bucket | Directory | Object Name | Object Content | Meta Tags | +| ------------ | ------- | ----- | ----- | ---- | +| as specified with **bucketName** in components.yaml | - (root) | nihilus | darth | category: dapr-state-store + + +Dapr uses a fixed key scheme with *composite keys* to partition state across applications. For general states, the key format is: +`App-ID||state key` +The OCI Object Storage state store maps the first key segment (for App-ID) to a directory within a bucket, using the [Prefixes and Hierarchy used for simulating a directory structure as described in the OCI Object Storage documentation](https://docs.oracle.com/en-us/iaas/Content/Object/Tasks/managingobjects.htm#nameprefix). + +The following operation therefore (notice the composite key) + +```shell +curl -X POST http://localhost:3500/v1.0/state \ + -H "Content-Type: application/json" + -d '[ + { + "key": "myApplication||nihilus", + "value": "darth" + } + ]' +``` + +will create the following object: + +| Bucket | Directory | Object Name | Object Content | Meta Tags | +| ------------ | ------- | ----- | ----- | ---- | +| as specified with **bucketName** in components.yaml | myApplication | nihilus | darth | category: dapr-state-store + You will be able to inspect all state stored through the OCI Object Storage state store by inspecting the contents of the bucket through the console, the APIs, CLI or SDKs. By going directly to the bucket, you can prepare state that will be available as state to your application at runtime. +## Time To Live and State Expiration +The OCI Object Storage state store supports Dapr's Time To Live logic that ensure that state cannot be retrieved after it has expired. See [this How To on Setting State Time To Live]({{< ref "state-store-ttl.md" >}}) for details. + +OCI Object Storage does not have native support for a Time To Live setting. The implementation in this component uses a meta data tag put on each object for which a TTL has been specified. The tag is called **expiry-time-from-ttl** and it contains a string in ISO date time format with the UTC based expiry time. When state is retrieved through a call to Get, this component checks if it has the **expiry-time-from-ttl** set and if so it checks whether it is in the past. In that case, no state is returned. + +The following operation therefore (notice the composite key) + +```shell +curl -X POST http://localhost:3500/v1.0/state \ + -H "Content-Type: application/json" + -d '[ + { + "key": "temporary", + "value": "ephemeral", + "metadata": {"ttlInSeconds": "120"}} + } + ]' +``` + +will create the following object: + +| Bucket | Directory | Object Name | Object Content | Meta Tags | +| ------------ | ------- | ----- | ----- | ---- | +| as specified with **bucketName** in components.yaml | - | nihilus | darth | category: dapr-state-store , expiry-time-from-ttl: 2022-01-06T08:34:32 + +The exact value of the expiry-time-from-ttl depends of course on the time at which the state was created and will be 120 seconds later than that moment. + + +Note that expired state is not removed from the state store by this component. An application operator may decide to run a periodic job that does a form of garbage collection in order to explicitly remove all state that has an **expiry-time-from-ttl** label with a timestamp in the past. + ## Concurrency OCI Object Storage state concurrency is achieved by using `ETag`s. Each object in OCI Object Storage is assigned a unique ETag when it is created or updated (aka replaced). When the Set and Delete requests for this state store specify the FirstWrite concurrency policy, then the request need to provide the actual ETag value for the state to be written or removed for the request to be successful. From 63c4c158108ca1a60a7ad687a0f5101532c6f8e7 Mon Sep 17 00:00:00 2001 From: lucasjellema Date: Sun, 9 Jan 2022 09:11:37 +0100 Subject: [PATCH 05/15] Adding InstancePrincipalAuthentication to docs on OCI ObjectStorage state store Signed-off-by: lucasjellema --- .../setup-oci-objectstorage.md | 44 +++++++++++-------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md index cd8345b71..4527e4469 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -21,19 +21,21 @@ spec: type: state.oci.objectstorage version: v1 metadata: + - name: instancePrincipalAuthentication + value: <"true" or "false"> # Optional. default: "false" - name: tenancyOCID - value: + value: # Not used when instancePrincipalAuthentication == "true" - name: userOCID - value: + value: # Not used when instancePrincipalAuthentication == "true" - name: fingerPrint - value: - - name: privateKey + value: # Not used when instancePrincipalAuthentication == "true" + - name: privateKey # Not used when instancePrincipalAuthentication == "true" value: | -----BEGIN RSA PRIVATE KEY----- REPLACE-WIH-PRIVATE-KEY-AS-IN-PEM-FILE - -----END RSA PRIVATE KEY----- + -----END RSA PRIVATE KEY----- - name: region - value: + value: # Not used when instancePrincipalAuthentication == "true" - name: bucketName value: - name: compartmentOCID @@ -49,25 +51,31 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| tenancyOCID | Y | The OCI tenancy identifier. | `"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`. -| userOCID | Y | The OCID for an OCI account (this account requires permissions to access OCI Object Storage).| `"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"` -| fingerPrint | Y | Fingerprint of the public key. | `"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"` -| privateKey | Y | Private key of the RSA key pair | `"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"` -| region | Y | OCI Region | `"us-ashburn-1"` +| instancePrincipalAuthentication | N | Boolean to indicate whether instance principal based authentication is used. Default: `"false"` | `"true"` or `"false"` . +| tenancyOCID | Y | The OCI tenancy identifier. Not required nor used when instancePrincipalAuthentication is true. | `"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`. +| userOCID | Y | The OCID for an OCI account (this account requires permissions to access OCI Object Storage). Not required nor used when instancePrincipalAuthentication is true.| `"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"` +| fingerPrint | Y | Fingerprint of the public key. Not required nor used when instancePrincipalAuthentication is true. | `"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"` +| privateKey | Y | Private key of the RSA key pair. Not required nor used when instancePrincipalAuthentication is true. | `"MIIEoyuweHAFGFG2727as+7BTwQRAIW4V"` +| region | Y | OCI Region. Not required nor used when instancePrincipalAuthentication is true. | `"us-ashburn-1"` | bucketName | Y | Name of the bucket written to and read from (and if necessary created) | `"application-state-store-bucket"` -| compartmentOCID | Y | The OCID for the compartment that contains the bucket | `"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"` +| compartmentOCID | Y | The OCID for the compartment that contains the bucket | `"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"` ## Setup OCI Object Storage -The OCI Object Storage state store needs to interact through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. +The OCI Object Storage state store needs to interact with Oracle Cloud Infrastructure. The state store supports two different approaches to authentication. One is based on an identity (a user or service account) and the other is instance principal authentication leveraging the permissions granted to the cmopute instance running the application workload. + +Dapr-applications running on Oracle Cloud Infrastructure - in a compute instance, a container on Kubernetes or as a function - can leverage instance principal authentication. See the [OCI documentation on calling OCI Services from instances](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm) for more background. In short: The instance needs to be member of a Dynamic Group and this Dynamic Group needs to get permissions for interacting with the Object Storage service through IAM policies. In case of such instance principal authentication, specify property instancePrincipalAuthentication as `"true"`. You do not need to configure the properties tenancyOCID, userOCID, region, fingerPrint and privateKey - these will be ignored if you define values for them. + +Identity based authentication interact with OCI through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. If you wish to create the bucket for Dapr to use, you can do so beforehand. However, Object Storage state provider will create one - in the specified compartment - for you automatically if it doesn't exist. In order to setup OCI Object Storage as a state store, you will need the following properties: -- **tenancyOCID**: The identifier for the OCI cloud tenancy in which the state is to be stored. -- **userOCID**: The identifier for the account used by the state store component to connect to OCI; this must be an account with appropriate permissions on the OCI Object Storage service in the specified compartment and bucket -- **fingerPrint**: The fingerprint for the public key in the RSA key pair generated for the account indicated by **userOCID** -- **privateKey**: The private key in the RSA key pair generated for the account indicated by **userOCID** -- **region**: The OCI region - for example **us-ashburn-1**, **eu-amsterdam-1**, **ap-mumbai-1** +- **instancePrincipalAuthentication**: The flag that indicates if instance principal based authentication should be used. +- **tenancyOCID**: The identifier for the OCI cloud tenancy in which the state is to be stored. Not used when **instancePrincipalAuthentication** is true. +- **userOCID**: The identifier for the account used by the state store component to connect to OCI; this must be an account with appropriate permissions on the OCI Object Storage service in the specified compartment and bucket. Not used when **instancePrincipalAuthentication** is true. +- **fingerPrint**: The fingerprint for the public key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true. +- **privateKey**: The private key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true. +- **region**: The OCI region - for example **us-ashburn-1**, **eu-amsterdam-1**, **ap-mumbai-1**. Not used when **instancePrincipalAuthentication** is true. - **bucketName**: The name of the bucket on OCI Object Storage in which state will be created. This bucket can exist already when the state store is initialized or it will be created during initialization of the state store. Note that the name of buckets is unique within a namespace - **compartmentOCID**: The identifier of the compartment within the tenancy in which the bucket exists or will be created. From 61c072e4ffd7c3d9692e9ff08f4c73ac12e26ae5 Mon Sep 17 00:00:00 2001 From: lucasjellema Date: Sun, 9 Jan 2022 21:29:30 +0100 Subject: [PATCH 06/15] Describe Resource Principal Authentication, remove Functions from description of Instance Principal Authentication, Fix type Signed-off-by: lucasjellema --- .../supported-state-stores/setup-oci-objectstorage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md index 4527e4469..60ba891c7 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -61,9 +61,9 @@ The above example uses secrets as plain strings. It is recommended to use a secr | compartmentOCID | Y | The OCID for the compartment that contains the bucket | `"ocid1.compartment.oc1..aaaaaaaacsssekayyuq7asjh78"` ## Setup OCI Object Storage -The OCI Object Storage state store needs to interact with Oracle Cloud Infrastructure. The state store supports two different approaches to authentication. One is based on an identity (a user or service account) and the other is instance principal authentication leveraging the permissions granted to the cmopute instance running the application workload. +The OCI Object Storage state store needs to interact with Oracle Cloud Infrastructure. The state store supports two different approaches to authentication. One is based on an identity (a user or service account) and the other is instance principal authentication leveraging the permissions granted to the compute instance running the application workload. Note: Resource Principal Authentication - used for resources that are not instances such as serverless functions - is not currently supported. -Dapr-applications running on Oracle Cloud Infrastructure - in a compute instance, a container on Kubernetes or as a function - can leverage instance principal authentication. See the [OCI documentation on calling OCI Services from instances](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm) for more background. In short: The instance needs to be member of a Dynamic Group and this Dynamic Group needs to get permissions for interacting with the Object Storage service through IAM policies. In case of such instance principal authentication, specify property instancePrincipalAuthentication as `"true"`. You do not need to configure the properties tenancyOCID, userOCID, region, fingerPrint and privateKey - these will be ignored if you define values for them. +Dapr-applications running on Oracle Cloud Infrastructure - in a compute instance or as a container on Kubernetes - can leverage instance principal authentication. See the [OCI documentation on calling OCI Services from instances](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm) for more background. In short: The instance needs to be member of a Dynamic Group and this Dynamic Group needs to get permissions for interacting with the Object Storage service through IAM policies. In case of such instance principal authentication, specify property instancePrincipalAuthentication as `"true"`. You do not need to configure the properties tenancyOCID, userOCID, region, fingerPrint and privateKey - these will be ignored if you define values for them. Identity based authentication interact with OCI through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. From 6cd8144d7465aaec15072ae21fcd8258b4326370 Mon Sep 17 00:00:00 2001 From: lucasjellema Date: Mon, 10 Jan 2022 14:52:10 +0100 Subject: [PATCH 07/15] Adding Configuration File based authentication to OCI ObjectStorage state store docs Signed-off-by: lucasjellema --- .../setup-oci-objectstorage.md | 36 +++++++++++++------ 1 file changed, 25 insertions(+), 11 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md index 60ba891c7..4dfbf38ff 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -23,19 +23,25 @@ spec: metadata: - name: instancePrincipalAuthentication value: <"true" or "false"> # Optional. default: "false" + - name: configFileAuthentication + value: <"true" or "false"> # Optional. default: "false" . Not used when instancePrincipalAuthentication == "true" + - name: configFilePath + value: # Optional. default: the operating system specific default location for the OCI config file; on Linux: "~/.oci/config" . Only used when configFileAuthentication == "true" + - name: configFileProfile + value: # Optional. default: "DEFAULT" . Only used when configFileAuthentication == "true" - name: tenancyOCID - value: # Not used when instancePrincipalAuthentication == "true" + value: # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" - name: userOCID - value: # Not used when instancePrincipalAuthentication == "true" + value: # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" - name: fingerPrint - value: # Not used when instancePrincipalAuthentication == "true" - - name: privateKey # Not used when instancePrincipalAuthentication == "true" + value: # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" + - name: privateKey # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" value: | -----BEGIN RSA PRIVATE KEY----- REPLACE-WIH-PRIVATE-KEY-AS-IN-PEM-FILE -----END RSA PRIVATE KEY----- - name: region - value: # Not used when instancePrincipalAuthentication == "true" + value: # Not used when configFileAuthentication == "true" or instancePrincipalAuthentication == "true" - name: bucketName value: - name: compartmentOCID @@ -52,6 +58,9 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| | instancePrincipalAuthentication | N | Boolean to indicate whether instance principal based authentication is used. Default: `"false"` | `"true"` or `"false"` . +| configFileAuthentication | N | Boolean to indicate whether identity credential details are provided through a configuration file. Default: `"false"` Not required nor used when instancePrincipalAuthentication is true. | `"true"` or `"false"` . +| configFilePath | N | Full path name to the OCI configuration file. Default: the default location on your operating system for the OCI confile file, for example `"~/.oci/config"` on Linux. Not used when instancePrincipalAuthentication is true. | `"/home/apps/configuration-files/myOCIConfig.txt"`. +| configFileProfile | N | Name of profile in configuration file to use. Default: `"DEFAULT"` Not used when instancePrincipalAuthentication is true. | `"DEFAULT"` or `"PRODUCTION"` . | tenancyOCID | Y | The OCI tenancy identifier. Not required nor used when instancePrincipalAuthentication is true. | `"ocid1.tenancy.oc1..aaaaaaaag7c7sljhsdjhsdyuwe723"`. | userOCID | Y | The OCID for an OCI account (this account requires permissions to access OCI Object Storage). Not required nor used when instancePrincipalAuthentication is true.| `"ocid1.user.oc1..aaaaaaaaby4oyyyuqwy7623yuwe76"` | fingerPrint | Y | Fingerprint of the public key. Not required nor used when instancePrincipalAuthentication is true. | `"02:91:6c:49:e2:94:21:15:a7:6b:0e:a7:34:e1:3d:1b"` @@ -65,17 +74,22 @@ The OCI Object Storage state store needs to interact with Oracle Cloud Infrastru Dapr-applications running on Oracle Cloud Infrastructure - in a compute instance or as a container on Kubernetes - can leverage instance principal authentication. See the [OCI documentation on calling OCI Services from instances](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm) for more background. In short: The instance needs to be member of a Dynamic Group and this Dynamic Group needs to get permissions for interacting with the Object Storage service through IAM policies. In case of such instance principal authentication, specify property instancePrincipalAuthentication as `"true"`. You do not need to configure the properties tenancyOCID, userOCID, region, fingerPrint and privateKey - these will be ignored if you define values for them. -Identity based authentication interact with OCI through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. +Identity based authentication interacts with OCI through an OCI account that has permissions to create, read and delete objects through OCI Object Storage in the indicated bucket and that is allowed to create a bucket in the specified compartment if the bucket is not created beforehand. The OCI documentation [describes how to create an OCI Account](https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users). The interaction by the state store is performed using the public key's fingerprint and a private key from an RSA Key Pair generated for the OCI account. The [instructions for generating the key pair and getting hold of the required information](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm) are available in the OCI documentation. + +Details for the identity and identity's credentials to be used for interaction with OCI can be provided directly in the Dapr component properties file - using the properties tenancyOCID, userOCID, fingerPrint, privateKey and region - or can be provided from a configuration file as is common for many OCI related tools (such as CLI and Terraform) and SDKs. In the latter case, a default configuration file can be assumed (such as ~/.oci/config on Linux) or the exact file name and path can be provided through property configFilePath. A configuration file can contain multiple profiles; the desired profile can be specified through property configFileProfile. If no value is provided, DEFAULT is used as the name for the profile to be used. Note: if the indicated profile is not found, then the DEFAULT profile (if it exists) is used instead. The OCI SDK documentation gives [details about the definition of the configuration file](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm). If you wish to create the bucket for Dapr to use, you can do so beforehand. However, Object Storage state provider will create one - in the specified compartment - for you automatically if it doesn't exist. In order to setup OCI Object Storage as a state store, you will need the following properties: - **instancePrincipalAuthentication**: The flag that indicates if instance principal based authentication should be used. -- **tenancyOCID**: The identifier for the OCI cloud tenancy in which the state is to be stored. Not used when **instancePrincipalAuthentication** is true. -- **userOCID**: The identifier for the account used by the state store component to connect to OCI; this must be an account with appropriate permissions on the OCI Object Storage service in the specified compartment and bucket. Not used when **instancePrincipalAuthentication** is true. -- **fingerPrint**: The fingerprint for the public key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true. -- **privateKey**: The private key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true. -- **region**: The OCI region - for example **us-ashburn-1**, **eu-amsterdam-1**, **ap-mumbai-1**. Not used when **instancePrincipalAuthentication** is true. +- **configFileAuthentication**: The flag that indicates if the OCI identity credential details are provided through a configuration file. Not used when **instancePrincipalAuthentication** is true. +- **configFilePath**: Full path name to the OCI configuration file. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is not true. +- **configFileProfile**: Name of profile in configuration file to use. Default: `"DEFAULT"` Not required nor used when instancePrincipalAuthentication is true or **configFileAuthentication** is not true. When the specified profile is not found in the configuration file, the DEFAULT profile is used when it exists +- **tenancyOCID**: The identifier for the OCI cloud tenancy in which the state is to be stored. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is true. +- **userOCID**: The identifier for the account used by the state store component to connect to OCI; this must be an account with appropriate permissions on the OCI Object Storage service in the specified compartment and bucket. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is true. +- **fingerPrint**: The fingerprint for the public key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is true. +- **privateKey**: The private key in the RSA key pair generated for the account indicated by **userOCID**. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is true. +- **region**: The OCI region - for example **us-ashburn-1**, **eu-amsterdam-1**, **ap-mumbai-1**. Not used when **instancePrincipalAuthentication** is true - **bucketName**: The name of the bucket on OCI Object Storage in which state will be created. This bucket can exist already when the state store is initialized or it will be created during initialization of the state store. Note that the name of buckets is unique within a namespace - **compartmentOCID**: The identifier of the compartment within the tenancy in which the bucket exists or will be created. From 37f359bb442f2907fbf5c3a07b7bca1fffa09647 Mon Sep 17 00:00:00 2001 From: Lucas Jellema Date: Wed, 12 Jan 2022 05:52:04 +0100 Subject: [PATCH 08/15] Apply suggestions from code review Signed-off-by: lucasjellema Co-authored-by: Mark Fussell Signed-off-by: lucasjellema --- .../supported-state-stores/setup-oci-objectstorage.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md index 4dfbf38ff..67fb4a4d3 100644 --- a/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md +++ b/daprdocs/content/en/reference/components-reference/supported-state-stores/setup-oci-objectstorage.md @@ -80,7 +80,7 @@ Details for the identity and identity's credentials to be used for interaction w If you wish to create the bucket for Dapr to use, you can do so beforehand. However, Object Storage state provider will create one - in the specified compartment - for you automatically if it doesn't exist. -In order to setup OCI Object Storage as a state store, you will need the following properties: +In order to setup OCI Object Storage as a state store, you need the following properties: - **instancePrincipalAuthentication**: The flag that indicates if instance principal based authentication should be used. - **configFileAuthentication**: The flag that indicates if the OCI identity credential details are provided through a configuration file. Not used when **instancePrincipalAuthentication** is true. - **configFilePath**: Full path name to the OCI configuration file. Not used when **instancePrincipalAuthentication** is true or **configFileAuthentication** is not true. @@ -111,7 +111,7 @@ curl -X POST http://localhost:3500/v1.0/state \ ]' ``` -will create the following object: +creates the following object: | Bucket | Directory | Object Name | Object Content | Meta Tags | | ------------ | ------- | ----- | ----- | ---- | @@ -163,7 +163,7 @@ curl -X POST http://localhost:3500/v1.0/state \ ]' ``` -will create the following object: +creates the following object: | Bucket | Directory | Object Name | Object Content | Meta Tags | | ------------ | ------- | ----- | ----- | ---- | @@ -176,7 +176,7 @@ Note that expired state is not removed from the state store by this component. A ## Concurrency -OCI Object Storage state concurrency is achieved by using `ETag`s. Each object in OCI Object Storage is assigned a unique ETag when it is created or updated (aka replaced). When the Set and Delete requests for this state store specify the FirstWrite concurrency policy, then the request need to provide the actual ETag value for the state to be written or removed for the request to be successful. +OCI Object Storage state concurrency is achieved by using `ETag`s. Each object in OCI Object Storage is assigned a unique ETag when it is created or updated (aka replaced). When the `Set` and `Delete` requests for this state store specify the FirstWrite concurrency policy, then the request need to provide the actual ETag value for the state to be written or removed for the request to be successful. ## Consistency From 604485977b22c9f66ac008f5b358fe03859fed5f Mon Sep 17 00:00:00 2001 From: greenie-msft <56556602+greenie-msft@users.noreply.github.com> Date: Wed, 19 Jan 2022 16:26:44 -0800 Subject: [PATCH 09/15] Upmerge v1.5 to v1.6 20220119 (#2119) * moving middleware to samples Signed-off-by: Paul Yuknewicz * Updated middleware doc to point to updated sample location Signed-off-by: Paul Yuknewicz * Fixing one more link after moving middleware code from quickstarts to samples repo Signed-off-by: Paul Yuknewicz Co-authored-by: Paul Yuknewicz --- daprdocs/content/en/developing-applications/middleware.md | 2 +- daprdocs/content/en/getting-started/quickstarts.md | 1 - .../supported-middleware/middleware-oauth2.md | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/daprdocs/content/en/developing-applications/middleware.md b/daprdocs/content/en/developing-applications/middleware.md index a48ceac16..282cffd2d 100644 --- a/daprdocs/content/en/developing-applications/middleware.md +++ b/daprdocs/content/en/developing-applications/middleware.md @@ -74,4 +74,4 @@ After the components-contrib change has been accepted, submit another pull reque * [Component schema]({{< ref component-schema.md >}}) * [Configuration overview]({{< ref configuration-overview.md >}}) -* [Middleware quickstart](https://github.com/dapr/quickstarts/tree/master/middleware) +* [Middleware sample](https://github.com/dapr/samples/tree/master/middleware-oauth-google) diff --git a/daprdocs/content/en/getting-started/quickstarts.md b/daprdocs/content/en/getting-started/quickstarts.md index de6a3313c..ecf04966a 100644 --- a/daprdocs/content/en/getting-started/quickstarts.md +++ b/daprdocs/content/en/getting-started/quickstarts.md @@ -22,7 +22,6 @@ The [Dapr Quickstarts](https://github.com/dapr/quickstarts/tree/v1.5.0) are a co | [Distributed Calculator](https://github.com/dapr/quickstarts/tree/v1.5.0/distributed-calculator) | Demonstrates a distributed calculator application that uses Dapr services to power a React web app. Highlights polyglot (multi-language) programming, service invocation and state management. | | [Pub/Sub](https://github.com/dapr/quickstarts/tree/v1.5.0/pub-sub) | Demonstrates how to use Dapr to enable pub-sub applications. Uses Redis as a pub-sub component. | | [Bindings](https://github.com/dapr/quickstarts/tree/v1.5.0/bindings) | Demonstrates how to use Dapr to create input and output bindings to other components. Uses bindings to Kafka. | -| [Middleware](https://github.com/dapr/quickstarts/tree/v1.5.0/middleware) | Demonstrates use of Dapr middleware to enable OAuth 2.0 authorization. | | [Observability](https://github.com/dapr/quickstarts/tree/v1.5.0/observability) | Demonstrates Dapr tracing capabilities. Uses Zipkin as a tracing component. | | [Secret Store](https://github.com/dapr/quickstarts/tree/v1.5.0/secretstore) | Demonstrates the use of Dapr Secrets API to access secret stores. | diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md index 7097835a1..90e0a3fa1 100644 --- a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md @@ -74,7 +74,7 @@ spec: ## Related links - [Configure API authorization with OAuth]({{< ref oauth >}}) -- [Middleware OAuth quickstart](https://github.com/dapr/quickstarts/tree/master/middleware) +- [Middleware OAuth sample (interactive)](https://github.com/dapr/samples/tree/master/middleware-oauth-google) - [Middleware]({{< ref middleware.md >}}) - [Configuration concept]({{< ref configuration-concept.md >}}) - [Configuration overview]({{< ref configuration-overview.md >}}) From 50911c11264af4742b78604ca9de7a797cdf7067 Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan Date: Thu, 20 Jan 2022 16:47:20 +0530 Subject: [PATCH 10/15] Update docs for Event Hubs pubsub Signed-off-by: Mukundan Sundararajan --- .gitignore | 1 + .../supported-pubsub/_index.md | 2 +- .../supported-pubsub/setup-azure-eventhubs.md | 37 ++++++++++++++++++- 3 files changed, 37 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 35a57cc3a..2cf039ab1 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ node_modules/ daprdocs/public daprdocs/resources/_gen .venv/ +.hugo_build.lock \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md index fb78b1374..d7ad5a8c6 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md @@ -48,5 +48,5 @@ Table captions: | Name | Status | Component version | Since | |-----------------------------------------------------------|--------| ----------------| -- | -| [Azure Event Hubs]({{< ref setup-azure-eventhubs.md >}}) | Alpha | v1 | 1.0 | +| [Azure Event Hubs]({{< ref setup-azure-eventhubs.md >}}) | Beta | v1 | 1.6 | | [Azure Service Bus]({{< ref setup-azure-servicebus.md >}})| Stable | v1 | 1.0 | diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md index 1af3cd062..e47b03e2f 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md @@ -9,6 +9,7 @@ aliases: ## Component format To setup Azure Event Hubs pubsub create a component of type `pubsub.azure.eventhubs`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. +Apart from the configuration metadata fields shown below, Azure Event Hubs also support [Azure Authentication]({{< ref "authenticating-azure.md" >}}) mechanisms. ```yaml apiVersion: dapr.io/v1alpha1 @@ -20,8 +21,23 @@ spec: type: pubsub.azure.eventhubs version: v1 metadata: - - name: connectionString + - name: connectionString # Either connectionString or eventHubNamespace. Should not be used when + # Azure Authentication mechanism is used. value: "Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}" + - name: eventHubNamespace # Either connectionString or eventHubNamespace. Should be used when + # Azure Authentication mechanism is used. + value: "namespace" + - name: enableEntityManagement + value: "false" + ## The following four properties are needed only if enableEntityManagement is set to true + - name: resourceGroupName + value: "test-rg" + - name: subscriptionID + value: "value of Azure subscription ID" + - name: partitionCount + value: "1" + - name: messageRetentionInDays + ## Subscriber attributes - name: storageAccountName value: "myeventhubstorage" - name: storageAccountKey @@ -38,10 +54,16 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| connectionString | Y | Connection-string for the Event Hubs | `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` +| connectionString | Y | Connection-string for the Event Hub or the Event Hub namespace. Mutally exclusive with `eventHubNamespace` field. Not to be used when [Azure Authentication]({{< ref "authenticating-azure.md" >}}) is used | `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` or `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key}"` +| eventHubNamespace | Y | The Event Hub Namespace name. Mutally exclusive with `connectionString` field. To be used when [Azure Authentication]({{< ref "authenticating-azure.md" >}}) is used | `"namespace"` | storageAccountName | Y | Storage account name to use for the EventProcessorHost |`"myeventhubstorage"` | storageAccountKey | Y | Storage account key to use for the EventProcessorHost. Can be `secretKeyRef` to use a secret reference | `"112233445566778899"` | storageContainerName | Y | Storage container name for the storage account name. | `"myeventhubstoragecontainer"` +| enableEntityManagement | N | Boolean value to allow management of EventHub namespace. Default: `false` | `"true", "false"` +| resourceGroupName | N | Name of the resource group the event hub namespace is a part of. Needed when entity management is enabled | `"test-rg"` +| subscriptionID | N | Azure subscription ID value. Needed when entity management is enabled | `"azure subscription id"` +| partitionCount | N | Number of partitions for the new event hub. Only used when entity management is enabled. Default: `"1"` | `"2"` +| messageRetentionInDays | N | Number of days to retain messages for in the newly created event hub. Used only when entity management is enabled. Default: `"1"` | `"90"` ## Create an Azure Event Hub @@ -58,6 +80,16 @@ For example, a Dapr app running on Kubernetes with `dapr.io/app-id: "myapp"` wil Note: Dapr passes the name of the Consumer group to the EventHub and so this is not supplied in the metadata. +## Entity Management + +When entity management is enabled in configuration, as long as the application has the right role and permissions to manipulate the Event Hub namespace, creation of Event Hubs and consumer groups can be done on the fly. + +The Evet Hub name is the `topic` field in the incoming request to publish or subscribe to, while the consumer group name is the name of the `dapr app` which subscribes to a given Event Hub. For example, a Dapr app running on Kubernetes with name `dapr.io/app-id: "myapp"` requires an Event Hubs consumer group named `myapp`. + +Entity management is only possible when using [Azure Authentication]({{< ref "authenticating-azure.md" >}}) mechanisms and not via `connectionString`. + +Note: Dapr passes the name of the Consumer group to the EventHub and this is not supplied in the metadata. + ## Subscribing to Azure IoT Hub Events Azure IoT Hub provides an [endpoint that is compatible with Event Hubs](https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-messages-read-builtin#read-from-the-built-in-endpoint), so the Azure Event Hubs pubsub component can also be used to subscribe to Azure IoT Hub events. @@ -98,3 +130,4 @@ For example, the headers of a delivered HTTP subscription message would contain: - [Basic schema for a Dapr component]({{< ref component-schema >}}) - Read [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) +- [Authentication to Azure]({{< ref "authenticating-azure.md" >}}) From 15bb344f5ab77aa909439b6b04a187558128fc9e Mon Sep 17 00:00:00 2001 From: Mukundan Sundararajan Date: Thu, 20 Jan 2022 23:56:32 +0530 Subject: [PATCH 11/15] fix typo Signed-off-by: Mukundan Sundararajan --- .../supported-pubsub/setup-azure-eventhubs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md index e47b03e2f..16de600b6 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/setup-azure-eventhubs.md @@ -9,7 +9,7 @@ aliases: ## Component format To setup Azure Event Hubs pubsub create a component of type `pubsub.azure.eventhubs`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. -Apart from the configuration metadata fields shown below, Azure Event Hubs also support [Azure Authentication]({{< ref "authenticating-azure.md" >}}) mechanisms. +Apart from the configuration metadata fields shown below, Azure Event Hubs also supports [Azure Authentication]({{< ref "authenticating-azure.md" >}}) mechanisms. ```yaml apiVersion: dapr.io/v1alpha1 From 429bce6f30e4a7384d41ddcecf2d448441f1c35c Mon Sep 17 00:00:00 2001 From: Shivam Kumar Date: Fri, 21 Jan 2022 00:14:31 +0530 Subject: [PATCH 12/15] Update MQTT pubsub to beta (#2113) Signed-off-by: shivam Co-authored-by: Mark Fussell --- .../reference/components-reference/supported-pubsub/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md index fb78b1374..4d5c1ccd0 100644 --- a/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-pubsub/_index.md @@ -24,7 +24,7 @@ Table captions: |-------------------------------------------------------|--------| -----| ------------- | | [Apache Kafka]({{< ref setup-apache-kafka.md >}}) | Stable | v1 | 1.5 | | [Hazelcast]({{< ref setup-hazelcast.md >}}) | Alpha | v1 | 1.0 | -| [MQTT]({{< ref setup-mqtt.md >}}) | Alpha | v1 | 1.0 | +| [MQTT]({{< ref setup-mqtt.md >}}) | Beta | v1 | 1.6 | | [NATS Streaming]({{< ref setup-nats-streaming.md >}}) | Beta | v1 | 1.0 | | [In Memory]({{< ref setup-inmemory.md >}}) | Alpha | v1 | 1.4 | | [JetStream]({{< ref setup-jetstream.md >}}) | Alpha | v1 | 1.4 | From 888f47f145ee7f7c8d70409d9d73f7e943b02c28 Mon Sep 17 00:00:00 2001 From: Abel Perez Martinez Date: Thu, 20 Jan 2022 18:59:05 +0000 Subject: [PATCH 13/15] Added notes for EKS users to watch out for hostnework issue (#2112) Signed-off-by: Abel Perez Martinez Co-authored-by: Mark Fussell --- .../troubleshooting/common_issues.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/daprdocs/content/en/operations/troubleshooting/common_issues.md b/daprdocs/content/en/operations/troubleshooting/common_issues.md index f63e0d54d..c374dd00f 100644 --- a/daprdocs/content/en/operations/troubleshooting/common_issues.md +++ b/daprdocs/content/en/operations/troubleshooting/common_issues.md @@ -64,6 +64,32 @@ In order to further diagnose any issue, check the logs of the Dapr sidecar injec *Note: If you installed Dapr to a different namespace, replace dapr-system above with the desired namespace* +If you are deploying Dapr on Amazon EKS and using an overlay network such as Calico, you will need to set `hostNetwork` parameter to true, this is a limitation of EKS with such CNIs. + +You can set this parameter using Helm `values.yaml` file: + +``` +helm upgrade --install dapr dapr/dapr \ + --namespace dapr-system \ + --create-namespace \ + --values values.yaml +``` + +`values.yaml` +```yaml +dapr_sidecar_injector: + hostNetwork: true +``` + +or using command line: + +``` +helm upgrade --install dapr dapr/dapr \ + --namespace dapr-system \ + --create-namespace \ + --set dapr_sidecar_injector.hostNetwork=true +``` + ## My pod is in CrashLoopBackoff or another failed state due to the daprd sidecar If the Dapr sidecar (`daprd`) is taking too long to initialize, this might be surfaced as a failing health check by Kubernetes. From 33981f34f8752d87c3856873efdc98d583eb7177 Mon Sep 17 00:00:00 2001 From: greenie-msft <56556602+greenie-msft@users.noreply.github.com> Date: Thu, 20 Jan 2022 12:35:59 -0800 Subject: [PATCH 14/15] List the specific software dependencies tested for a given Dapr releaseList (#2105) * List the specific software dependencies tested for a given Dapr releaseList Signed-off-by: Nick Greenfield * Add OTEL link Signed-off-by: Nick Greenfield * Change OTEL link Signed-off-by: Nick Greenfield Co-authored-by: Mark Fussell --- .../en/operations/support/support-release-policy.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/daprdocs/content/en/operations/support/support-release-policy.md b/daprdocs/content/en/operations/support/support-release-policy.md index 6bd27c761..7bed1e92d 100644 --- a/daprdocs/content/en/operations/support/support-release-policy.md +++ b/daprdocs/content/en/operations/support/support-release-policy.md @@ -95,9 +95,14 @@ After announcing a future breaking change, the change will happen in 2 releases ## 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 >}}) -### Supported Kubernetes versions +### Supported versions of dependencies +Below is a list of software that the latest version of Dapr (v{{% dapr-latest-version long="true" %}}) has been tested against. -Dapr follows [Kubernetes Version Skew Policy](https://kubernetes.io/releases/version-skew-policy). +| Dependency | Supported Version | +|-----------------------|----------------------------------------------------------------------------------------------------------------------------------| +| Kubernetes | Dapr support for Kubernetes is aligned with [Kubernetes Version Skew Policy](https://kubernetes.io/releases/version-skew-policy/) | +| [Open Telemetry collector (OTEL)](https://github.com/open-telemetry/opentelemetry-collector/releases)| v0.4.0| +| [Prometheus](https://prometheus.io/download/) | v2.28 | ## Related links * Read the [Versioning policy]({{< ref support-versioning.md >}}) From 6d7f5c86c68c9382c83f48f197caa176ed02bd63 Mon Sep 17 00:00:00 2001 From: Taction Date: Fri, 21 Jan 2022 05:15:57 +0800 Subject: [PATCH 15/15] Feature/pulsar: Add tenant namespace and backoff doc (#1930) * Add tenant namespace and backoff Signed-off-by: Taction * fix review Signed-off-by: Taction Co-authored-by: Mark Fussell --- .../supported-pubsub/setup-pulsar.md | 27 ++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) 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 2c4a25a23..834df5457 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 @@ -24,14 +24,35 @@ spec: value: "localhost:6650" - name: enableTLS value: "false" -``` + - name: tenant + value: "public" + - name: namespace + value: "default" + - name: persistent + value: "true" + - name: backOffPolicy + value: "constant" + - name: backOffMaxRetries + value: "-1" +``` ## Spec metadata fields | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| host | Y | Address of the Pulsar broker. Default is `"localhost:6650"` | `"localhost:6650"`| -| enableTLS | N | Enable TLS. Default: `"false"` | `"true"`, `"false"`| +| host | Y | Address of the Pulsar broker. Default is `"localhost:6650"` | `"localhost:6650"` +| enableTLS | N | Enable TLS. Default: `"false"` | `"true"`, `"false"` +| tenant | N | The topic tenant within the instance. Tenants are essential to multi-tenancy in Pulsar, and spread across clusters. Default: `"public"` | `"public"` +| 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 kind 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. Note: the default retry behavior is to retry until it succeeds, so when you use a non-persistent theme, you can reduce or prohibit retries by defining `backOffMaxRetries` to `0`. Default: `"true"` | `"true"`, `"false"` +| backOffPolicy | N | Retry policy, `"constant"` is a backoff policy that always returns the same backoff delay. `"exponential"` is a backoff policy that increases the backoff period for each retry attempt using a randomization function that grows exponentially. Defaults to `"constant"`. | `constant`、`exponential` | +| backOffDuration | N | The fixed interval only takes effect when the `backOffPolicy` is `"constant"`. There are two valid formats, one is the fraction with a unit suffix format, and the other is the pure digital format that is processed as milliseconds. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Defaults to `"5s"`. | `"5s"`、`"5000"` | +| backOffInitialInterval | N | The backoff initial interval on retry. Only takes effect when the `backOffPolicy` is `"exponential"`. There are two valid formats, one is the fraction with a unit suffix format, and the other is the pure digital format that is processed as milliseconds. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Defaults to `"500"` | `"50"` | +| backOffMaxInterval | N | The backoff initial interval on retry. Only takes effect when the `backOffPolicy` is `"exponential"`. There are two valid formats, one is the fraction with a unit suffix format, and the other is the pure digital format that is processed as milliseconds. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Defaults to `"60s"` | `"60000"` | +| backOffMaxRetries | N | The maximum number of retries to process the message before returning an error. Defaults to `"0"` which means the component will not retry processing the message. `"-1"` will retry indefinitely until the message is processed or the application is shutdown. Any positive number is treated as the maximum retry count. | `"3"` | +| backOffRandomizationFactor | N | Randomization factor, between 1 and 0, including 0 but not 1. Randomized interval = RetryInterval * (1 ± backOffRandomizationFactor). Defaults to `"0.5"`. | `"0.5"` | +| backOffMultiplier | N | Backoff multiplier for the policy. Increments the interval by multiplying it with the multiplier. Defaults to `"1.5"` | `"1.5"` | +| backOffMaxElapsedTime | N | After MaxElapsedTime the ExponentialBackOff returns Stop. There are two valid formats, one is the fraction with a unit suffix format, and the other is the pure digital format that is processed as milliseconds. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Defaults to `"15m"` | `"15m"` | ### Delay queue