Image Maintenance

Administrators may wish to create and maintain a library of Kasm Workspaces with custom software and configurations. They may also wish to ensure Images are always up to date with the latest software patches for improved security and reliability with no user downtime. In this situation, it is recommended for administrators to create a DevOps process for automatically building, testing and publishing custom Images to their Kasm deployment.

Process Overview

The following diagram highlights general steps that may be used to orchestrate an Image maintenance process.

Image Maintenance Process

• Build : Create a repository inside a Version Control System (VCS) (e.g GitLab, BitBucket) to host the custom image Dockerfiles. Utilize automated CI/CD toolchains such as pipelines built into the VCS or standalone tools such as Jenkins to automatically build images based on a schedule.

  See Building Custom Images for more details in image creation.

  References:

  • GitLab Pipelines

  • BitBucket Pipelines

  • Jenkins Pipelines

• Push : Utilize the CI/CD toolchain to push the images to a docker container registry. This can be a public registry such as DockerHub, or private registry such those provided by GitLab, AWS, Digital Ocean, etc. The registry must be accessible by all Kasm Agents in order for them to automatically pull the Images.

  When defining the Workspaces inside the Kasm UI, utilize the custom docker image name, registry , and if needed a username and password/access token needed to authenticate to the private registry.

  Consider the naming convention of the docker image tags. It may be beneficial to push an image with multiple tags such as one that represents something unique such as the current date/time myimage:11302020 and another that represents a moving target such as myimage:latest . Consider the Pull Behavior and how that will impact the desired process.

  References:

  • Docker Registry

  • GitLab Container Registry

  • Digital Ocean Container Registry

  • Amazon Elastic Container Registry

  • Google Cloud Artifact Registry

• Test : Create a new Workspace and set the Docker image name, Docker Registry, and the Docker Registry Username and Password if authentication is used. Within a few minutes the Agents will pull down the Images from the defined registry. Assign the Image to a testing group, and verify the desired functionality.

  

  Registering a Test Image

• Deploy : When ready, update the user-facing Images to use the verified docker image name and tag. The next time the user creates a session, the new Image will be used.

Pull Behavior

Kasm Agents check-in with the Kasm Web App service every 30 seconds and will inform the Agent about which Images are defined in the system. If the Agent does not have currently have the Image it will immediately issue a docker pull. The default maximum number of image pulls is 2, and is configurable in section below Changing MAX Concurrent Docker Pulls. Separately, the Agent will also issue a pull every hour for those images even if they are present on the system in order to fetch an updated version if available. In either case, a pull only occurs if a Docker Registry is defined on the Workspace.

Note

Some registries such as DockerHub have implemented Pull Rate Limiting. Administrators should authenticate to the registry to raise those limits by utilizing the Docker Registry Username and Docker Registry Password options when registering an image.

Note

For the Google Cloud Artifact Registry or Google Cloud Container Registry a JSON Service Account Key must be entered in the Docker Registry Password field and the Docker Registry Username must be set to _json_key.

For the Google Cloud Artifact Registry a base64-encoded key can be used instead, with the Docker Registry Username of _json_key_base64.

Changing MAX Concurrent Docker Pulls

By default, each Kasm Agent will only pull a maximum number of 2 docker images at a time. However, for users running Kasm in environments with more available resources you may want to increase this to satisfy your needs.

Warning

Changing the MAX Concurrent Docker Pulls involves restarting the Kasm Agent service(s) and will result in an interruption in service.

Login to each server with the agent role and complete the following steps:

Stop the Agent Services

sudo /opt/kasm/bin/stop

Replace the value of max_concurrent_docker_pulls in the agent config with the new value.

sudo vi /opt/kasm/current/conf/app/agent.app.config.yaml

Start the Agent Services

sudo /opt/kasm/bin/start

If you tail the logs of the agent, after 30 seconds, and if you have multiple images pending will see notifications of images now being pulled.

sudo docker logs -f kasm_agent