github.com/docker/compose-on-kubernetes@v0.5.0/docs/architecture.md (about)

     1  # Architecture
     2  
     3  Compose on Kubernetes is made up of server-side and client-side components. This
     4  architecture was chosen so that the entire life cycle of a stack can be managed.
     5  The following image is a high-level diagram of the architecture:
     6  
     7  ![Compose on Kubernetes architecture](./images/architecture.jpg)
     8  
     9  The REST API is provided by a custom API server exposed to Kubernetes clients
    10  using [API server aggregation](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#api-server-aggregation).
    11  
    12  The client communicates with the server using a declarative REST API. It creates
    13  a stack by either POSTing a serialized stack struct (v1beta2) or a Compose file
    14  (v1beta1) to the API server. This API server stores the stack in an etcd
    15  key-value store.
    16  
    17  The REST API is declarative meaning that the stack stored in etcd is considered
    18  the desired state. The Compose controller is responsible for breaking the stack
    19  up into Kubernetes components, reconciling the current cluster state with the
    20  desired state, and aggregating the stack status.
    21  
    22  ## Server-side architecture
    23  
    24  There are two server-side components in Compose on Kubernetes: the Compose API
    25  server, and the Compose controller.
    26  
    27  The Compose API server extends the Kubernetes API by adding routes for creating
    28  and manipulating stacks. It is responsible for storing the stacks in an etcd
    29  key-value store. It also contains the logic to convert v1beta1 representations
    30  to v1beta2, so that the Compose controller only needs to work one representation
    31  of a stack.
    32  
    33  The Compose controller is responsible for converting a stack struct (v1beta2
    34  schema) into Kubernetes objects and then reconciling the current cluster state
    35  with the desired one. It does this by interacting with the Kubernetes API -- it
    36  is a Kubernetes client that watches for interesting events and manipulates lower
    37  level Kubernetes objects.
    38  
    39  ### API server
    40  
    41  While API aggregation is more complex than a CRD (Custom Resource Definition),
    42  it brings much more flexibiliy. This includes but is not limited to:
    43  subresources, non-trivial validation, and user identity recording. Instead of
    44  relying on Kubernetes to create the API endpoints and logic for storing and
    45  manipulating stack objects, Compose on Kubernetes deploys a custom API server to
    46  do this. As part of the install process, the component is registered with the
    47  Kubernetes API server for API aggregation so that it is forwarded all requests
    48  on the `compose.docker.com/` group route.
    49  
    50  ### Compose controller
    51  
    52  The Compose controller fetches the desired stack from the API server. This
    53  struct is then cut up into Kubernetes resources which the controller creates and
    54  manipulates through the Kubernetes API server. The mapping for this can be found
    55  in [mapping.md](./mapping.md).
    56  
    57  The API server also records user identity, group membership and claims on stack
    58  creations and updates, and exposes them as a subresource. The Controller
    59  consumes this subresource to impersonate this user, to create Kubernetes objects
    60  with the user identity.
    61  
    62  ## Client-side architecture
    63  
    64  The code for the Docker CLI implementation of the client can be found [here](https://github.com/docker/cli/tree/master/kubernetes/compose).
    65  
    66  ### v1beta1
    67  
    68  The v1beta1 API requires that the client uploads a Compose file to describe the
    69  stack. This was used in early versions of Compose on Kubernetes and is used by
    70  Docker Enterprise 2.0.
    71  
    72  In the medium-term, we aim to deprecate this API.
    73  
    74  ### v1beta2
    75  
    76  The v1beta2 API requires that the client parses the Compose file and uploads a
    77  stack struct. This is used by the Docker CLI by default.