Configuring backups for Developer Portal on OpenShift and Cloud Pak for Integration

Configure backups for the Developer Portal service in your OpenShift or Cloud Pak for Integration environment.

About this task

Run commands in the namespace where the Developer Portal is installed.

For points to consider when you are backing up and restoring a two data center configuration, see Backup and restore requirements for a two data center deployment.

The default Developer Portal backup schedule is once every 24 hours, but the schedule can be changed in the backup settings. The Developer Portal saves all system and site backups locally, and also saves them remotely based on the configured SFTP and s3 settings.

The local backups are automatically maintained so that the latest three backups of each site and of the system are kept, and older backups are removed. This maintenance means that the Developer Portal retains the latest three backups for each site and for the system however old they are, but there is no deletion of the old backups on the remote server. If a site is deleted, then all of the local backups for that site are also deleted, as otherwise the backup volume might become full of old site backups. For remote backups, you can configure a retention policy on your remote server to remove the old backup files as required.

Procedure

  1. Create your Developer Portal backup secret.
    The backup secret is a Kubernetes secret that contains your credentials for accessing the s3 or sftp backup database.
    • S3

      Only password-based authentication is supported for S3, not authentication based on public certificates and private keys. Password-based authentication for S3 requires that you generate an access key and secret. For example:

      The secret can be created with the following command:
      oc create secret generic portal-backup-secret --from-literal=username='Your_access_key-or-user_name' 
          --from-literal=password='Your_access_key_secret-or-password' -n <Portal_namespace>
    • SFTP

      Supported credentials types:

      • User name and password (v10.0.2.0 or later).
      • User name and SSH-key (v10.0.3.0 or later). Only OpenSSH keys are supported.1

      Use one of the following commands to create the secret:

      • User name and password credentials
        oc create secret generic portal-backup-secret --from-literal=username='<Your_user_name>' 
        --from-literal=password='<Your_password>' -n <Portal_namespace>
      • Version 10.0.3.0 or later: User name and SSH-key credentials:
        oc create secret generic portal-backup-secret --from-literal=username='<Your_user_name>'
         --from-file=ssh-privatekey='<Your_private_key_file>' -n <Portal_namespace>
  2. Add a portalBackup subsection to the spec.portal section of the top-level apiconnectcluster CR.
    You can edit the YAML in the UI, or you can run the following command and then add the portalBackup block:
    oc edit apiconnectcluster <Portal_namespace>

    An example when you use protocol: objstore:

    spec:
      portal:
        portalBackup:
          credentials: portal-backup-secret
          host: s3.eu-gb.cloud-object-storage.appdomain.cloud/eu-standard
          path: test-bucket/restore-test
          port: 443
          backupCerts: <custom-s3-server-CA-cert>
          backups3URIStyle: <host-or-path>
          schedule: '0 2 * * *'

    An example when you use protocol: sftp:

    spec:
      portal:
        portalBackup:
          credentials:   portal-backup-secret
          host:          sftp-service.example.com
          path:          /home/fvtuser/site-backups
          port:          22
          protocol:      sftp
          schedule:      '0 2 * * *'

    Notes about the portalBackup: entry:

    • If portalBackup: entry is empty or omitted from the API Connect Cluster CR, then local backups will be taken if a backup CR is created. If the schedule exists, backups are taken at the scheduled time.
    • For S3 and SFTP, the portalBackup: entry must contain host, credentials, protocol, and path.
    • For S3, the portalBackup: section can optionally contain either, or both, of backupCerts and backupS3URIStyle.
    Table 1. Developer Portal backup settings
    Setting Description
    credentials The name of the secret you created.

    Supported credential types:

    • S3

      Only password-based authentication is supported for S3, not authentication based on public certificates and private keys. Password-based authentication for S3 requires that you generate an access key and secret.

    • SFTP
      • User name and password (v10.0.2.0 or later)
      • User name and SSH-key (v10.0.3.0 or later)
    host
    • S3 - host: is the S3 endpoint with the corresponding S3 region in the format <S3endpoint>, or with an optional S3 region in the format <S3endpoint>/<S3region>.
    • SFTP - the hostname of the sftp server
    path
    • S3 - the name of your S3 bucket to store backup data, optionally followed by a / and then any subdirectories inside the bucket. Valid examples:
      bucket
      bucket/path
      bucket/lots/of/paths
    • SFTP - the full absolute path of the folder on the SFTP server, beginning with /.
    Attention: Ensure that your backup path has the correct permissions to allow your backup user to be able to read and write to it from within the Developer Portal.
    port The port for the protocol to connect to the host.
    • S3 - Ignored for S3 (because objstore always connects to port 443)
    • SFTP - Defaults to 22 if not specified
    • local - Ignored for local
    protocol The protocol that is used to communicate with your remote backup endpoint. Specify one of the following values:
    • sftp - for secure file transfer protocol.
    • objstore - for S3 compatible object storage.
    backupCerts (S3 storage only) backupCerts is the name of a custom certificate that contains your upstream custom S3 CA certificate. Supported beginning with 10.0.2.
    Note: If you use a public certificate for the S3 storage provider, it must be signed by a known certificate authority that is trusted by API Connect. Use of an untrusted authority can cause the following error during backup upload:
    x509:
            certificate signed by unknown authority

    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 Portal subsystem already trusts the server certificate. You can test this by configuring the Portal 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 the 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 <APIC_namespace>
    backups3URIStyle (S3 storage only) Optional - backups3URIStyle indicates whether URIs to your S3 backup should use specify a host or a path value. When not specified, default to host. Supported beginning with 10.0.2.

    Valid values: host and path.

    Some custom S3 providers require URI style to be set to path. For example, MinIO supports both host and path style setup. You can create a MinIO S3 server to only accept path style client communications.

    Important: Contact your custom S3 administrator before configuring this field. If not properly configured, an upstream custom S3 can reject connections from the client, such as the API Connect Management subsystem.
    schedule The schedule for how often automatic Developer Portal backups are run. The format for the schedule is any valid cron string. The timezone for backups is UTC.

    Valid for all backup types: S3, SFTP, and local.

    spec:
      portal:
        portalBackup:
          ...
          schedule: '0 2 * * *'
1 PuTTY style keys can be converted to OpenSSH by using the PuTTY Key Generator (PuTTYgen) application; see https://www.puttygen.com/.