kompose Documentation

Technical Documentation: kubernetes/kompose

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Kompose (Kubernetes + Compose)

kompose is a tool to help users who are familiar with docker-compose move to Kubernetes. kompose takes a Compose Specification file and translates it into Kubernetes resources.

kompose is a convenience tool to go from local Compose environment to managing your application with Kubernetes. Transformation of the Compose Specification format to Kubernetes resources manifest may not be exact, but it helps tremendously when first deploying an application on Kubernetes.

Use Case Copy Chapter

Convert compose.yaml into Kubernetes deployments and services with one simple command:

$ kompose convert -f compose.yaml
INFO Kubernetes file "frontend-service.yaml" created
INFO Kubernetes file "redis-leader-service.yaml" created
INFO Kubernetes file "redis-replica-service.yaml" created
INFO Kubernetes file "frontend-deployment.yaml" created
INFO Kubernetes file "redis-leader-deployment.yaml" created
INFO Kubernetes file "redis-replica-deployment.yaml" created

Other examples are provided in the examples directory.

Installation Copy Chapter

We have multiple ways to install Kompose. Our preferred method is downloading the binary from the latest GitHub release.

Our entire list of installation methods are located in our installation.md document.

Installation methods:

• Binary (Preferred method)
• Go
• CentOS
• openSUSE/SLE
• NixOS
• macOS (Homebrew and MacPorts)
• Windows
• Docker

Binary installation

Kompose is released via GitHub on a three-week cycle, you can see all current releases on the GitHub release page.

Linux and macOS:

# Linux
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-linux-amd64 -o kompose

# macOS
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-darwin-amd64 -o kompose

chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose

Windows:

Download from GitHub and add the binary to your PATH.

Shell autocompletion Copy Chapter

We support Bash, Zsh and Fish autocompletion.

# Bash (add to .bashrc for persistence)
source <(kompose completion bash)

# Zsh (add to .zshrc for persistence)
source <(kompose completion zsh)

# Fish autocompletion
kompose completion fish | source

Development and building of Kompose Copy Chapter

Building with `go` Copy Section

Requisites:

1. make
2. Golang v1.6 or later
3. Set GOPATH correctly or click SettingGOPATH for details

Steps:

1. Clone repository

$ git clone https://github.com/kubernetes/kompose.git $GOPATH/src/github.com/kubernetes/kompose

2. Change directory to the cloned repo.

cd $GOPATH/src/github.com/kubernetes/kompose

3. Build with make

$ make bin

4. Or build with go

$ go build -o kompose main.go

5. Test your changes

$ make test

Documentation Copy Chapter

Documentation can be found at our kompose.io website or our docs folder.

Here is a list of all available docs:

• Quick start
• Installation
• User guide
• Conversion
• Architecture
• Development

Community, Discussion, Contribution, and Support Copy Chapter

Issues: If you find any issues, please file it.

Kubernetes Community: As part of the Kubernetes ecosystem, we follow the Kubernetes community principles. More information can be found on the community page.

Chat (Slack): We're fairly active on Slack and you can find us in the #kompose channel.

Code of Conduct Copy Section

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

Overview (`build/README.md`) Copy Section

Fedora RPM packaging

There are instructions on how to build the RPM.

1. Gofed

Grab gofed from https://github.com/gofed/gofed

Choose which version of the repo you want to build. For kompose it was 0.3.0 and the commit was 135165b39c55d29a5426479ded81eddd56bfbaf4

Run the following to generate spec file:

gofed repo2spec --detect github.com/kubernetes/kompose --commit 135165b39c55d29a5426479ded81eddd56bfbaf4 --with-extra --with-build -f

The spec file is now located at:

$HOME/gofed/golang-github-kubernetes-incubator-kompose/golang-github-kubernetes-incubator-kompose.spec

2. Dependencies

Now we need to go through and fix some things.

Generate bundled dependencies by using parsedeps.go

Go to the kompose source folder and then run:

go run parsedeps.go

In the future this will possibly done by gofed, see: https://github.com/gofed/gofed/issues/42

3. Building a source RPM locally on CentOS

First, follow instructions to do local setup https://wiki.centos.org/HowTos/SetupRpmBuildEnvironment

Source: https://wiki.centos.org/HowTos/RebuildSRPM

Second, checkout the source to the release commit

Copy the kompose code directory with name kompose-135165b39c55d29a5426479ded81eddd56bfbaf4

Tar the kompose-135165b39c55d29a5426479ded81eddd56bfbaf4 code directory as kompose-135165b.tar.gz and copy it to $HOME/rpmbuild/SOURCES/

Run following command:

rpmbuild -ba kompose.spec

Find the srpm in $HOME/rpmbuild/SRPMS

Find the RPM in $HOME/rpmbuild/RPM/arch/

Check that the dependencies are proper:

rpm -qpR RPMS/x86_64/kompose-0.3.0-0.1.git135165b.el7.centos.x86_64.rpm

4. Running in on Koji (build system)

First, setup your environment in order to run Koji: https://fedoraproject.org/wiki/Using_the_Koji_build_system

Example setup:

fedora-packager-setup
kinit <username>@FEDORAPROJECT.ORG

To build it on koji run:

koji build --scratch rawhide kompose-0.3.0-0.1.git135165b.el7.centos.src.rpm

Overview (`docs/README.md`) Copy Section

View the site via:

bundle exec jekyll serve .

And visiting localhost:4000 on your browser.

Overview (`.openvex/templates/README.md`) Copy Section

OpenVEX Templates Directory

This directory contains the OpenVEX data for this repository.
The files stored in this directory are used as templates by
vexctl generate when generating VEX data for a release or
a specific artifact.

To add new statements to publish data about a vulnerability,
download vexctl
and append new statements using vexctl add. For example:

vexctl add --in-place main.openvex.json pkg:oci/test CVE-2014-1234567 fixed

That will add a new VEX statement expressing that the impact of
CVE-2014-1234567 is under investigation in the test image. When
cutting a new release, for pkg:oci/test the new file will be
incorporated to the relase's VEX data.

Read more about OpenVEX Copy Chapter

To know more about generating, publishing and using VEX data
in your project, please check out the vexctl repository and
documentation: https://github.com/openvex/vexctl

OpenVEX also has an examples repository with samples and docs:
https://github.com/openvex/examples

Overview (`examples/web/README.md`) Copy Section

A fork of https://github.com/kubernetes/examples/blob/master/guestbook-go/README.md

A simple example that shows the functionality of Kompose

Pushed to https://docker.io/kompose/web

Overview (`script/test/README.md`) Copy Section

Functional Test

Requirements Copy Section

Install jq - commandline JSON processor with minimum version of 1.5

Running tests Copy Section

Test running ./cmd/tests.sh

Getting Started (`docs/getting-started.md`) Copy Section

layout: default
permalink: /getting-started/
title: Getting Started
redirect_from:

• /docs/getting-started.md/
• /docs/getting-started/

Getting Started

• TOC
  {:toc}

This is how you'll get started with Kompose!

There are three different guides depending on your container orchestrator as well as operating system.

For beginners and the most compatibility, follow the Minikube and Kompose guide.

Minikube and Kompose Copy Chapter

In this guide, we'll deploy a sample compose.yaml file to a Kubernetes cluster.

Requirements:

• minikube
• kompose

Start minikube:

If you don't already have a Kubernetes cluster running, minikube is the best way to get started.

$ minikube start
Starting local Kubernetes v1.7.5 cluster...
Starting VM...
Getting VM IP address...
Moving files into cluster...
Setting up certs...
Connecting to cluster...
Setting up kubeconfig...
Starting cluster components...
Kubectl is now configured to use the cluster

Download an example Compose file, or use your own:

wget https://raw.githubusercontent.com/kubernetes/kompose/main/examples/compose.yaml

Convert your Compose file to Kubernetes:

Run kompose convert in the same directory as your compose.yaml file.

$ kompose convert
INFO Kubernetes file "frontend-service.yaml" created
INFO Kubernetes file "redis-leader-service.yaml" created
INFO Kubernetes file "redis-replica-service.yaml" created
INFO Kubernetes file "frontend-deployment.yaml" created
INFO Kubernetes file "redis-leader-deployment.yaml" created
INFO Kubernetes file "redis-replica-deployment.yaml" created

Then you can use kubectl apply to create these resources in Kubernetes.

Access the newly deployed service:

Now that your service has been deployed, let's access it.

If you're using minikube you may access it via the minikube service command.

$ minikube service frontend

Otherwise, use kubectl to see what IP the service is using:

$ kubectl describe svc frontend
Name:                   frontend
Namespace:              default
Labels:                 service=frontend
Selector:               service=frontend
Type:                   LoadBalancer
IP:                     10.0.0.183
LoadBalancer Ingress:   123.45.67.89
Port:                   80      80/TCP
NodePort:               80      31144/TCP
Endpoints:              172.17.0.4:80
Session Affinity:       None
No events.

Note: If you're using a cloud provider, your IP will be listed next to LoadBalancer Ingress.

If you have yet to expose your service (for example, within GCE), use the command:

kubectl expose deployment frontend --type="LoadBalancer"

To check functionality, you may also curl the URL.

$ curl http://123.45.67.89

Minishift and Kompose Copy Chapter

In this guide, we'll deploy a sample compose.yaml file to an OpenShift cluster.

Requirements:

• minishift
• kompose
• An OpenShift route created

Note: The service will NOT be accessible until you create an OpenShift route with oc expose. You must also have a virtualization environment setup. By default, minishift uses KVM.

Start minishift:

Minishift is a tool that helps run OpenShift locally using a single-node cluster inside a VM. Similar to minikube.

$ minishift start
Starting local OpenShift cluster using 'kvm' hypervisor...
-- Checking OpenShift client ... OK
-- Checking Docker client ... OK
-- Checking Docker version ... OK
-- Checking for existing OpenShift container ... OK
...

Download an example Compose file, or use your own:

wget https://raw.githubusercontent.com/kubernetes/kompose/main/examples/compose.yaml

Convert your Compose file to OpenShift:

Run kompose convert --provider=openshift in the same directory as your compose.yaml file.

$ kompose convert --provider=openshift
INFO OpenShift file "frontend-service.yaml" created
INFO OpenShift file "redis-leader-service.yaml" created
INFO OpenShift file "redis-replica-service.yaml" created
INFO OpenShift file "frontend-deploymentconfig.yaml" created
INFO OpenShift file "frontend-imagestream.yaml" created
INFO OpenShift file "redis-leader-deploymentconfig.yaml" created
INFO OpenShift file "redis-leader-imagestream.yaml" created
INFO OpenShift file "redis-replica-deploymentconfig.yaml" created
INFO OpenShift file "redis-replica-imagestream.yaml" created

Then you can use kubectl apply to create these resources in OpenShift cluster.

Access the newly deployed service:

After deployment, you must create an OpenShift route in order to access the service.

If you're using minishift, you'll use a combination of oc and minishift commands to access the service.

Create a route for the frontend service using oc:

$ oc expose service/frontend
route "frontend" exposed

Access the frontend service with minishift:

$ minishift openshift service frontend --namespace=myproject
Opening the service myproject/frontend in the default browser...

You can also access the GUI interface of OpenShift for an overview of the deployed containers:

$ minishift console
Opening the OpenShift Web console in the default browser...

RHEL and Kompose Copy Chapter

In this guide, we'll deploy a sample compose.yaml file using both RHEL (Red Hat Enterprise Linux) and OpenShift.

Requirements:

• Red Hat Enterprise Linux 7.4
• Red Hat Development Suite
  • Which includes:
  • minishift
  • kompose

Note: A KVM hypervisor must be setup in order to correctly use minishift on RHEL. You can set it up via the CDK Documentation under "Set up your virtualization environment".

Install Red Hat Development Suite:

Before we are able to use both minishift and kompose, DevSuite must be installed. A more concise installation document is available.

Change to root.

$ su -

Enable the Red Hat Developer Tools software repository.

$ subscription-manager repos --enable rhel-7-server-devtools-rpms
$ subscription-manager repos --enable rhel-server-rhscl-7-rpms

Add the Red Hat Developer Tools key to your system.

$ cd /etc/pki/rpm-gpg
$ wget -O RPM-GPG-KEY-redhat-devel https://www.redhat.com/security/data/a5787476.txt
$ rpm --import RPM-GPG-KEY-redhat-devel

Install Red Hat Development Suite and Kompose.

$ yum install rh-devsuite kompose -y

Start minishift:

Before we begin, we must do a few preliminary steps setting up minishift.

$ su -
$ ln -s /var/lib/cdk-minishift-3.0.0/minishift /usr/bin/minishift
$ minishift setup-cdk --force --default-vm-driver="kvm"
$ ln -s /home/$(whoami)/.minishift/cache/oc/v3.5.5.8/oc /usr/bin/oc

Now we may start minishift.

$ minishift start
Starting local OpenShift cluster using 'kvm' hypervisor...
-- Checking OpenShift client ... OK
-- Checking Docker client ... OK
-- Checking Docker version ... OK
-- Checking for existing OpenShift container ... OK
...

Download an example Compose file, or use your own:

wget https://raw.githubusercontent.com/kubernetes/kompose/main/examples/compose.yaml

Convert your Compose file to OpenShift:

Run kompose convert --provider=openshift in the same directory as your compose.yaml file.

$ kompose convert --provider=openshift
INFO OpenShift file "frontend-service.yaml" created
INFO OpenShift file "redis-leader-service.yaml" created
INFO OpenShift file "redis-replica-service.yaml" created
INFO OpenShift file "frontend-deploymentconfig.yaml" created
INFO OpenShift file "frontend-imagestream.yaml" created
INFO OpenShift file "redis-leader-deploymentconfig.yaml" created
INFO OpenShift file "redis-leader-imagestream.yaml" created
INFO OpenShift file "redis-replica-deploymentconfig.yaml" created
INFO OpenShift file "redis-replica-imagestream.yaml" created

Then you can use kubectl apply to create these resources in OpenShift.

Access the newly deployed service:

After deployment, you must create an OpenShift route in order to access the service.

If you're using minishift, you'll use a combination of oc and minishift commands to access the service.

Create a route for the frontend service using oc:

$ oc expose service/frontend
route "frontend" exposed

Access the frontend service with minishift:

$ minishift openshift service frontend --namespace=myproject
Opening the service myproject/frontend in the default browser...

You can also access the GUI interface of OpenShift for an overview of the deployed containers:

$ minishift console
Opening the OpenShift Web console in the default browser...

Index (`docs/index.md`) Copy Section

Feel free to add content and custom Front Matter to this file.

To modify the layout, see https://jekyllrb.com/docs/themes/#overriding-theme-defaults

layout: index Copy Chapter

$ kompose convert -f compose.yaml

$ kubectl apply -f .

$ kubectl get po
NAME                            READY     STATUS              RESTARTS   AGE
frontend-591253677-5t038        1/1       Running             0          10s
redis-leader-2410703502-9hshf   1/1       Running             0          10s
redis-replica-4049176185-hr1lr  1/1       Running             0          10s

Config.Yml (`docs/_config.yml`) Copy Section

title: Kompose
name: Kompose
email: [email protected]
github_page: https://github.com/kubernetes/kompose
slack_page: https://slack.k8s.io
Convert your Docker Compose file to Kubernetes or OpenShift
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
year: 2024

Google Analytics number (starts with UA?)

analytics: 12345

instagram: https://www.instagram.com
facebook: https://www.facebook.com

Build settings

theme: minima
plugins:

• jekyll-feed

Architecture (`docs/architecture.md`) Copy Section

layout: default
permalink: /architecture/
title: Architecture
redirect_from:

• /docs/architecture.md/
• /docs/architecture/

Architecture and Internal Design

• TOC
  {:toc}

kompose has 3 stages: Loader, Transformer and Outputter. Each stage should have a well-defined interface, so it is easy to write a new Loader, Transformer, or Outputters and plug it in. Currently, only Loader and Transformer interfaces are defined.

Loader Copy Chapter

The Loader reads the input file now kompose supports Compose v1, v2 and converts it to KomposeObject.

Loader is represented by a Loader interface:

type Loader interface {
      LoadFile(file string) kobject.KomposeObject
}

Every loader “implementation” should be placed into kompose/pkg/loader (like compose). More input formats will be supported in the future. You can take a look for more details at:

• kompose/pkg/loader
• kompose/pkg/loader/compose

KomposeObject Copy Chapter

KomposeObject is Kompose internal representation of all containers loaded from input file. First version of KomposeObject looks like this (source: kobject.go):

// KomposeObject holds the generic struct of Kompose transformation
type KomposeObject struct {
    ServiceConfigs map[string]ServiceConfig
}

// ServiceConfig holds the basic struct of a container
type ServiceConfig struct {
    ContainerName string
    Image         string
    Environment   []EnvVar
    Port          []Ports
    Command       []string
    WorkingDir    string
    Args          []string
    Volumes       []string
    Network       []string
    Labels        map[string]string
    Annotations   map[string]string
    CPUSet        string
    CPUShares     int64
    CPUQuota      int64
    CapAdd        []string
    CapDrop       []string
    Entrypoint    []string
    Expose        []string
    Privileged    bool
    Restart       string
    User          string
}

Transformer Copy Chapter

The Transformer takes KomposeObject and converts it to target/output format (currently, there are sets of Kubernetes/OpenShift objects). Similar to the Loader, Transformer is represented by a Transformer interface:

type Transformer interface {
     Transform(kobject.KomposeObject, kobject.ConvertOptions) []runtime.Object
}

If you wish to add more providers containing different kinds of objects, the Transformer would be the place to look into. Currently, Kompose supports Kubernetes (by default) and OpenShift providers. More details at:

• kompose/pkg/transformer
• kompose/pkg/transformer/Kubernetes
• kompose/pkg/transformer/openshift

Outputter Copy Chapter

The Outputter takes the Transformer result and executes the given action. For example, action can display results to stdout or directly deploy artifacts to Kubernetes/OpenShift.

Conversion (`docs/conversion.md`) Copy Section

layout: default
title: Conversion
permalink: /conversion/
redirect_from:

• /docs/conversion.md/
• /docs/conversion/

Conversion Matrix

• TOC
  {:toc}

This document outlines all possible conversion details regarding compose.yaml values to Kubernetes / OpenShift artifacts.

Version Support Copy Chapter

Under the hood, we're using compose-go, the reference library for parsing Compose files. We should be able to load all versions of Compose files.
We're doing our best to keep it up to date as soon as possible in our releases to be compatible with the latest features defined in the Compose specification. If you absolutely need a feature we don't support yet, please open a PR!

Conversion Table Copy Chapter

Glossary:

• ✓: Converts
• -: Not in this Compose Version
• n: Not yet implemented
• x: Not applicable / no 1-1 conversion

Development (`docs/development.md`) Copy Section

layout: default
permalink: /development/
title: Development
redirect_from:

• /docs/development.md/
• /docs/development/

Development Guide

Building Kompose Copy Chapter

Read about building kompose here.

Workflow Copy Chapter

Fork the main repository Copy Section

1. Go to https://github.com/kubernetes/kompose
2. Click the "Fork" button (at the top right)

Clone your fork Copy Section

The commands below require that you have $GOPATH. We highly recommended you put the Kompose code into your $GOPATH.

git clone https://github.com/$YOUR_GITHUB_USERNAME/kompose.git $GOPATH/src/github.com/kubernetes/kompose
cd $GOPATH/src/github.com/kubernetes/kompose
git remote add upstream 'https://github.com/kubernetes/kompose'

Create a branch and make changes Copy Section

git checkout -b myfeature
# Make your code changes

Keeping your development fork in sync Copy Section

git fetch upstream
git rebase upstream/main

Note: If you have write access to the main repository at github.com/kubernetes/kompose, you should modify your git configuration so that you can't accidentally push to upstream:

git remote set-url --push upstream no_push

Committing changes to your fork Copy Section

git commit
git push -f origin myfeature

Creating a pull request Copy Section

1. Visit https://github.com/$YOUR_GITHUB_USERNAME/kompose.git
2. Click the "Compare and pull request" button next to your "myfeature" branch.
3. Check out the pull request process for more details

Go Modules and dependency management Copy Chapter

Kompose uses Go Modules to manage dependencies.
If you want to introduce changes to dependencies, please ensure that go.mod and go.sum are updated properly.

Updating Kubernetes and OpenShift

Kubernetes version depends on what version is OpenShift using.
OpenShift is using forked Kubernetes to carry some patches.
Currently, it is not possible to use a different Kubernetes version from the version that OpenShift uses.
(for more see comments in go.mod)

Adding CLI tests Copy Section

Kompose CLI tests run kompose convert with compose files, and cross-check the k8s and OpenShift artifacts generated with the template files.

CI Copy Section

For Kompose, we use numerous CI's:

• TravisCI: Unit and CLI tests
• SemaphoreCI: Integration / cluster tests
• Fabric8CI: Secondary integration tests / future cluster tests

Installation (`docs/installation.md`) Copy Section

layout: default
permalink: /installation/
title: Installation
redirect_from:

• /docs/installation.md/
• /docs/installation/

Installation

• TOC
  {:toc}

We have multiple ways to install Kompose. Our preferred (and most up-to-date) method is downloading the binary from the latest GitHub release.

GitHub release Copy Chapter

Kompose is released via GitHub, you can see all current releases on the GitHub release page.

This is the recommended way of installing Kompose.

Linux and macOS:

# Linux
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-linux-amd64 -o kompose

# Linux ARM64
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-linux-arm64 -o kompose

# macOS
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-darwin-amd64 -o kompose

# macOS ARM64
curl -L https://github.com/kubernetes/kompose/releases/download/v1.38.0/kompose-darwin-arm64 -o kompose

chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose

Windows:

Download from GitHub and add the binary to your PATH.

Go Copy Chapter

Installing using go install pulls from the main branch with the latest development changes.

go install github.com/kubernetes/kompose@latest

CentOS Copy Chapter

Kompose is in EPEL (Available in EPEL 7 package repository) CentOS repository.
If you don't have EPEL repository already installed and enabled you can do it by running sudo yum install epel-release

If you have EPEL enabled in your system, you can install Kompose like any other package.

sudo yum -y install kompose

macOS Copy Chapter

On macOS, you can install the latest release via Homebrew or MacPorts.

brew install kompose

Windows Copy Chapter

Kompose can be installed via Chocolatey

choco install kubernetes-kompose

or using winget

winget install Kubernetes.kompose

Docker Copy Chapter

You can build an image from the official repo for Docker or Podman:

docker build -t kompose https://github.com/kubernetes/kompose.git\#main

To run the built image against the current directory, run the following command:

docker run --rm -it -v $PWD:/opt -w /opt kompose kompose convert

Integrations (`docs/integrations.md`) Copy Section

layout: default
permalink: /integrations/
title: Integrations
redirect_from:

• /docs/integrations.md/
• /docs/integrations/

Integrations

• TOC
  {:toc}

There are some projects out there known to use Kompose integrated in some form or another

Kompose UI by Jad Chamoun (ICANN) and Joe Haddad (Anghami) Copy Section

Description: "A web interface to convert Compose files to Kubernetes YAML"

Link: https://github.com/JadCham/komposeui

Kompose Docker Container by Cloudfind Copy Section

Description: "A Docker container for the Kompose translator for compose"

Link: https://github.com/cloudfind/kompose-docker

KPM by CoreOS Copy Section

Description: "KPM is a tool to deploy and manage application stacks on Kubernetes"

Link: https://github.com/coreos/kpm

Docker Image for Adobe Enterprise Manager by Adfinis SyGroup AG Copy Section

Description: "Docker Image for Adobe Enterprise Manager"

Link: https://github.com/adfinis-sygroup/aem-docker/tree/master

Kompose Ansible Playbook by Chris Houseknecht (Red Hat) Copy Section

Description: "Download and unarchive the latest kompose release asset for your OS"

Link: https://github.com/chouseknecht/kompose-install-role

Fabric8 Maven Plugin by Red Hat Copy Section

Description: "Maven is one of the widely used build tools for Java applications. The Fabric8 Maven Plugin is a maven extension that simplifies the deployment of Java applications to Kubernetes or OpenShift clusters.
The main task of this plugin is to build Docker images, generate Kubernetes or OpenShift resource descriptors and run/deploy the application on Kubernetes or OpenShift cluster.
The plugin has a wide range of configuration options. Compose is one of the options to bring up deployments on Kubernetes or OpenShift clusters.
Technically, Fabric8 Maven Plugin processes the external compose.yml file and generates Kubernetes or OpenShift resources via Kompose."

Links:

• Quickstart
• Documentation

Maven Example (`docs/maven-example.md`) Copy Section

layout: default
permalink: /maven-example/
title: Maven Example
redirect_from:

• /docs/maven-example.md/
• /docs/maven-example/

Fabric8 Maven Plugin + Kompose:

Let's deploy a Springboot Java application with Compose file using Fabric8 Maven Plugin to Kubernetes or OpenShift.

Requirements

• Linux or MacOS or Windows
• JDK 1.7+ - JDK Quick Installation Guide
• Maven 3.x+ - Maven Installation Guide
• Kompose - Kompose Installation Guide

1. Clone the example project from GitHub

$ git clone https://github.com/piyush1594/kompose-maven-example.git

Change current directory to kompose-maven-example directory.

$ cd kompose-maven-example

2. Add Fabric8 Maven Plugin to your project

$ mvn io.fabric8:fabric8-maven-plugin:3.5.28:setup

Add the Fabric8 Maven Plugin configuration to pom.xml of project. pom.xml is manifest or deployment descriptor file of a maven project.

3. Install Kompose through Maven

$ mvn fabric8:install

This command installs the kompose on the host.

4. Configure Fabric8 Maven Plugin to use a Compose file

<plugin>
  <groupId>io.fabric8</groupId>
  <artifactId>fabric8-maven-plugin</artifactId>
  <configuration>
    <composeFile>path for docker compose file</composeFile>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>resource</goal>
        <goal>build</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Add the <configuration> and <executions> sections to pom.xml as shown in above pom.xml snippet. Update the <composeFile> to provide the relative path of Compose file from pom.xml

5. Deploy application on Kubernetes or OpenShift

Make sure that Kubernetes/OpenShift cluster or Minikube/Minishift is running. In case, if anything of this is not running, you can run Minishift to test this application by using the following command.

$ minishift start

Below command deploys this application on Kubernetes or OpenShift.

$ mvn fabric8:deploy

Now that your service has been deployed, let's access it by querying pod, service from Kubernetes or OpenShift.

$ oc get pods
NAME                                    READY     STATUS      RESTARTS   AGE
springboot-compose-1-xl0vb       1/1       Running     0          5m
springboot-compose-s2i-1-build   0/1       Completed   0          7m

$ oc get svc
NAME                        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
springboot-compose   172.30.205.137   <none>        8080/TCP   6m

Let's access the Springboot service.

$ minishift openshift service --in-browser springboot-compose
Created the new window in existing browser session.

It will open your application endpoint in default browser.

User Guide (`docs/user-guide.md`) Copy Section

layout: default
permalink: /user-guide/
title: User Guide
redirect_from:

• /docs/user-guide.md/
• /docs/user-guide/

User Guide

Table of contents Copy Chapter

• Kompose conversion example
• CLI Modifications
• Labels
• Restart Policy
• Building and Pushing Images

Kompose Conversion Example Copy Chapter

Kompose has support for two providers: OpenShift and Kubernetes.
You can choose a targeted provider using global option --provider. If no provider is specified, Kubernetes is set by default.

Kubernetes Copy Section

$ kompose --file compose.yaml convert

You can also provide multiple compose files at the same time:

$ kompose -f compose.yaml -f compose.yaml convert

When multiple compose files are provided the configuration is merged. Any configuration that is common will be over ridden by subsequent file.

You can provide your compose files via environment variables as following:

$ COMPOSE_FILE="compose.yaml alternative-compose.yaml" kompose convert

OpenShift Copy Section

$ kompose --provider openshift --file compose.yaml convert

CLI Modifications Copy Chapter

On the command line, you can modify the output of the generated YAML. For example, using alternative controllers such as Replication Controllers objects, Daemon Sets, or Statefulset.

Daemon Set example:

$ kompose convert --controller daemonSet

A full list of these options can be found on kompose convert --help.

Labels Copy Chapter

kompose supports Kompose-specific labels within the compose.yaml file to get you the rest of the way there.

Labels are an important kompose concept as they allow you to add Kubernetes modifications without having to edit the YAML afterwards. For example, adding an init container, or a custom readiness check.

kompose.controller.port.expose Copy Section

services:
  web:
    image: wordpress:latest
    ports:
      - '80:80'
    labels:
      kompose.controller.expose.port: true

kompose.controller.type Copy Section

services:
  web:
    image: wordpress:latest
    ports:
      - '80:80'
    labels:
      kompose.controller.type: deployment

kompose.cronjob.backoff_limit Copy Section

services:
  cron-job:
    image: busybox
    labels:
      kompose.cronjob.backoff_limit: 3

kompose.cronjob.concurrency_policy Copy Section

services:
  periodic-task:
    image: busybox
    labels:
      kompose.cronjob.concurrency_policy: Forbid

kompose.cronjob.schedule Copy Section

services:
  cron-job:
    image: busybox
    labels:
      kompose.cronjob.schedule: "*/5 * * * *"

kompose.hpa.cpu Copy Section

services:
  web:
    image: nginx
    labels:
      kompose.hpa.cpu: 80

kompose.hpa.memory Copy Section

services:
  db:
    image: mysql
    labels:
      kompose.hpa.memory: 512Mi

kompose.hpa.replicas.max Copy Section

services:
  api:
    image: custom-api
    labels:
      kompose.hpa.replicas.max: 10

kompose.hpa.replicas.min Copy Section

services:
  api:
    image: custom-api
    labels:
      kompose.hpa.replicas.min: 2

kompose.image-pull-policy Copy Section

services:
  example-service:
    image: example-image
    labels:
      kompose.image-pull-policy: "IfNotPresent"

kompose.image-pull-secret Copy Section

services:
  private-service:
    image: private-repo/image:tag
    labels:
      kompose.image-pull-secret: "my-private-registry-key"

kompose.init.containers.command Copy Section

services:
  init-service:
    image: busybox
    labels:
      kompose.init.containers.command: ["echo", "Initializing..."]

kompose.init.containers.image Copy Section

services:
  init-service:
    image: busybox
    labels:
      kompose.init.containers.image: busybox

kompose.init.containers.name Copy Section

services:
  init-service:
    image: busybox
    labels:
      kompose.init.containers.name: "initial-setup"

kompose.security-context.fsgroup Copy Section

services:
  secured-service:
    image: nginx
    labels:
      kompose.security-context.fsgroup: 2000

kompose.service.external-traffic-policy Copy Section

services:
  front-end:
    image: quay.io/kompose/web
    ports:
      - 8080:8080
    labels:
      kompose.service.external-traffic-policy: local

kompose.service.expose Copy Section

services:
  web-app:
    image: nginx
    ports:
      - 80:80
    labels:
      kompose.service.expose: "example.com"

kompose.service.expose.ingress-class-name Copy Section

services:
  web:
    image: nginx
    ports:
      - 80:80
    labels:
      kompose.service.expose.ingress-class-name: "nginx"

kompose.service.expose.tls-secret Copy Section

services:
  web:
    image: nginx
    ports:
      - 443:443
    labels:
      kompose.service.expose.tls-secret: "my-ssl-secret"

kompose.service.group Copy Section

version: "3"

services:
  nginx:
    image: nginx
    depends_on:
      - logs
    labels:
      - kompose.service.group=sidecar

  logs:
    image: busybox
    command: ["tail -f /var/log/nginx/access.log"]
    labels:
      - kompose.service.group=sidecar

kompose.service.healthcheck.liveness.http_get_path Copy Section

services:
  web:
    image: custom-web
    ports:
      - "8080:8080"
    labels:
      kompose.service.healthcheck.liveness.http_get_path: /health

kompose.service.healthcheck.liveness.http_get_port Copy Section

services:
  web:
    image: custom-web
    ports:
      - "8080:8080"
    labels:
      kompose.service.healthcheck.liveness.http_get_port: 8080

kompose.service.healthcheck.liveness.tcp_port Copy Section

services:
  db:
    image: mysql
    ports:
      - "3306:3306"
    labels:
      kompose.service.healthcheck.liveness.tcp_port: 3306

kompose.service.healthcheck.readiness.disable Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.disable: true

kompose.service.healthcheck.readiness.http_get_path Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.http_get_path: /ready

kompose.service.healthcheck.readiness.http_get_port Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.http_get_port: 8081

kompose.service.healthcheck.readiness.interval Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.interval: 10s

kompose.service.healthcheck.readiness.retries Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.retries: 3

kompose.service.healthcheck.readiness.start_period Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.start_period: 30s

kompose.service.healthcheck.readiness.tcp_port Copy Section

services:
  db:
    image: mysql
    labels:
      kompose.service.healthcheck.readiness.tcp_port: 3307

kompose.service.healthcheck.readiness.test Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.test: ["CMD", "curl", "-f", "http://localhost:8081/ready"]

kompose.service.healthcheck.readiness.timeout Copy Section

services:
  web:
    image: custom-web
    labels:
      kompose.service.healthcheck.readiness.timeout: 5s

kompose.service.nodeport.port Copy Section

services:
  web:
    image: nginx
    ports:
      - "30000:80"
    labels:
      kompose.service.nodeport.port: 30000

kompose.service.type Copy Section

services:
  web:
    image: nginx
    ports:
      - "80:80"
    labels:
      kompose.service.type: nodeport

kompose.volume.size Copy Section

services:
  db:
    image: postgres:10.1
    labels:
      kompose.volume.size: 1Gi
    volumes:
      - db-data:/var/lib/postgresql/data

kompose.volume.storage-class-name Copy Section

services:
  db:
    image: postgres:10.1
    labels:
      kompose.volume.storage-class-name: custom-storage-class-name
    volumes:
      - db-data:/var/lib/postgresql/data

kompose.volume.subpath Copy Section

services:
  pgadmin:
    image: postgres
    labels:
      kompose.volume.subpath: pg-data

kompose.volume.type Copy Section

services:
  db:
    image: postgres
    labels:
      kompose.volume.type: persistentVolumeClaim
    volumes:
      - db-data:/var/lib/postgresql/data

Restart Policy Copy Chapter

If you want to create normal pods without a controller you can use the restart construct of compose to define that. Follow the table below to see what happens on the restart value.

Note: controller object could be deployment, replicationcontroller, etc.

For example, the pival service will become a pod down here. This container calculated the value of pi.

version: '2'

services:
  pival:
    image: perl
    command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
    restart: "on-failure"

For example, the pival service will become a cron job down here. This container calculated the value of pi every minute.

version: '2'

services:
  pival:
    image: perl
    command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
    restart: "no"
    labels:
      kompose.cronjob.schedule: "* * * * *"
      kompose.cronjob.concurrency_policy: "Forbid"
      kompose.cronjob.backoff_limit: "0"

Warning about Deployment Configs

If the Compose file has a volume specified for a service, the Deployment (Kubernetes) or DeploymentConfig (OpenShift) strategy is changed to "Recreate" instead of "RollingUpdate" (default). This is done to avoid multiple instances of a service from accessing a volume at the same time.

If the Compose file has a service name with _ or . in it (e.g., web_service or web.service), then it will be replaced by - and the service name will be renamed accordingly (e.g., web-service). Kompose does this because "Kubernetes" doesn't allow _ in object names.

Please note that changing the service name might break some compose files.

Building and Pushing Images Copy Chapter

If the Compose file has build or build:context, build:dockerfile keys, build will run when --build specified.

And Image will push to docker.io (default) when --push-image=true specified.

It is possible to push to a custom registry by specifying --push-image-registry, which will override the registry from the image name.

Authentication on Registry Copy Section

Kompose uses the docker authentication from file $DOCKER_CONFIG/config.json, $HOME/.docker/config.json, and $HOME/.dockercfg after docker login.

This only works fine on Linux but macOS would fail when using "credsStore": "osxkeychain".

However, there is an approach to push successfully on macOS, by not using osxkeychain for credsStore. To disable osxkeychain:

• remove credsStore from the config.json file, and docker login again.
• for some docker desktop versions, there is a setting Securely store Docker logins in macOS keychain, which should be unchecked. Then restart docker desktop if needed, and docker login again.

Now config.json should contain base64 encoded passwords, then push image should succeed. Working, but not safe though! Use it at your risk.

For Windows, there is also credsStore which is wincred. Technically it will fail on authentication as macOS does, but you can try the approach above like macOS too.

Custom Build and Push Copy Section

If you want to customize the build and push processes and use another containers solution than Docker,
Kompose offers you the possibility to do that. You can use --build-command and --push-command flags
to achieve that.

e.g: kompose -f convert --build-command 'whatever command --you-use' --push-command 'whatever command --you-use'

Data Dates.Yml (`docs/_data/dates.yml`) Copy Section

• date: "Saturday May 8"
  green: 20
  yellow: 20
  red: 20
• date: "Monday May 17"
  green: 20
  yellow: 20
  red: 20
• date: "Monday May 31"
  green: 20
  yellow: 20
  red: 20
• date: "Monday June 7"
  green: 20
  yellow: 20
  red: 20
• date: "Monday June 14"
  green: 20
  yellow: 20
  red: 20
• date: "Monday June 21"
  green: 20
  yellow: 20
  red: 20
• date: "Monday July 5"
  green: 20
  yellow: 20
  red: 20
• date: "Monday July 19"
  green: 20
  yellow: 20
  red: 20
• date: "Monday July 26"
  green: 20
  yellow: 20
  red: 20
• date: "Monday August 9"
  green: 20
  yellow: 20
  red: 20
• date: "Monday August 16"
  green: 20
  yellow: 20
  red: 20
• date: "Monday August 23"
  green: 20
  yellow: 20
  red: 20
• date: "Monday August 30"
  green: 20
  yellow: 20
  red: 20
• date: "Monday September 13"
  green: 20
  yellow: 20
  red: 20
• date: "Friday September 24"
  green: 20
  yellow: 20
  red: 20
• date: "Monday September 27"
  green: 20
  yellow: 20
  red: 20
• date: "Monday October 4"
  green: 20
  yellow: 20
  red: 20
• date: "Sunday October 10"
  green: 20
  yellow: 20
  red: 20

Data Menu.Yml (`docs/_data/menu.yml`) Copy Section

other_links:
"Installation": "/installation/"
"Getting Started": "/getting-started/"
"User Guide": "/user-guide/"
"Conversion Matrix": "/conversion/"
"Architecture": "/architecture/"

--- METRICS ---

• Files Extracted: 18
• Estimated Token Budget: ~19092 tokens
• Canonical Reference: https://codewiki.google/github.com/kubernetes/kompose