Deploying Docker containers on IBM zCX

How to deploy HCL Workload Automation for Z containers on IBM z/OS Container Extensions (IBM zCX).

Before you deploy HCL Workload Automation components on an IBM zCX instance, ensure that you have:
  • The IBM z/OS Management Facility (z/OSMF) up and running.
  • An IBM zCX instance where you configured the workflow_variables.properties file (by default, located in /usr/lpp/zcx_zos/properties) with all the input variables listed in Properties for Workflow.
    Table 1. Properties for Workflow
    Input Variables Variable Name IBM z/OSMF field
    zCX General Configuration ZCX_INSTALL_DIR Install Directory
    ZCX_INSTNAME zCX Instance Name
    ZCX_REGISTRY_DIR zCX Instance Registry Directory
    ZCX_CTRACE_NAME CTRACE Member Name
    ZCX_TEMP_DASD_UNIT_PARM Temporary DASD Unit Parm
    ZCX_SAVE_PROPERTIES Directory for saving input properties file
    ZCX_UNIQUE_JOBNAMES Use unique job names for submitted jobs
    ZCX_UNIQUE_JOBNAME_PREFIX Job name prefix
    zCX CPU and Memory Configuration ZCX_CPUS Guest CPUs
    ZCX_MEMGB Guest Memory Size (in GB)
    ZCX_PAGE_FRAME_SIZE Page Frame Size
    zCX Network Configuration ZCX_HOSTNAME Hostname
    ZCX_GUESTIPV4 (DVIPa 4) Guest IPV4 Address
    ZCX_MTU MTU Size
    ZCX_HOSTDNS1 Primary DNS Server
    zCX Root and Config Storage Configuration HLQ HLQ
    ZCX_ROOTMB Root Size (in MB)
    ZCX_ROOTVOLSER Root Volume Serial
    ZCX_CONFIGMB Config Size (in MB)
    CX_CONFIGVOLSER Config Volume Serial
    zCX Instance Directory Storage Configuration ZCX_ZFS_FILESYSTEM_HLQ zFS Filesystem HLQ
    ZCX_ZFS_ENCRYPT Encrypt zFS Filesystem
    ZCX_ZFS_VOLUME zFS Filesystem Volume Serial
    ZCX_ZFS_PRIMARY_MEGABYTES Primary Megabytes
    ZCX_ZFS_SECONDARY_MEGABYTES Secondary Megabytes
    zCX Swap Data Storage Configuration ZCX_CREATE_SWAP Create Swap Data Volume
    ZCX_SWAPMB Swap Data Size (in MB)
    ZCX_SWAP_COUNT Swap Data Volume Count
    ZCX_SWAPVOLSER Swap Data Volume Serial
    zCX User Data Storage Configuration ZCX_DATAMB User Data Size (in MB)
    ZCX_DATA_COUNT User Data Volume Count
    ZCX_DATAVOLSER User Data Volume Serial
    zCX Diagnostics Data Storage Configuration ZCX_DLOGSMB Dlogs Data Size (in MB)
    ZCX_DLOGS_COUNT Dlogs Data Volume Count
    ZCX_DLOGSVOLSER Dlogs Data Volume Serial
    zCX Docker Configuration ZCX_DOCKER_LOGLEVEL Docker Daemon Logging Level
    ZCX_DOCKER_LOGDRIVER Docker Logging Driver
    ZCX_SECURE_DOCKER_REGISTRY_ENABLE Secure Docker Registry
    zCX Proxy Configuration ZCX_CONFIGURE_PROXY Configure Proxy Server
    zCX Docker User Management Configuration ZCX_DOCKER_ADMIN Docker Admin User ID
    ZCX_DOCKER_ADMIN_SSH_KEY Docker Admin SSH Key
    ZCX_SSHD_LDAP_ENABLE Enable LDAP Authentication
    ZCX_SSHD_LDAP_ENABLE_TLS Enable LDAP Client TLS Authentication
    zCX ILMT Configuration ZCX_ILMT_ENABLE Enable ILMT services
To deploy the HCL Workload Automation for Z containers to the IBM zCX instance, perform the following procedure:
  1. Start the IBM zCX instance as follows:
    1. From z/OSMF, copy the command provided in the last step of the workflow output. The command looks like the following example: 
      S GLZ,JOBNAME=<ZCX_INSTNAME>,CONF='<ZCX_REGISTRY_DIR>/start.json'
      where <ZCX_INSTNAME> and <ZCX_REGISTRY_DIR> are the variables that you set in workflow_variables.properties.
    2. Log in to your z/OS system, and from the ISPF Primary Option Menu panel issue the SDSF command.

      The SDSF menu opens.

    3. Issue the ST command. The SDSF STATUS DISPLAY panel opens.
    4. Issue the command / to display the SYSTEM COMMAND EXTENSION panel.
    5. From the command line, enter the command that you copied from the z/OSMF workflow output.

      You are returned to the SDSF STATUS DISPLAY, where <ZCX_INSTNAME> is added to the list of jobs as in EXECUTION.

    6. When the job starts processing, the following message is stored in the job' SYSPRINT log showing that the zCX instance is up and running on the indicated port and Dynamic Virtual IP address (DVIPA):
      Please Connect to IBM z/OS Container Extensions Docker CLI via your SSH client using port <port_number>.
The server is listening on: <ZCX_GUESTIPV4>
  2. Log in to the zCX instance:
    1. From the ISPF command shell of your z/OS system, access the UNIX interface by issuing the command: omvs
    2. From the command line issue the command:
      ssh -i <keydir_path>/.ssh/id_rsa -p <port_number> admin@<ZCX_GUESTIPV4>
      where:
      <keydir_path>
      Path where the <ZCX_DOCKER_ADMIN_SSH_KEY> that you set in workflow_variables.properties is stored.
      <port_number>
      Port indicated by the message stored in the job' SYSPRINT log.
      <ZCX_GUESTIPV4>
      Value set for the corresponding variable in workflow_variables.properties
    3. At first logon, a warning message about the authenticity of the host is displayed. This is an expected ssh behavior, enter Yes.
      The following message is displayed: 
      Welcome to the IBM z/OS Container Extensions (IBM zCX) shell
that provides access to Docker commands.

      You are now logged in to the zCX instance. You can start importing and deploying containers.

To import the HCL Workload Automation for Z containers into the zCX instance, perform the following steps:
  1. From the SDSF STATUS DISPLAY panel, enable the FTP process to the zCX instance by issuing the command:
    /S FTPSERVE
  2. To perform an SFTP, from your ssh session issue the command: 
    sftp -i <keydir_path>/.ssh/id_rsa -P <port_number> admin@<ZCX_GUESTIPV4>
    where:
    <keydir_path>
    Path where the <ZCX_DOCKER_ADMIN_SSH_KEY> that you set in workflow_variables.properties is stored.
    <port_number>
    Port indicated by the message stored in the job' SYSPRINT log.
    <ZCX_GUESTIPV4>
    Value set for the corresponding variable in workflow_variables.properties

    The message Connected to <ZCX_GUESTIPV4> is displayed.

  3. Import the HCL Workload Automation for Z container by issuing the command: 
    put <container_name>.tar /tmp
    The message Uploading <container_name>.tar to /tmp/<container_name>.tar is displayed.

After importing and deploying the containers, to access the container shell and run HCL Workload Automation for Z commands see Accessing the Docker containers.