Zowe server component runtime lifecycle

Zowe runtime lifecycle

This topic describes the runtime lifecycle of Zowe core components and how an offering that provides a Zowe extension can set up runtime lifecycle for their component.

The Zowe UNIX System Services (USS) components are run as part of the started task ZWESLSTC. There are two key USS directories that play different roles when launching Zowe.

• The Zowe runtime directory <RUNTIME_DIR> that contains the executable files is an immutable set of directories and files that are replaced each time a new release is applied. The initial release or an upgrade is installed either with UNIX shell scripts (see Installing Zowe runtime from a convenience build), or SMP/E where the runtime directory is laid down initially as FMID AZWE002 and then upgraded through rollup PTF builds (see Installing Zowe SMP/E). The Zowe runtime directory is not altered during operation of Zowe, so no data is written to it and no customization is performed on its contents. Important, any customizations to the original Zowe runtime directory are not recommended. This may include installing extensions to this directory, putting your zowe.yaml or Zowe workspace into this directory, or changing any of the files in it, etc.

• The Zowe workspace directory <WORKSPACE_DIR> contains information that is specific to a launch of Zowe. It contains temporary configuration settings that helps an instance of the Zowe server to be started, such as ports that are used or paths to dependent Java and Node.js runtimes. Zowe runtime user should have write permission to this directory. More than one Zowe workspace directories can be created to allow multiple launches of a Zowe runtime, each one isolated from each other and starting Zowe depending on how Zowe YAML configuration is configured.

• The Zowe logs directory <LOGS_DIR> contains USS file logs when running Zowe. Some components like app-server and zss will always write USS log files. Some components like APIML Gateway will write log files to this directory if you enabled debug mode. Zowe runtime user should have write permission to this directory.

To start Zowe, the command zwe start is run from a USS shell. This uses a program ZWELNCH to launch the started task ZWESLSTC, passing an optional HAINST parameter to define which Zowe HA instance will be started. It is the equivalent of using the TSO command /S ZWESLSTC,HAINST='<HA_INSTANCE>',JOBNAME='<JOBNAME>'. The ZWELNCH program understands your Zowe YAML configuration and will start components enabled in the <HA_INSTANCE> by executing zwe internal start component command. If you execute zwe internal start directly, the USS processes will not run as a started task and will run under the user ID of whoever ran the zwe internal start command rather than the Zowe user ID of ZWESVUSR, likely leading to permission errors accessing the contents of the <RUNTIME_DIR> as well as the Zowe certificate. For these reasons, the zwe start script launches Zowe's USS process beneath the started task ZWESLSTC.

Zowe relies on zowe.yaml configuration file to know your customization for the instance. For more information, see Zowe YAML Configuration File Reference.

Note:

The scripts of core Zowe components and some extensions use the helper library <RUNTIME_DIR>/bin/libs. You can also use those functions but please keep away from functions marked as internal or experimental.

Zowe component runtime lifecycle

Each Zowe component will be installed with its own USS directory, which contains its executable files. Within each component's USS directory, a manifest file is required to describe itself and a bin directory is recommended to contain scripts that are used for the lifecycle of the component. When Zowe is started, by reading components manifest commands definition, it identifies the components that are configured to launch and then execute the scripts of those components in the cycle of validate, configure, and start. All components are validated, then all are configured, and finally all are started. This technique is used as follows:

• Used for the base Zowe components that are included with the core Zowe runtime.
• Applies to extensions to allow vendor offerings to be able to have the lifecycle of their 'microservices' within the Zowe USS shell and be included as address spaces under the ZWESLSTC started task.

Note:

All lifecycle scripts are executed from the root directory of the component. This directory is usually where the component manifest is located.

Check Server Component Manifest File Reference to learn how to define lifecycle commands in component manifest file.

Validate

Each component can optionally instruct Zowe runtime to validate itself with a USS command defined in manifest commands.validate.

If present, the validate script performs tasks such as:

• Check that the shell has the correct prerequisites.
• Validate that ports are available.
• Perform other steps to ensure that the component is able to be launched successfully.

During execution of the validate script, if an error is detected, then a component should echo a message that contains information to assist a user diagnosing the problem.

Configure

Each component can optionally instruct Zowe runtime to configure itself with a USS command defined in manifest commands.configure.

If the component has manifest defined, some configure actions will be performed automatically based on manifest definition:

• apimlServices.static: Zowe runtime will automatically parse and add your static definition to API Mediation Layer.
• appfwPlugins.[].path: Zowe runtime will automatically parse and install/configure the component to Zowe App Framework.

It's possible to export configuration variables from the configure step to the start step. Each component runs in separated shell space, which means that the variable of one component does not affect the same variable of another component. For example, when you run export MY_VAR=val in /bin/configure.sh, then the variable ${MY_VAR} will be available in your /bin/start.sh script. However, ${MY_VAR} will not be available in other components.

Start

Each component can optionally instruct Zowe runtime to start itself with a USS command defined in manifest commands.start. If this is not defined, for backward compatible purpose, a call to its /bin/start.sh script will be executed if it exists. If your component is not supposed to be started by itself, for example, the component is a shared library, you can skip this instruction.

It is up to each component to start itself based on how it has been written. We recommend that any variables that someone who configure Zowe may need to vary, such as timeout values, port numbers, or similar, are specified as variables in the instance.env file and then referenced as shell variables in the start.sh script to be passed into the component runtime.