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.
In general, the image should follow Best practices for writing Dockerfiles. The below requirements are in addition to the list.
You are free to choose a base image based on your requirements.
Here are our recommendations of base images:
- Zowe base images:
zowe-docker-release.jfrog.io/ompzowe/base-node:latest-ubihas node.js LTS (v14) version pre-installed.
zowe-docker-release.jfrog.io/ompzowe/base-jdk:latest-ubihas JRE v8 pre-installed.
- Red Hat Universal Base Image 8 Minimal
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
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
bash. If it's not, you can fix it by installing and overwriting
/bin/shwith the symbolic link of
- These softwares must exist in the image:
- These softwares are optional but good to have:
- Zowe core components must release images based on both
- Zowe core component images must use multiple manifests to define if the image supports multiple CPU architectures.
These descriptive labels are required in the Dockerfile:
### Required Labels
LABEL name="APPLICATION NAME" \
vendor="COMPANY NAME" \
version="VERSION NUMBER" \
release="RELEASE NUMBER" \
summary="APPLICATION SUMMARY" \
description="APPLICATION DESCRIPTION" \
Zowe core component image tags must be a combination of the following information in this format:
- version: must follow semantic versioning or partial semantic versioning with major or major + minor. It may also be
lts. For example,
- linux-distro: for example,
- cpu-arch: for example,
- customize-build: string sanitized by converting non-letters and non-digits to dashes. For example,
- Source Build: must be a string
-sourcesappended 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:
For example, these are valid image tags:
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:
├── manifest.yaml, manifest.yml or manifest.json
/licensesfolder 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.mdprovides 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:
│ ├── <lifecycle-scripts>
/component/bin/<lifecycle-scripts>must remain the same as what it is when running on z/OS.
In the Dockerfile, a
zowe user and group must be created. The
UID and group
GID must be defined as
ARG and with default values of
GID=20000. Example commands:
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
If you use Zowe base images,
zowe user and group are already created.
A multi-stage build is recommended to keep images small and concise. Learn more from Use multi-stage builds.
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.
- 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
zowe.yamlas a configuration file, the same as when running on z/OS.
- This persistent volume MUST be created:
Files and Directories
In the runtime, the Zowe content is organized in this structure:
│ ├── bin/
│ ├── components/
│ │ ├── <component-id>/
│ ├── logs/
│ ├── workspace/
│ ├── zowe.yaml
/home/zowe/runtimeis a shared volume initialized by the
/home/zowe/runtime/components/<component-id>is a symbolic link to the
nameentry defined in
/home/zowe/instance/zowe.yamlis a Zowe configuration file and MUST be mounted from a ConfigMap.
/home/zowe/instance/logsis the logs directory of Zowe instance. This folder will be created automatically by
/home/zowe/instance/workspaceis 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/keystoreis the directory where certificate is mounted. With a typical setup (by using
zwe migrate for kubernetescommand), this folder contains
- Any confidential environment variables, for example, a Redis password, in
zowe.yamlmust be extracted and stored as Secrets. These configurations must be imported back as environment variables.
ConfigMap and Secrets
zowe.yamlmust be stored in a ConfigMap and be mounted under
- All certificates must be stored in Secrets. Those files will be mounted under the
- 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
zowe-docker-release.jfrog.io/ompzowe/zowe-launch-scripts:latest-ubiimage contains necessary scripts to start Zowe components in Zowe context.
- This image has a
/componentdirectory and it will be used to prepare
/home/zowe/instancevolumes to help Zowe component start.
- In Kubernetes and OpenShift environments this step is defined with
ENTRYPOINTdirectives 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
/home/zowe/runtime/bin/internal/run-zowe.sh -c /home/zowe/instance. Here is example start command:
command: ["/bin/bash", "-c"]
- "/home/zowe/runtime/bin/zwe internal start -c /home/zowe/instance/zowe.yaml"
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
true. The value of this variable can be assigned to
metadata.namespace(which default value is
- name: ZWE_POD_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
- name: ZWE_POD_CLUSTERNAME
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.ioregistry 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.ioand Docker Hub registry under
- Release images MUST also update relevant major/minor version tags and the
latesttag. For example, when a component releases a
1.2.3image, the component CI/CD pipeline MUST also tag the image as
latest. Update the
ltstag when it is applicable.
- Zowe core component release images MUST be signed by Zowe committer(s).