Zowe Containerization Conformance Criteria

These conformance criteria are applicable for all Zowe components intending to run in a containerized environment. The containerized environment could be Kubernetes or OpenShift running on Linux or Linux on Z.

Image

In general, the image should follow Best practices for writing Dockerfiles. The below requirements are in addition to the list.

Base Image

You are free to choose a base image based on your requirements.

Here are our recommendations of base images:

• Zowe base images:
  • ompzowe/base: zowe-docker-release.jfrog.io/ompzowe/base:latest-ubuntu and zowe-docker-release.jfrog.io/ompzowe/base:latest-ubi.
  • ompzowe/base-node: zowe-docker-release.jfrog.io/ompzowe/base-node:latest-ubuntu and zowe-docker-release.jfrog.io/ompzowe/base-node:latest-ubi has node.js LTS (v14) version pre-installed.
  • ompzowe/base-jdk: zowe-docker-release.jfrog.io/ompzowe/base-jdk:latest-ubuntu and zowe-docker-release.jfrog.io/ompzowe/base-jdk:latest-ubi has JRE v8 pre-installed.
• Red Hat Universal Base Image 8 Minimal
• Ubuntu

The image should contain as few software packages as possible for security and should be as small as possible such as by reducing package count and layers.

Zowe base images,

• are based on both Ubuntu and Red Hat Universal Base Image,
• provide common dependencies including JDK and/or node.js,
• support both amd64 and s390x CPU architecture.

If you use your own base image other than Zowe base images, please check this list and make sure it is compatible with Zowe runtime:

• The default shell /bin/sh must be bash. If it's not, you can fix it by installing and overwriting /bin/sh with the symbolic link of /bin/bash.
• These softwares must exist in the image: date, awk, sed, xargs.
• These softwares are optional but good to have: ping, dig, netstat.

Multi-CPU Architecture

• Zowe core components must release images based on both amd64 and s390x CPU architecture.
• Zowe core component images must use multiple manifests to define if the image supports multiple CPU architectures.

Image Label

These descriptive labels are required in the Dockerfile: name, maintainer, vendor, version, release, summary, and description.

Example line:

### Required Labels 
LABEL name="APPLICATION NAME" \
      maintainer="EMAIL@ADDRESS" \
      vendor="COMPANY NAME" \
      version="VERSION NUMBER" \
      release="RELEASE NUMBER" \
      summary="APPLICATION SUMMARY" \
      description="APPLICATION DESCRIPTION" \

Tag

Zowe core component image tags must be a combination of the following information in this format: <version>-<linux-distro>[-<cpu-arch>][-sources][.<customize-build>].

• version: must follow semantic versioning or partial semantic versioning with major or major + minor. It may also be latest or lts. For example, 1, 1.23, 1.23.0, lts, latest, etc.
• linux-distro: for example, ubi, ubuntu, etc.
• cpu-arch: for example, amd64, s390x, etc.
• customize-build: string sanitized by converting non-letters and non-digits to dashes. For example, pr-1234, users-john-fix123, etc.
• Source Build: must be a string -sources appended to the end of the tag.
  • If this is a source build, the tag must contain full version number (major+minor+patch) information.
  • Linux Distro information is recommended.
  • Must NOT contain customize build information.
  • For example: 1.23.0-ubi-sources.

For example, these are valid image tags:

• latest
• latest-ubuntu
• latest-ubuntu-sources
• latest-ubi
• latest-ubi-sources
• lts
• lts-ubuntu
• lts-ubi
• 1
• 1-ubuntu
• 1-ubi
• 1.23
• 1.23-ubuntu
• 1.23-ubi
• 1.23.0
• 1.23.0-ubuntu
• 1.23.0-ubuntu-amd64
• 1.23.0-ubuntu-sources
• 1.23.0-ubi
• 1.23.0-ubi-s390x
• 1.23.0-ubi-sources
• 1.23.0-ubuntu.pr-1234
• 1.23.0-ubi.users-john-test1

The same image tag pattern is recommended for Zowe extensions.

Files and Directories

These file(s) and folder(s) are REQUIRED for all Zowe components:

├── licenses/
└── component/
    ├── manifest.yaml, manifest.yml or manifest.json
    ├── README.md

• /licenses folder holds all license-related files. It MUST include at least the license information for current application. It's recommended to include a license notice file for all pedigree dependencies. All licenses files must be in UTF-8 encoding.
• /component/README.md provides information about the application for end-user.
• /component/manifest.(yaml|yml|json) provides basic information of the component. The format of this file is defined at Zowe component manifest. Components must use the same manifest file as when it's running on z/OS.

These file(s) and folder(s) are recommended:

└── component/
    ├── bin/
    │   ├── <lifecycle-scripts>
    ├── <other-application-files>

• /component/bin/<lifecycle-scripts> must remain the same as what it is when running on z/OS.

User zowe

In the Dockerfile, a zowe user and group must be created. The zowe user UID and group GID must be defined as ARG and with default values of UID=20000 and GID=20000. Example commands:

ARG UID=20000
ARG GID=20000
RUN groupadd -g $GID -r zowe && useradd --no-log-init -u $UID -d /home/zowe -r -g zowe zowe

USER zowe must be specified before the first CMD or ENTRYPOINT.

If you use Zowe base images, zowe user and group are already created.

Multi-Stage Build

A multi-stage build is recommended to keep images small and concise. Learn more from Use multi-stage builds.

Runtime

This section is mainly for information. No actions are required for components except where it's specified explicitly.

The below sections are mainly targeting Kubernetes or OpenShift environments. Starting Zowe containers in a Docker environment with docker-compose is in a planning stage and may change some of the requirements.

General rules

Components MUST:

• NOT be started as root user in the container.
• listen to only ONE port in the container except for API Mediation Layer Gateway.
• be cloud-vendor neutral and must NOT rely on features provided by a specific cloud vendor.
• NOT rely on host information such as hostIP, hostPort, hostPath, hostNetwork, hostPID and hostIPC.
• accept zowe.yaml as a configuration file, the same as when running on z/OS.

Persistent Volume(s)

• This persistent volume MUST be created:
  • zowe-workspace mounted to /home/zowe/instance/workspace.

Files and Directories

In the runtime, the Zowe content is organized in this structure:

└── home/
    └── zowe/
        ├── runtime/
        │   ├── bin/
        │   ├── components/
        │   │   ├── <component-id>/
        ├── instance/
        │   ├── logs/
        │   ├── workspace/
        │   ├── zowe.yaml
        ├── keystore/

• /home/zowe/runtime is a shared volume initialized by the zowe-launch-scripts container.
• /home/zowe/runtime/components/<component-id> is a symbolic link to the /component directory. <component-id> is the name entry defined in /component/manifest.(yaml|yml|json).
• /home/zowe/instance/zowe.yaml is a Zowe configuration file and MUST be mounted from a ConfigMap.
• /home/zowe/instance/logs is the logs directory of Zowe instance. This folder will be created automatically by zowe-launch-scripts container.
• /home/zowe/instance/workspace is the persistent volume mounted to every Zowe component container.
  • Components writing to this directory should be aware of the potential conflicts of same-time writing by multiple instances of the same component.
  • Components writing to this directory must NOT write container-specific information to this directory as it may potentially be overwritten by another container.
• /home/zowe/keystore is the directory where certificate is mounted. With a typical setup (by using zwe migrate for kubernetes command), this folder contains keystore.p12, truststore.p12, keystore.key, keystore.cer and ca.cer.
• Any confidential environment variables, for example, a Redis password, in zowe.yaml must be extracted and stored as Secrets. These configurations must be imported back as environment variables.

ConfigMap and Secrets

• zowe.yaml must be stored in a ConfigMap and be mounted under /home/zowe/instance directory.
• All certificates must be stored in Secrets. Those files will be mounted under the /home/zowe/keystore directory.
• Secrets must be defined manually by a system administrator. Zowe Helm Chart and Zowe Operator do NOT define the content of Secrets.

ompzowe/zowe-launch-scripts Image and initContainers

• The zowe-docker-release.jfrog.io/ompzowe/zowe-launch-scripts:latest-ubuntu or zowe-docker-release.jfrog.io/ompzowe/zowe-launch-scripts:latest-ubi image contains necessary scripts to start Zowe components in Zowe context.
• This image has a /component directory and it will be used to prepare /home/zowe/runtime and /home/zowe/instance volumes to help Zowe component start.
• In Kubernetes and OpenShift environments this step is defined with initContainers specification.

Command Override

• Component CMD and ENTRYPOINT directives will be overwritten with the Zowe launch script used to start it in Zowe context.
• Components running in Zowe context requires to be started with bash with argument /home/zowe/runtime/bin/internal/run-zowe.sh -c /home/zowe/instance. Here is example start command:

  command: ["/bin/bash", "-c"]
  args:
    - "/home/zowe/runtime/bin/zwe internal start -c /home/zowe/instance/zowe.yaml"

Environment Variables

These runtime environment variable(s) are REQUIRED to start Zowe components.

• ZWE_POD_NAMESPACE: holds the current Kubernetes namespace. This variable can be optional if the service account automountServiceAccountToken attribute is true. The value of this variable can be assigned to metadata.namespace (which default value is zowe) in Pod spec section:

  env:
    - name: ZWE_POD_NAMESPACE
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.namespace

These runtime environment variable(s) are OPTIONAL to start Zowe components.

• ZWE_POD_CLUSTERNAME: holds the Kubernetes cluster name. This variable has default value cluster.local. If your cluster name is not default value, you should pass the variable to all workloads. The value of this variable can be assigned in Pod spec section:

  env:
    - name: ZWE_POD_CLUSTERNAME
      value: "my.cluster.name"

CI/CD

Build, Test and Release

• Zowe core component and extension images MUST be built, tested, and released on their own cadence.
• The component CI/CD pipeline MUST NOT rely on the Zowe level CI/CD pipeline and Zowe release schedule.
• Zowe core component images must be tested. This includes starting the component and verifying the runtime container works as expected.
• It is recommended to build snapshot images before release. Zowe core components MUST publish snapshot images to the zowe-docker-snapshot.jfrog.io registry with proper tags.
• Zowe core component images MUST be released before Zowe is released.
• Zowe core components MUST publish release images to both zowe-docker-release.jfrog.io and Docker Hub registry under ompzowe/ prefix.
• Release images MUST also update relevant major/minor version tags and the latest tag. For example, when a component releases a 1.2.3 image, the component CI/CD pipeline MUST also tag the image as 1.2, 1, and latest. Update the lts tag when it is applicable.
• Zowe core component release images MUST be signed by Zowe committer(s).