search

camunda / camunda-docs

Camunda 8 Documentation, including all components and features
https://docs.camunda.io/
Other
54 stars 185 forks source link

Document helm variable name of environment variables for all components. #3856

Open zalanszak opened 5 months ago

zalanszak commented 5 months ago

It is often confusing and very time consuming to find the appropriate environment variables to use in helm charts - both for our customers and for the support team.

For example from this doc:

https://docs.camunda.io/docs/self-managed/zeebe-deployment/exporters/elasticsearch-exporter/?configuration=index

it is not straightforward to craft the correct property path for e.g. index.numberOfReplicas. Eventually I have to look it up in https://github.com/camunda/camunda/blob/main/dist/src/main/config/broker.yaml.template so I know that it's zeebe.broker.exporters.elasticsearch.args.index.numberOfReplicas, and then I need to transform it to the helm-compatible variable name, ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INDEX.... where I need to make an educated guess that numberOfReplicas becomes NUMBER_OF_REPLICAS and not NUMBEROFREPLICAS.

This is not really user friendly: it is time consuming and quite error prone. Instead, what we would propose in support is to have a 4th column for each property and each component, where the exact Helm environment variable is explicitly presented - and even a "copy-to-clipboard" button for each variable.

This confusion came up in multiple occasions - recently in this comment: https://jira.camunda.com/browse/SUPPORT-22104?focusedCommentId=351509&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-351509

akeller commented 5 months ago

@conceptualshark, as our emerging Self-Managed docs specialist, this looks like something in your wheelhouse. Can you have a look at this issue? Let's further discuss in a 1:1 before assigning you.

garima-camunda commented 2 months ago

Hi @akeller, do we have any timeline for this doc ticket? I am asking because this has been a consistent pain area for customers and support engineers to figure out the name of environment variables.

They need to go to multiple doc pages to construct one variable name, which is tedious, error prone and not a good experience for customers, and also cause more support tickets. It would be nice if this can be prioritized.

One recent example is - https://camunda.slack.com/archives/C55U06YRG/p1724319405582199

conceptualshark commented 2 months ago

@garima-camunda I've actually just drafted a new epic to tackle organizing the components pages, which includes this issue/organizing the configuration options generally. Starting work on this is on my radar for next week, but will take some time to roll through updates for every component between release-related work.

garima-camunda commented 2 months ago

Thanks @conceptualshark.

Here are few more recent examples, in case it helps to prioritize this.

SUPPORT-22104 - Customer did not know how to construct name and Support provided wrong value SUPPORT-23300 - (incident channel - lot of back and forth only on naming construct :disappointed:) SUPPORT-23296