Skip to content
Permalink
Browse files

Merge pull request #14 from simonferquel/docs

Add first batch of documentation
  • Loading branch information
simonferquel committed Dec 7, 2018
2 parents 9aecee9 + e197650 commit b2e3a6b653077a8b9de0f9588fac540bc6d30a0d
Showing with 420 additions and 0 deletions.
  1. +77 −0 docs/architecture.md
  2. +132 −0 docs/compatibility.md
  3. BIN docs/images/architecture.jpg
  4. +211 −0 docs/mapping.md
@@ -0,0 +1,77 @@
# Architecture

Compose on Kubernetes is made up of server-side and client-side components. This
architecture was chosen so that the entire life cycle of a stack can be managed.
The following image is a high-level diagram of the architecture:

![Compose on Kubernetes architecture](./images/architecture.jpg)

The REST API is provided by a custom API server exposed to Kubernetes clients
using [API server aggregation](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#api-server-aggregation).

The client communicates with the server using a declarative REST API. It creates
a stack by either POSTing a serialized stack struct (v1beta2) or a Compose file
(v1beta1) to the API server. This API server stores the stack in an etcd
key-value store.

The REST API is declarative meaning that the stack stored in etcd is considered
the desired state. The Compose controller is responsible for breaking the stack
up into Kubernetes components, reconciling the current cluster state with the
desired state, and aggregating the stack status.

## Server-side architecture

There are two server-side components in Compose on Kubernetes: the Compose API
server, and the Compose controller.

The Compose API server extends the Kubernetes API by adding routes for creating
and manipulating stacks. It is responsible for storing the stacks in an etcd
key-value store. It also contains the logic to convert v1beta1 representations
to v1beta2, so that the Compose controller only needs to work one representation
of a stack.

The Compose controller is responsible for converting a stack struct (v1beta2
schema) into Kubernetes objects and then reconciling the current cluster state
with the desired one. It does this by interacting with the Kubernetes API -- it
is a Kubernetes client that watches for interesting events and manipulates lower
level Kubernetes objects.

### API server

While API aggregation is more complex than a CRD (Custom Resource Definition),
it brings much more flexibiliy. This includes but is not limited to:
subresources, non-trivial validation, and user identity recording. Instead of
relying on Kubernetes to create the API endpoints and logic for storing and
manipulating stack objects, Compose on Kubernetes deploys a custom API server to
do this. As part of the install process, the component is registered with the
Kubernetes API server for API aggregation so that it is forwarded all requests
on the `compose.docker.com/` group route.

### Compose controller

The Compose controller fetches the desired stack from the API server. This
struct is then cut up into Kubernetes resources which the controller creates and
manipulates through the Kubernetes API server. The mapping for this can be found
in [mapping.md](./mapping.md).

The API server also records user identity, group membership and claims on stack
creations and updates, and exposes them as a subresource. The Controller
consumes this subresource to impersonate this user, to create Kubernetes objects
with the user identity.

## Client-side architecture

The code for the Docker CLI implementation of the client can be found [here](https://github.com/docker/cli/tree/master/kubernetes/compose).

### v1beta1

The v1beta1 API requires that the client uploads a Compose file to describe the
stack. This was used in early versions of Compose on Kubernetes and is used by
Docker Enterprise 2.0.

In the medium-term, we aim to deprecate this API.

### v1beta2

The v1beta2 API requires that the client parses the Compose file and uploads a
stack struct. This is used by the Docker CLI by default.
@@ -0,0 +1,132 @@
# Natively support Compose files on Kubernetes

These are the Compose file features supported on Kubernetes

| Feature | docker stack deploy | Compose on Kubernetes |
|----------------------------|---------------------|------------------------|
| build | | |
| - context | | |
| - dockerfile | | |
| - args | | |
| - cache_from | | |
| - labels | | |
| cap_add | | Yes |
| cap_drop | | Yes |
| command | Yes | Yes |
| configs | Yes | Yes |
| - external | Yes | Yes |
| - file | Yes | Yes |
| - mode | Yes | Yes |
| cgroup_parent | | |
| container_name | | |
| credential_spec | Yes | |
| deploy | Yes | |
| - endpoint_mode: vip | Yes | Yes |
| - endpoint_mode: dnsrr | Yes | |
| - labels | Yes | Yes |
| - mode | Yes | Yes |
| - placement | Yes | Partial |
| - replicas | Yes | Yes |
| - resources | Yes | Yes |
| -- limits | Yes | Yes |
| -- reservations | Yes | Yes |
| - restart_policy | Yes | Yes |
| -- condition: none | Yes | Yes |
| -- condition: on-failure | Yes | Yes |
| -- condition: any | Yes | Yes |
| -- delay | Yes | |
| -- max_attempts | Yes | |
| -- window | Yes | |
| - update_config | Yes | |
| -- parallelism | Yes | Yes |
| -- delay | Yes | |
| -- failure_action | Yes | |
| -- monitor | Yes | |
| -- max_failure_ratio | Yes | |
| - devices | | |
| - depends_on | | |
| - dns | | |
| - dns_search | | |
| - tmpfs | | Yes |
| - entrypoint | Yes | Yes |
| - env_file | Yes | Yes |
| - environment | Yes | Yes |
| -- key=value | Yes | Yes |
| -- key | Yes | |
| - expose | Yes | Yes |
| - external_links | | |
| - extra_hosts | Yes | Yes |
| - healthcheck | Yes | Yes |
| -- test | Yes | Yes |
| -- test: NONE | Yes | Yes |
| -- interval | Yes | Yes |
| -- timeout | Yes | Yes |
| -- retries | Yes | Yes |
| -- disable | Yes | Yes |
| - image | Yes | Yes |
| - isolation | Yes | |
| - labels | Yes | Yes |
| - links | | |
| - logging | Yes | |
| -- driver | Yes | |
| -- options | Yes | |
| - network_mode | | |
| - networks | Yes | |
| -- aliases | Yes | |
| -- ipv4_address | Yes | |
| -- ipv6_address | Yes | |
| - pid: host | Yes | Yes |
| - ports | Yes | Yes |
| -- target | Yes | Yes |
| -- published | Yes | Yes |
| -- protocol | Yes | Yes |
| -- mode: host | Yes | Not sure |
| -- mode: ingress | Yes | Not sure |
| - secrets | Yes | Yes |
| -- source | Yes | Yes |
| -- target | Yes | Yes |
| -- uid | Yes | |
| -- gid | Yes | |
| -- mode | Yes | Yes |
| - security_opt | | |
| - stop_grace_period | Yes | Yes |
| - stop_signal | | |
| - sysctls | | |
| - ulimits | | |
| - userns_mode | | |
| - volumes | Yes | Yes |
| -- type: volume | Yes | Yes |
| -- type: bind | Yes | Yes |
| -- source | Yes | Yes |
| -- target | Yes | Yes |
| -- read_only | Yes | Yes |
| -- bind/propagation | Yes | |
| -- volume/nocopy | Yes | |
| - restart | | |
| - domainname | | |
| - hostname | Yes | Yes |
| - ipc | | Yes |
| - mac_address | | |
| - privileged | | Yes |
| - read_only | Yes | Yes |
| - shm_size | | |
| - stdin_open | Yes | Yes |
| - tty | Yes | Yes |
| - user: numerical | Yes | Yes |
| - user: name | Yes | |
| - working_dir | Yes | Yes |

# Not supported by k8s

+ mac_address (https://github.com/kubernetes/kubernetes/issues/2289)
+ shm_size (https://github.com/kubernetes/kubernetes/issues/28272)
+ ulimits (https://github.com/kubernetes/kubernetes/issues/3595)
+ non numerical user

# Placeholders interpolation

Before a yaml file is sent to Kubernenetes, its `${...}` placeholders
are replaced with actual values.
+ A first attempt is made at reading the variable from a `.env` file is
current working directory.
+ If no value is found, an environment variable are used.
Binary file not shown.

0 comments on commit b2e3a6b

Please sign in to comment.
You can’t perform that action at this time.