--- myst: html_meta: "description lang=en": "Keeping custom Kasm Workspaces images up to date using automated CI. " "keywords": "Kasm, How to, How-to, Continuous Integration, Image Updates, Docker, Custom Images, Security, System Packages" "property=og:locale": "en_US" --- ```{title} Image Maintenance ``` # Image Maintenance Administrators may wish to create and maintain a library of Kasm {term}`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. ```{figure} /images/image_maintenance/process.png :align: center **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 {doc}`Building Custom Images ` for more details in image creation. **References:** - [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines/) - [BitBucket Pipelines](https://bitbucket.org/product/features/pipelines) - [Jenkins Pipelines](https://www.jenkins.io/doc/book/pipeline/) - **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 GitLab, AWS, Digital Ocean etc. The registry must be accessible by all Kasm {term}`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 {code}`myimage:11302020` and another that represents a moving target such as {code}`myimage:latest` . Consider the [Pull Behavior](#pull-behavior) and how that will impact the desired process. **References:** - [Docker Registry](https://docs.docker.com/registry/) - [GitLab Container Registry](https://docs.gitlab.com/ee/user/packages/container_registry/) - [Digital Ocean Container Registry](https://www.digitalocean.com/products/container-registry/) - [Amazon Elastic Container Registry](https://aws.amazon.com/ecr/) - [Google Cloud Artifact Registry](https://cloud.google.com/artifact-registry/docs/docker) - **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. {doc}`Assign the Image` to a testing group, and verify the desired functionality. ```{figure} /images/image_maintenance/test_image.webp :align: center **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 {term}`Agents ` check-in with the Kasm {term}`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 {code}`docker pull`. The default maximum number of image pulls is {code}`2`, and is configurable in section below [Changing MAX Concurrent Docker Pulls](#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](https://docs.docker.com/docker-hub/download-rate-limit/). 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](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-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 {code}`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 ```Bash sudo /opt/kasm/bin/stop ``` Replace the value of {code}`max_concurrent_docker_pulls` in the agent config with the new value. ```Bash sudo vi /opt/kasm/current/conf/app/agent.app.config.yaml ``` Start the Agent Services ```Bash 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. ```Bash sudo docker logs -f kasm_agent ```