Planning for the CICS TS resource builder container images

Use this information to plan for installation of CICS® CICS Transaction Server (CICS TS) resource builder container images.

Before you begin

Check that you meet the system and security requirements to use CICS TS resource builder container images:

Download and install Podman. For more information about installing Podman, see Podman installation instructions .
NOTE: If you are using IBM® z/OS® Container Platform (zOSCP), Podman will already be installed and your user ID configured to use Podman. For more information, see:
- Configuring the container runtime on your z/OS system
- User ID requirements
Optional: Verifying a CICS TS resource builder container image signature is an optional step, see Verifying the CICS TS resource builder container images signature.

Getting access to the container images

The cics-resource-builder-ubi8 image can be accessed directly and without an API key. Before using the image, ensure that you understand the terms of use, see Terms.

To get access to the cics-resource-builder-zos container image, you must have an IBM entitlement registry key to pull the images from the IBM Cloud® Container Registry icr.io. The entitlement key can be found within the Additional Licensed Publications section on your order of CICS Transaction Server (CICS TS) in ShopZ External link icon . You can download the entitlement key to your workstation by using HTTPS. For more information on the terms of use, see Terms.

When pulling the cics-resource-builder-ubi8 image to run it as a container, you need to complete the commands on your Linux® compatible platform.
When pulling the cics-resource-builder-zos image to run it as a container, you need to complete the commands on your z/OS system (with the entitlement key).
When pulling both images locally to verify or to push them to the internal image registry, you can run the commands on either Linux or z/OS.

Terms

By downloading, installing, and/or using the CICS TS resource builder images, you agree to the applicable IBM license terms and the separate license terms of any dependencies that might be required as part of the installation and/or execution of the container images:

CICS TS resource builder license terms: IBM Support - License Terms

If you are accepting these terms on behalf of another person, company, or other legal entity, you represent and warrant that you have full authority to bind that person, company, or other legal entity to these terms.

For a list of license terms for key dependencies of CICS TS container images, refer to IBM Support - Key license agreements for IBM CICS Transaction Server for z/OS container images External link icon .

Optional: Verifying the CICS TS resource builder container images signature

Digital signatures provide a way to ensure that an image is both authentic (it originated from the expected source) and has integrity (it is what is expected). The CICS TS resource builder container images are signed and this describes how to verify the signature on these images.

You need to enable sigstore attachments by specifying the use-sigstore-attachments option in a configuration file. By setting this option, it enables Podman to read and write container sigstore signatures for a container image.
Create a yaml file in the registries configuration directory. By default, the registries configuration directory is $HOME/.config/containers/registries.d if it exists, otherwise /etc/containers/registries.d. In your yaml add the following content to set use-sigstore-attachments for both the Linux and z/OS container images:
```
docker: 
   icr.io/ibm-cics/cics-resource-builder-ubi8:
       use-sigstore-attachments: true
   icr.io/ibm-cics-ts/cics-resource-builder-zos:
       use-sigstore-attachments: true
```

The CICS TS resource builder public key must exist on the same machine as the command-line tools.

Copy the following text block exactly as shown into a text editor, and save it in a file that is named cics-resource-builder.pub.key in the $HOME/.config/containers if it exists, otherwise use the /etc/containers directory:

Enable a verification policy to enforce the usage of the public key. By default, the policy is read from $HOME/.config/containers/policy.json, if it exists, otherwise from /etc/containers/policy.json.

You need to add two entries to the docker section of the policy, one for icr.io/ibm-cics/cics-resource-builder-ubi8 and one for icr.io/ibm-cics-ts/cics-resource-builder-zos. Use the following example:

    "transports": {
    "docker": {
        "icr.io/ibm-cics/cics-resource-builder-ubi8": [
            {
                "type": "sigstoreSigned",
                "keyPath": "/etc/containers/cics-resource-builder.pub.key",
                "signedIdentity": {
                    "type": "matchRepository"
                }
            }
        ],
        "icr.io/ibm-cics-ts/cics-resource-builder-zos": [
            {
                "type": "sigstoreSigned",
                "keyPath": "/etc/containers/cics-resource-builder.pub.key",
                "signedIdentity": {
                    "type": "matchRepository"
                }
            }
        ]
    }
}

The keyPath location depends on the location of the cics-resource-builder.pub.key file that you created, your location is either $HOME/.config/containers or /etc/containers. Ensure that you change the code snippet to the corresponding location.

Verify the container image signature. The container image signature is verified when a podman copy, or podman pull command uses the container images. When the verification of the container image is successful, the image ID is returned. The following shows an example output when the commands perform image signature verification:
Linux
```
$ podman pull --os linux --arch amd64 icr.io/ibm-cics/cics-resource-builder-ubi8:1.0.6
b0405b027d410add4fee4e05e7d401b7a937f76b405c189f66c9e8abf91b02ba
```
IBM Z
```
$ podman pull --os zos --arch s390x icr.io/ibm-cics-ts/cics-resource-builder-zos:1.0.6
5138418e3ae74224e7d3defb13b403bbd0eaf4c2b9c84529f9645cec479400a9
```
When a signature cannot be verified an error occurs. The following is an example of an error when the ability to read container image sigstore attachments is disabled:
```
$ podman pull icr.io/ibm-cics-ts/<image-name>:1.0.6
zosError: Source image rejected: A signature was required, but no signature exists
```

Downloading the CICS TS resource builder container images

To get access to the cics-resource-builder-zos image, you must have an IBM entitlement registry key to pull the images from the IBM Cloud Container Registry icr.io. Your entitlement key can be found in your license documents. For more information, see Getting access to the container images.

Pull the CICS TS resource builder container images to your local system.
Linux
```
podman pull icr.io/ibm-cics/cics-resource-builder-ubi8:1.0.6
```
IBM Z
```
podman pull --creds iamapikey:<entitlement_key> icr.io/ibm-cics-ts/cics-resource-builder-zos:1.0.6
```
You need to replace <entitlement_key> with the entitlement key found in your license documents.
Run the command podman images to see that the cics-resource-builder-ubi8 and cics-resource-builder-zos images are available.

Downloading and pushing the container images into your internal images registry

Pull both container images to your local system.

Linux

$ podman pull --os linux --arch amd64 icr.io/ibm-cics/cics-resource-builder-ubi8:1.0.6
b0405b027d410add4fee4e05e7d401b7a937f76b405c189f66c9e8abf91b02ba

IBM Z

$ podman pull --os zos --arch s390x icr.io/ibm-cics-ts/cics-resource-builder-zos:1.0.6
5138418e3ae74224e7d3defb13b403bbd0eaf4c2b9c84529f9645cec479400a9

To make the CICS TS resource builder container images available to others, they can be pushed into your internal images registry for others to access it. To do this, use podman login to login to the internal images registry, then enter the following command to push the CICS TS resource builder container images to your internal registry.

Tip: It is recommended, but optional, to verify the container image signatures before using or sharing the images, see Verifying the CICS TS resource builder container images signature.

Linux

podman push icr.io/ibm-cics/cics-resource-builder-ubi8:1.0.6 docker://<internal-registry-location>/cics-resource-builder-ubi8:1.0.6

IBM Z

podman push icr.io/ibm-cics-ts/cics-resource-builder-zos:1.0.6 docker://<internal-registry-location>/cics-resource-builder-zos:1.0.6

Next steps

Using the CICS TS resource builder container images