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 v1 phase now.

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 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 capsule-delete <uuid>
$ zun capsule-delete <capsule-name>

List capsule:

$ zun capsule-list

Describe capsule:

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

TODO

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.