Merge remote-tracking branch 'upstream/main' into grpc-endpoint-parsi…

…ng-table

0001-P-proposal-process.md → 20221025-P-proposal-process.md

@@ -1,8 +1,8 @@
 # Improving the Dapr proposal process
 
 * Author(s): John Ewart (@johnewart), Mukundan Sundararajan (@mukundansundar)
-* State: Draft
-* Updated: 10/25/2022
+* State: Approved
+* Date: 10/25/2022
 
 ## Overview
 

0002-RCBS-Crypto-building-block.md → 20230327-RCBS-Crypto-building-block.md

@@ -69,7 +69,7 @@ Previous proposal as GitHub issue: dapr/dapr#4508
 
 ## Data flow: runtime and components
 
-![data flow](./resources/0002-RCBS-Crypto-building-block/data-flow.png)
+![data flow](./resources/20230327-RCBS-Crypto-building-block/data-flow.png)
 
 ## Dapr encryption scheme: dapr.io/enc/v1
 

20230918-S-unified-api-token-env-variable.md

@@ -0,0 +1,71 @@
+# Unify the `DAPR_API_TOKEN` env variable across all SDKs
+
+* Author(s): Elena Kolevska (@elena-kolevska)
+* State: Ready for Implementation
+* Updated: 2023-09-18
+
+## Overview
+
+This is a design proposal to unify usage of the `DAPR_API_TOKEN` variable across all SDKs.
+
+## Background
+
+Currently, the `DAPR_API_TOKEN` env variable is used in some SDKs, but not in others. For example, the Python SDK uses it, but the Javascript SDK does not. This can be confusing for users, and makes it difficult to write documentation that is consistent across all SDKs. It is also an unnecessary complication for maintainers who switch between SDKs. 
+
+And finally, with a unified environment variable across all SDKs system administrators don't need to have different configurations per application based on programming language, because the same environment variables will work with every SDK.
+
+## Related Items
+
+This has already been discussed in different repos, notably in [this issue](https://github.com/dapr/java-sdk/issues/303) in the java-sdk.
+
+We are moving to unify other environment variable across all SDKs, as discussed in [this proposal](https://github.com/dapr/proposals/blob/main/0008-S-sidecar-endpoint-tls.md).
+
+
+## Expectations and alternatives
+
+**What is in scope for this proposal?**  
+- All supported SDKs need to consistently support the `DAPR_API_TOKEN` environment variable for authentication to Dapr
+
+**SDKs that already use the `DAPR_API_TOKEN` env variable:**  
+- java-sdk
+- go-sdk
+- dotnet-sdk
+- python-sdk
+- php-sdk
+
+**SDKs that currently don't use the `DAPR_API_TOKEN` env variable:**  
+- js-sdk
+- rust-sdk
+- cpp-sdk
+
+
+## Implementation Details
+
+### Design
+
+- The `DAPR_API_TOKEN` environment variable will be used in all SDKs to authenticate to Dapr. The token will be passed to the Dapr sidecar via the `dapr-api-token` header.
+
+
+### Feature lifecycle outline
+
+- Some SDKs currently accept the a Dapr API token as an argument through the constructor. In this case, when a token is specified through the constructor of the client, it will take precedence over the environment variable.
+- If there is an existing environment variable for the Dapr api token by a different name, the new `DAPR_API_TOKEN` variable will take precedence.
+
+### Acceptance Criteria
+
+How will success be measured? 
+
+* Performance targets: N/A
+* Compabitility requirements: Same environment variables work with any SDK
+* Metrics: N/A
+
+## Completion Checklist
+
+What changes or actions are required to make this proposal complete?
+
+* SDK changes (if needed)
+    - Add support for the `DAPR_API_TOKEN` environment variable to all supported SDKs
+    - Add integration testing on each SDK when possible
+* Documentation
+    - Update documentation to reflect the new environment variable
+

20231024-CIR-trust-distribution.md

@@ -0,0 +1,117 @@
+# Dapr Trust Distribution
+
+* Author(s): joshvanl
+* State: Approved
+* Updated: 2023-10-24
+
+## Overview
+
+This is a design proposal to implement a proper trust distribution process in Dapr.
+Trust distribution will be implemented in a seamless way without downtime.
+This will improve and unlock security related features.
+
+## Background
+
+### Motivation
+
+To support the creation of features:
+
+- Proper Certificate Authority (CA) rotation (without re-using the root's private key)
+- External CA sources such as cert-manager and cloud provider CAs etc.
+- Dapr multi-cluster and networking federation
+
+Related issues:
+- [Multicluster Kubernetes](https://github.com/dapr/dapr/issues/3460)
+- [[Proposal] Support third-party CA - Integrate Cert Manager with Dapr](https://github.com/dapr/dapr/issues/3968)
+- [[Proposal] Automatic root certificate rotation](https://github.com/dapr/dapr/issues/5958)
+
+### Goals
+
+- Implement an active trust distribution mechanism for Dapr in Kubernetes that responds to updates.
+- Trust distribution in self-hosted mode can be be implemented by the user.
+- Enable root certificate rotation with no downtime.
+
+### Non-Goals
+
+- Sentry implements CA root rotation.
+- Implement external CA support, though this proposal will enable this feature to be developed in the future.
+- Implement Dapr trust federation.
+
+### Current Shortfalls
+
+Trust distribution is the act of propagating trust data to enable secure communication or networking between peers.
+In the case of Dapr, this involves propagating PEM encoded CA bundle files to clients and servers in the cluster, which are then used to authenticate peers over TLS.
+Today, their are two methods of CA deployment to Dapr; either Sentry generated or provided by the Dapr cluster administrator.
+From the prospective of trust distribution, these two modes are functionally the same as they both result in the `dapr-trust-bundle` ConfigMap containing the CA bundle, and the `dapr-trust-bundle` Secret containing the issuer certificate chain.
+From here, trust distribution for the control plane occurs by the Operator, Placement, and Injector services reading from the mounted `dapr-trust-bundle` ConfigMap.
+Trust distribution for Daprds occurs from the Injector patching the Daprd container with an environment variable containing the CA Bundle originating from the `dapr-trust-bundle` ConfigMap.
+
+The problem with the current strategy is that once trust is distributed once (the `dapr-trust-bundle` ConfigMap and Secret is populated), the root of trust cannot change in the cluster.
+This is because trust bundles are only injected to Dapr containers at Pod creation time.
+Trust anchors are also set as environment variables whose values are static for the entire duration of a unix process, meaning they cannot be dynamically updated, for example in the event of CA root rotation.
+Today, Dapr pods will have to be restarted in order to pick-up a new trust bundle.
+It is also undefined and untested as to whether the control plane components will successfully pick-up a new trust bundle during execution; though whether they can is irrelevant as Daprds do not also support this feature.
+
+## Solution
+
+### Trust Distributor
+
+It is paramount that the entity that conducts the trust distribution is separate from the entity that issues identities from that root of trust, in Dapr's case this is Sentry.
+This is because trust distribution must happen out of band of identity issuance.
+An analogous to this is roots of trust of the Internet are delivered via the computers Operating System or Internet Browser, rather than fetching them from DNS servers themselves.
+Similarly for example, asset SHA hashes should be downloaded from a separate source then the assert server themselves.
+Decoupling these roles also has the benefit of improving separation of concerns between responsibilities from the identity issuer, and the trust distributor.
+
+Trust distribution will be conducted by the Operator and written to the ConfigMap `dapr-root-ca.crt` in all Namespaces.
+The Operator is a natural fit as it is not Sentry (the identity issuance server), and machinery for Kubernetes controllers already exists in the Operator today.
+ConfigMaps are a natural choice as they can be mounted by Pods & containers in Kubernetes, and trust bundles are not secrets so Secrets are not appropriate.
+There is also prior art to other projects distributing trust in this way, such as [Istio](https://github.com/istio/istio/blob/4c65649a9b116584281fadcaf8c3dd6b42d34036/istioctl/pkg/workload/workload_test.go#L340) and cert-manager's [trust-manager](https://github.com/cert-manager/trust-manager#example-bundle).
+We can also add support for writing to Kubernetes [ClusterTrustBundles](https://github.com/kubernetes/enhancements/issues/3257), though this resource is very new, and will not be available in all target Kubernetes cluster versions.
+The `dapr-root-ca.crt` ConfigMap name is consistent with Kubernetes and Istio naming.
+The operator will source the root of trust to be distributed from the mounted `dapr-root-ca.crt` Secret in the control plane namespace.
+The operator will watch for this mounted file for updates using [fsnotify](https://github.com/fsnotify/fsnotify), and distribute the contents to the named ConfigMap in all namespaces.
+
+Once propagated, the Injector, Placement, and Dapr sidecars can mount this ConfigMap and use it as the root of trust when connecting to peers.
+Similarly, when the file is updated, these services can update their local trust stores to use the new version of the bundle.
+
+The Operator will need to metadata watch all Namespaces and ConfigMaps in the cluster.
+The Operator should no fully inform these resources as that will massively increase the memory consumption of the Operator.
+In the event of a Namespace being created, the Operator will write the ConfigMap to that namespace.
+The Operator will also ensure that the `dapr-root-ca.crt` ConfigMap stays consistent with its local trust bundle version.
+
+### CA Rotation
+
+CA rotation can now be solved by the new trust bundle being _appended_ to the existing `dapr-root-ca.crt` Secret in the control plane namespace.
+This new bundle containing the old and new CA will be propagated to all services by the Operator, allowing for a zero downtime & graceful roll over of the CA.
+The Dapr CLI will be updated to automate this task, ensuring that the new appended trust bundle has been correctly propergated to all namespaces before writing the new CA to sentry.
+Checking propagation involves ensuring the new bundle contents is present at the named ConfigMap in all namespaces.
+The CLI needs to take care of the fact that mounted ConfigMaps can take up to [60 seconds](https://github.com/kubernetes/kubernetes/blob/v1.26.0/pkg/kubelet/pod_workers.go#L1175C1-L1175C96) before the file is updated on the container mount, so there is some lag between the ConfigMap being updated and the trust bundle being updated in a service's trust store.
+
+### External CA Support
+
+External CA support is now made easier by the fact that the external CA trust bundle can be safely written to the `dapr-cert-ca.crt` Secret in the control plane namespace.
+Dapr services will now trust the external CA's root of trust.
+
+### Dapr multi-cluster and Networking Federation
+
+Similarly, the trust bundle of another Dapr cluster can be appended to the existing CA bundle so that the two clusters may trust one another.
+
+### Self Hosted Mode
+
+Self hosted mode will continue to function as before, however using a file reference for the trust bundle rather than an environment variable means that services can respond and update their trust stores on file changes.
+
+### Deprecation
+
+The `DAPR_TRUST_ANCHORS` environment variable in Daprd will become deprecated, and instead favour using a file reference configured via the CLI flag `-trust-anchors-file`.
+For backwards compoatabiliy, the `DAPR_TRUST_ANCHORS` environment variable will continue to be supported until `v1.14`, where the Injector service will no long patch it into Daprd sidecar containers.
+
+## Completion Checklist
+
+- [ ] In Kubernetes CA mode, Sentry writes its own generated CA bundle to the `dapr-root-ca.crt` Secret in the control plane namespace.
+- [ ] The Operator propagates this trust bundle to the `dapr-root-ca.crt` ConfigMap in all namespaces.
+- [ ] Placement, Injector, and Daprds all read and watch the trust anchors from the mounted `dapr-root-ca.crt` ConigMap referenced by the `-trust-anchors-file` flag's value, updating their trust stores accordingly.
+- [ ] Dapr CLI CA rotation command updated to respect the `dapr-root-ca.crt` Secret and append the CA bundle accordingly.
+
+### Acceptance Criteria
+- Trust distribution is active and responds to updates.
+- Dapr CLI `mtls renew-certificate` has been updated to implement proper CA rotation.

README.md

@@ -22,9 +22,9 @@ As mentioned above, any significant change that needs design and a conversation
 
 Proposal file are named in the following format:
 
-> `NNNN-FLAGS-description.md`
+> `YYYYMMDD-FLAGS-description.md`
 
-Where *NNNN* is the next incremental number in the proposal repository, as a 4 digit number (i.e 0001, 0002...), and *FLAGS* is one (or possibly more)  of:
+Where *YYYY* is a 4-digit year, MM for 2-digit month and DD for 2-digit day of when the proposal was last updated (like `20240309`, for example), and *FLAGS* is one (or possibly more)  of:
 
 * B - Building block change / creation
 * C - Components change / creation
@@ -33,7 +33,7 @@ Where *NNNN* is the next incremental number in the proposal repository, as a 4 d
 * R - Runtime
 * S - Affects SDKs
 
-So, for example, a proposal to create a new building block, such as the workflow building block, might be something like `0004-BRS-workflow-building-block.md`, whereas a change to the actor system, which does not require any changes to the SDKs themselves, would be something like `0005-R-actor-reminder-system.md`
+So, for example, a proposal to create a new building block, such as the workflow building block, might be something like `20240102-BRS-workflow-building-block.md`, whereas a change to the actor system, which does not require any changes to the SDKs themselves, would be something like `20240103-R-actor-reminder-system.md`
 
 ## Proposal Process
 

resources/README.md

@@ -2,6 +2,6 @@
 
 Any files related to proposals (images, attachments, etc.) that are needed to embed into a proposal should go in here. 
 
-Assets should be kept in a directory that matches the proposal name - i.e `0001-R-foo-bar.md` should store its assets in `resources/0001-R-foo-bar/`
+Assets should be kept in a directory that matches the proposal name - i.e `20230114-R-foo-bar.md` should store its assets in `resources/20230114-R-foo-bar/`