procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide #2121

max-cx · 2021-09-22T08:39:43Z

What does this pull request change?

https://www.eclipse.org/che/docs/che-7/administration-guide/backup-and-disaster-recovery/
Preview

What issues does this pull request fix or reference?

3268

Specify the version of the product this pull request applies to

7.36

Pull Request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

Any procedure:
- Successfully tested.
Any page or link rename:
- The page contains a redirection for the previous URL.
- Propagate the URL change in:
  - Dashboard default branding data
  - Chectl constants.ts
Builds on Eclipse Che hosted by Red Hat.
the Validate language on files added or modified step reports no vale warnings.

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

…-an-variable.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

...-guide/partials/proc_configuring-che-with-custom-resources-to-use-an-sftp-backup-server.adoc

...rtials/proc_configuring-prod-cli-with-environment-variables-to-use-a-rest-backup-server.adoc

...tials/proc_configuring-prod-cli-with-environment-variables-to-use-an-sftp-backup-server.adoc

modules/administration-guide/partials/proc_configuring-the-external-postgresql.adoc

...als/proc_restoring-a-che-instance-by-using-prod-cli-and-a-checluserbackup-custom-object.adoc

modules/administration-guide/partials/con_backup-and-recovery.adoc

mmorhun · 2021-12-22T07:48:44Z

modules/administration-guide/partials/con_supported-restic-compatible-backup-servers.adoc

+
+{prod-short} can use the following backup servers that are compatible with the integrated Restic:
+
+SFTP:: See the documentation for the SFTP server solution you plan to use (link:https://www.openssh.com/[OpenSSH] or a derived commercial product) and the link:https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#sftp[Restic Docs on SFTP].


nitpick: I'd like to put it at the end of the list, please, or even better, reverse the order to have rest, s3, sftp.

@mmorhun
I understand that I'm not a typical admin. That said, on another page, we recommend a specific REST server with which I ran into the following issues when I was trying to set it up:

Neither restic nor rest server show any error messages if something in the setup is missing or not as expected. So trying this combination of both restic nor rest server to work together using a remote server turned into frustrating guesswork for me.

The README on https://github.com/restic/rest-server is brief and unclear, and I couldn't find online any third-party explanation about the details of how it should be used correctly (without experimenting to make it work "trial and error"). I believe they need to improve their docs.

I was setting up the external server from scratch, so I ended up having to research and install some dependencies for the rest server that I didn't have to worry about for SFTP.

So I killed a lot of time trying to make the rest server work on a remote server, and then in contrast I quickly and easily set up an SFTP server. BTW, SFTP also involves an open source solution.

The page on REST servers is full-size in this PR. It's just that I moved it to the third place for users who have no preference and just pick the first option (like I did). If any users prefer to use rest server, they still have everything we expect to give them in the docs.

@max-cx thank you for explaining the reasons. In my case, REST server was the easiest solution, it just worked, where as I had to deal with SSH keys and proper settings for SSH server in case of SFTP (not a problem, but took more time than for REST server).
@tolusha what do you think about this?

...ation-guide/partials/assembly_backing-up-of-che-instances-to-the-internal-backup-server.adoc

...ng-up-a-che-instance-to-the-internal-server-by-using-the-checlusterbackup-custom-object.adoc

...ls/assembly_backing-up-a-che-instance-to-a-rest-backup-server-by-using-custom-resources.adoc

...n-guide/partials/proc_configuring-che-with-custom-resources-to-use-a-rest-backup-server.adoc

...ministration-guide/partials/proc_configuring-che-with-custom-resources-to-use-amazon-s3.adoc

mmorhun · 2021-12-22T08:47:06Z

...tials/proc_restoring-a-che-instance-from-a-backup-by-using-the-checlusterrestore-object.adoc

+
+include::snip_warning-backup-snapshots-are-bound-to-specific-cluster.adoc[]
+
+IMPORTANT: The `CheClusterRestore` custom object is unusable for recovering a {prod-short} instance of an earlier version of {prod-short}. Use `{prod-cli}` to recover a {prod-short} instance of an earlier version of {prod-short}; see xref:restoring-a-che-instance-from-a-backup-by-using-prod-cli_{context}[].


nitpick: this is more my fault, but it is still possible if admin manually deletes current and deploy required version of Che and the apply the procedure.

@mmorhun I can fix it. Could you clarify what you want me to change or add in this IMPORTANT admonition?

I don't think we should hightlight that, but just let users know. Preferred way is to use chectl, but just in case, if a user doesn't want to use it for some reason, we can tell about a long way.

@mmorhun, no worries, I've changed it to:

IMPORTANT: Do not use the `CheClusterRestore` custom object to recover a {prod-short} instance of an earlier version of {prod-short}! Use only `{prod-cli}` to recover a {prod-short} instance of an earlier version of {prod-short}; see xref:restoring-a-che-instance-from-a-backup-by-using-prod-cli_{context}[]!

...tials/proc_restoring-a-che-instance-from-a-backup-by-using-the-checlusterrestore-object.adoc

...als/proc_restoring-a-che-instance-by-using-prod-cli-and-a-checluserbackup-custom-object.adoc

...dministration-guide/partials/proc_restoring-a-che-instance-from-a-backup-by-snapshot-id.adoc

...tials/proc_restoring-a-che-instance-from-a-backup-by-using-the-checlusterrestore-object.adoc

...n-guide/partials/proc_restoring-a-che-instance-from-its-latest-backup-by-using-prod-cli.adoc

...ration-guide/partials/assembly_backing-up-a-che-instance-to-amazon-s3-by-using-prod-cli.adoc

...inistration-guide/partials/assembly_backing-up-of-che-instances-to-a-rest-backup-server.adoc

modules/administration-guide/partials/assembly_backing-up-of-che-instances-to-amazon-s3.adoc

...nistration-guide/partials/assembly_backing-up-of-che-instances-to-an-sftp-backup-server.adoc

...ng-up-a-che-instance-by-using-prod-cli-and-a-CheBackupServerConfiguration-custom-object.adoc

mmorhun · 2021-12-24T15:34:10Z

...ide/partials/proc_backing-up-a-che-instance-by-using-the-checlusterbackup-custom-object.adoc

+  useInternalBackupServer: false <2>
+----
+<1> Name of the `CheBackupServerConfiguration` custom object defining what backup server to use.
+<2> Configures the custom resource to back up to a backup server.


I'd rephrase because it backup to a backup server anyway. The question is between internal backup server managed by Che or a server (internal or external) managed by admin.
nitpick: it configures operator via this CR, not CR itself

@mmorhun, I've changed it to:

<2> Configures the Operator via this custom resource to use the {prod-short}-managed internal backup server or an administrator-managed external backup server (SFTP, Amazon S3 or S3 API compatible storage, or REST).

...proc_backing-up-a-che-instance-to-amazon-s3-by-using-prod-cli-with-command-line-options.adoc

mmorhun

LGTM, but please address my remarks

max-cx · 2022-01-05T11:25:26Z

@themr0c

Mykola completed his engineering review.
Brian, Rolfe, Preeti, and Oss completed their language reviews.
I updated the PR in response to all of the suggestions and nitpicks.

This PR can be (finally!) merged after the following Vale updates that I requested are completed:
redhat-documentation/vale-at-red-hat#145

…tions of the admin guide (#2121) Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com> Co-authored-by: Robert Krátký <rkratky@redhat.com> Co-authored-by: Michal Maléř <mmaler@redhat.com> Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>

max-cx and others added 30 commits July 16, 2021 23:57

first draft

4a53ab2

rewrote two example files

44d4148

replaced comma with brackets and reworded

e311fd7

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

fe7acc3

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

735cacd

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

737ef8b

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

f7f4500

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rewrote a few sentences

9a21736

forgot an *

68d7d3f

fixed one sentence, added a comment line

f6de209

fixed a few lines

97b6fe8

Update che-ref_a-kubernetes-secret-as-a-file.adoc

8845cd3

Update che-ref_a-kubernetes-secret-as-an-variable.adoc

1a29937

Update che-ref_a-kubernetes-secret-as-a-file.adoc

bb957ea

work in progress on the final NOTE

ffc7cf2

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

15d0a9e

…-a-file.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Merge branch 'master' into 2885max-cx

6c4dcb9

Update che-ref_a-kubernetes-secret-as-a-file.adoc

7184c91

Update che-ref_a-kubernetes-secret-as-a-file.adoc

d6bba45

Update che-ref_a-kubernetes-secret-as-a-file.adoc

b7cd15b

Update che-ref_a-kubernetes-secret-as-a-file.adoc

9bc645d

Update modules/end-user-guide/examples/che-ref_a-kubernetes-secret-as…

5e58ce9

…-an-variable.adoc Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update che-ref_a-kubernetes-secret-as-a-file.adoc

2e93fe3

Merge branch 'master' into 2885max-cx

2d636aa

Rewrote one paragraph

468bf8d

test

cd10bb8

added a missing data to data key

bcf4353

minor fixes

e76aef8

minor fix

24f0add

reordered sentences and preview test

f5a3c89

missmesss reviewed Dec 22, 2021

View reviewed changes

mmorhun reviewed Dec 22, 2021

View reviewed changes

Merge branch 'master' into 2974-7.35

6abbb89

missmesss reviewed Dec 23, 2021

View reviewed changes

responding to lang review part 7

b4ec12f

mmorhun reviewed Dec 24, 2021

View reviewed changes

mmorhun approved these changes Dec 24, 2021

View reviewed changes

max-cx added 11 commits December 24, 2021 18:38

responding to lang and engineering reviews part 8

1e62437

removing ,shell, from code blocks

77812e2

updated verification steps

fde9c38

replace missed chectl with prod-cli

8535339

minor fixes

93b07ba

Merge remote-tracking branch 'upstream/master' into 2974-7.35

b796ab3

responding to engineering review

1664783

minor fix

845397e

restarting GH checks

e70970f

fixing Vale errors

e0ca3b3

fixing Vale errors

6c022f4

max-cx changed the title ~~procedures: substantially edit "Backup and disaster recovery" sections of the admin guide~~ procedures: completely rewrite and expand in length the "Backup and disaster recovery" sections of the admin guide Jan 5, 2022

max-cx changed the title ~~procedures: completely rewrite and expand in length the "Backup and disaster recovery" sections of the admin guide~~ procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide Jan 5, 2022

missmesss approved these changes Jan 6, 2022

View reviewed changes

Merge branch 'master' into 2974-7.35

e0b4ab6

themr0c merged commit 0fc2d92 into eclipse-che:master Jan 25, 2022

themr0c added the need-cherry-pick/7.42.x label Jan 25, 2022

che-bot removed the status/code-review label Jan 25, 2022

themr0c added cherry-picked to 7.42.x and removed need-cherry-pick/7.42.x labels Jan 25, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide #2121

procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide #2121

max-cx commented Sep 22, 2021 •

edited

Loading

mmorhun Dec 22, 2021

max-cx Dec 23, 2021 •

edited

Loading

mmorhun Dec 24, 2021

mmorhun Dec 22, 2021

max-cx Dec 23, 2021

mmorhun Dec 24, 2021

max-cx Jan 3, 2022

mmorhun Dec 24, 2021

max-cx Jan 3, 2022

mmorhun left a comment

max-cx commented Jan 5, 2022 •

edited

Loading


		{prod-short} can use the following backup servers that are compatible with the integrated Restic:

		SFTP:: See the documentation for the SFTP server solution you plan to use (link:https://www.openssh.com/[OpenSSH] or a derived commercial product) and the link:https://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#sftp[Restic Docs on SFTP].


		include::snip_warning-backup-snapshots-are-bound-to-specific-cluster.adoc[]

		IMPORTANT: The `CheClusterRestore` custom object is unusable for recovering a {prod-short} instance of an earlier version of {prod-short}. Use `{prod-cli}` to recover a {prod-short} instance of an earlier version of {prod-short}; see xref:restoring-a-che-instance-from-a-backup-by-using-prod-cli_{context}[].

procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide #2121

procedures: rewrite and expand the "Backup and disaster recovery" sections of the admin guide #2121

Conversation

max-cx commented Sep 22, 2021 • edited Loading

What does this pull request change?

What issues does this pull request fix or reference?

Specify the version of the product this pull request applies to

Pull Request checklist

Choose a reason for hiding this comment

max-cx Dec 23, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mmorhun left a comment

Choose a reason for hiding this comment

max-cx commented Jan 5, 2022 • edited Loading

max-cx commented Sep 22, 2021 •

edited

Loading

max-cx Dec 23, 2021 •

edited

Loading

max-cx commented Jan 5, 2022 •

edited

Loading