Introduction to Kontena Stacks

This article was originally published on December 15, 2016. Since then, many things have been updated. This article now properly describes Kontena Stacks as they are today with Kontena version 1.4.x.

Traditionally in application development, developers can use third-party components and libraries that implement some specific features instead of implementing those features by themselves. With containers it’s not so straightforward. Of course you can use ready made images, but you may still need to extend and combine those images together, add some configuration files and remember to execute those files in the correct order to achieve a working application or system. And eventually someone has to maintain those configurations.

To help ease this problem Kontena 1.0 introduced Kontena Stacks to make developers’ lives easier. The Kontena Stacks feature some great features such as:

The ultimate goal of Kontena Stacks is that developers can just define service dependencies of their applications and don’t need to worry about their internals. Also installing some ready-made third-party applications is made extremely easy.

A software stack is a group of programs that work in tandem to produce a result or achieve a common goal.

Kontena Stacks are pre-packaged and reusable collections of Kontena services with associated configuration in the form of a YAML file.

Kontena Stacks can be categorized roughly into three categories:

• Service stacks
• In-house stacks
• Application stacks

Service stacks are ready-made stacks that you can use with your applications. Those stacks can be installed directly from Kontena Stack Registry and utilized with your in-house applications. Typically those stacks are for example clustered databases (MongoDB Replica Set, Stolon (PostgreSQL), Redis Sentinel etc) or some API gateways (Kong etc).

In-house stacks are your custom made stacks that contain your application services. Typically configuration for these stacks are stored in the version control system among the application’s source code.

Application stacks are ready-made applications. These stacks are for example CI/CD tools like Drone. These stacks are available and ready to use from Kontena Stack Registry.

Stack files

Kontena Stacks are defined with Kontena Stack Files which describe the entire solution with a lifecycle. They are composed of Kontena Services running on top of the Kontena Platform.

Since the Kontena Platform is abstracting the underlying infrastructure, Kontena Stacks are infrastructure agnostic. The main goal of stack files is to make stacks easy to configure, install and share.

The YAML file contains the stack definition, variables that are used to customize services and service definitions. Service definitions can be extended from Docker Compose YAML files (version 2). In addition, you can use advanced features such as dependencies, exposing, infrastructure agnostic volumes, dynamic variables and built-in template language.

Stack

In stack definition you can define stack, version, description and expose options.

It’s recommended to define stack in the format of username/stack. That way it's easy to share the stack in the Kontena Stack Registry and see the author of the stack.

The version must follow Semantic Versioning format.

The description contains some summary of your stack to help people understand it better if you share it in the Kontena Stack registry.

With the expose option you can define which service you want to publish from your stack to other stacks. That service will get the <stack>.<grid>.kontena.local DNS address.

For example, the internal Kontena Registry is deployed as a registry stack that exposes the internal api service. The registry.test.kontena.local DNS name is an alias for the api-1.registry.test.kontena.local service container. Other service containers and the host nodes can use the bare registry DNS name to connect to the Kontena Registry.

Dependencies

You can use stack dependencies to break a stack monolith into bite-sized reusable micro stacks or start using ready-made stacks with your application from stack registry. Stacks that are listed as dependencies will be automatically installed, built, upgraded, deployed and uninstalled together with the main stack.

You can use depends key to list additional stacks that need to be installed together, for example:

stack: example/app  
version: 0.1.0  
expose: app  
depends:  
  cockroachdb:
    stack: kontena/cockroachdb
services:  
  app:
    image: example/app
    environment:
      - "DB_HOST=${cockroachdb}" # becomes "DB_HOST=app-cockroachdb"

See more information about stack dependencies.

Variables

Variables can be used to fill in values and to create conditional logic in kontena.yml files.

When defining variables you basically give it some name, where the value is obtained from and where to store the value of the variable.

By default a variable gets set to a local env with the same name, making it possible to use the value later in the YAML.

variables:  
  this_is_the_name:
services:  
  ...
  environment:
    - ENV_VAR=${this_is_the_name}

You can define multiple sources where the value of a variable is got from:

from:  
    env: MYSQL_PASSWORD # First try local environment variable
    vault: mysql-password # Then try to read from Kontena Vault
    prompt: Enter MySQL password # Then ask for a value if still not found
    random_string: 32 # Finally generate random string if user does not provide anything

Then you can define what to do with the value. The default behavior is to set it to the local environment using the variable name.

You can also use another environment variable name or write the value to the Kontena Vault.

to:  
  env: MYSQL_ROOT_PASSWORD # set to local env
  vault: mysql-password # also send to vault

It’s also possible to add conditionals and use different resolvers and data types.

Services

Service definitions configure running application services. If you are familiar with Docker Compose V2 files you are ready to go.

Kontena supports the majority of docker-compose YAML definitions and adds a bunch more options to leverage for example secret management, deployment and orchestration possibilities.

Example of the Complete Stack

stack: acme/example-app  
version: 0.1.0  
description: This is an example app  
depends:  
  redis:
    stack: kontena/redis:0.1.0
    variables:
      version: 3.2-alpine
variables:  
  mysql_root_pw:
    type: string
    from:
      vault: EXAMPLE_MYSQL_ROOT_PASSWORD
      prompt: Enter a root password for MySQL or leave empty to auto generate
      random_string: 16
    to:
      vault: EXAMPLE_MYSQL_ROOT_PASSWORD
  app_domain:
    type: string
    default: www.my-app.com
    from:
      prompt: App domain
expose: loadbalancer  
services:  
  loadbalancer:
    image: kontena/lb:latest
    ports:
      - 80:80
  app:
    build: .
    image: images.kontena.io/acme/example-app:latest
    instances: 2
    links:
      - loadbalancer
    environment:
      - DB_URL=db
      - KONTENA_LB_INTERNAL_PORT=8080
      - KONTENA_LB_VIRTUAL_HOSTS={{ app_domain }}
      - REDIS_HOST={{ redis }}
    deploy:
      strategy: ha
      wait_for_port: 8080
    hooks:
      post_start:
        - name: sleep
          cmd: sleep 10
          instances: *
  db:
    image: mysql:5.6
    stateful: true
    secrets:
      - secret: EXAMPLE_MYSQL_ROOT_PASSWORD
        name: MYSQL_ROOT_PASSWORD
        type: env
    volumes:
      - mysql-data:/var/lib/mysql
volumes:  
  mysql-data:
    external:
      name: example-mysql-data

How to install stacks

There are two ways to install stacks. You can install them directly from the Kontena Stack registry or install from your YAML file.

Installing from an YAML file

Stacks are installed with the kontena stack installcommand:

$ kontena stack install kontena.yml

Installing from Kontena Stack registry:

To install the latest version:

$ kontena stack install kontena/mongodb

To install some specific version:

$ kontena stack install kontena/mariadb:5.5

See the complete documentation how to use Kontena Stacks.

Future Road Map

Kontena Stacks already include handy features but we are working hard to make them even better. Here are some short-term improvements that we are introducing in the near future.

• network isolation for the stacks
• vault isolation for the stacks
• better life-cycle management

About Kontena

Kontena provides the most easy-to-use, fully integrated solution for DevOps and software development teams to deploy, run, monitor and operate containers on the cloud. The underlying Kontena Platform technology is open source and available under Apache 2.0 license. It is used by hundreds of startups and software development teams working for some of the biggest enterprises in the world. www.kontena.io.

Image credits: Mountain Peak View by Wolfgang Lutz.