Automating provisioning with z/OS Provisioning Toolkit

To allow the provision and deprovision of containers to be automated, z/OS PT can be configured so that no user input is needed at run time. You can specify options on the zospt run command to make it easier to retrieve the name of the provisioned containers for use in further automation steps.

Configuring z/OS PT for use in automation

Configure the following z/OS PT environment variables:
  • Set the zospt_pw environment variable to the password of the user ID that runs the automation. The user ID that runs the automation must have the appropriate authority in z/OSMF to run the z/OS PT commands.
  • If z/OS PT is configured to use a truststore (truststore environment variable), the truststore must already contain the certificate authorities that are needed to trust the z/OSMF server's certificate.
For more information about setting the zospt_pw and truststore environment variables, see Configuring z/OS Provisioning Toolkit. For information about the container name, including the maximum length and a list of acceptable characters, see the zospt run command in The zospt command syntax.

Obtaining the container name from a zospt run command

By default, the zospt run command reports the progress of the provisioning process by writing messages to STDOUT, which can make it difficult to capture the container name that is allocated dynamically to the provisioned container. To make it easier to obtain the container name, specify the --quiet option on the zospt run command:

/u/cicsusr:>zospt run cics_55 --quiet
CICS_CICPJ001

If the command is successful, only the container name is written to STDOUT. If the command fails, error information is written to STDERR.

Example script to retrieve the z/OS PT container name

In the following example, the script provisions a container and uses a variable that is called mycontainer to obtain the container name. In the following example, if the provision completes successfully with a return code zero, the script then inspects the provisioned container by using the obtained name: 
#!/bin/sh
mycontainer=$(zospt run myimage --quiet)
if [ $? -eq 0 ]
then 
  zospt inspect $mycontainer
fi

Specifying the container name on a zospt run command

Instead of receiving a dynamic container name from a zospt run command, you can specify the container name to use. For example, use the following command:

zospt run imageName --name containerName

If the automated script provisions multiple containers, the automation needs a way to generate a unique container name for each container that gets provisioned.

Example script that sets the z/OS PT container name

In the following example, the script provisions a container that is named mycics and then inspects the container:
#!/bin/sh
zospt run myimage --name mycics
zospt inspect mycics

Logging

z/OS PT commands emit informational messages to STDOUT and error messages to STDERR.

z/OS PT return codes

z/OS PT commands return the following exit codes:

  • 0 = Success.
  • 12 = An error occurred. If the error occurs during a zospt run command, the container is created and must be removed. If the error occurs on other commands, it can be possible to retry those commands. The container must be removed when it is no longer needed.
  • 16 = An error occurred during a zospt run command before the container was created. The container does not need to be removed.
  • 20 = An internal error occurred. For more information, see the z/OS PT logs and STDERR.