Overview

Purpose

Kontainers is a Kotlin framework providing the capability to run Open Container Images (OCI) on Docker, Kubernetes, and possibly other platforms in the near future. This can be valuable in cases where you want to run a database or messaging system for integration testing and then tear down such resources after tests complete.

Kontainers enables users to write and run integration tests locally with Docker Desktop, while also utilizing modern, Kubernetes based CI/CD systems that may not permit or support the Docker runtime.

Architecture

Kontainers provides a platform-agnostic Kontainer specification that allows users to define a request to run a container or Docker and K8S. The specification is then used by a Kontainer factory to start the container on either Docker or Kubernetes, depending on the capabilities of the platform on which your code is run.

Defining Kontainers

Kontainers ships with a Kotlin domain-specific language to support declarative Kontainer definitions, called Kontainer Specs.

The Kontainers project ships with a number of pre-defined Kontainer Specs that can use used as-is or extended for simple customization.

Sample Kontainer Spec

For example, here's a Kontainer Spec for MariaDB:

val mariaKontainerSpec = kontainerSpec {
    name = "mariadb"
    image = "mariadb:10.7"
    environment {
        set(MARIADB_DATABASE to "test")
        set(MARIADB_ROOT_PASSWORD to "test")
        set(MARIADB_USER to "test")
        set(MARIADB_PASSWORD to "test")
    }
    ports {
        expose tcp 3306
    }
    resources {
        limit memory 128.MB
    }
}

Extending a Kontainer Spec

Additionally, an existing Kontainer Spec can be overridden to fit your needs. For example, the above MariaDB spec may suite your needs, but you want to customize the database name, and you're loading a large dataset, so you need more memory. You can create a new Kontainer Spec from the mariaKontainerSpec, overriding only the values you want to change:

val myMariaKontainerSpec = kontainerSpec(mariaKontainerSpec) {
    environment {
        set(MARIADB_DATABASE to "my_db")
    }
    resources {
        limit memory 1.3.GB
    }
}

For a list of Kontainer Specs this ship with this project, please see the MicroKt Kontainers documentation. More information about Kontainer Specs can also be found on the DSL documentation.