[Docker] Docker applications developer reference
Change-Id: I90e9f5ab67829fd4c9dd6256ed835a458da692eb
This commit is contained in:
Stan Lagun
parent
e70a09f6e7
commit
3eee90646d
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue