TIER Docker Container Specifications

Statement

All Docker containers created or maintained by TIER are built to the specifications described in this document.  We have tried to limit the requirements to the 

Background

In order to facilitate support, TIER has made decisions throughout the course of the project to standardize on certain sub-components and more recently to ensure that TIER containers are compatible with our default orchestration strategy of using Docker Swarm mode via Compose.  

Specification

1. Base Linux Image
   
   1. Centos 7
      1. Standard maintained Centos 7 image
      2. (Under Discussion) potential use of Centos 7 image from Dockerhub that includes what is needed to use systemd as init (instead of supervisord).  We may enable this option is optaining/implementing the logging changes we need to supervisord are hard - - https://hub.docker.com/r/centos/systemd/
2. Servlet Engine
   1. Tomcat will be used whenever a servlet engine is needed.
3. Java Distribution
   1. Oracle's Java distribution will be used whenever Java is needed.
4. Database
   1. If a relational database is provided, MARIADB will be used.
5. Multi-Process Container
   1. Supervisord will be used whenever a container needs more than one process.
6. Container Configuration
   1. Standard Data
      1. Containers may receive configuration data via the environment as described below for Secret Data (6.b)
      2. Configuration data may be mounted into the container from external storage
      3. Configuration data may be "burned" into the container while it is being built.
      4. There are many trade-offs between ii and iii, some environments will choose to enable the end user to build their containers using either method.
   2. Secret Data
      1. The preferred mechanism to support data that must be protected (e.g., passwords, keys, etc.) is Swam-mode Docker Secrets
7. Compatibility/ease of use with Docker SWARM mode, using Docker Stack Deploy and Compose files, while working to not preclude other orchestration options.

1. Secret Processing

1. Assume secrets are mounted in /run/secrets (to support compose in swarm)

2. Secret Availability - in-container startup script behavior

1. Accept the secret in the environment, e.g.,

COMPONENT_DATABASE_PASSWORD=foobar

1. If the filename version of the name exists, prefer it:
   COMPONENT_DATABASE_PASSWORD_FILE=/var/run/secrets/some_file

2. If both exist, prefer the FILE option a

1. Logging

1. All containers log to stdout

2. Goal - easily parsable logs for:

1. Component Name

2. Native logfile name

3. Environment (e.g., Prod, Dev, test)

4. A user supplied token via the environment

3. We will have deployers use the --log-opt tag

1. https://docs.docker.com/config/containers/logging/log_tags/

2. This solution solves items 3.iii.2.a, 3.iii.2.c, and 3.iii.2.d

4. To solve 3.iii.2.b, we need an inventory of components where we are unable to change logfile format.  Components with a single logfile per container should be OK and not need remediation.

1. Supervisord

1. Issue: can not change format of logfile to prepend “supervisord.log”.

2. Looked at potential for external process to transform log format before writing to stdout but prefer not to use this mechanism due to added complexity

3. Scott did some digging

1. No good news - a source code change is needed

2. The code is python but they do not use python logging

3. [AI] Scott will ask about possibility for a feature update

2. Mariadb - should be OK, single logfile per container

3. OpenLDAP - should be OK, single logfile per container

4. COmanage (yet--this could become a requirement for upstream)

5. Shibboleth idp

1. Shibboleth itself OK via log4j

2. Catalina.out tomcat issues

6. Grouper

1. Core grouper logging will be ok

2. Same issues with Supervisord and tomcat