docs: communicate on secret breaking changes#8390
docs: communicate on secret breaking changes#8390mathias-vandaele wants to merge 2 commits intomainfrom
Conversation
|
👋 🤖 🤔 Hello, @mathias-vandaele! Did you make your changes in all the right places? These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.8/.
You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines. |
…on.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
mesellings
added
component:connectors
alexronquillo
requested review from
alexronquillo
and removed request for
a team
alexronquillo
left a comment
alexronquillo
left a comment
There was a problem hiding this comment.
Nice work! I left a few comments, mostly to align with certain aspects of the style guide (including some styles that have been discussed but aren't yet formalized 😅). Please feel free to push back on any feedback I've given.
| camunda.connector.secret-provider.environment.prefix= | ||
| ``` | ||
|
|
||
| :::caution |
There was a problem hiding this comment.
According to a recent style guide change, we're only using :::warning, :::note, and :::tip to help keep usage consistent.
| :::caution | |
| :::warning |
| This improves security by preventing all environment variables from being exposed as connector secrets. Existing secrets that do not use the configured prefix will no longer resolve until you update either the environment variables or the prefix configuration. | ||
|
|
||
| To limit the environment that can be accessed by the default secret provider, configure a prefix. For example: | ||
| #### Configuring a custom prefix |
There was a problem hiding this comment.
| #### Configuring a custom prefix | |
| #### Configure a custom prefix |
Generally, we've gravitated toward action verbs over gerunds for instructional guides and sections.
| export SUPER_SECRETS_MY_SECRET='foo' # Resolved via {{ secrets.MY_SECRET }} | ||
| ``` | ||
|
|
||
| #### Restoring the previous behavior (unsafe) |
There was a problem hiding this comment.
| #### Restoring the previous behavior (unsafe) | |
| #### Restore the previous behavior (unsafe) |
Generally, we've gravitated toward action verbs over gerunds for instructional guides and sections.
| Starting with Camunda 8.9, the environment-based secret provider uses `SECRET_` as the default prefix. Only environment variables starting with the configured prefix are available as connector secrets. | ||
|
|
||
| - **Before 8.9**: With no prefix configured, all environment variables were accessible as connector secrets. | ||
| - **From 8.9**: Only environment variables starting with `SECRET_` (or your configured prefix) are considered connector secrets. |
There was a problem hiding this comment.
I suggest we link "or your configured prefix" to the Configure a custom prefix section to help users find that documentation faster.
| ``` | ||
| camunda.connector.secret-provider.environment.prefix= | ||
| ``` | ||
| This mode logs a warning and is not recommended for production. |
There was a problem hiding this comment.
| This mode logs a warning and is not recommended for production. | |
| This mode logs a warning, and Camunda does not recommend it for production environments. |
Generally, we've gravitated toward "Camunda recommends" over "it is recommended". Though, this isn't part of the style guide, so I wouldn't consider this a super important change at this time.
| camunda.connector.secret-provider.environment.prefix= | ||
| ``` | ||
| This mode logs a warning and is not recommended for production. | ||
| - **Custom prefix:** Configure your own prefix via: |
There was a problem hiding this comment.
Do you think there's a case to be made that this should be presented as the first action? Otherwise, the user has already set the SECRET_ prefix, and later we're telling them they can change it.
|
|
||
| This is a **breaking change** for Self-Managed deployments that relied on unprefixed environment variables as secrets. Existing, unprefixed secrets will no longer resolve after upgrading. | ||
|
|
||
| **Actions required:** |
There was a problem hiding this comment.
Nitpick: Only one item in this list of three items is actually a "required action": The user has to choose between the first or second actions, but can't do both. The third action is also optional. Maybe we should rephrase?
| - Java property: `camunda.connector.secret-provider.environment.prefix` | ||
| - Environment variable: `CAMUNDA_CONNECTOR_SECRET_PROVIDER_ENVIRONMENT_PREFIX` | ||
|
|
||
| For full configuration details, see [Connector secrets configuration](/self-managed/components/connectors/connectors-configuration.md#secrets). |
There was a problem hiding this comment.
| For full configuration details, see [Connector secrets configuration](/self-managed/components/connectors/connectors-configuration.md#secrets). | |
| For full configuration details, see [connector secrets configuration](/self-managed/components/connectors/connectors-configuration.md#secrets). |
According to a recent discussion (not yet included in the style guide), we've decided to always use lowercase link references.
3 participants
Description
When should this change go live?
bugorsupportlabel)available & undocumentedlabel)holdlabel)low priolabel)PR Checklist
{type}(scope): {description}commit message(s)/docsdirectory (version 8.9)./versioned_docsdirectory.@camunda/tech-writersunless working with an embedded writer.