Readme File for IBM^® Spectrum Symphony 7.3.1 Podman support

Readme file for: IBM Spectrum Symphony

Product release: 7.3.1

Fix ID: sym-7.3.1-build601652-jpmc

Publication date: August 3, 2023

 

Enhancement to support running IBM Spectrum Symphony SIs (service instances) in containers using Podman on Red Hat 8.  

 

Contents

1. Scope

2. Installation

3. Configuration and usage

4. Troubleshooting

5. Uninstallation

6. List of files

7. Product notifications

8. Copyright and trademark information

 

 

1.    Scope

Before you install this enhancement to your cluster, note the following requirements:

Operating system	Red Hat Linux 8 versions supported in Symphony 7.3.1
Product version	IBM Spectrum Symphony 7.3.1

 

2.    Installation

Follow these instructions to download and install this enhancement on hosts in your cluster.

Prerequisites

All IBM Spectrum Symphony compute hosts that will run Podman containers must first satisfy the following requirements:

l   The host runs on supported Red Hat Linux version.

l   Podman version 3.3 or later is installed properly on the host, with runc as the runtime CLI tool.

l   Your container is able to run in Podman rootless mode.

l   Python 3.8 is installed and used on the host (with /usr/bin/python pointing to python3.8 binary). If you installed Python from source code, ensure the Python required dependencies, libffi-devel and openssl-devel, are also installed.

l   To use the IBM Spectrum Symphony resource limit feature, ensure that cgroup v1 is used on the host (to check the cgroup version, run the podman info |grep cgroupVersion command).

l   To run rootless containers, ensure that you enable lingering mode for the non-root user by running the loginctl enable-linger system command. For more details about lingering mode requirements for Podman rootless containers, refer to https://github.com/containers/podman/blob/main/troubleshooting.md

Packages

To install this enhancement, download the following packages for your hosts:

Name	Description
egocore-3.9.0.0_x86_64_build601652.tar.gz	EGO package containing the EGO core binaries for the cluster.
soamcore-7.3.1.0_x86_64_build601652.tar.gz	SOAM package containing the SOAM core binaries for the cluster.

 

Installing on management and compute hosts

a.     Log on to the primary host as the cluster administrator and source your environment:

(BASH) . $EGO_TOP/profile.platform

(CSH) source $EGO_TOP/cshrc.platform

b.   Log on as the cluster administrator, disable all applications, stop the SD service, and shut down your cluster:

> egosh user logon -u Admin -x password

> soamcontrol app disable all -f

> egosh service stop SD

> egosh ego shutdown all

c.    Download the packages to each of your management and compute hosts (or just one host if you are using a shared file system) to, for example, to a /symfixes directory.

d.    Run the egoinstallfixes command to install the egocore-3.9.0.0_x86_64_build601652.tar.gz and soamcore-7.3.1.0_x86_64_build601652.tar.gz files:

> egoinstallfixes /symfixes/egocore-3.9.0.0_x86_64_build601652.tar.gz

> egoinstallfixes /symfixes/soamcore-7.3.1.0_x86_64_build601652.tar.gz

Note: Running the egoinstallfixes command automatically backs up the current binary files to a fix backup directory for recovery purposes. Do not delete this backup directory; you will need it if you want to recover the original files. For more information on using this command, see the egoinstallfixes command reference.

3.    Configuration and usage

Configuration

Before using Podman with IBM Spectrum Symphony, add the new podman_active resource to the ego.cluster.cluster_name and ego.shared configuration files:

a.     From the primary host, add the following line to the last section (the Resource section) of the $EGO_CONFDIR/ego.shared file:

podman_active    String  5  ()       ([MDS]Podman active hosts)

b.     From the primary host, add the following line to the last section (the ResourceMap section) of the $EGO_CONFDIR/ego.cluster.cluster_name file:

podman_active   [default]

Check the Podman environment

To verify that your Podman environment works properly with IBM Spectrum Symphony, log on to the host as a consumer execution user who will run the IBM Spectrum Symphony application SI, and ensure that the user is able to successfully run the following operations:

·       Run podman pull image_name, to verify that the user can successfully pull the specified image.

·       Run podman system service --time 5, to verify that the user can start the Podman API service successfully for 5 seconds without errors.

·      Run a container with podman run image_name, to verify that the container can run successfully.

Run IBM Spectrum Symphony SIs in Podman containers

The following steps guide you through configuring and registering the sample symping7.3.2-test application profile to run the symping service in a Podman rootless container. Follow this example to test that you can successfully run SIs in Podman containers:

a.     From the primary host, start the cluster:

> egosh ego start all

b.     After the host in the cluster is ready, check that the new podman_active resource takes effect and shows the right values. For example:

> egosh resource list -o podman_active

NAME      podman_active

lxj-bui*    NotInstalled

ingathe*          3.3.0

splurge*          4.1.1

c.     Configure the symping7.3.1 application profile to run the symping service in a Podman rootless container:

Note: To run in rootless container mode, the application’s consumer execution user cannot be the root user. For example, there, the execution user is called test:

> id test

uid=1001(test) gid=1001(test) groups=1001(test)

> egosh consumer list -ll |grep Symping

"Symping731","/SymTesting/Symping731","Admin","test"

 

1)     Add the Docker > ContainerDefinition section to the application profile, before the SOAM section, to run the SI with image called ubuntu:

<Docker>

   <ContainerDefinition imageName="ubuntu" name="sympingpodman">

   </ContainerDefinition>

</Docker>

 

2)     Add the SOAM_ENABLE_PODMAN_FOR_SERVICE_INSTANCE and SOAM_PODMAN_VERSIONS environment variables to enable Podman in the osTypes > osType section which should locate at the beginning of the SOAM > SSM section of the application profile:

<osTypes>

   <osType name="all">

      <env name="SOAM_ENABLE_PODMAN_FOR_SERVICE_INSTANCE">true</env>

      <env name="SOAM_PODMAN_VERSIONS">4.1.1</env>

   </osType>

</osTypes>

 

The two environment variables are defined as follows:

Environment variable name	Description	Mandatory or not	Valid values	Default values
SOAM_ENABLE_PODMAN_FOR_SERVICE_INSTANCE	Enables Podman containers for the SI of an application.	N	true false	false
SOAM_PODMAN_VERSIONS	Configures allowable Podman versions for running SIs for an application.	N	Any Podman version number supported for IBM Spectrun Symphony SIs	"" (an empty string  means that the SI can run with any Podman version)

 

3)     Modify the Service section of the application profiles:

                                  i.         Configure the dockerContainerDefinitionName value to use the defined containerDefinition: sympingpodman.

                                 ii.         Configure the logDirectory value for the service to ensure the consumer execution user test has write permissions to the log directory.

                                iii.         Configure the PODMAN_CONTAINER_KEEP_ID environment variable to true, to keep the user’s uid and gid values to be the same inside the container as on the host.

      The PODMAN_CONTAINER_KEEP_ID environment variable is defined as follows:

Environment variable name	Description	Mandatory or not	Valid values	Default values
PODMAN_CONTAINER_KEEP_ID	Allows the container user to use the same uid and gid inside the container as on the host	N	true or false	false

 

4)     Register the application:
> soamreg application_profile

d.     Submit workload for the symping service:
 > symping -r 60000

e.     Check the container status:

1)     View the allocation for SIM. The Requirement output should show the corresponding select information about podman_active:

> egosh alloc view 815 |grep Requirement

Requirement     : select((!mg) && (podman_active='4.1.1'))

 

2)     Log on as the user called test, and run the podman ps command. Verify that the command output shows that the container which runs the symping service is started and running correctly.

3)     Run the podman top -l huser user command. Verify that the command output shows the container is running with user test for both host user and container user as follows:

> podman top -l huser user

HUSER       USER

test        test

test        test

 

When PODMAN_CONTAINER_KEEP_ID is not defined, or is defined to false, the output will be as follows:

> podman top -l huser user

HUSER       USER

test        root

test        root

 

f.      Verify that symping workloads run successfully.

4.    Troubleshooting

If the Podman container cannot run successfully, you can troubleshoot with the following checks:

·       Check if SSM receives resources for SIM and SI via by running egosh alloc view.

·       If SIM has tried to start the Docker Controller (the container controller also used by Podman), but controller does not successfully run the container, check the errors in the dockercontroller.log.hostname.applicationname log file under the directory configured in the Service > osTypes > osType > logDirectory section of your application profile.

Note that if the logDirectory is an unsupported path, then the log file will be written to the /tmp directory.

If the log file cannot be found, try to enable DEBUG level logging for the SIM, to see if the log can be generated. You can also check if the execution user is able to create a file under the logDirectory manually.

·       If the pull image timeout (retryLimit*retryInterval) is not accepted, check if the service register timeout duration defined by Service > Control > Method > Timeout > duration is using a smaller timeout. Under this type of configuration, the service register timeout duration will be accepted, and the Docker Controller will be terminated once the system reaches the defined register timeout.

·       If the pull image operation fails with a registry authentication error, check if the auth.json file is located in the default location of /run/user/${uid}/containers. When you use a non-default value  for the XDG_RUNTIME_DIR environment variable, the auth.json file will be located in ${XDG_RUNTIME_DIR}/containers; you need to configure the same XDG_RUNTIME_DIR environment variable in application profile’s Service > osTypes > osType > env section.

For example, if your XDG_RUNTIME_DIR is the user’s home directory, then set:

<env name="XDG_RUNTIME_DIR">${HOME}</env>

The default value is /run/user/${uid}

 

·       When the container runs in rootful mode, and the container encounters an  "unable to find user XX: no matching entries in passwd file" error, then check if the specified containerUser is a built-in user in the image, or if it is an existing host user (both /etc/passwd and /etc/shadow are mounted to the container at the same time).

 

5.    Uninstallation

If required, uninstall this enhancement from management and compute hosts in your cluster:

a.     Log on to the primary host as the cluster administrator and source your environment:

(BASH) . $EGO_TOP/profile.platform

(CSH) source $EGO_TOP/cshrc.platform

b.   Log on on as the cluster administrator, disable all applications, stop the SD service, and shut down your cluster:

> egosh user logon -u Admin -x password

> soamcontrol app disable all -f

> egosh service stop SD

> egosh ego shutdown all

c.   From each of your management and compute hosts (or just one host if you are using a shared file system), roll back this fix:

> egoinstallfixes -r 601652

d.   From primary host, remove the two lines added for podman_active from the ego.cluster.cluster_name and ego.shared configuration files.

e.   From the primary host, start the cluster and enable your applications:

> egosh ego start all

> soamcontrol app enable appName

6.    List of files

e3111bcdd88cf671ed8fe9822dd0ca2d  egocore-3.9.0.0_x86_64_build601652.tar.gz

73f869ac6a32832dfece955ea4f7e6cb  soamcore-7.3.1.0_x86_64_build601652.tar.gz

7.    Product notifications

To receive information about product solution and patch updates automatically, subscribe to product notifications on the My Notifications page http://www.ibm.com/support/mynotifications/ on the IBM Support website (http://support.ibm.com). You can edit your subscription settings to choose the types of information you want to get notification about, for example, security bulletins, fixes, troubleshooting, and product enhancements or documentation changes. 

8.    Copyright and trademark information

© Copyright IBM Corporation 2023

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM®, the IBM logo and ibm.com® are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.