docs(data-purge): adds operational guide for data purge

[srsp]

Description

This PR describes the new cluster data purge functionality described here: #25861

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the DevEx team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• My changes are for an upcoming minor release and:

  • are in the /docs directory (version 8.8).
  • are in the /versioned_docs/version-8.7/ directory (version 8.7).

• My changes are for an already released minor and are in a /versioned_docs directory.

• I included my new page in the sidebar file(s).

• I added a redirect for a renamed or deleted page to the .htaccess file.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:

  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

[github-actions]

👋 🤖 🤔 Hello, @npepinpe! 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.6/.

• docs/self-managed/operational-guides/data-purge/data-purge.md

These files were changed only in docs/. You might want to duplicate these changes in versioned_docs/version-8.7/.

• docs/self-managed/operational-guides/data-purge/data-purge.md

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.

[npepinpe]

Very nice, just some suggestions :)

[npepinpe]

🔧 We should emphasize the latter part - while yes it deletes data, it's more that it restores the cluster to a "fresh" state. So there will be some things there after - e.g. the default user (if so configured), default tenant, some schema metadata, etc.

[npepinpe]

❓ Is the syntax highlighting automatic, or do we need to add json here?

[srsp]

So it looks like I have taken one of the only sites as a model, where this was not done :)
I'll add it.

[npepinpe]

🔧 Can we add a section either at the top or the end, which puts it all together? For example, I want to purge, so I would send the POST request, grab the change ID, and then poll the cluster via GET until my change ID is the last completed one. I think that's really helpful for users if we can "put it all together" in a runbook like format.

[srsp]

I agree that the runbook style is good for the user. I had hoped that the current versions already accomplishes that.
I fear that if I include that, it feels like there is too much repetition, because the current structure is already close to that.

The screenshot is from a relatively small screen (23"), when scrolled to the "Purge data" paragraph. The runbook should come after the "Danger" block, so if people have already scrolled until there, they can already see both steps involved, even on a smaller screen.

I could get rid of some of the explanations regarding the output, which I copied from the Cluster Scaling doc, and just reference it. That would make it more compact and less noisy.

What do you think?

[npepinpe]

No no, I liked all of the content so far - I was just thinking, how about we put a "TL;DR" kind of section at the top, which shows usage of both requests together to achieve a "complete" purge, e.g.

changeId=$(curl -XPOST http://localhost:9600/actuator/cluster/purge | jq '.changeId')
lastCompletedChangeId=-1
while [ $changeId -neq $lastCompletedChangeId ] do;
  lastCompletedChangeId=$(curl http://locahost:9600/actuator/cluster | jq '.lastCompletedChangeId')
  echo "Last completed change ID ${lastCompletedChangeId} == ${changeId}?"
  sleep 1
done

Don't use the above, it probably doesn't work 😄 But just to get the idea. Explain how one could purge and wait until it's complete, i.e. the expected usage together. Does that make sense?

[github-actions]

🚧 The preview environment for the commit d96da38 is being built. This usually takes 15-20 minutes.