Kontainers

Prerelease Software Notice

Kontainers is currently prerelease software and is subject to breaking changes until version 1.0.0 is released.

MircoKt Kontainers

Each Kontainer below ships with the Kontainers project and is fully tested on Docker and Kubernetes on amd64/ x86_64 and arm64 platforms on Ubuntu Linux 20.04 and macOS, unless noted otherwise.

Kontainers are listed in alphabetical order.

Kafka

Limited Platform Support

Kontainers currently uses Bitnami's Kafka image and only supports amd64 at this time.

Provides support for Apache Kafka, an open-source distributed event streaming platform.

Usage

implementation("io.microkt.kontainers:kontainers-kafka:$version")

Default Configuration

Dynamic Configuration

The Kafka Kontainer factory makes modifications to the Kontainer Spec depending on the runner (Docker vs Kubernetes).

val kafkaKontainerSpec = kontainerSpec() {
    name = "kafka"
    image = "bitnami/kafka:2.8.1"
    environment {
        set("KAFKA_BROKER_ID" to "1")
        set("ALLOW_PLAINTEXT_LISTENER" to "yes")
        set("KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP" to "CLIENT:PLAINTEXT,EXTERNAL:PLAINTEXT")
        set("KAFKA_CFG_LISTENERS" to "CLIENT://:9092,EXTERNAL://:9093")
        set("KAFKA_CFG_INTER_BROKER_LISTENER_NAME" to "CLIENT")
    }
    ports {
        expose tcp 9092
        expose tcp 9093
    }
    resources {
        limit memory 1.5.GB
    }
}

LocalStack

Provides support for LocalStack, a fully functional AWS local development environment. Both the full LocalStack and LocalStack Light images are supported.

Usage

implementation("io.microkt.kontainers:kontainers-localstack:$version")

Configurations

tip

Localstack relies on the SERVICES environment variable to enable various cloud services at startup. Extend the default or light Kontainer Spec to enable services.

val sqsLocalStack = kontainerSpec(localStackKontainerSpec) {
    environment {
        set("SEVICES" to "sqs")
    }
}

Default

val localStackKontainerSpec = kontainerSpec {
    name = "localstack"
    image = "localstack/localstack:0.14"
    ports {
        expose tcp 4566
    }
    resources {
        limit memory 512.MB
    }
}

Light

val localStackLightKontainerSpec = kontainerSpec(localStackKontainerSpec) {
    image = "localstack/localstack-light:0.14"
}

MariaDB

Provides MariaDB Kontainer support.

Usage

implementation("io.microkt.kontainers:kontainers-mariadb:$version")

Default Configuration

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

Mongo

Provides support for MongoDB document database. Uses the official Docker mongo image version 5.0.6.

Usage

implementation("io.microkt.kontainers:kontainers-mongodb:$version")

Default Configuration

val mongoKontainerSpec = kontainerSpec {
    name = "mongo"
    image = "mongo:5.0.6"
    environment {
        set(MONGO_INITDB_ROOT_USERNAME to "test")
        set(MONGO_INITDB_ROOT_PASSWORD to "test")
    }
    ports {
        expose tcp 27017
    }
    resources {
        limit memory 512.MB
    }
}

MySQL

Usage

implementation("io.microkt.kontainers:kontainers-mysql:$version")

Default Configuration

val mysqlKontainerSpec = kontainerSpec {
    name = "mysql"
    image = "mysql:8.0-oracle"
    environment {
        set(MYSQL_DATABASE to "test")
        set(MYSQL_ROOT_PASSWORD to "test")
        set(MYSQL_USER to "test")
        set(MYSQL_PASSWORD to "test")
    }
    ports {
        expose tcp 3306
    }
    resources {
        limit memory 512.MB
    }
}

PostgreSQL

Usage

implementation("io.microkt.kontainers:kontainers-postgresql:$version")

Default Configuration

val postgresKontainerSpec = kontainerSpec {
    name = "postgres"
    image = "postgres:13.4"
    command = listOf("postgres", "-c", "fsync=off")
    environment {
        set(POSTGRES_DB to "test")
        set(POSTGRES_USER to "test")
        set(POSTGRES_PASSWORD to "test")
    }
    ports {
        expose tcp 5432
    }
    resources {
        limit memory 256.MB
    }
}

Redis

Usage

implementation("io.microkt.kontainers:kontainers-redis:$version")

Default Configuration

val redisKontainerSpec = kontainerSpec {
    name = "redis"
    image = "redis:6.2-alpine"
    ports {
        expose tcp 6379
    }
    resources {
        limit memory 128.MB
    }
}

Zookeeper

Usage

implementation("io.microkt.kontainers:kontainers-zookeeper:$version")

Default Configuration

val zookeeperKontainerSpec = kontainerSpec {
    name = "zookeeper"
    image = "zookeeper:3.6.3"
    environment {
        set("ALLOW_ANONYMOUS_LOGIN" to "yes")
    }
    ports {
        expose tcp 2181
    }
    resources {
        limit memory 256.MB
    }
}

DSL

Kontainers DSL

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

val mysqlKontainerSpec = kontainerSpec {
    name = "mysql"
    image = "mysql:8.0-oracle"
    environment {
        set(MYSQL_DATABASE to "test")
        set(MYSQL_ROOT_PASSWORD to "test")
        set(MYSQL_USER to "test")
        set(MYSQL_PASSWORD to "test")
    }
    ports {
        expose tcp 3306
    }
}

Customizing MicroKt Kontainers

Kontainers' DSL makes it simple to customize an existing container specification. Simply declare a new kontainerSpec using the pre-defined specification as its starting point and change any settings as you see fit.

For example, to match the exact point release of MySQL you run in production, you may want to override the image to match that version. If your configuration already specifies as database name, user, and password you may want to override these as well:

// override any settings from the base specification
val myCustomMysqlSpec = kontainerSpec(mysqlKontainerSpec) {
    image = "mysql:8.0.28"
    environment {
        set(MYSQL_DATABASE to "mydb")
        set(MYSQL_USER to "myIntegrationTestUser")
        set(MYSQL_PASSWORD to "myIntegrationTestPassword")
    }
}

// create the Kontainer
val myKontainer = MysqlKontainerFactory().createKontainer(myCustomMysqlSpec)

Requirements & Limitations

Kontainers is designed to be platform-agnostic. Therefore, only features reasonably implemented on both Docker & Kubernetes are acceptable. Furthermore, Kontainers is designed to theoretically support other runtimes, such as AWS Fargate.

Requirements

• Kontainer images must be pre-built and pull-able from a Docker compatible repository
• Kontainers must expose at least 1 TCP or UDP port

Limitations

• Kontainer images must be Linux based
• Kontainer image content cannot be modified at runtime
• Kontainers may not map volumes to and from each other and / or the host machine