Installing and uninstalling an IBM z/OS Connect Server image with Podman

1. Log in to IBM Cloud Container Registry. If you are in an airgapped environment, skip this step.

   podman login icr.io

   Provide your username and password login credentials. Instructions for obtaining these credentials can be found in your license documents.
2. Pull the z/OS Connect Server image to your local system.

   podman pull icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100

   If your environment is a disconnected (airgapped) environment, copy the z/OS Connect Server image to a registry you have access to before completing the next steps. For example, by using either the podman pull or skopeo copy commands.

   podman pull <internal-registry-location>/ibm-zcon-server:3.0.100

   skopeo copy <internal-registry-location>/ibm-zcon-server:3.0.100

3. Optional: To make the z/OS Connect Server image available to others, it can be pushed into the internal image registry for others to access it. To do this, enter the following command to push the z/OS Connect Server image to your internal registry.

   podman push <internal-registry-location>/ibm-zcon-server:3.0.100

podman images

REPOSITORY                                  TAG        IMAGE ID    CREATED     SIZE
icr.io/zosconnectunlimited/ibm-zcon-server 3.0.100    6d2af17d10bd  1 days ago   979MB

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). z/OS Connect images are signed and this topic describes how to verify the signatures on those images.

1. Import the z/OS Connect public key on the machine that you prepared according to the Prerequisites section:

   sudo gpg --import PRD0012028key.pub.asc

   This step needs to be done only once on each machine you use for signature verification.
2. Calculate the fingerprints:

   fingerprint=$(sudo gpg --fingerprint --with-colons | grep -B1 'IBM z/OS Connect Enterprise Edition Unlimited' | grep fpr | tr -d ‘fpr:’)

   This command stores the keys' fingerprint in an environment variable that is called fingerprint, which is needed to verify the signature. When you exit your shell session, the variable is deleted. The next time that you log in to your machine, you can set it again by rerunning the command.

3. Log in to Skopeo.

   sudo skopeo login icr.io

4. Create a directory for the image and use skopeo to pull it into local storage:

   mkdir images

   sudo skopeo copy docker://icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100 dir:./images -a

   This command downloads the image as a set of files and places them in the images directory (or another directory that you choose). If the source image is a list of images for different architectures, the -a attribute copies all of the images.

   Tip: One of these files is a manifest file that is named images/manifest.json, and a signature file is named images/signature-1. You reference both these files in the next step (in the command to verify the signature).
5. Verify the signature:

   sudo skopeo standalone-verify ./images/manifest.json icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100 ${fingerprint} ./images/signature-1

   The confirmation output should be similar to the following where the sha256 value is a 64-byte hexadecimal string.

   Signature verified, digest sha256:0000000000000000000000000000000000000000000000000000000000000000

1. Go to the root of your z/OS Connect API project and open the Dockerfile.
2. Make sure that the Dockerfile within the z/OS Connect API project references your downloaded z/OS Connect Server image in the FROM instruction.
   For example,

   FROM icr.io/zosconnectunlimited/ibm-zcon-server:3.0.100
   

   If you pushed the z/OS Connect Server image to an internal registry in step 3 of Download a z/OS Connect Server image, the image location in the FROM instruction should be updated to reflect that location.

   FROM <internal-registry-location>/ibm-zcon-server:3.0.100

3. If you are building the z/OS Connect API image from your API project on IBM z/OS Container Platform, you need to complete the following step.
   In the Dockerfile, replace the --chown options from the COPY instructions with --chmod=755 options. Update the Dockerfile to the following.

   FROM <internal-registry-location>/ibm-zcon-server:3.0.100
   
   # customise server.xml via dropins
   COPY --chmod=755 src/main/liberty/config /config/configDropins/overrides
   
   # install war
   COPY --chmod=755 build/libs /config/dropins

4. Log in to the private Container Registry.
   Note: This is not the IBM Cloud Container Registry, but the registry where you intend to host your z/OS Connect API image.
   For example,

   podman login example.io

5. Build the z/OS Connect API image by using the podman build command from the same location as the Dockerfile. This makes sure that the build directory is correct.

   podman build -f Dockerfile -t <internal_registry_location>/<api_image>:<api_image_tag> .

   Where

   • <internal_registry_location> is the registry location of the z/OS Connect API image.
   • <api_image> is a descriptive name for your z/OS Connect API image.
   • <api_image_tag> is a descriptive tag for your z/OS Connect API image.

   An example of the podman build command is:

   podman build -f Dockerfile -t example.io/zcon-employees-api:v1.0.0 .

   Note: The trailing period '.' in the command states to use the current directory as the build context.
   Important:

   The z/OS Connect API image is a multi-architecture image and defaults to an architecture that matches the system on which it is built. To build a z/OS Connect API image with a different architecture to your build system, use podman build --platform <os/arch> to specify the target platform for the build output. For example,

   podman build --platform linux/amd64 -t example.io/zcon-employees-api:v1.0.0 .

   For more information, see Building multi-platform images.

   Images for the IBM z/OS Container Platform can be built only on a z/OS LPAR with Podman installed.

6. Verify that the z/OS Connect Server image is built by using Podman.
   Run the following command to list the available images.

   podman images

   The output should be similar to:

   REPOSITORY                                     TAG             IMAGE ID             CREATED         SIZE       
   <internal_registry_location>/<api_image>      <api_image_tag>   08f295112cff       2 mins ago    1.17 GB   
   <internal_registry_location>/ibm-zcon-server   3.0.100          290218c5a5ct         2 weeks ago     1.17 GB   

   If the image is listed, the z/OS Connect API image has been built.

1. Create a secret for the z/OS Connect API. In the following example, it is referred to as <api-secret>.
   On the command-line run.

   SECRET="mypassword" podman secret create <api-secret> --env SECRET

   Change the value of mypassword to the value of your secret. For example, iamasecret.

   This <api-secret> is provided to the container in Run the z/OS Connect API container when Podman is used to run the z/OS Connect API container.

   For more information on podman secret create, see podman-secret-create - Create a new secret.

2. Run the following command to list the secrets that are available.

   podman secret ls

   The output is:

   
   ID                           NAME                         DRIVER      CREATED             UPDATED
   2d2827fde389659effd3a27c5    <api-secret>                 file        3 seconds ago       3 seconds ago

1. Start the configured z/OS Connect API container with the following podman run command.

   podman run -p=<hostport>:9080 -d --rm <api_image>:<api_image_tag>

   Note: For IBM z/OS Container Platform, don't specify -p=<hostport>:9080 as Podman will dynamically allocate an IP address for the container that the API container is contactable on.

   If you need to pass in secrets and or environmental variables, the following is an example of passing the environmental variables and secrets to the z/OS Connect API projects.

   podman run -p=<hostport>:9080 -d --rm --secret <product>-password,type=env,target=<product>_PASSWORD -e <product>_HOST=<host> -e <product>_PORT=<port> -e <product>_USER=<user> <api_image>:<api_image_tag>
   

   The podman run command output shows the ID of the container that is now running.
   For example,

   0734b19230649ffa1f2edec0c6198aa61bad0756f9316b405a81605bd9be1fb8

2. Copy this container ID value to your clipboard as you need to reference the container ID when using Podman to work with this container.
   Tip: If you lose the container ID, the container ID can be found by using the podman ps command.

podman logs -f <container-id>

[AUDIT   ] CWWKZ0001I: Application api started in <time> seconds.

[AUDIT   ] CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in <time> seconds.
[INFO    ] Setting the server's publish address to be /
[INFO    ] SRVE0242I: [api] [/] [CatalogManagerApi]: Initialization successful.

1. Find the API endpoint. The API endpoint is specific to the API project that you are running and is found in the z/OS Connect Server logs.
   Note: All API endpoints are relative to the base URL.

   For example, assuming the base URL of https://api.example.com/v1, the /users endpoint refers to https://api.example/com/v1/users.

2. Invoke the API with the following curl command on your host system to send an HTTP request to invoke the z/OS Connect API endpoint.
   Note:

   • Choose the configured endpoint port. Typical defaults are port 9080 for HTTP endpoints and 9443 for HTTPS endpoints.
   • For z/OS Container Platform, replace 127.0.0.1 with the <container-ip-address> identified with the following command.

     podman inspect -f "{{.NetworkSettings.IPAddress}}" <container-id>

   curl -s 127.0.0.1:<port>/<api_endpoint>

   For example,

   curl -s http://127.0.0.1:9080/v1/users

{"employeeNumber":"000010","firstName":"CHRISTINE","middleInitial":"I","lastName":"HAAS","department":"A00","phoneNumber":"3978",
"hireDate":"1965-01-01","job":"PRES    ","educationLevel":18,"sex":"F","dateOfBirth":"1933-08-14","salary":52750.0,"bonus":1000.0,"commission":4220.0}

1. Log in to your internal Container Registry.
   For example, where example.io is your internal Container Registry location.

   podman login example.io

   Note: This is not the IBM Cloud Container Registry, but the registry where you host your z/OS Connect API image.
2. Push the z/OS Connect API image to your internal Container Registry.
   For example,

   podman push <internal_registry_location>/<api_image>:<api_image_tag>

   Note: Using the <api_image_tag> latest adds the risk of updating the image automatically.

1. Before uninstalling the z/OS Connect API image, stop and remove the container from the system. Use the following command to list all the running containers on the system to make sure it's stopped and removed.

   podman ps --all

   If the container you want to uninstall is still running, go to Stopping the container to stop and remove the container.
2. To remove the z/OS Connect API image, use the following command.

   podman rmi <internal_registry_location>/<api_image>:<api_image_tag>

3. Verify that the z/OS Connect API image is removed with the following command.

   podman images

   The z/OS Connect API image should no longer be listed.