From e2e4b6a1fe719dfdd1a8d8a929476f33bcdb43a6 Mon Sep 17 00:00:00 2001 From: Thien-Thi Nguyen Date: Wed, 18 May 2016 19:48:17 +0200 Subject: [PATCH] Add section "Backup and Restore" to the Cluster Administration Guide. * _build_cfg.yml: ...here. * admin_guide/backup_restore.adoc: New file. --- _build_cfg.yml | 2 + admin_guide/backup_restore.adoc | 192 ++++++++++++++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 admin_guide/backup_restore.adoc diff --git a/_build_cfg.yml b/_build_cfg.yml index 9456cb934a01..dcf6694e1b89 100644 --- a/_build_cfg.yml +++ b/_build_cfg.yml @@ -461,6 +461,8 @@ Topics: - Name: Building Dependency Trees File: building_dependency_trees Distros: openshift-origin,openshift-enterprise + - Name: Backup and Restore + File: backup_restore - Name: Troubleshooting Networking File: sdn_troubleshooting Distros: openshift-origin,openshift-enterprise diff --git a/admin_guide/backup_restore.adoc b/admin_guide/backup_restore.adoc new file mode 100644 index 000000000000..b8e0aa10d60a --- /dev/null +++ b/admin_guide/backup_restore.adoc @@ -0,0 +1,192 @@ += Backup and Restore +{product-author} +{product-version} +:data-uri: +:icons: font +:experimental: +:toc: macro +:toc-title: +:prewrap!: + +toc::[] + +== Overview + +In {product-title}, you can _back up_ (saving state to separate storage) and +_restore_ (recreating state from separate storage) at the cluster level. There +is also some preliminary support for xref:project-backup[per-project backup]. +The full state of a cluster installation includes: + +- etcd data on each master +- API objects +- registry storage +- volume storage + +This topic does not cover how to back up and restore +xref:../install_config/persistent_storage/index.adoc#install-config-persistent-storage-index[persistent +storage], as those topics are left to the underlying storage provider. + + +[[backup-restore-prerequisites]] +== Prerequisites + +. Because the restore procedure involves a xref:cluster-restore[complete +reinstallation], save all the files used in the initial installation. This may +include: ++ +- *_~/.config/openshift/installer.cfg.yml_* (from the +xref:../install_config/install/quick_install.adoc#install-config-install-quick-install[Quick Installation] +method) +- Ansible playbooks and inventory files (from the +xref:../install_config/install/advanced_install.adoc#install-config-install-advanced-install[Advanced +Installation] method) +- *_/etc/yum.repos.d/ose.repo_* (from the +xref:../install_config/install/disconnected_install.adoc#install-config-install-disconnected-install[Disconnected +Installation] method) + +. Install packages that provide various utility commands: ++ +---- +# yum install etcd +---- + +Note the location of the *etcd* data directory (or `$ETCD_DATA_DIR` in the +following sections), which depends on how *etcd* is deployed. + +[options="header",cols="1,2"] +|=== +| Deployment Type| Data Directory + +|all-in-one cluster +|*_/var/lib/openshift/openshift.local.etcd_* + +|external etcd (not on master) +|*_/var/lib/etcd_* + +|embedded etcd (on master) +|*_/var/lib/origin/etcd_* +|=== + + +[[cluster-backup]] +== Cluster Backup + +. Save all the certificates and keys, on each master: ++ +---- +# cd /etc/origin/master +# tar cf /tmp/certs-and-keys-$(hostname).tar \ + master.proxy-client.crt \ + master.proxy-client.key \ + proxyca.crt \ + proxyca.key \ + master.server.crt \ + master.server.key \ + ca.crt \ + ca.key \ + master.etcd-client.crt \ + master.etcd-client.key \ + master.etcd-ca.crt +---- + +. If *etcd* is running on more than one host, stop it on each host: ++ +---- +# sudo systemctl stop etcd +---- ++ +Although this step is not strictly necessary, doing so ensures that the *etcd* +data is fully synchronized. + +. Create an *etcd* backup: ++ +---- +# etcdctl backup \ + --data-dir $ETCD_DATA_DIR \ + --backup-dir $ETCD_DATA_DIR.bak +---- ++ +[NOTE] +==== +If *etcd* is running on more than one host, +the various instances regularly synchronize their data, +so creating a backup for one of them is sufficient. +==== + +. Create a template for all cluster API objects: ++ +==== +---- +$ oc export all \ + --exact \//<1> + --all-namespaces \ + --as-template=mycluster \//<2> + > mycluster.template.yaml +---- +<1> Preserve fields that may be cluster specific, +such as service `portalIP` values or generated names. +<2> The output file has `kind: Template` and `metadata.name: mycluster`. +==== ++ +The object types included in `oc export all` are: + +- BuildConfig +- Build +- DeploymentConfig +- ImageStream +- Pod +- ReplicationController +- Route +- Service + +[[cluster-restore]] +== Cluster Restore + +. Reinstall {product-title}. ++ +This should be done in the +xref:../install_config/install/index.adoc#install-config-install-index[same way] +that {product-title} was previously installed. + +. Restore the certificates and keys, on each master: ++ +---- +# cd /etc/origin/master +# tar xvf /tmp/certs-and-keys-$(hostname).tar +---- + +. Restore from the *etcd* backup: ++ +---- +# mv $ETCD_DATA_DIR $ETCD_DATA_DIR.orig +# cp -Rp $ETCD_DATA_DIR.bak $ETCD_DATA_DIR +# chcon -R --reference $ETCD_DATA_DIR.orig $ETCD_DATA_DIR +# chown -R etcd:etcd $ETCD_DATA_DIR +---- + +. Create the API objects for the cluster: ++ +---- +$ oc create -f mycluster.template.yaml +---- + +[[project-backup]] +== Project Backup + +A future release of {product-title} will feature specific support for +per-project back up and restore. + +For now, to back up API objects at the project level, use `oc export` for each +object to be saved. For example, to save the deployment configuration `frontend` +in YAML format: + +---- +$ oc export dc frontend -o yaml > dc-frontend.yaml +---- + +To back up all of the project (with the exception of cluster objects like +namespaces and projects): + +---- +$ oc export all -o yaml > project.yaml +----