modules/containers.mdtext - aries-antora-site - Git at Google

 Title: Aries Containers

 # Aries Containers
 Aries Containers is a project to manage container deployment, such as docker containers, from a Java API.

 Many technologies exist to manage container deployments. Examples include Kubernetes, Marathon/Mesos, Docker Swarm, Amazon ECS
 and others. While each technology provides specific features, many of these management technologies share common behaviour.
 Aries Containers provides an abstraction that allows users to easily switch between these technologies.

 Benefits:

   - Requirements change - container users may find that they need to change target platforms at short notice. Using an abstraction API
 helps making such changes without too much additional work.
   - Testing - many container management systems require cluster of machines or otherwise large setup which may make testing during
 development difficult. Aries Containers also contains a `docker.local` binding which makes it possible to run the same code with a different
 binding on a local developer machine, as long as docker is installed there.

 Current modules:

   - `containers-api` - the API implemented by the various bindings.
   - `containers-docker-local` - Binding that uses the local docker installation.
   - `containers-marathon` - Marathon binding.
   - `containers-parent` - Parent pom.
   - `containers-examples` - Examples.
   - ...

 This project may be used as input to the design process of the [OSGi RFP 179][1].

 # Source
 The Aries RSA source is in a separate [git repository aries-containers][2] there is also a [mirror on github][3].

 To build the source, just run:

 `mvn install`

 Java 1.8 or higher is required. Maven 3.3.9+ is recommended.

 # Quick Start
 The easiest way to get started is with the examples and the local docker binding. Aries Containers work well in an OSGi
 environment where bindings are provided as OSGi services.

 As an alternative, Aries Containers can also be used in a plain Java environment. Instead of obtaining the bindings
 from the service registry, they need to be instantiated directly in this case.

 This quick start focuses on a number of examples to suit your environment.

 ## OSGi example

 The OSGi example uses the Felix SCR implementation to get the currently active ServiceManager injected into a simple servlet.
 The servlet provides a simple UI to perform some of the management operations.

 The servlet is written using OSGi Declarative Service annotations and OSGi Http Whiteboard annotations and can be found here:
 [ServiceManagerServlet.java][4]

 Main part of the functionality of the servlet can be summarized as follows:

     @Component(service = Servlet.class,
         property = {HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN + "=/manager"})
     public class ServiceManagerServlet extends HttpServlet {

     @Reference
     ServiceManager serviceManager;

     @Override
     protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
         PrintWriter pw = resp.getWriter();
         pw.println("<BODY><H1>Service Deployments</H1>");

         pw.println("<UL>");
         for (String dep : serviceManager.listServices()) {
             pw.println("<LI>" + dep);
         }

 In short - an OSGi Declarative Service Component is registered as a HTTP Whiteboard Servet. The Aries Containers Service Manager is
 injected into the `serviceManager` field and then used in the servlet to manage the deployment.


 TODO: Describe how to run the servlet using a small Felix setup.

 ## Plain Java example

 This example launches a small Java Application to create a service deployment. Initially a single container is deployed. The user can
 modify the number of replicas using the application.

 The code can be found here: [Main.java][5]

 The main functionality is:


             ServiceManager sm = new LocalDockerServiceManager();

             // If you want to run with Marathon, use the following line
             // ServiceManager sm = new MarathonServiceManager("http://192.168.99.100:8080/");

             ServiceConfig sc = ServiceConfig.builder("mytesthttpd", "httpd").
                 cpu(0.2).memory(32).port(80).build();
             Service svc = sm.getService(sc);
             // The service is now created

 If you are running this the Docker local binding, you can see the docker container created:

     $ docker ps
     CONTAINER ID        IMAGE               COMMAND              STATUS              PORTS                   NAMES
     7cc5c753777e        httpd               "httpd-foreground"   Up 4 seconds        0.0.0.0:51467->80/tcp   mytesthttpd

 The example also allows scaling up and down of replica containers for this service.

 #Bindings

 ##Docker Local

 This binding works by issuing `docker` commands on the local machine and is very useful for testing. Make sure the environment
 variables normally provided via `docker-machine env <myenv>` are set.

 OSGi ServiceManager identifier: `container.factory.binding = docker.local`

 Constructor, for use outside of OSGi: `org.apache.aries.containers.docker.local.impl.LocalDockerServiceManager`

 ##Marathon

 This binding uses Marathon as the underlying container manager. It requires the following configuration to be set:

     service.pid: org.apache.aries.containers.marathon
       marathon.url=<the URL where marathon can be contacted>

 Once configured, the Marathon binding will register its OSGi service.
 OSGi ServiceManager identifier: `container.factory.binding = marathon`

 Constructors, for use outside of OSGi: `org.apache.aries.containers.marathon.impl.MarathonServiceManager`

     /**
      * Create the Marathon Service Manager.
      *
      * @param marathonURL The Marathon URL
      */
     public MarathonServiceManager(String marathonURL);

     /**
      * Create the Marathon Service Manager for use with DC/OS.
      *
      * @param marathonURL The Marathon URL.
      * @param dcosUser The DCOS user or service-user.
      * @param passToken The password or token to use.
      * @param serviceAcct `true` if this is a service account `false` if this is a plain user.
      */
     public MarathonServiceManager(String marathonURL, String dcosUser, String passToken, boolean serviceAcct);


   [1]: https://github.com/osgi/design/blob/master/rfps/rfp-0179-ComputeManagementService.pdf
   [2]: https://git-wip-us.apache.org/repos/asf/aries-containers.git
   [3]: https://github.com/apache/aries-containers
   [4]: https://git-wip-us.apache.org/repos/asf?p=aries-containers.git;a=blob;f=containers-examples/containers-example-osgiservlet/src/main/java/org/apache/aries/containers/examples/osgiservlet/ServiceManagerServlet.java;h=5783718d0ba80a612cf44a331a45aefeb6e71ebf;hb=HEAD
   [5]: https://git-wip-us.apache.org/repos/asf?p=aries-containers.git;a=blob;f=containers-examples/containers-example-javaapp/src/main/java/org/apache/aries/containers/examples/javaapp/Main.java;h=0f06a304fc5ec96ce3f50e6af338b5b320d901d1;hb=HEAD
	Title: Aries Containers

	# Aries Containers
	Aries Containers is a project to manage container deployment, such as docker containers, from a Java API.

	Many technologies exist to manage container deployments. Examples include Kubernetes, Marathon/Mesos, Docker Swarm, Amazon ECS
	and others. While each technology provides specific features, many of these management technologies share common behaviour.
	Aries Containers provides an abstraction that allows users to easily switch between these technologies.

	Benefits:

	- Requirements change - container users may find that they need to change target platforms at short notice. Using an abstraction API
	helps making such changes without too much additional work.
	- Testing - many container management systems require cluster of machines or otherwise large setup which may make testing during
	development difficult. Aries Containers also contains a `docker.local` binding which makes it possible to run the same code with a different
	binding on a local developer machine, as long as docker is installed there.

	Current modules:

	- `containers-api` - the API implemented by the various bindings.
	- `containers-docker-local` - Binding that uses the local docker installation.
	- `containers-marathon` - Marathon binding.
	- `containers-parent` - Parent pom.
	- `containers-examples` - Examples.
	- ...

	This project may be used as input to the design process of the [OSGi RFP 179][1].

	# Source
	The Aries RSA source is in a separate [git repository aries-containers][2] there is also a [mirror on github][3].

	To build the source, just run:

	`mvn install`

	Java 1.8 or higher is required. Maven 3.3.9+ is recommended.

	# Quick Start
	The easiest way to get started is with the examples and the local docker binding. Aries Containers work well in an OSGi
	environment where bindings are provided as OSGi services.

	As an alternative, Aries Containers can also be used in a plain Java environment. Instead of obtaining the bindings
	from the service registry, they need to be instantiated directly in this case.

	This quick start focuses on a number of examples to suit your environment.

	## OSGi example

	The OSGi example uses the Felix SCR implementation to get the currently active ServiceManager injected into a simple servlet.
	The servlet provides a simple UI to perform some of the management operations.

	The servlet is written using OSGi Declarative Service annotations and OSGi Http Whiteboard annotations and can be found here:
	[ServiceManagerServlet.java][4]

	Main part of the functionality of the servlet can be summarized as follows:

	@Component(service = Servlet.class,
	property = {HttpWhiteboardConstants.HTTP_WHITEBOARD_SERVLET_PATTERN + "=/manager"})
	public class ServiceManagerServlet extends HttpServlet {

	@Reference
	ServiceManager serviceManager;

	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
	PrintWriter pw = resp.getWriter();
	pw.println("<BODY><H1>Service Deployments</H1>");

	pw.println("<UL>");
	for (String dep : serviceManager.listServices()) {
	pw.println("<LI>" + dep);
	}

	In short - an OSGi Declarative Service Component is registered as a HTTP Whiteboard Servet. The Aries Containers Service Manager is
	injected into the `serviceManager` field and then used in the servlet to manage the deployment.




	TODO: Describe how to run the servlet using a small Felix setup.

	## Plain Java example

	This example launches a small Java Application to create a service deployment. Initially a single container is deployed. The user can
	modify the number of replicas using the application.

	The code can be found here: [Main.java][5]

	The main functionality is:


	ServiceManager sm = new LocalDockerServiceManager();

	// If you want to run with Marathon, use the following line
	// ServiceManager sm = new MarathonServiceManager("http://192.168.99.100:8080/");

	ServiceConfig sc = ServiceConfig.builder("mytesthttpd", "httpd").
	cpu(0.2).memory(32).port(80).build();
	Service svc = sm.getService(sc);
	// The service is now created

	If you are running this the Docker local binding, you can see the docker container created:

	$ docker ps
	CONTAINER ID IMAGE COMMAND STATUS PORTS NAMES
	7cc5c753777e httpd "httpd-foreground" Up 4 seconds 0.0.0.0:51467->80/tcp mytesthttpd

	The example also allows scaling up and down of replica containers for this service.

	#Bindings

	##Docker Local

	This binding works by issuing `docker` commands on the local machine and is very useful for testing. Make sure the environment
	variables normally provided via `docker-machine env <myenv>` are set.

	OSGi ServiceManager identifier: `container.factory.binding = docker.local`

	Constructor, for use outside of OSGi: `org.apache.aries.containers.docker.local.impl.LocalDockerServiceManager`

	##Marathon

	This binding uses Marathon as the underlying container manager. It requires the following configuration to be set:

	service.pid: org.apache.aries.containers.marathon
	marathon.url=<the URL where marathon can be contacted>

	Once configured, the Marathon binding will register its OSGi service.
	OSGi ServiceManager identifier: `container.factory.binding = marathon`

	Constructors, for use outside of OSGi: `org.apache.aries.containers.marathon.impl.MarathonServiceManager`

	/**
	* Create the Marathon Service Manager.
	*
	* @param marathonURL The Marathon URL
	*/
	public MarathonServiceManager(String marathonURL);

	/**
	* Create the Marathon Service Manager for use with DC/OS.
	*
	* @param marathonURL The Marathon URL.
	* @param dcosUser The DCOS user or service-user.
	* @param passToken The password or token to use.
	* @param serviceAcct `true` if this is a service account `false` if this is a plain user.
	*/
	public MarathonServiceManager(String marathonURL, String dcosUser, String passToken, boolean serviceAcct);


	[1]: https://github.com/osgi/design/blob/master/rfps/rfp-0179-ComputeManagementService.pdf
	[2]: https://git-wip-us.apache.org/repos/asf/aries-containers.git
	[3]: https://github.com/apache/aries-containers
	[4]: https://git-wip-us.apache.org/repos/asf?p=aries-containers.git;a=blob;f=containers-examples/containers-example-osgiservlet/src/main/java/org/apache/aries/containers/examples/osgiservlet/ServiceManagerServlet.java;h=5783718d0ba80a612cf44a331a45aefeb6e71ebf;hb=HEAD
	[5]: https://git-wip-us.apache.org/repos/asf?p=aries-containers.git;a=blob;f=containers-examples/containers-example-javaapp/src/main/java/org/apache/aries/containers/examples/javaapp/Main.java;h=0f06a304fc5ec96ce3f50e6af338b5b320d901d1;hb=HEAD