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:

  1. Run the mirantis/ucp:3.5.6 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 3.5.6 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 \
      mirantis/ucp:3.5.6 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 3.5.6 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 \
      mirantis/ucp:3.5.6 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".

  2. 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.

  3. 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
    
  4. 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

  1. Log in to the MKE web UI.

  2. In the left-side navigation panel, navigate to Admin Settings.

  3. Click Backup.

  4. 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 back end, 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