zun/doc/source/contributor/capsule.rst

Capsule Quick Start

Capsule is a container composition unit that includes sandbox container, multiple application containers and multiple volumes. All container inside the capsule share the same network, ipc, pid namespaces. In general, it is the same unit like Azure Container Instance(ACI) or Kubernetes Pod.

The diagram below is an overview of the structure of capsule.

+-----------------------------------------------------------+
|                       +-----------+                       |
|                       |           |                       |
|                       |  Sandbox  |                       |
|                       |           |                       |
|                       +-----------+                       |
|                                                           |
|                                                           |
|   +-------------+    +-------------+    +-------------+   |
|   |             |    |             |    |             |   |
|   |  Container  |    |  Container  |    |  Container  |   |
|   |             |    |             |    |             |   |
|   +-------------+    +-------------+    +-------------+   |
|                                                           |
|                                                           |
|              +----------+       +----------+              |
|              |          |       |          |              |
|              |  Volume  |       |  Volume  |              |
|              |          |       |          |              |
|              +----------+       +----------+              |
|                                                           |
+-----------------------------------------------------------+

Capsule API is currently in experimental phase, so you have to specify --experimental-api option in each of the commands below. They will be moved to stable API once they become stable.

Note

Please make sure that every capsule commands have --experimental-api flags in client side.

Experimental API is a separated API. After users deploy Zun by devstack, a separated set of API endpoints and service type will be created in service catalog. Zun stable API endpoints will have service name zun and service type container, while Zun experimental API endpoints will have service name zun-experimental and service type container-experimental. We can see the service and endpoint information as below:

+------------------+------------------------+---------+-----------+--------------------------------------+
| Service Name     | Service Type           | Enabled | Interface | URL                                  |
+------------------+------------------------+---------+-----------+--------------------------------------+
| zun              | container              | True    | public    | http://***/container/v1              |
| zun              | container              | True    | internal  | http://***/container/v1              |
| zun              | container              | True    | admin     | http://***/container/v1              |
| zun-experimental | container-experimental | True    | public    | http://***/container/experimental    |
| zun-experimental | container-experimental | True    | internal  | http://***/container/experimental    |
| zun-experimental | container-experimental | True    | admin     | http://***/container/experimental    |
+------------------+------------------------+---------+-----------+--------------------------------------+

Now basic capsule functions are supported. Capsule API methods:

• Create: Create a capsule based on special yaml file or json file.
• Delete: Delete an existing capsule.
• Describe: Get detailed information about selected capsule.
• List: List all the capsules with essential fields.

Note

Volume is not yet supported, but it is in the roadmap. It will be implemented after Zun volume support has been finished.

If you need to access to the capsule port, you might need to open the port in security group rules and access the port via the floating IP that assigned to the capsule. The capsule example below assumes that a capsule has been launched with security group "default" and user want to access the port 22, 80 and 3306:

# use "-" because that the fields have many items
capsuleVersion: beta
kind: capsule
metadata:
  name: template
  labels:
    app: web
    foo: bar
restartPolicy: Always
spec:
  containers:
  - image: ubuntu
    command:
      - "/bin/bash"
    imagePullPolicy: ifnotpresent
    workDir: /root
    ports:
      - name: ssh-port
        containerPort: 22
        hostPort: 22
        protocol: TCP
    resources:
      requests:
        cpu: 1
        memory: 1024
    env:
      ENV1: /usr/local/bin
      ENV2: /usr/sbin
    volumeMounts:
    - name: volume1
      mountPath: /data1
      readOnly: True
  - image: centos
    command:
      - "/bin/bash"
    args:
      - "-c"
      - "\"while true; do echo hello world; sleep 1; done\""
    imagePullPolicy: ifnotpresent
    workDir: /root
    ports:
      - name: nginx-port
        containerPort: 80
        hostPort: 80
        protocol: TCP
      - name: mysql-port
        containerPort: 3306
        hostPort: 3306
        protocol: TCP
    resources:
      requests:
        cpu: 1
        memory: 1024
    env:
      ENV2: /usr/bin/
    volumeMounts:
    - name: volume2
      mountPath: /data2
    - name: volume3
      mountPath: /data3
  volumes:
  - name: volume1
    cinder:
      size: 5
      autoRemove: True
  - name: volume2
    cinder:
      volumeID: 9f81cbb2-10f9-4bab-938d-92fe33c57a24
  - name: volume3
    cinder:
      volumeID: 67618d54-dd55-4f7e-91b3-39ffb3ba7f5f

Pay attention, the volume2 and volume3 referred in the above yaml are already created by Cinder. Also capsule doesn't support Cinder multiple attach now. One volume only could be attached to one Container.

Capsule management commands in details:

Create capsule, it will create capsule based on capsule.yaml:

$ source ~/devstack/openrc demo demo
$ zun --experimental-api capsule-create -f capsule.yaml

If you want to get access to the port, you need to set the security group rules for it.

$ openstack security group rule create default \
  --protocol tcp --dst-port 3306:3306 --remote-ip 0.0.0.0/0
$ openstack security group rule create default \
  --protocol tcp --dst-port 80:80 --remote-ip 0.0.0.0/0
$ openstack security group rule create default \
  --protocol tcp --dst-port 22:22 --remote-ip 0.0.0.0/0

Delete capsule:

$ zun --experimental-api capsule-delete <uuid>
$ zun --experimental-api capsule-delete <capsule-name>

List capsule:

$ zun --experimental-api capsule-list

Describe capsule:

$ zun --experimental-api capsule-describe <uuid>
$ zun --experimental-api capsule-describe <capsule-name>

To DO

Add security group set to Capsule

Build this documentation and push it to .

Add Gophercloud support for Capsule

See Gophercloud support for Zun

Add Kubernetes connect to Capsule

see zun connector for k8s.