Backing up of Che instances to Amazon S3

You can send backups of Che instances to Amazon S3 (or S3 API compatible storage) with custom resources or chectl:

Backing up a Che instance to Amazon S3 by using custom resources

Backing up a Che instance to Amazon S3 (or S3 API compatible storage) by using custom resources requires two custom objects:

  • First you create a custom object to configure Che to use Amazon S3.

  • Then you create a custom object to make and send a backup snapshot of a Che instance to the configured Amazon S3.

Configuring Che with custom resources to use Amazon S3

To configure Che to use Amazon S3:

Prerequisites
Procedure

  1. Create a Secret containing the repo-password key with a password:

    apiVersion: v1
kind: Secret
metadata:
  name: backup-encryption-password-secret
  namespace: eclipse-che
type: Opaque
stringData:
  repo-password: <password>

    (The Che Operator will set up this password for the backup repository that the Che Operator will create from this custom object on the backup server.)

    The backup repository password is used to encrypt the backup data. If you lose this password, you will lose the backup data.

  2. Create a Secret (for example, name: aws-user-credentials-secret) containing:

    • awsAccessKeyId key with the AWS access key ID of the user

    • awsSecretAccessKey key with the AWS secret access key of the user

  3. Create the CheBackupServerConfiguration custom object:

    apiVersion: org.eclipse.che/v1
kind: CheBackupServerConfiguration
metadata:
  name: backup-server-configuration
  namespace: eclipse-che
spec: (1)
  awss3:
    protocol: https (2)
    hostname: s3.amazonaws.com (3)
    port: 443 (4)
    repositoryPath: eclipse-che-backups (5)
    repositoryPasswordSecretRef: backup-encryption-password-secret (6)
    awsAccessKeySecretRef: aws-user-credentials-secret (7)
    1 Must only contain one section (such as awss3).
    2 Optional property that specifies the protocol to be used. https is the default value; http is a permitted value.
    3 Optional property that specifies the S3 hostname. The default value is s3.amazonaws.com.
    4 Optional property that specifies the port on which the backup server is running. The default value is 443.
    5 Name of the bucket resource that stores the backup snapshots. You must manually create the bucket resource before configuring it here.
    6 Secret created in step 1.
    7 Secret created in step 2.

  4. Optional: To configure multiple backup servers, create a separate CheBackupServerConfiguration custom object for each backup server.

The Che Operator automatically backs up the Che instance before every Che update, permitting rollback to previous Che version if needed. If you configure only one backup server, that backup server is automatically used for pre-update backups by default. If you configure multiple backup servers, you must add the che.eclipse.org/backup-before-update: true annotation to the custom object of only one of them to specify it as the default backup server for pre-update backups. (If you don’t add this annotation for one of multiple backup servers, or if you add this annotation for multiple backup servers, then the Che Operator defaults to using the internal backup server for pre-update backups.)

Backing up a Che instance to Amazon S3 by using the CheClusterBackup custom object

You can use a CheClusterBackup custom object to make a backup snapshot of a Che instance and to send the snapshot to the configured backup server. To create each and every backup snapshot requires a new CheClusterBackup custom object; that is, editing an already consumed CheClusterBackup custom object, during or after backing up, has no effect.

This procedure does not back up the source code stored in users' workspaces. To back up the source code stored in users' workspaces, see Backups of persistent volumes.
Prerequisites
Procedure

  1. Create the CheClusterBackup custom object, which creates a backup snapshot:

    apiVersion: org.eclipse.che/v1
kind: CheClusterBackup
metadata:
  name: eclipse-che-backup
  namespace: eclipse-che
spec:
  backupServerConfigRef: backup-server-configuration (1)
  useInternalBackupServer: false (2)
    1 Name of the CheBackupServerConfiguration custom object defining what backup server to use.
    2 Configures the Operator through this custom resource to use the Che-managed internal backup server or an administrator-managed external backup server (SFTP, Amazon S3 or S3 API compatible storage, or REST).

    If you intend to reuse a name for CheClusterBackup custom objects, first delete any existing custom object with the same name. To delete it on the command line, use kubectl:

    $ kubectl delete CheClusterBackup <name> -n eclipse-che

  2. Read the status section of the CheClusterBackup custom object to verify the backup process, for example:

    status:
  message: 'Backup is in progress. Start time: <timestamp>' (1)
  stage: Collecting Che installation data (2)
  state: InProgress (3)
    1 Summary of the latest state of the backup process.
    2 Current stage of the backup process in a human-readable format.
    3 Backup process state: InProgress or Succeeded or Failed.

    The Che instance is backed up in a snapshot when state is Succeeded:

    status:
  ...
  message: >-
    Backup successfully finished at 2021-12-03 10:07:51.151090621 +0000 UTC
    m=+999.553272281 (1)
  snapshotId: 9f0adce2 (2)
  state: Succeeded (3)
    1 Summary of the latest state of the backup process.
    2 ID of the created backup snapshot. This field appears only when state is Succeeded.
    3 Backup process state: Succeeded (or Failed).

Backing up a Che instance to Amazon S3 by using chectl

You can use chectl to make a backup snapshot of a Che instance and send the snapshot to the configured Amazon S3 (or S3 API compatible storage). To do so, enter chectl with the command-line options or set the environment variables.

Backing up a Che instance to Amazon S3 by using chectl with command-line options

To make a backup snapshot of a Che instance and send the snapshot to the configured Amazon S3, run chectl with the command-line options.

This procedure does not back up the source code stored in users' workspaces. To back up the source code stored in users' workspaces, see Backups of persistent volumes.
Prerequisites
Procedure

  1. Enter the chectl server:backup command with the following arguments:

    $ chectl server:backup \
--repository-url=<repository_url> \ (1)
--repository-password=<repository_password> \ (2)
--aws-access-key-id=<aws-access-key-id> \ (3)
--aws-secret-access-key==<aws-secret-access-key> (4)
    1 Backup repository URL as an argument using the --repository-url or -r option. Syntax for the backup repository URL: s3:s3.amazonaws.com/<bucket_name>. For more details about repository URL syntax, see Restic Documentation.
    2 Backup repository password as an argument using the --repository-password or -p option.
    3 User’s AWS access key ID.
    4 User’s AWS secret access key.
    Last used backup server information is stored in a Secret inside the Che cluster. When consistently using the same backup server, you can enter the --repository-url and --repository-password options with the chectl server:backup command just once and omit them onward when entering chectl server:backup or chectl server:restore.

  2. Verify the output of the entered command. For example:

    ...
  ✔ Scheduling backup...OK
  ✔ Waiting until backup process finishes...OK
Backup snapshot ID: 9f0adce2
Command server:backup has completed successfully in 00:10.

Backing up a Che instance to Amazon S3 by using chectl and a CheBackupServerConfiguration custom object

You can back up a Che instance by entering the name of a CheBackupServerConfiguration custom object as an argument with the chectl server:backup command.

Prerequisites
Procedure

  1. Run the following command on a command line:

    $ chectl server:backup \
--backup-server-config-name=<name_of_CheBackupServerConfiguration> (1)
    1 This option points chectl to a CheBackupServerConfiguration custom object. You can find the name of the CheBackupServerConfiguration custom object under metadata in the custom object.
    Last used backup server information is stored in a Secret inside the Che cluster. When consistently using the same backup server, you can enter the --backup-server-config-name option with the chectl server:backup command just once and omit this option onward when entering chectl server:backup.

  2. Verify the output of the entered command. For example:

    ...
  ✔ Scheduling backup...OK
  ✔ Waiting until backup process finishes...OK
Backup snapshot ID: 9f0adce2
Command server:backup has completed successfully in 00:10.

Configuring chectl with environment variables to use Amazon S3

As an alternative to using command-line options for chectl server:backup, you can configure chectl for Amazon S3 with environment variables. This enables you to run chectl server:backup without having to enter those options with it.

Prerequisites
Procedure

Which environment variables you need to set depends on your use case:

  • If you do not have a CheBackupServerConfiguration custom object yet, then you can set the following environment variables:

    • BACKUP_REPOSITORY_URL for the backup repository.

    • BACKUP_REPOSITORY_PASSWORD for the backup repository password.

    • AWS_ACCESS_KEY_ID for the user’s AWS access key ID.

    • AWS_SECRET_ACCESS_KEY for the user’s AWS secret access key.

  • If you already have a CheBackupServerConfiguration custom object, you can set the following environment variable that will point chectl to that CheBackupServerConfiguration custom object:

    • BACKUP_SERVER_CONFIG_NAME for the name of a CheBackupServerConfiguration custom object to point chectl to. (You can find name under metadata in the custom object.)