Backup procedure#

You can create an MKE backup using either the CLI, the MKE web UI, or the MKE API.

The backup process runs on one manager node.

Create an MKE backup using the CLI#

The following example demonstrates how to:

Create an MKE manager node backup.
Encrypt the backup by using a passphrase.
Decrypt the backup.
Verify the backup contents.
Store the backup locally on the node at /tmp/mybackup.tar.

To create an MKE backup:

Run the {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} backup command on a single MKE manager node, including the --file and --include-logs options. This creates a .tar archive with the contents of all volumes used by MKE and streams it to stdout. Replace {{ page.ucp_version }} with the version you are currently running.
```
docker container run \
  --rm \
  --log-driver none \
  --name ucp \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume /tmp:/backup \
  {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} backup \
  --file mybackup.tar \
  --passphrase "secret12chars" \
  --include-logs=false
```
If you are running MKE with Security-Enhanced Linux (SELinux) enabled, which is typical for RHEL hosts, include --security-opt label=disable in the docker command, replacing {{ page.ucp_version }} with the version you are currently running:
```
docker container run \
  --rm \
  --log-driver none \
  --security-opt label=disable \
  --name ucp \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  {{ page.ucp_org }}/{{ page.ucp_repo }}:{{ page.ucp_version }} backup \
  --passphrase "secret12chars" > /tmp/mybackup.tar
```
Note

To determine whether SELinux is enabled in MCR, view the host /etc/docker/daemon.json file, and search for the string "selinux-enabled":"true".
You can access backup progress and error reporting in the stderr streams of the running backup container during the backup process. MKE updates progress after each backup step, for example, after volumes are backed up. The progress tracking is not preserved after the backup has completed.
A valid backup file contains at least 27 files, including ./ucp-controller-server-certs/key.pem. Verify that the backup is a valid .tar file by listing its contents, as in the following example:
```
gpg --decrypt /tmp/mybackup.tar | tar --list
```
A log file is also created, in the same directory as the backup file. The passphrase for the backup and log files are the same. Review the contents of the log file by using the following command:
```
gpg --decrypt '/tmp/mybackup.log'
```

Create a backup using the MKE web UI#

Log in to the MKE web UI.
In the left-side navigation panel, navigate to Admin Settings.
Click Backup.
Initiate an immediate backup by clicking Backup Now.

The MKE web UI also provides the following options:

Display the status of a running backup
Display backup history
Display backup outcome

Create, list, and retrieve backups using the MKE API#

The MKE API provides three endpoints for managing MKE backups:

/api/ucp/backup
/api/ucp/backups
/api/ucp/backup/{backup_id}

You must be an MKE administrator to access these API endpoints.

To create a backup using the MKE API:

You can create a backup with the POST: /api/ucp/backup endpoint. This JSON endpoint accepts the following arguments:

Field name	JSON data type	Description
`passphrase`	String	Encryption passphrase
`noPassphrase`	Boolean	Sets whether a passphrase is used
`fileName`	String	Backup file name
`includeLogs`	Boolean	Sets whether to include a log file
`hostPath`	String	File system location

The request returns one of the following HTTP status codes, and if successful, a backup ID.

200: Success
500: Internal server error
400: Malformed request (payload fails validation)

Example API call:

curl -sk -H "Authorization: Bearer $AUTHTOKEN"  https://$UCP_HOSTNAME/api/ucp/backup \
  -X POST \
  -H "Content-Type: application/json" \
  --data  '{"passphrase": "secret12chars", "includeLogs": true, "fileName": "backup1.tar", "logFileName": "backup1.log", "hostPath": "/tmp"}'

$AUTHTOKEN is your authentication bearer token if using auth token identification.
$UCP_HOSTNAME is your MKE hostname.

Example output:

200 OK

To list all backups using the MKE API:

You can view all existing backups with the GET: /api/ucp/backups endpoint. This request does not expect a payload and returns a list of backups, each as a JSON object following the schema detailed in Backup schema.

The request returns one of the following HTTP status codes, and if successful, a list of existing backups:

200: Success
500: Internal server error

Example API call:

curl -sk -H "Authorization: Bearer $AUTHTOKEN" https://$UCP_HOSTNAME/api/ucp/backups

Example output:

[
  {
    "id": "0d0525dd-948a-41b4-9f25-c6b4cd6d9fe4",
    "encrypted": true,
    "fileName": "backup2.tar",
    "logFileName": "backup2.log",
    "backupPath": "/secure-location",
    "backupState": "SUCCESS",
    "nodeLocation": "ucp-node-ubuntu-0",
    "shortError": "",
    "created_at": "2019-04-10T21:55:53.775Z",
    "completed_at": "2019-04-10T21:56:01.184Z"
  },
  {
    "id": "2cf210df-d641-44ca-bc21-bda757c08d18",
    "encrypted": true,
    "fileName": "backup1.tar",
    "logFileName": "backup1.log",
    "backupPath": "/secure-location",
    "backupState": "IN_PROGRESS",
    "nodeLocation": "ucp-node-ubuntu-0",
    "shortError": "",
    "created_at": "2019-04-10T01:23:59.404Z",
    "completed_at": "0001-01-01T00:00:00Z"
  }
]

To retrieve backup details using the MKE API:

You can retrieve details for a specific backup using the GET: /api/ucp/backup/{backup_id} endpoint, where {backup_id} is the ID of an existing backup. This request returns the backup, if it exists, as a JSON object following the schema detailed in Backup schema.

The request returns one of the following HTTP status codes, and if successful, the backup for the specified ID:

200: Success
404: Backup not found for the given {backup_id}
500: Internal server error

Specify a backup file#

To avoid directly managing backup files, you can specify a file name and host directory on a secure and configured storage backend, such as NFS or another networked file system. The file system location is the backup folder on the manager node file system. This location must be writable by the nobody user, which is specified by changing the directory ownership to nobody. This operation requires administrator permissions to the manager node, and must only be run once for a given file system location.

To change the file system directory ownership to nobody:

sudo chown nobody:nogroup /path/to/folder

Caution

Specify a different name for each backup file. Otherwise, the existing backup file with the same name is overwritten.
Also specify a location that is mounted on a fault-tolerant file system, such as NFS, rather than the node local disk. Otherwise, it is important to regularly move backups from the manager node local disk to ensure adequate space for ongoing backups.

Backup schema#

The following table describes the backup schema returned by the GET: /api/ucp/backups and GET: /api/ucp/backup/{backup_id} endpoints:

Field name	JSON data type	Description
`id`	String	Unique ID
`encrypted`	Boolean	Sets whether to encrypt with a passphrase
`filename`	String	Backup file name if backing up to a file, empty otherwise
`logFilename`	String	Backup log file name if saving backup logs, empty otherwise
`backupPath`	String	Host path where backup is located
`backupState`	String	Current state of the backup (`IN_PROGRESS`, `SUCCESS`, `FAILED`)
`nodeLocation`	String	Node on which the backup was taken
`shortError`	String	Empty unless `backupState` is set to `FAILED`
`created_at`	String	Time of backup creation
`completed_at`	String	Time of backup completion