Restore warnings to Helm Chart documentation
Problem to solve
The Helm Chart documentation in the index and install pages (and perhaps beyond) used to be covered in warnings that the Helm chart was an advanced deployment, requiring stateful components running outside of the cluster and strong Kubernetes knowledge to manage. This wording was specifically strong and repetitive, with NOTE:
and bold for further emphasis. We continued to add warnings and strong language because customers kept using Helm charts without being familiar with Kubernetes and with stateful components in the cluster.
Recent changes have reworked these pages, removing some of this language and making the rest appear more soft.
Further details
In Support, we constantly have to warn customers that their instance is not production ready, and we need the documentation to either deflect these cases (because a customer reads them and follows them before we see the horror) or to back us up (so we may link to something strongly worded to reinforce our recommendation).
Recent Support AMER skip level meeting discussion
In the AMER skip level meeting in Support that took place yesterday (agenda (only for Support team members granted access)), we discussed the seeming uptick in customers who were not following our recommendations in their architecture. It is possible that this reorganizing of the Helm chart docs contributed to this uptick.
Recent Slack discussion
In a #support_self-managed
Slack thread (internal), a few Support Engineers (me, @bocarbonell, and @jessie), a Support Engineering Manager (@rspainhower), and a Staff Distribution Engineer (@WarheadsSE) discussed these recommendations. This started when Bo asked:
Is this a 'that is correct' type of question? "...it is not recommended to run Gitaly (cluster or non cluster) at all in k8s?"
An screenshot excerpt of the resulting conversation:
Proposal
Return to having more strongly worded and obvious warnings, so that customers are less likely to use an improper setup, and so that we can point them to the documentation section which makes it clear that Helm is advanced, requires k8s expertise, and needs to have stateful components outside of the cluster (preferably following a reference architecture).
Who can address the issue
Anyone interested in writing some documentation, but as I believe that @axil is the assigned technical writer, he should probably be involved.
Other links/references
There are a few recent merge requests that removed this sort of language, seemingly as a part of the TW KR on improving the cloud native docs: