Skip to content

Requirements of container image

In order for your service to run smoothly on the DSH, the container images need to comply with the requirements below.

Termination signals

Make your container responsive to termination signals:

  • This ensures that the DSH can shut down your custom service gracefully.
  • To stop a custom service, the DSH sends the “SIGTERM” signal to the container. Make sure that your service properly listens for that signal as the trigger to initiate a graceful shutdown.
  • The DSH gives your custom service 30 seconds to shut down gracefully. After 30 seconds, the DSH will shut down your service forcefully, using a “SIGKILL” signal.

Non-root user

The DSH enforces the container to run as your tenant’s DSH user ID, so it’s recommended to use this user ID for your containers. You can find it in the DSH Console, on the “Resources” overview page.

If you have your tenant’s user ID, you can create a new user in your Dockerfile and switch to it. For example:

FROM alpine

# Set environment variable for the tenant's user ID
ENV id=<tenant-user-ID>

# Create a new user "appuser", and set it as the default user to run commands
RUN useradd --uid $id appuser

# Here, do things as root, for example install packages
# Switch to appuser
USER $id:$id
# Here, run your processes

Correct target platform

The DSH only supports containers for the linux/amd64 platform. If you build the container image on a machine with a different processor design (for example MacBook), then you need to specify the target platform explicitly.

You can specify the platform in the docker build command:

docker build --platform linux/amd64 .

Or you can specify the platform in the Dockerfile:

FROM --platform=linux/amd64 
…

Tip

See From and Set the target platforms for the build (–platform) for more information.

Transparent Huge Pages

The DSH supports the use of Transparent Huge Pages (THP), with a page size of 2 MB:

  • If you activate THP for your container image, then you need to make sure that your code and processes are compatible with THP.
  • Some virtual machines activate THP by default, so make sure to deactivate it explicitly if necessary.
  • If you see unexpected OOMKilled errors from Kubernetes, then this may be related to THP. In that case, try deactivating THP for your container image.

Correct name

Tag your container with the correct name:

  • Use the command docker build -t registry.cp.kpn-dsh.com/<tenant-name>/<container-name>:<version> ..
  • This is necessary when you push a container to the Harbor container registry, and before you deploy the service via the DSH Console.
  • The DSH’s Harbor container image registry is the only container image registry that you can use for the DSH.
  • The Harbor projects are shared across platforms:
    • As a consequence, you can first test an image on a DSH staging platform.
    • You can then deploy that same image to a DSH production platform.
    • You can use exactly the same image, without having to go through the process of rebuilding it and pushing it to the registry.

Container size

Make your container images as small as possible:

  • The DSH distributes the container image to the computing node that your custom service will run on. The larger the image, the slower the startup of your service.
  • Uploading a large container and starting it costs bandwidth, storage room, and time.

Volumes

Create the volume(s) that are necessary for your custom service:

  • The root volume of every container has a limit of 1 GiB, and you should only use it for temporary storage purposes.
  • If you define a volume in the container image but don’t create an actual volume for it on the DSH, then the custom service uses the root volume. The usage will count towards the limit of 1 GiB.
  • The DSH will restart your service if it goes over this 1 GiB limit.
  • Make sure that your custom service doesn’t log to a file:
    • Once the log reaches 1 GiB in size, the DSH will terminate your service.
    • Make sure to log to either “stderr” or “stdout” to ensure that the logs end up in Loki.
    • You can reach Loki via the “Task” overview in the DSH Console. See the Services page for more information.

Note

  • A volume can be attached to one running instance only.
  • As a consequence, you can’t use multiple instances and a volume without setting the singleInstance key to true. See Single instance for more information.