Preparing for sandbox instances provisioning

Before you create a sandbox instance with WaziSandboxSystem or copy volumes with WaziSandboxVolumeCopy, ensure that these requirements are met.

Audience: Application developers

  • You need to be familiar with the basic Red Hat® OpenShift or Kubernetes commands: oc or kubectl
  • The cluster administrator installed the Sandbox Operator in the cluster and provided the following information to you.
    Table 1. Instructions on preparing for sandbox instances provisioning
    Custom Resource Requirements Required/Optional Detailed instructions
    WaziSandboxSystem or WaziSandboxVolumeCopy A project or namespace where the Sandbox Operator is running, and you have permissions to create the Custom Resource for the sandbox instance. Required  
    Any cluster-specific configuration to control deployment of the sandbox instance. Required  
    A unique name in the namespace for the sandbox instance. Required  
    The image pull secret for the registry with the Sandbox container. The name of the image pull secret must be wazi-sandbox-pull-secret. Required How to create an image pull secret
    The name of a Secret that contains the password for the SFTP server that holds the Extended ADCD volumes. Or the password for the SFTP server. Required How to create a Secret for the SFTP server password
    The name of a ConfigMap that contains the address of the Sandbox License Server and the details of the SFTP server. Or the detailed information of the Sandbox License Server and the SFTP server. Required How to specify information of the Sandbox License Server and the SFTP server
    WaziSandboxVolumeCopy The name of a manually created PersistentVolumeClaim to be used for the cloud-ready image, or the information to create a PersistentVolumeClaim, such as the storage class name, claim size, and any selectors to use and authority to do so. Required if storage is expected to outlive the sandbox instance

    For more information, see Why to create a PersistentVolumeClaim manually.

    		 How to create a PersistentVolumeClaim manually
    WaziSandboxSystem The name of a cloud-ready image to be used for the sandbox instance Prepare a cloud-ready image for future faster sandbox instance provisioning
Detailed instructions of each requirement are as follows.

How to create an image pull secret

Complete the following procedure to create an image pull secret.
  1. Obtain an entitlement key for the image pull secret from IBM Container Library. Click Get an entitlement key if you are not on the entitlement page.
  2. Create the secret on the namespace that you installed the wazi-sandbox-operator with the following command.
    oc create secret -n <NAMESPACE> docker-registry wazi-sandbox-pull-secret --docker-server=cp.icr.io --docker-username=cp --docker-password=<your IBM Entitled registry key> --dry-run -o yaml | oc apply -f -

How to create a Secret for the SFTP server password

If the cluster administrator did not create one to be shared among developers, you as the developer must create a Secret to be used in the spec.zpdt.secretName of the Custom Resource YAML file as follows before you create the sandbox instance.

How to create a Secret for the SFTP server password
  1. In the Red Hat OpenShift® web console, navigate to Workloads > Secrets.
  2. Click Create, select Key/Value Secret, and complete the required details. Two keys are required in the Secret.
    • zdtAuthPassword: Sets an internal password that is used within the container. It must be provided so the sandbox system will not use a hardcoded password.
    • sftpPassword: Holds the password for the SFTP server and username that is provided by the cluster administrator.

  3. Click Create.

View of creating secrets

For more information about Custom Resource YAML file, see Configuration reference.

How to specify information of the Sandbox License Server and the SFTP server

If the cluster administrator provided the name of an existing ConfigMap, set spec.zpdt.configMap.name to the name in the Custom Resource YAML file, and leave other ConfigMap fields out of the file.

If the cluster administrator did not provide the name of an existing one to use, follow the procedure below to provide the detailed information of the Sandbox License Server and the SFTP server.

How to specify information of the Sandbox License Server and the SFTP server
  1. Set spec.zpdt.configMap.create to true in the Custom Resource YAML file.
  2. Specify the following keys with the correct values as provided by the cluster administrator.
    Key Description
    licenseServer The address of the Sandbox License Server.
    sftpHost The address of the SFTP server.
    sftpPort The port that the SFTP server listens on.
    sftpUser The username to access the SFTP server.
    sftpPath The directory path on the SFTP server that contains z/OS® volume files.
    All keys are required except sftpPort that defaults to 22. The sftpPort key is required only if a different port was used. The cluster administrator might also provide additional keys and values to use. See the Configuration reference for a complete list of available configuration options.

Why to create a PersistentVolumeClaim manually

As sandbox instances cannot share z/OS volumes, each instance requires its own PersistentVolumeClaim to hold its copy of the z/OS volume files. PersistentVolumeClaim can be created in either of the following ways:
  • (Option 1) PersistentVolumeClaim is created by the Sandbox Operator automatically. In this case, all changes will be lost when the sandbox instance is deleted. If you take this default approach, you do not need to create a PersistentVolumeClaim manually.

    Use case: This might be desirable in some use cases. For example, an automated test might always want a clean environment and only need a pass or fail result but does not need to retain the contents of the volume.

  • (Option 2) PersistentVolumeClaim is created manually, either by developers or the cluster administrator.

    Use case: In most cases, this storage should outlive the sandbox instance and must be managed outside the Sandbox Operator. This is because copying of the volumes from the SFTP server is relatively expensive, and any subsequent changes to the contents, for example, customizations for the target application, need to be saved even if the sandbox instance is deleted. The sandbox instance can then be re-created by using the same storage.

How to create a PersistentVolumeClaim manually

Both developers and the cluster administrator can manually create a PersistentVolumeClaim.

If the cluster administrator did not create the claim, you as the developer need to complete the following procedure:
  1. Obtain the authority to create a PersistentVolumeClaim and information such as the storage class name, claim size, and any selectors to use from the cluster administrator.
  2. Create a PersistentVolumeClaim as described in Kubernetes documentation about PersistentVolumeClaims.