Configuring backup settings for Analytics

Use the apicup utility to configure backup settings for the Analytics database in your VMware environment.

About this task

The Analytics database can be backed up and restored from an S3 repository. S3-compatible object storage is required; for example, IBM Cloud Object Storage.
Note:
  • Only host-style S3 backups are supported. Path-style S3 backups are not supported.
  • If you are using a self-managed S3 backup server, check that you have a DNS hostname entry and matching TLS certificate for your S3 backup endpoint.
  • When you specify a filepath in a backup setting, be sure to escape any blank spaces in the path.

Procedure

  1. Use the apicup utility to configure the backup settings.

    Configure each setting by running the following command with the key and value from Table 1 that you want to apply:

    apicup subsys set <analytics_subsystem> <key> <value>

    Table 1 shows the supported backup settings with the default value (if any) and a description of each setting.

    Table 1. Analytics backup settings
    Key Default value Description
    analytics-backup-auth-pass   Server password for Analytics backups.
    analytics-backup-auth-user   Server user name for Analytics backups.
    analytics-backup-host   The S3 endpoint with the corresponding S3 region in the format:
    s3.s3region.s3domain
    For example:
    s3.eu-gb.cloud-object-storage.appdomain.cloud

    Or with an optional S3 region in the format <S3endpoint>/<S3region>.

    analytics-backup-certs   The name of a custom certificate that contains your upstream custom S3 CA certificate.

    This field accepts name of the Kubernetes secret containing your upstream custom S3 CA certificate. The key of the secret must be ca.crt and the value is the base64-encoded value of the CA certificate.

    If the server certificate that is presented by your S3/object-store endpoint is signed by a well known CA and includes any intermediate certificates in the chain, then you do not need to provide the CA certificate using this feature because the analytics subsystem already trusts the server certificate. You can test this by configuring the analytics backup to your S3/object-store server without providing the CA certificate.

    If you do need to provide the CA certificate then you must provide the entire chain in the ca.crt member of the secret, as follows:
    intermediate-certificate-1
    intermediate-certificate-2
    . . .
    intermediate-certificate-n
    root-certificate

    Where the first certificate in the ca.crt member (intermediate-certificate-1) is the issuer of the S3/object-store server certificate, and each subsequent certificate in the ca.crt member is the issuer of the preceding certificate. The root certificate in the ca.crt member must be self-signed.

    If there are no intermediate certificates involved, then the ca.crt member contains only the root certificate.

    The following sample bash script creates a Kubernetes secret:
    cat >customs3ca.yaml <<EOF
    apiVersion: v1
    data:
      ca.crt: $(base64 <path-to-ca-certificate> | tr -d '\n' )
    kind: Secret
    metadata:
      name: custom-server-ca
    type: generic
    EOF
    
    kubectl apply -f customs3ca.yaml -n <namespace>
    analytics-backup-path   A combination of the S3 bucket and the base path within the bucket, using the format: bucket_name/path
    analytics-backup-chunk-size 1GB (Optional) Specifies how large files are stored. Large files can be stored as chunks when the snapshot is created. This setting specifies the size of the chunks as GB, MB, or KB.
    analytics-backup-schedule 0 2 * * * (Optional) Determines how often backups will be invoked automatically. The format for the schedule is any valid cron string.

    The timezone for backups is UTC. Backing up once a day is probably sufficient; remember that the more frequently you run backups, the more storage space you need.

    analytics-enable-compression true (Optional) Determines whether metadata files are stored in compressed format.
    analytics-enable-server-side-encryption false (Optional) Determines whether files are encrypted. When set to true, files are encrypted on the server side using AES256.
  2. Validate the backup settings by running the following command:
    apicup subsys get <analytics_subsystem> --validate
  3. Apply the backup settings to the Analytics subsystem by reinstalling with the following command:
    apicup subsys install <analytics_subsystem>
    Note: The apicup subsys install command automatically runs apicup health-check prior to installing the new configuration. An error is displayed if a problem is found that will prevent successful reconfiguration.

    In some scenarios, after you fix the problem, the health check might continue to fail. In this case, you can use the --skip-health-check flag to suppress the automatic health check:

    apicup subsys install <subsystem_name> --skip-health-check
  4. Verify that the backup settings were successfully applied by running the following command:
    apicup subsys health-check <analytics_subsystem>