This is an automated email from the ASF dual-hosted git repository.
grag pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mesos.git
The following commit(s) were added to refs/heads/master by this push:
new b24ab0a Added documentation about standalone containers.
b24ab0a is described below
commit b24ab0a97e0043cb4a06624f7593dec9e15f5661
Author: Joseph Wu <jos...@mesosphere.io>
AuthorDate: Mon Sep 9 10:37:57 2019 -0700
Added documentation about standalone containers.
This outlines some of the differences to expect from this
new type of container and shows some example API calls.
Review: https://reviews.apache.org/r/65112/
---
docs/csi.md | 2 +-
docs/home.md | 1 +
docs/standalone-containers.md | 202 ++++++++++++++++++++++++++++++++++++++++++
3 files changed, 204 insertions(+), 1 deletion(-)
diff --git a/docs/csi.md b/docs/csi.md
index 4a83581..aa03175 100644
--- a/docs/csi.md
+++ b/docs/csi.md
@@ -80,7 +80,7 @@ More details about SLRP can be found in the following
[section](#storage-local-r
CSI plugins are long-running [gRPC](https://grpc.io/) services, like daemons.
Those CSI plugins are packaged as containers, and are launched by SLRPs using
-the [standalone containers](standalone-container.md) API from the agent.
+the [standalone containers](standalone-containers.md) API from the agent.
Standalone containers can be launched without any tasks or executors. They use
the same isolation mechanism provided by the agent for task and executor
containers.
diff --git a/docs/home.md b/docs/home.md
index ad19919..4e62b4a 100644
--- a/docs/home.md
+++ b/docs/home.md
@@ -59,6 +59,7 @@ layout: documentation
* [Container Sandboxes](sandbox.md)
* [Container Volumes](container-volume.md)
* [Nested Container and Task Group (Pod)](nested-container-and-task-group.md)
+* [Standalone Containers](standalone-containers.md)
## Networking
* [Networking Overview](networking.md)
diff --git a/docs/standalone-containers.md b/docs/standalone-containers.md
new file mode 100644
index 0000000..1e1e306
--- /dev/null
+++ b/docs/standalone-containers.md
@@ -0,0 +1,202 @@
+---
+title: Apache Mesos - Standalone Containers
+layout: documentation
+---
+
+# Standalone Containers
+
+Traditionally, launching a container in a Mesos cluster involves
+communication between multiple components:
+
+```
+ Container(s)
+ +-----------+ +--------+ +-------+ +----------+
+ | Framework | <-> | Master | <-> | Agent | <-> | Executor |
+ +-----------+ +--------+ +-------+ | `->Task |
+ ^ +----------+
+ | +-------+ +----------+
+ +------> | Agent | <-> | Executor |
+ | +-------+ | `->Task |
+ ... +----------+
+```
+
+Mesos 1.5 introduced "Standalone Containers", which provide an alternate
+path for launching containers with a reduced scope and feature set:
+
+```
+ +-------+ +----------------------+
+ Operator API <-> | Agent | -> | Standalone Container |
+ +-------+ +----------------------+
+```
+
+**NOTE:** Agents currently require a connection to a Mesos master in
+order to accept any Operator API calls. This limitation is not necessary
+and may be fixed in future.
+
+**NOTE:** Standalone containers only apply to the Mesos containerizer.
+For standalone docker containers, use docker directly.
+
+As hinted by the diagrams, standalone containers are launched on single
+Agents, rather than cluster-wide. This document describes the major
+differences between normal containers and standalone containers; and
+provides some examples of how to use the new Operator APIs.
+
+
+## Launching a Standalone Container
+
+Because standalone containers are launched directly on Mesos Agents,
+these containers do not participate in the Mesos Master's offer cycle.
+This means standalone containers can be launched regardless of resource
+allocation and can potentially overcommit the Mesos Agent, but cannot
+use reserved resources.
+
+An Operator API might look like this:
+
+```
+LAUNCH_CONTAINER HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: agenthost:5051
+Content-Type: application/json
+
+{
+ "type": "LAUNCH_CONTAINER",
+ "launch_container": {
+ "container_id": {
+ "value": "my-standalone-container-id"
+ },
+ "command": {
+ "value": "sleep 100"
+ },
+ "resources": [
+ {
+ "name": "cpus",
+ "scalar": { "value": 2.0 },
+ "type": "SCALAR"
+ },
+ {
+ "name": "mem",
+ "scalar": { "value": 1024.0 },
+ "type": "SCALAR"
+ },
+ {
+ "name": "disk",
+ "scalar": { "value": 1024.0 },
+ "type": "SCALAR"
+ }
+ ],
+ "container": {
+ "type": "MESOS",
+ "mesos": {
+ "image": {
+ "type": "DOCKER",
+ "docker": {
+ "name": "alpine"
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+The Agent will return:
+
+ * 200 OK if the launch succeeds, including fetching any container images
+ or URIs specified in the launch command.
+ * 202 Accepted if the specified ContainerID is already in use by a running
+ container.
+ * 400 Bad Request if the launch fails for any reason.
+
+**NOTE:** Nested containers share the same Operator API. To launch a nested
+container, the ContainerID needs to have a parent; and no resources may be
+specified in the request.
+
+
+## Monitoring a Standalone Container
+
+Standalone containers are not managed by a framework, do not use executors,
+and therefore do not have status updates. They are not automatically
+relaunched upon completion/failure.
+
+After launching a standalone container, the operator should monitor the
+container via the `WAIT_CONTAINER` call:
+
+```
+WAIT_CONTAINER HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: agenthost:5051
+Content-Type: application/json
+Accept: application/json
+
+{
+ "type": "WAIT_CONTAINER",
+ "wait_container": {
+ "container_id": {
+ "value": "my-standalone-container-id"
+ }
+ }
+}
+
+WAIT_CONTAINER HTTP Response (JSON):
+
+HTTP/1.1 200 OK
+
+Content-Type: application/json
+
+{
+ "type": "WAIT_CONTAINER",
+ "wait_container": {
+ "exit_status": 0
+ }
+}
+```
+
+This is a blocking HTTP call that only returns after the container has
+exited.
+
+If the specified ContainerID does not exist, the call returns a 404.
+
+
+## Killing a Standalone Container
+
+A standalone container can be signalled (usually to kill it) via this API:
+
+```
+KILL_CONTAINER HTTP Request (JSON):
+
+POST /api/v1 HTTP/1.1
+
+Host: agenthost:5051
+Content-Type: application/json
+
+{
+ "type": "KILL_CONTAINER",
+ "kill_container": {
+ "container_id": {
+ "value": "my-standalone-container-id"
+ }
+ }
+}
+
+KILL_CONTAINER HTTP Response (JSON):
+
+HTTP/1.1 200 OK
+```
+
+If the specified ContainerID does not exist, the call returns a 404.
+
+
+## Cleaning up a Standalone Container
+
+Unlike other containers, a standalone container's sandbox is not garbage
+collected by the Agent after some time (like other sandbox directories).
+The Agent is unable to garbage collect these containers because there is
+no status update mechanism to report the exit status of the container.
+
+Standalone container sandboxes must be manually cleaned up by the operator and
+are located in the agent's work directory under
+`/containers/<my-standalone-container-id>`.
