Building an image with z/OS Provisioning Toolkit

After templates are set up in z/OSMF, you use the zospt build command to build an image. This image is a set of files and configuration information that is used with an associated z/OSMF template to provision one or more containers with the same capability. You need to set up the zosptfile, then run the zospt build command to build the image.

About this task

A z/OS PT image is created by using the zospt build command. You can create images from scratch, or base an image on an existing one. In this way, you can create stacks of images that together build different containers. For a reminder of how images work with z/OS PT, see What is z/OS Provisioning Toolkit?.

The build command takes the contents of a zosptfile and uses that to determine what is put into an image. A zosptfile is a text document in UTF-8 encoding that defines the instruction set that is used to assemble an image. Valid instructions are shown in the following table:

Instruction	Description
FROM `imageName`	Defines the image on which this image is based. If you specify `FROM scratch`, this image is the base image. It is not based on another image. `scratch` is a reserved base image that is the starting point for building environments. `scratch` cannot be directly built or run. Note: If you create an image by building on an existing image, the environment variables in the original image persist.
ENV ZOSMF_TEMPLATE=`template name`	Associate this image with a z/OSMF template.
ENV `key`=`value`	Define an environment variable for this image. Some templates, such as CICS®, allow environment variables to be specified to further customize the configuration of a provisioned environment. You can customize some of the properties of a provisioned environment by adding environment variable definitions to the zosptfile for the image, which can override values that are specified in the properties file of the template that is named in the image. For more information about which properties can be added to the zosptfile for an image, see the Configuration properties file for the product you are provisioning. Environment variables that are defined in a zosptfile for `image_1` can also be referenced by other instructions in the same zosptfile, or by zosptfile instructions of other images built `FROM image_1`, by referencing the environment variable as `${key}`. For example, you might define an environment variable to represent the directory into which certain files are to be copied, and the environment variable might then be used in `COPY` instructions in the zosptfile to ensure that the files are copied into the correct directory. To show that an environment variable is only referenced by other instructions in the zosptfile, prefix the environment variable name with `IMAGE_`. The sample images that are provided with z/OS PT give examples of environment variables. For more information about sample images, see Samples provided with z/OS Provisioning Toolkit.
COPY `fromFile` `toFile`	Copy a file or directory into this image. The file must be in the same directory as the zosptfile, or one of its subdirectories.

For examples of zosptfile text files, see Samples provided with z/OS Provisioning Toolkit.

Procedure

Edit the zosptfile:
1. Define the image on which this image is based:
  - To build this image from nothing, specify FROM scratch.
  - To build this image from an existing one, specify FROM imageName.
  To see available images, use the zospt images command to print a list of the images that are available to provision, and the zospt inspect command to see more details about a specified image.
2. Optional: If the image is a base image, specify the template name that you want to call in z/OSMF when the image is run.
3. Optional: Set environment variables.
4. Optional: Copy files or directories into this image.
Run the zospt build command to build the image.
```
zospt build -t imageName path
```
This command builds an image that is called imageName by using the zosptfile found in the directory that is specified by path, and adds it to the local images directory.
This command operates on local resources, and runs without connecting to z/OSMF.

For a complete syntax description, and for information about how to remove an image, see The zospt command syntax.
If you set all the properties successfully, a success message is displayed, as shown in the following example console output:
```
Successfully built /u/user/zospt/samples/cics_55_liberty/zosptfile into
    image cics_55_liberty.
```

What to do next

The image is ready to use for provisioning with the zospt run command, as described in Running a z/OS Provisioning Toolkit image.