From 931fd4406ed7b8d1699dcbc3f9b8583bd740e655 Mon Sep 17 00:00:00 2001 From: Stan Lagun Date: Tue, 1 Dec 2015 13:24:44 +0300 Subject: [PATCH] [Docker] Docker applications developer reference Change-Id: I90e9f5ab67829fd4c9dd6256ed835a458da692eb --- DockerInterfacesLibrary/README.rst | 205 +++++++++++++++++++++++++++++ README.rst | 29 ++++ 2 files changed, 234 insertions(+) create mode 100644 DockerInterfacesLibrary/README.rst create mode 100644 README.rst diff --git a/DockerInterfacesLibrary/README.rst b/DockerInterfacesLibrary/README.rst new file mode 100644 index 0000000..ba965da --- /dev/null +++ b/DockerInterfacesLibrary/README.rst @@ -0,0 +1,205 @@ +Docker Interface Library +======================== + +This library provides 3 major things: + +* DockerApplication: base class that all Docker applications must inherit. + Provides a way to define image name and docker container parameters. + +* DockerContainerHost: interface for applications that provide Docker + application hosting capabilities. Docker applications use this interface + to deploy themselves on the Docker host. + +* Data structures that are pass between DockerApplications and + DockerContainerHosts. They define things like volumes, ports etc. + Most important data structure is DockerContainer which describes the + container itself. + + +DockerApplication +================= + +This is the base class for all Docker applications. At minimum all inheritors +must provide an implementation of `getContainer` method. Everything else is +either optional or implemented in the base class. + +It has the following properties: + +* `host`: an instance of `DockerContainerHost`. This is the hosting provider + (`DockerStandaloneHost`, `KubernetesPod`, etc.) that applications should + be deployed to. + +* `applicationEndpoints`: output property that is filled with application + endpoints after deployment. See below for exact format details. + +Class also has the following methods: + +* `getContainer`: returns an instance of `DockerContainer` class that describes + container information. Alternatively method can return a properties + dictionary that would automatically be converted to `DockerContainer` by + MuranoPL. This method must be implemented by inheritors! + +* `deploy`: used to deploy Docker application on given `DockerContainerHost`. + This method is already implemented in this class and should not be overridden + by inheritors. It relies on the information returned by `getContainer`. + +* `getConnectionTo`: used to get full endpoint for another Docker application's + port when there is a need to connect two Docker applications. + Requires three parameters: + + * `application`: an instance of `DockerApplication` that we want to + talk to. + * `port`: port number of the target application. + * `protocol`: `TCP` or `UDP`. + + Returns a dictionary with two keys - `host` and `port` that represent the + endpoint. Note that target application must be deployed before calling this + method so it is advised to call `deploy()` first. + + See `DockerGrafana/DockerInfluxDB` as an example or connected Docker + applications. + +* `onInstallationStart`: a method that get get called when installation starts. + May be overridden by inheritor class to provide extra logging or reporting. + +* `onInstallationFinish`: a method that get get called when installation ends. + May be overridden by inheritor class to provide extra logging or reporting. + + +DockerContainer +=============== + +This is a data structure defining a Docker container. + +It has the following properties: + +* `name`: container name. Must be unique within single `DockerContainerHost`. + This is the same as application name for regular + applications. + +* `image`: Docker image name. + +* `commands`: optional list of shell commands to execute upon container start. + +* `env`: a dictionary of environment key-values (inputs for Docker containers) + +* `ports`: a list of `ApplicationPort` instances. This is a list of ports that + need to be opened/exposed by the container. + +* `volumes`: an optional mapping that defines volumes that need to be mounted + into Docker container. Keys are the paths within container and values are + instances of DockerVolume. + + +ApplicationPort +=============== + +Defines a network port that need to be exposed by the application. +This is a structure with three properties: + +* `port`: port number + +* `protocol`: `TCP` or `UDP` + +* `scope`: one of `public`, `cloud`, `host` or `internal`. + This property specifies the scope of port visibility: within the single + docker instance (on single server) - `host`, within single + `DockerContainerHost` - `internal`, single OpenStack cloud - `cloud` + or `public` for ports that are bind to public floating IP. + + + +DockerVolume +============ + +Represents base class for Docker volumes. One of the two inheritors must be +used: + +* `DockerTempVolume`: temporary storage space + +* `DockerHostVolume`: a directory on the host machine that is mounted inside + container. The path on host server is specified by the `path` property + of `DockerHostVolume`. + + +DockerContainerHost +=================== + +Defines an interface that all applications capable of hosting Docker +applications must implement. Currently there are two implementations of this +interface: `DockerStandaloneHost` and `KubernetesPod`. + +It has the following property: + +* `name`: name of the application instance. + +It also has the following methods: + +* `hostContainer`: Docker applications call this method to register Docker + containers on the Docker host during deployment. It accepts single argument - + `container` - an instance of DockerContainer class. + + `deleteContainer`: deletes container from Docker host. Container is + identified by its name through `name` parameter. + + `getEndpoints`: returns a list of endpoints for specified Docker container + Container is identified by its name through `applicationName` parameter. + See below on endpoint format specification. + + `getInternalScopeId`: returns an common identifier for all Docker hosts + belonging to the same container manager (host aggregation used to group + together endpoints of `internal` scope. + + +Endpoint representation +======================= + +Docker container hosts are responsible for management of application +endpoints. Application define what ports they want to expose and what +should be the scope of visibility for those ports. It is up to the host +to map those ports to ports on hosting server and OpenStack floating IPs. + +Single port on the container might be accesses in different ways. +It usually it may be accessed using 127.0.0.1 address from other containers +on the same server, using internal IP from containers on the same cluster, +using internal OpenStack server IP from other servers in the same environment +or using floating IP for external access. Scope defines maximum level of +visibility in the order `host` -> `internal` -> `cloud` -> `public`. +Each subsequent scope extends the visibility for the previous one. So if +the application wants a `public` endpoint for its port the host allocates four +endpoints for that port starting from 127.0.0.1:port to access it from the +same server and up to FIP:port to access it from the Internet. Thus +each port/protocol pair results in 1-4 entries in `applicationEndpoints` list. + +Each entry of that list is a dictionary that has the following keys: + +* `address`: IP or hostname. +* `port`: port number that caller must use to access the application. +* `scope`: greatest visibility scope name for the endpoint. +* `portScope`: scope name for the port endpoint was allocated for. For example + if `ApplicationPort` had a 'local` scope then two endpoints will be allocated + (`host` and `local` and each of them will have `local` in `portScope`). +* `containerPort`: port number inside the container. +* `protocol`: `TCP` or `UDP`. There can be two endpoints with the same port + number that differ only in protocol. + + +Tips on Docker applications development +======================================= + +* MuranoPL can automatically convert dictionaries to an instances of + appropriate class when passing it as an input to a function that has + proper class() contract on that value. Thus in most cases data structures + can be represented as a dictionaries of property name->value form rather + than as MuranoPL objects (thus no need to use new() function to construct + them) + +* Use `getConnectionTo` method of DockerApplication to get endpoint to + access one docker application from another. If application A wants to talk + to application B then this method is called on A with an information about + what port of B it requires. The method is smart enough to return the nearest + endpoint. This if both A and B are located on the same server returned + endpoint will likely to have 127.0.0.1 as an address. + +* Call deploy() on dependent applications before retrieving endpoints or + obtaining connections to it. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b799884 --- /dev/null +++ b/README.rst @@ -0,0 +1,29 @@ +Docker support for Murano +========================= + +Docker is an open-source project that automates the deployment of applications +inside software containers. Docker containers could be run either by the +Docker itself or by container management platforms that built on top of the +Docker and provide extra value to schedule and manage containers on multiple +hosts. + + +This folder contains needed abstractions and applications to develop and +run Docker applications: + +* DockerInterfaceLibrary: library that defines a framework for building Docker + applications. It provides set of common interfaces and data structures + that are used by all Docker applications and Docker hosting services. + If you want to develop your own Docker application this is a good place to + start. See DockerInterfaceLibrary/README.rst for more details. + +* DockerStandaloneHost: a regular Docker host. Docker containers are run on + a dedicated VM running docker software (require pre-built image with + docker and murano-agent). + +* Kubernetes: an open source container cluster manager by Google. It allows + to schedule and run Docker applications on multiple clustered nodes. + Application both installs Kubernetes and provides capabilities to run + Docker applications similar to DockerStandaloneHost. + +* Applications: Examples of some of the most popular Docker applications.