Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: document new backup/restore procedure and webapps specific config #4791

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: document new backup/restore procedure and webapps specific config #4791

wants to merge 3 commits into from
+102 −239

Conversation

entangled90
Copy link
Contributor

@entangled90 entangled90 commented Dec 18, 2024 •
edited by akeller
Loading

Description

This PR updates the documentation related to performing backups and restoring them for self managed as a result EPIC camunda/camunda#24456.

Backups for webapps can now be performed by any webapps (operate, tasklist or optimize) and there is no need anymore to perform one for each app.

The order of the operations has also changed (source: decision document):
1 - Soft Pause on Zeebe to export - POST actuator/exporting/pause?soft=true
2 - SaaS Controller triggers WebApps and monitor it together
3 - Backup Zeebe ES Records
4 - Backup Zeebe Data
5 - Resume exporting

When should this change go live?

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

PR Checklist

  • My changes are for an already released minor and are in /versioned_docs directory.
  • My changes are for the next minor and are in /docs directory (aka /next/).

@entangled90 entangled90 added component:zeebe Issues related with Zeebe project component:operate Issues related with Operate project component:tasklist Issues related with Tasklist project component:optimize Issues related with Optimize project labels Dec 18, 2024
@entangled90 entangled90 self-assigned this Dec 18, 2024
@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Dec 18, 2024 •
edited
Loading

👋 🤖 🤔 Hello, @entangled90! 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/backup-restore/backup-and-restore.md
  • docs/self-managed/operational-guides/backup-restore/optimize-backup.md
  • docs/self-managed/operational-guides/backup-restore/webapps-backup.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.

@entangled90 entangled90 force-pushed the cs-4790-new-backup-restore-procedure branch from b18d8db to 4bd252d Compare December 19, 2024 10:02
@akeller
Copy link
Member

akeller commented Jan 6, 2025

@entangled90 is this part of alpha3? Or 8.7? I see its still in draft, but I'm not sure how quickly a tech writer would need to review this PR. Can you add the appropriate alpha or minor labels?

@entangled90 entangled90 added the target:8.7 Issues included in the 8.7 release label Jan 7, 2025
@entangled90 entangled90 marked this pull request as ready for review January 7, 2025 08:19
@entangled90 entangled90 requested review from npepinpe and Szik January 8, 2025 10:35
ChrisKujawa
ChrisKujawa previously approved these changes Jan 20, 2025
View reviewed changes
Copy link
Member

@ChrisKujawa ChrisKujawa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @entangled90 I have smaller comments and some questions, but in general looks good 👍🏼

docs/self-managed/operational-guides/backup-restore/backup-and-restore.md Outdated
@@ -6,7 +6,7 @@ keywords: ["backup", "backups"]
---

:::note
This release introduces breaking changes for [Operate and Tasklist](./operate-tasklist-backup.md), as well as [Optimize](./optimize-backup.md).
This release introduces breaking changes for [Operate, Tasklist and Optimize](./webapps-backup.md).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❓ Do we need to specify an exact release (to reduce confusion)? Or is this obvious due to the version picker?

wdyt @akeller ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great question, given that it's a breaking change, please specify the exact release @ChrisKujawa.

docs/self-managed/operational-guides/backup-restore/backup-and-restore.md Outdated Show resolved Hide resolved
docs/self-managed/operational-guides/backup-restore/webapps-backup.md Outdated Show resolved Hide resolved
docs/self-managed/operational-guides/backup-restore/webapps-backup.md Outdated Show resolved Hide resolved
docs/self-managed/operational-guides/backup-restore/webapps-backup.md
Comment on lines 43 to +44
1. The [Elasticsearch snapshot repository](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html) must be configured.
2. Operate and Tasklist must be configured with the repository name using one of the following configuration options:
2. All deployed webapps must be configured with the **same** repository name using one of the following configuration options.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔧 Should we also mention that we need permissions to write ?

docs/self-managed/operational-guides/backup-restore/webapps-backup.md Outdated
### Index prefix

:::warning breaking change
Since version 8.7 the `indexPrefix` of all webapps must match. By default it's set to `""`, but if it was overriden, then it must done consistently across Operate, Tasklist and Optimize.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍🏼

docs/self-managed/operational-guides/backup-restore/webapps-backup.md

```
POST actuator/backups
POST actuator/backupHistory
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🙃 I guess it is a bit late for this, but why is it actually backupHistory? It is backing up more than history, right? It feels like it is not syntactically correct somehow 🤔

Copy link
Contributor Author

@entangled90 entangled90 Jan 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but we never found a better term. I think we had backupZeebe and backupWebapps as proposal, but in the end the current names were chosen

docs/self-managed/operational-guides/backup-restore/webapps-backup.md
Comment on lines +318 to +321
1. Stop all webapps.
2. Ensure there are no webapp indices present in Elasticsearch (otherwise the restore process will fail).
3. Iterate over all Elasticsearch snapshots included in the desired backup and restore them using the Elasticsearch restore snapshot API.
4. Start Operate.

## Backup and restore of Tasklist data

Backup and restore of Tasklist may be performed in exactly the same way as [Operate data](#).
4. Start all webapps.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❓ Should we note that Zeebe also need to be restored? Because webapp independently from Zeebe restoring will not really work right?

Copy link
Contributor Author

@entangled90 entangled90 Jan 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is mentioned in the root document.
I think this section just expand on what "restoring webapps" means

@ChrisKujawa
Copy link
Member

One thing I missed. I think we should a note to the announcements https://docs.camunda.io/docs/next/reference/announcements/announcements-870/ regarding the simplifications of backups, but also the breaking change.

@npepinpe
Copy link
Member

@entangled90 - do you need my review as well as Chris', or is his enough?

@entangled90
Copy link
Contributor Author

I think Chris review is enough 👍

@conceptualshark
Copy link
Contributor

Is this ready for a technical writing review?

@entangled90 entangled90 added target:8.8 Issues included in the 8.8 release and removed target:8.7 Issues included in the 8.7 release labels Jan 21, 2025
@entangled90 @ChrisKujawa
doc: applied suggestions from review
306d373 
Co-authored-by: Christopher Kujawa (Zell) <[email protected]>
@entangled90
Copy link
Contributor Author

I just realized that there are a couple of points that this PR does not address:

  • Identity: we are performing backup of identity indices as well, so I guess it should be mentioned, but I don't have much context about that.
  • Opensearch: currently only Elasticsearch is mentioned, I assume it should have already been mentioned considering that we already support it. Can we address this in a separate PR?

@akeller akeller added the hold This issue is parked, do not merge. label Jan 22, 2025
@akeller
Copy link
Member

akeller commented Jan 22, 2025

Hi - I see this PR is now labeled for 8.8. Please do not merge! I've added a hold label. Watch #ask-c8-documentation for when you can merge 8.8 docs items. If this is applicable to 8.7 too, adjust the labels.

@entangled90 entangled90 force-pushed the cs-4790-new-backup-restore-procedure branch from f3cd457 to 07d87b6 Compare January 23, 2025 14:39
@entangled90
Copy link
Contributor Author

Updated with the latest suggestions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@akeller akeller akeller left review comments

@ChrisKujawa ChrisKujawa ChrisKujawa left review comments

@npepinpe npepinpe Awaiting requested review from npepinpe

@Szik Szik Awaiting requested review from Szik

At least 1 approving review is required to merge this pull request.

Assignees

@entangled90 entangled90

Labels
component:operate Issues related with Operate project component:optimize Issues related with Optimize project component:tasklist Issues related with Tasklist project component:zeebe Issues related with Zeebe project hold This issue is parked, do not merge. target:8.8 Issues included in the 8.8 release
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@entangled90 @akeller @ChrisKujawa @npepinpe @conceptualshark