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-build601283-cs
Publication date: September 23, 2022
Enhancement to support running IBM Spectrum Symphony SIs (service
instances) in containers using Podman on Red Hat 8.4.
Contents
2. Installation
8. Copyright and trademark information
Before you install this enhancement to your cluster, note the following requirements:
|
Operating system |
Red Hat Linux 8.4 |
|
Product version |
IBM Spectrum Symphony 7.3.1 |
Follow these instructions to download
and install this enhancement on hosts in your cluster.
All IBM Spectrum Symphony compute hosts that will run Podman containers must first satisfy the following
requirements:
l
The host runs on Red Hat Linux 8.4.
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
To install this enhancement, download the following packages for your hosts:
|
Name |
Description |
|
egocore-3.9.0.0_x86_64_build601283.tar.gz |
EGO package containing the EGO core binaries for the cluster. |
|
soamcore-7.3.1_x86_64_build601283.tar.gz |
SOAM
package containing the SOAM core binaries for the 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 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_build601283.tar.gz and soamcore-7.3.1.0_x86_64_build601283.tar.gz files:
> egoinstallfixes
/symfixes/egocore-3.8.0.0_x86_64_build601107.tar.gz
> egoinstallfixes
/symfixes/soamcore-7.3.1.0_x86_64_build601283.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.
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 applicaton profile, 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 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.
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).
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 601283
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
93e2285a2ce2398a9f5357555b833fef egocore-3.9.0.0_x86_64_build601283.tar.gz
3604640652e7d7d2edaa8687b76541ff soamcore-7.3.1.0_x86_64_build601283.tar.gz
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.
© Copyright IBM Corporation 2022
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.