Rewrite UCP backup/restore and improve uninstall and support guides #1785

alexmavr · 2017-02-16T23:29:21Z

Signed-off-by: Alex Mavrogiannis [email protected]

Proposed changes

Fixes Document that ucp-reconcile being stopped is not bad #1751
Fixes How to backup and restore UCP #1724
Slightly touches Improve docs around scaling UCP up and down #1750 but does not close it
Renamed all "controller" occurences to "manager"
Slightly rephrased a couple sentences here and there
Added documentation for CLI support dumps on the "Get Support" page

joaofnfernandes · 2017-02-16T23:34:20Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

-You need to run the backup command on a UCP manager node. Since UCP stores
-the same data on all manager nodes, you only need to create a backup of a
-single node.
+To create a UCP backup, you may use the `{{ page.docker_image }} backup` command


This is way more complete, but you sound like a boring lecturer in some sentences. Try writing like you speak.

What about

To create a backup of UCP, you can run the {{ page.docker_image }} backup command on a UCP manager node. <you don't need to tell me you're going to explain something below. If it's interesting I'm going to continue reading>
This command creates a tar archive...

Understood. Please read my response to your comment in the next paragraph.

Oh wait.

joaofnfernandes · 2017-02-16T23:37:19Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+UCP](../architecture.md) to persist data and streams it to stdout.
+
+You only need to run the backup command on a single UCP manager node. Since UCP
+stores the same data on all manager nodes, you do not need to capture periodic


Maybe the other way around will be more obvious

"Since UCP stores the same data on all manager nodes, you only need to make periodic backups of a single node"

joaofnfernandes

This looks really good!

joaofnfernandes · 2017-02-16T23:41:13Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

-containers and services are not affected by this.
+resources, such as services, containers and stacks are not affected by this
+operation and will continue operating as expected. Any long-lasting `exec`,
+`logs`, `events` or `attach` operations against the affected manager node will


Internally we use the word "against" a lot but when reading things for the first time, that word is a bit ambiguous. Maybe

"If you're running commands like exec, logs, events, or attach on a manager node, when performing a backup those commands will be disconnected."

joaofnfernandes · 2017-02-16T23:42:51Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+  -v /var/run/docker.sock:/var/run/docker.sock \
+  {{ page.docker_image }} backup --interactive /tmp/backup.tar
+
+# Ensure the backup is a valid tar and list its contents


Can we include a bit more information on what to visually search for. I'll see a list of files, but I'll have no idea whether they contain all the data or not.

joaofnfernandes · 2017-02-16T23:43:47Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+The restore command can be used to create a new UCP cluster from a backup file.
+After the restore operation is complete, the following data will be recovered
+from the backup file:
+* Users, Teams and Permissions.


We only capitalize product names, not concepts or features.

joaofnfernandes · 2017-02-16T23:44:28Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+After the restore operation is complete, the following data will be recovered
+from the backup file:
+* Users, Teams and Permissions.
+* All UCP Configuration options available under `Admin Settings`, such as the


Configuration -> configuration
Subscription->subscription

joaofnfernandes · 2017-02-16T23:51:45Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+DDC Subscription license, scheduling options, Content Trust and authentication
+backends.
+
+There restore operation can be performed in any of three environments:


There -> The
You say "three environments" but you only list two. Also you can make it a bit more straightforward like

"There are two ways to restore a UCP cluster"

joaofnfernandes · 2017-02-16T23:52:34Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

  {{ page.docker_image }} restore -i
 ```

-## Restore your cluster
+## Disaster Recovery


Only capitalize the first word of a title (and product names)

joaofnfernandes · 2017-02-16T23:57:11Z

datacenter/ucp/2.1/guides/get-support.md


 2. On the top-right menu, **click your username**, and choose **Support Dump**.
+   An archive will be downloaded by your browser after a brief time interval.
+
+If the User Interface is not accessible, you may perform the following number of


No need to capitalize "user interface" too

alexmavr · 2017-02-17T00:04:01Z

Added a commit which addresses comments and adds a few minor tweaks to the actual backup/restore commands that I discovered while actually going through the disaster recovery scenario.

@joaofnfernandes PTAL

joaofnfernandes · 2017-02-17T00:15:21Z

Everything looks good. Can you just address the comment on backups-and-disaster-recovery.md line 18?

alexmavr · 2017-02-17T00:34:08Z

I did, not sure what you're referring to. I just amended the commit to rewrite that line word-for-word as per your recommendation, so I hope that checks out

vikstrous · 2017-02-17T00:44:48Z

Does a ucp backup include a swarm backup? Also, by reading the swarm backup docs it's not clear to me what a swarm backup does.

alexmavr · 2017-02-17T00:51:49Z

No, the UCP backup does not include a swarm backup. I think the swarm backup captures the set of services, node and CA keys and swarm-scoped configuration. The only actual things that is affected by UCP not performing a swarm backup is that services are not restored as part of the backup.

Given that it's possible to restore UCP on a different swarm cluster with a different set of services running, this might not be a feature worth pursuing. Additionally, instrumenting a swarm backup may prove to be challenging from UCP's perspective depending on whether the raft store should be unlocked for the backup or not.

joaofnfernandes · 2017-02-17T00:53:22Z

That's an awesome question @vikstrous. Can we include something that states that the UCP backup command doesn't backup the cluster information like services, networks, ...
And maybe link to the swarm backup docs /engine/swarm/admin_guide/#/back-up-the-swarm

Signed-off-by: Alex Mavrogiannis <[email protected]>

joaofnfernandes

Minor nitpicks, but we're almost there!

joaofnfernandes · 2017-02-17T19:52:33Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

-To have minimal impact on your business, you should:
+Additionally, if UCP is not configured for high availability, you will be
+temporarily unable to:
+* Log in to the UCP Web UI


Our markdown renderer requires a space before list items 😓

joaofnfernandes · 2017-02-17T19:52:55Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md


-* Schedule the backup to take place outside business hours.
+To minimize the impact of the backup policy on your business, you should:


Add \n here too

joaofnfernandes · 2017-02-17T19:54:10Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+The example below shows how to create a backup of a UCP manager node and
+verify its contents:
+
+```bash


Our syntax highlighting is all crazy so change this to none.

joaofnfernandes · 2017-02-17T19:54:26Z

datacenter/ucp/2.1/guides/admin/backups-and-disaster-recovery.md

+DDC subscription license, scheduling options, Content Trust and authentication
+backends.
+
+There are two ways to restore a UCP cluster:


Add \n here too

Signed-off-by: Alex Mavrogiannis <[email protected]>

alexmavr · 2017-02-17T21:19:51Z

Addressed comments in new commit

alexmavr requested a review from joaofnfernandes February 16, 2017 23:29

joaofnfernandes reviewed Feb 16, 2017

View reviewed changes

joaofnfernandes suggested changes Feb 16, 2017

View reviewed changes

alexmavr force-pushed the backup-restore-support-uninstall branch from 4e1832b to 1f1da00 Compare February 17, 2017 00:33

joaofnfernandes approved these changes Feb 17, 2017

View reviewed changes

alexmavr force-pushed the backup-restore-support-uninstall branch from 1f1da00 to 514decd Compare February 17, 2017 02:43

Alex Mavrogiannis added 2 commits February 17, 2017 10:21

Rewrite UCP backup/restore and improve uninstall and support guides

2464396

Signed-off-by: Alex Mavrogiannis <[email protected]>

Address backup/restore comments and add minor flow details

f348bfb

Signed-off-by: Alex Mavrogiannis <[email protected]>

alexmavr force-pushed the backup-restore-support-uninstall branch from 514decd to f348bfb Compare February 17, 2017 18:23

joaofnfernandes suggested changes Feb 17, 2017

View reviewed changes

address nit-picks

88011f2

Signed-off-by: Alex Mavrogiannis <[email protected]>

joaofnfernandes approved these changes Feb 17, 2017

View reviewed changes

joaofnfernandes merged commit d0d9636 into docker:master Feb 17, 2017

londoncalling mentioned this pull request Apr 5, 2017

For HA, state how to restore a replica; in DR note instructions are only for lost clusters #671

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite UCP backup/restore and improve uninstall and support guides #1785

Rewrite UCP backup/restore and improve uninstall and support guides #1785

alexmavr commented Feb 16, 2017 •

edited

Loading

joaofnfernandes Feb 16, 2017

alexmavr Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes left a comment

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

joaofnfernandes Feb 16, 2017

alexmavr commented Feb 17, 2017 •

edited

Loading

joaofnfernandes commented Feb 17, 2017

alexmavr commented Feb 17, 2017

vikstrous commented Feb 17, 2017

alexmavr commented Feb 17, 2017

joaofnfernandes commented Feb 17, 2017

joaofnfernandes left a comment

joaofnfernandes Feb 17, 2017

joaofnfernandes Feb 17, 2017

joaofnfernandes Feb 17, 2017

joaofnfernandes Feb 17, 2017

alexmavr commented Feb 17, 2017


		* Schedule the backup to take place outside business hours.
		To minimize the impact of the backup policy on your business, you should:

Rewrite UCP backup/restore and improve uninstall and support guides #1785

Rewrite UCP backup/restore and improve uninstall and support guides #1785

Conversation

alexmavr commented Feb 16, 2017 • edited Loading

Proposed changes

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joaofnfernandes left a 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

Choose a reason for hiding this comment

alexmavr commented Feb 17, 2017 • edited Loading

joaofnfernandes commented Feb 17, 2017

alexmavr commented Feb 17, 2017

vikstrous commented Feb 17, 2017

alexmavr commented Feb 17, 2017

joaofnfernandes commented Feb 17, 2017

joaofnfernandes left a 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

alexmavr commented Feb 17, 2017

alexmavr commented Feb 16, 2017 •

edited

Loading

alexmavr commented Feb 17, 2017 •

edited

Loading