.. title:: Image Maintenance

Image Maintenance
-----------------
Administrators may wish to create and maintain a library of Kasm :term:`Images <Image>` 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
  :width: 80%
  :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 </how_to/building_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 <Agent>` in order for them to automatically pull the Images.

    When defining the Image 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 :ref:`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/>`__


* Test
    Register the desired Image in the Kasm UI. Within a few minutes the Agents will pull down the Images from the
    defined registry. :doc:`Assign the Image</guide/groups>` to a testing group, and verify the desired functionality.

    .. figure:: /images/image_maintenance/test_image.png
      :width: 80%
      :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:


Pull Behavior
=============

Kasm :term:`Agents <Agent>` check in with the Kasm :term:`Web App <Web Application>` 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`. 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 registered Image.


.. 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.