Managing containers created by z/OS Provisioning Toolkit

After you provision containers by using the zospt run command, you can manage them by using other z/OS PT commands. You can see which containers are running, start and stop them, and deprovision them when they are no longer needed.

Listing running containers

To list running containers, use the zospt ps command:
zospt ps

This command lists details for any running containers that you are authorized to view, and all running registered containers. You can view running containers that you created, and you might be able to view running containers that were created by other members of the same tenant. If you are a domain administrator, you can view more containers. Any user can view all registered containers.

The command shows the container name, the image name, the owner, the date the container was created, the current state, the template that was used to create the container, the system the container was created on, and the container type of each running container. The container name of each registered container is prefixed with REG.


2018-12-12 16:24:35  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
NAME                IMAGE             OWNER   CREATED                 STATE               TEMPLATE             SYSTEM  CONTAINER TYPE
CICS_CICPD000       cics_55           user01  2018-12-09T10:58:31     provisioned         cics_55              MV01    Standard
ZOSCONNECT_ZCON008  testApi           user01  2018-12-10T02:27:34     provisioned         zosconnect_v3r0      MV02    Standard
CICS_CICPD000       cics_55_liberty   user02  2018-12-11T10:44:31     provisioned         cics_55              MV01    Standard
REG-DB2_DB2000      N/A               user02  2018-12-12T15:01:55     provisioned         db2_registration     MV01    Standard

Listing all containers

To list all containers, enter the following command:
zospt ps -a

This command lists details for any running containers that you are authorized to view, including deprovisioned and deprovisioning-failed containers, and all registered containers. You can view running containers that you created, and you might be able to view running containers that were created by other members of the same tenant. If you are a domain administrator, you can view more containers. Any user can view all registered containers.

The command shows the version of z/OS and z/OSMF on the running LPAR. It then shows the container name, the image name, the owner, the date the container was created, the current state, the template that was used to create the container, the system the container was created on, and the container type of each container. The container name of each registered container is prefixed with REG.


2018-12-12 16:34:35  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
2018-12-12 16:34:35  z/OS level is V2R3.
2018-12-12 16:34:35  z/OS Management Facility level is V2R3.
2018-12-12 16:34:35  z/OSMF system nicknames are MV01, MV02.
2018-12-12 16:34:35  Getting started workflows will run on the system with nickname MV01.
2018-12-12 16:34:35  zospt installation directory : /u/cicsuser/zospt
NAME                IMAGE             OWNER   CREATED                 STATE                 TEMPLATE             SYSTEM  CONTAINER TYPE
CICS_CICPD000       cics_55           user01  2018-12-09T10:58:31     provisioned           cics_55              MV01    Standard
ZOSCONNECT_ZCON008  testApi           user01  2018-12-10T02:27:34     provisioned           zosconnect_v3r0      MV02    Standard
CICS_CICPD000       cics_55_liberty   user02  2018-12-11T10:44:31     provisioned           cics_55              MV01    Standard
REG-DB2_DB2000      N/A               user02  2018-12-12T15:01:55     provisioned           db2_registration     MV01    Standard
CICS_CICPD00C       cics_55_app       user02  2018-12-12T15:43:34     being-deprovisioned   cics_55              MV01    Standard
REG-MQ_CICPJ00A     N/A               user03  2018-12-12T16:01:03     deprovisioned         mq_registration      MV01    Standard

Filtering the list of containers

To filter the results of the zospt ps or zospt ps -a commands by OWNER, STATE, or SYSTEM, you can add -f or --filter to the command. You can specify the -f option multiple times in a single command. For example, to filter the results by OWNER and STATE, enter the following command:
zospt ps -f owner=user02 -f state=provisioned
Output from this example command is as follows:
2018-12-12 16:44:35  Connecting to z/OSMF on host system01.hursley.ibm.com port 32000.
NAME                IMAGE             OWNER   CREATED                 STATE                 TEMPLATE             SYSTEM  CONTAINER TYPE
CICS_CICPD000       cics_55_liberty   user02  2018-12-11T10:44:31     provisioned           cics_55              MV01    Standard
REG-DB2_DB2000      N/A               user02  2018-12-12T15:01:55     provisioned           db2_registration     MV01    Standard
For a complete syntax description and any conditions of use, see The zospt command syntax.

Inspecting containers

To see more details about the container you created, including the status of the container, and to see a list of any linked-to containers, use the zospt inspect command:
zospt inspect containerName | containerID
Example output from the command zospt inspect CICS_CICPJ00Z is as follows:

{
   "container-name": "CICS_CICPJ00Z",
   "container-id": "5209fa00-fadc-4d1e-aa37-e2c4b7160f30",
   "instance-name": "CICS_CICPJ00Z",
   "template": "cics_55",
   "image_name": "cics_55",
   "created-time": "2018-12-09T12:31:14.425Z",
   "type": "CICS",
   "system": "MV01",
   "sysplex": "PLEX01",
   "owner": "user123",
   "state": "provisioned",
   "tenant-name": "default",
   "domain-name": "default",
   "public_properties": {
      "DFH_CICS_TYPE": "SMSS",
      "DFH_REGION_APPLID": "CICPJ00Z",
      "DFH_REGION_CMCIPORT": "32001",
      "DFH_REGION_HOSTNAME": "HOST",
      "DFH_REGION_HTTP": "28499",
      "DFH_REGION_ZFS_DIRECTORY": "/u/zospt/mount/CICPJ00Z",
      "INSTANCE_STATUS": "active"
   },
   "connected-containers": [{"container-name": "DB2_DB2J001"}]
}
You can also use the zospt inspect command to see more details about a registered container that is created by any user:

{
   "container-name": "REG-DB2_CICPJ000",
   "container-id": "89b5481b-acbb-4a6c-9ffd-a3139e0b504f",
   "instance-name": "REG-DB2_CICPJ000",
   "template": "db2_registration",
   "image_name": "N/A",
   "created-time": "2018-12-09T15:01:55.034Z",
   "type": "REG-DB2",
   "system": "MV01",
   "sysplex": "PLEX01",
   "owner": "user234",
   "state": "provisioned",
   "tenant-name": "default",
   "domain-name": "default",
   "public_properties": {
      "DSN_HLQ": "SYS2.DB2.V11",
      "DSN_SSID": "DJ29",
      "DSN_ZFS_HLQ": "/db2/db2v11"
   },
   "connected-containers": []
}

The INSTANCE_STATUS property that is returned shows the current status of the container. If the container was stopped in any way, the INSTANCE_STATUS shows as inactive.

The connected-containers property that is returned shows the container or containers that the inspected container is linked to.

For a complete syntax description and any conditions of use, see The zospt command syntax.

Starting and stopping containers

Containers are started in the running state when you provision them. You can use the zospt stop command to stop one or more running containers and a zospt start command to restart one or more containers. You can use containerName or containerID to specify a target container, and you can specify multiple container names or IDs, each separated by a space. For example, you might use the following commands to stop and start two containers and use their name and ID interchangeably:
zospt stop CICS_CICPP003 05dc7424-3178-4e98-a179-1d7f95b749a2
  ...
zospt start d5975552-711d-437e-ba86-63d97108523e CICS_CICPD001

For a complete syntax description and any conditions of use, see The zospt command syntax.

Removing and deprovisioning containers

When one or more containers are no longer needed, use the zospt rm command to remove them. This process deletes the data sets and zFS directories that are associated with the environment. This example command shows how to remove two containers:
zospt rm containerName1 containerName2

If one or more of the specified containers are running, the zospt rm command fails. In this case, you can either stop any running containers, or use the --force option on the command to deprovision the environment. If the container you want to remove is a registered container, you must use the --force option.

You can use containerName or containerID to specify a target container, and you can specify multiple container names or IDs, each separated by a space.

For a complete syntax description and any conditions of use, see The zospt command syntax.

Exploring further

Now that you are working with z/OS PT, stay in touch through the IBM® developerCenters. There, you can find scenarios and examples of z/OS PT in action: