Deploy a service to the DSH

This page contains the steps to deploy a very simple custom service that writes a message to Grafana.

Prerequisites

Before you can follow this tutorial, you need the following:

• On the DSH:
  • Access to a tenant on a DSH platform
  • Access to the Harbor container image registry, and the username and CLI secret for your user. See Accessing Harbor for more information.
  • The Grafana service. See Requesting Prometheus and Grafana for more information.
• On your machine:
  • A Unix-based system, for example Linux, MacOS or Windows Subsystem for Linux
  • Docker CLI

Create a working directiory

Open the Terminal, create a directory for this tutorial, and enter it:

Terminal

mkdir hello-dsh
cd hello-dsh

Create the bash script

In the working directory, create a script hello.sh with the contents below, using the command line or your favorite editor:

#!/bin/sh
# (1)!

function terminate_gracefully() # (2)!
{
    echo "Terminating gracefully..."
    echo "Bye bye world from the DSH!"
}

trap 'terminate_gracefully;exit' TERM # (3)!

while true # (4)!
do
    echo "Hi world from the DSH!"
    sleep 5
done

1. Always add a shebang line with the path to the interpreter of the script.
2. This function terminates the script gracefully if the container receives the signal to terminate.
3. Always listen for signals from the DSH, and handle them gracefully.
4. Print a message every 5 seconds.

Take the following into account when you write a script for a container on the DSH:

• It’s good practice to always specify the interpreter of the bash script.
• Eventually, the script will run inside a container on the DSH:
  • As a consequence, it should always listen for relevant signals from the DSH (line 10).
  • If the container receives the TERM signal to terminate, then you can add code to clean up and terminate gracefully (line 4–8).

Next, you need to make sure that the script has the correct permissions to be executed. In the Terminal, do the following:

Terminal

chmod +x hello.sh

Create the Dockerfile

In the working directory, create a file Dockerfile. This file contains the instructions and commands to assemble an image using Docker:

# Use the Alpine Linux official Docker image
FROM alpine:3.21 

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

# Copy our script, and make it executable
COPY hello.sh /hello.sh
RUN chmod +x /hello.sh

# Create a new user "appuser", and set it as the default user to run commands
RUN adduser --disabled-password --uid $id appuser
USER $id:$id

# Execute the script
CMD ["/hello.sh"]

• It’s important that you don’t run commands in your image as the root user:
  • Running commands as root raises security issues.
  • As a solution, you can add a new user and set it as the default user to run commands (line 12–13).
• It’s recommended that you assign your tenant’s user ID to the new user:
  • In the menu bar of the DSH Console, navigate to “Resources” > “Overview” to see the user ID of your tenant.
  • You can add your tenant’s user ID as an environment variable (line 5).
  • Specify the user ID via the environment variable when you create the user (line 12), and when you switch to the user (line 13).
• Docker recommends that you use the Alpine Docker official image:
  • See How to use the Alpine Docker official image for more information.
  • The code snippet uses version 3.21, but always make sure that you use a recent version for your container images.

Log in to the DSH container image registry

In the next step, log in to the Harbor container image registry of the DSH. Execute the command below, and enter the CLI secret for your user when prompted:

Terminal

docker login registry.cp.kpn-dsh.com -u <your-Harbor-username>

• Replace <your-Harbor-username> with your actual Harbor username.
• See Accessing Harbor for more information about Harbor and the credentials.

Build and push the container image

Now that you have access, you can actually build the container image using Docker, and push it to the DSH’s container image registry:

Terminal

docker build -t registry.cp.kpn-dsh.com/<your-tenant-name>/hello-dsh:1.0.0 .
docker push registry.cp.kpn-dsh.com/<your-tenant-name>/hello-dsh:1.0.0

• Replace <your-tenant-name> with the name of your tenant on the DSH.
• It’s recommended to tag your container images. For that reason, the code snippet uses the -t (or --tag) option, and the image has the name:tag format.
• It’s recommended to use semantic versioning for the tag, which applies the pattern <major>.<minor>.<patch> for version numbers.
• You’re free to choose a different name for your image.

Add the custom service

Finally, you need to add a custom service, and set up the service definition:

• Click “Services” > “Overview” in the menu bar of the DSH Console.
• Click the “+ Service” button at the top of the “Services” overview page.
• Enter the name for the service, for example ‘hello-dsh’.
• Edit the JSON file for the service definition so that it has the form in the code snippet below. Don’t forget to replace the variables with the correct values:
  • <your-tenant-name>: Your tenant’s name
  • <tenant-user-ID>: Your tenant’s user ID. You can find it in the DSH Console, on the “Resources” overview page.
  • Use the name and tag for the image that you pushed in the previous step.
• Click “Start service” if the service definition looks good to you.

{
  "name": "hello-dsh",
  "image": "registry.cp.kpn-dsh.com/<your-tenant-name>/hello-dsh:1.0.0",
  "cpus": 0.1,
  "mem": 256,
  "instances": 1,
  "singleInstance": false,
  "needsToken": true,
  "user": "<tenant-user-ID>"
}

Inspect the service

When you start the service, the DSH automatically redirects you to its details page. You can also reach this page by clicking “Services” > “Overview” in the menu of the DSH Console, and then clicking the relevant line for your service in the overview page.

You can inspect the output of the service:

• Navigate to the details page of the service if you aren’t already there.
• Under “Running tasks”, click the button with the blue “Page” icon at the right of the running task.
• In a new browser tab, the DSH leads you to the correct query in Grafana for your service’s logs:
  • Scroll down to inspect the log entries.
  • It may take a minute before log entries start coming in.
  • Click the “Live” button at the top right of your Grafana page to see the log entries in real time. In that case, <timestamp> Hi world from the DSH! should appear every 5 seconds.

Now stop your service:

• Head back to the details page of your service.
• Click the “Stop” button at the top right of the page.
• Go back to the log entries in Grafana. The logs should show <timestamp> Cleaning up... and <timestamp> Bye bye world from the DSH!.

Congratulations: you have deployed your first service to the DSH, and terminated it gracefully.