Enabling service instances in TLS-enabled Docker environments

Configure your applications to run service instances on Docker containers in a TLS-enabled Docker environment.

Before you begin

A supported Docker version must be installed on the physical hosts where Docker must run. See Supported Docker versions.
Docker networking must be set up to use the host's networking stack.
The Docker environment must be set up for TLS.
Docker images for IBM Spectrum Symphony compute hosts and service instances must be available. See Docker images.
The DOCKER_HOST_URL environment variable must be defined to specify the Docker host URL to allow the Docker controller to connect to the Docker daemon. Specify the URL in the format tcp://FQDN_hostname:port. IP addresses are not supported.
You can use the -e, --env, and --env-file flags to set simple environment variables in the Docker container. For example, pass the DOCKER_HOST_URL variable with the -e option when you start the container:
```
docker run -it -v /var/run/docker.sock:/var/run/docker.sock -v /usr/bin/docker:/usr/bin/docker 
-e "DOCKER_HOST_URL=tcp://docker01.eng.lab.mycompany.com:2376" -d -h containerName --privileged=true --name=containerName imageName
```

About this task

Enabling service instances to run in a TLS-enabled Docker container involves configuring the application profile. You must first enable service instances to run in a Docker container, then configure environment variables to run service instances in a TLS-enabled container. Configure the application profile either from the cluster management console or manually through an XML editor.

Procedure

Enable service instances to run in a Docker container. See Configuring Docker for IBM Spectrum Symphony service instances.
In the service section of the application profile, add the TLS environment variables:
1. Add the DOCKER_TLS_VERIFY environment variable to start service instances in a TLS Docker container. Valid values are 1 (enabled) or 0 (disabled). Default is 0.
2. Optional: If TLS authentication certificates for the Docker daemon and client are not available at ${HOME}/.docker, add the DOCKER_CERT_PATH environment variable to specify the location of your certificates.
3. Optional: Add the DOCKER_API_VERSION environment variable to specify the Docker API version. Ensure that the version you specify exists on the hosts, otherwise, the default version (1.21) is used.
Here's a sample configuration:
```
<Service description="Symping Service" dockerContainerDefinitionName="test" name="sympingservice">
  <osTypes>
    <osType name="all"
       startCmd="${SOAM_HOME}/version/EGO_machine_type/bin/sympingservice">
      <env name="DOCKER_TLS_VERIFY">1</env>
      <env name="DOCKER_API_VERSION">1.26</env>
      <env name="DOCKER_HOST_URL">tcp://docker01.eng.lab.mycompany.com:2376</env>
    </osType>
  </osTypes>
…
</Service>
```
Reregister the application with the soamreg command.

What to do next

If you encounter issues, try the following tips to troubleshoot:

If the SSM does not start a SIM for the application on the compute host, check Docker resources on the compute host:
1. On the cluster management console, go to Resources > Resource Planning (Slot) > Resource Groups, click ComputeHosts > Member Hosts, and check whether the docker_active value for the compute host shows a valid Docker version.
2. Check whether the docker.sockfile (required for Docker startup) exists on the compute host at /var/run/.
If the service container is not started, it might be any of the following reasons:
- If the SIM cannot communicate with the Docker daemon:
  1. Check whether the TCP listening address for the Docker daemon matches the FQDN_hostname specified in the DOCKER_HOST_URL environment variable.
  2. Confirm whether the FQDN_hostname in the DOCKER_HOST_URL variable can be parsed on the compute host. If not, add the FQDN_hostname and address in the /etc/hosts file.
  3. Check whether the DOCKER_HOST_URL variable is a valid value on the compute host.
  4. Use the Docker command to check whether the certificate is generated successfully and is still valid.
  5. Check whether Python (required for SIM communication with the Docker daemon) is installed on the compute host.
- If the SIM starts the service container successfully, but it exits in a short time, check whether all the dependent packages exist in the service image.