Setting the number of times and frequency to pull Docker images for service instances

By default, in IBM® Spectrum Symphony, a Docker client pulls a Docker image for service instances once, and does not retry if unsuccessful. You can change this configuration by specifying the number of attempts the Docker client should try pulling the image, and the frequency to try the attempts.

1. Enable Docker for service instances by updating the Consumer section of the application profile.

   See Configuring Docker for IBM Spectrum Symphony service instances and for details.

2. Associate your service with a Docker container definition name, by adding the dockerContainerDefinitionName attribute to the Service section of the application profile.

   Valid values are 0 to 9, A to Z, a to z, underscore (_), and hyphen (-). The maximum length is 128 characters. For example:

   <Service name="sympingservice" dockerContainerDefinitionName="ABC" description="ABC Docker definition">

3. Define the number of times and frequency to pull Docker images for service instances, by adding the imagePull element as a child element to the ContainerDefinition element in the Docker section of the application profile.

   Note the name attribute for the ContainerDefinition element should be the same name as specified for the dockerContainerDefinitionName attribute specified in the previous step (for example, ABC).

   Use the retryLimit attribute to specify the number of times the Docker client will retry pulling a Docker image, if it cannot pull the image. If the number of attempts exceeds this value, the system will stop starting the Docker container. Valid values are any positive integer from 0 to 2147483647. The default is 0, meaning that the Docker client only pulls once, and does not retry if it is unsuccessful. If you specify an unsupported value for the retryLimit attribute in the application profile, registering the application will be rejected. If you do not specify a value, the default will be used instead.

   Use the retryInterval attribute to specify the number of seconds to wait before the Docker client attempts to re-pull the Docker image, if the previous pull failed. Valid values are any positive integer from 0 to 2147483647. The default is 3 seconds. If you specify an unsupported value for the retryInterval attribute in the application profile, registering the application will be rejected. If you do not specify a value, the default will be used instead.

   For example:

   <Docker>
      <ContainerDefinition containerUser="root" imageName="docker.io/ubuntu:14.04" name="ABC">
         <ImagePull retryLimit="3" retryInterval="60"/>
      </ContainerDefinition>
   </Docker>

   Note: This Docker image pulling feature interacts with the IBM Spectrum Symphony timeout duration for service instances feature (for the Register method), which is defined in the Service section of the application profile, under Service > Control > Method > Timeout > duration:

   <Method name="Register">
      <Timeout actionOnSI="blockHost" duration="60"/>
      <Exit actionOnSI="blockHost"/>
   </Method>

   If the service instance register timeout duration is triggered when the Docker client is pulling a Docker image, the client will stop pulling the image, and any remaining Docker image pull retries will be ignored because the service instance register timeout duration started before Docker image pulling started.

   Take, for example, a service instance register timeout duration of 60 seconds (duration="60" in the Service section of the application profile), a Docker image pull retry limit of 9 retries (retryLimit=9 in the Docker section of the application profile), and a Docker image pull retry wait interval of 10 seconds (retryInterval=10). The duration timer starts immediately after SIM starts the Docker controller. Upon unsuccessfully pulling the Docker image, the system waits 10 seconds (retryInterval=10), and then retries to pull the image again, using the retry attempt 1, then retry 2, and then up until retry 5. After 60 seconds (duration="60"), the Docker controller will be terminated, and therefore, not allow retries 6 to 9 to be executed. The service instance register timeout of 60 seconds triggered first, and therefore ended before the system could attempt retries 6 to 9.

4. Reregister the application with the soamreg command.

<Consumer applicationName="symping7.3.2" consumerId="/SymTesting/Symping732" enableDockerForServiceInstance="true"/>

<Docker>
   <ContainerDefinition containerUser="root" imageName="docker.io/ubuntu:14.04" name="ABC">
      <ImagePull retryLimit="3" retryInterval="60"/>
   </ContainerDefinition>
</Docker>

...

<Service name="sympingservice" dockerContainerDefinitionName="ABC" description="ABC Docker definition">