Add a Compose Runtime Image

Introduction

The Compose Runtime is a virtual machine image that runs the Docker Engine and the compose agent on an edge node. Before you can deploy Docker Compose applications, the Compose Runtime must exist as an edge app in your enterprise marketplace.

The recommended path is to import a ZEDEDA-published Compose Runtime edge app from the Global Marketplace. It arrives with its image, its two network interfaces, and its custom configuration template already defined. If you received the Compose Runtime as a QCOW2 file instead, add the image to the Library and create the edge app yourself.

The edge app is what you select when deploying the Compose Runtime as an edge app instance. If the edge app does not define network interfaces, the deployment wizard cannot complete.

This is a series of articles. You will likely follow them in this order.

1. Docker Compose Overview
2. Add a Compose Runtime Image (you are here)
3. Deploy the Compose Runtime Application
4. Attach an Existing ZFS Pool to the Compose Runtime (ZFS variant only)
5. Compose App Instance Control Overview
6. Add a Docker Compose as an Edge App Type
7. Troubleshooting Docker Compose

Prerequisites

• You have the SysManager role in your enterprise.
• If you add the image yourself: the Compose Runtime QCOW2 file, or its SHA-256 hash, file size, and datastore path if uplinking from an existing datastore, and a configured datastore to store the image.

Choose a Runtime Variant

ZEDEDA publishes the Compose Runtime in two variants. Both run the same Docker Engine and compose agent, and both are deployed the same way. They differ only in whether the runtime can attach an existing ZFS storage pool.

Each variant is published in more than one size. The size sets the default CPU, memory, and storage of the runtime VM. Choose the size that matches your edge node's capacity.

NOTE: The ZFS variant needs one additional drive on the edge app and two configuration files that you edit before deployment. After you complete this article, see Attach an Existing ZFS Pool to the Compose Runtime for those steps.

Import the Compose Runtime From the Global Marketplace

This is the recommended path. The imported edge app includes the runtime image, the two required network interfaces, and the custom configuration template.

1. From the Marketplace, select Edge Apps.
2. Under the Global Edge Apps tab, search for zed-compose-runtime.
3. Locate the variant and size you chose in the preceding section. The card shows the runtime version, for example 3.0.0.
4. Select Import.

The imported edge app appears under the Local Edge Apps tab. You can deploy it as it is. Continue to Deploy the Compose Runtime Application.

If you need to change the resources, drives, or configuration template before deploying, duplicate the imported edge app and edit the copy. The sections that follow describe each wizard step. The ZFS variant always needs this step, because you must add the pool drive and edit the configuration template.

Add the Compose Runtime Image Yourself

Use this section only if you received the Compose Runtime as a QCOW2 file rather than importing it from the Global Marketplace. This process is based on Manage an Edge App Image. See that article if you need further details about images in general.

1. From the Library, select Edge App Images.
2. Select Add.
3. For Image Type, select Compose Runtime.
4. For Image Format, select QCOW2.
5. Select the Image Architecture the image targets: AMD64 for x86-64 edge nodes, or ARM64 for ARM 64-bit edge nodes.
6. Select Upload to upload the QCOW2 file from your computer and choose the datastore to store it in, or select Uplink to reference a file already stored in a datastore. For an uplink, enter the Image SHA256, the Image Size, the Datastore, and the Image Relative URL (the path to the file within the datastore).
7. Enter a unique Name (for example, compose-runtime-amd64), a Title, and an optional Description.
8. Select Add.

ZEDEDA Cloud uploads the file or begins uplinking. The image status changes to Ready when the process completes.

Create the Compose Runtime Edge App

The edge app defines the manifest that the deployment wizard reads, including the network interfaces and drives. This process is based on Add a Virtual Machine as an Edge App Type. See that article if you need further details about VM app types in general. If you duplicated an imported edge app, the wizard opens pre-filled and you can review each step rather than entering values from scratch.

Configure the identity

1. In the Identity section, fill in the following:
   1. Name: This value cannot be changed later.
   2. Title: You can change this value at any time.
   3. Description: Use this to help other admins understand the purpose of the app.
2. There is nothing specific for the Category, so configure it as you wish.
3. For the Deployment Type, select Compose Runtime. This runtime is provided and managed by ZEDEDA.
4. Select Next.

Configure the resources and drives

1. For Resource, select one of the predefined resource profiles such as Tiny, Small, Typical, X-Large, or XX-Large. This selection auto-populates the CPU and Memory fields. You can also select Custom to specify them yourself.
2. For Storage, specify the size of a dedicated blank disk. This is the maximum capacity of the virtual drive attached to your runtime app. It holds the app image (OS and binaries).
3. For Persistence Storage Size, specify the size of the dedicated disk that stores the runtime's own persistent container state, such as Docker volumes created by compose apps (for example, 20 GB). When the runtime deploys, a persistent data volume of this size is created, and its data survives upgrades of the runtime software. This disk is not the same as an attached ZFS pool, which is an existing volume that the ZFS variant imports rather than creates.
4. For VM Mode, select HVM. The Compose Runtime image is an HVM-compatible QCOW2 image.
5. Select a Drive Type of HDD.
6. Select a Target of Disk.
7. Choose the Compose Runtime Edge App Image that you imported or added.
8. For Max Size, select the size of your drive, such as 10 GB.
9. To give the runtime an additional blank data disk that belongs to the instance, select Add Drive, leave the Edge App Image empty, set the Max Size, and set Purge so that the volume is persistent. See Add Persistent Volume Instances.
10. For the ZFS variant, select Add Drive and configure the second drive as described in Attach an Existing ZFS Pool to the Compose Runtime. That drive references the existing pool volume by its Volume Label rather than by an image. Skip this step for the standard variant.
11. Select Next.

NOTE: Data disks must come after the boot image in the drive list. While instances of the edge app exist, you can add or remove data disks only at the end of the list.

Configure the interfaces

This is the step that determines whether the deployment wizard can proceed. Each runtime must have exactly two non-direct-attach Ethernet adapters.

The first adapter connects to a switch network instance for data traffic. This gives the containers network access and makes the services exposed in the containers externally accessible.

1. Select Configure interfaces for the edge app.
2. Enter a Name for the interface, such as eth0.
3. Select an interface Type of Virtual Network Interface.
4. In Outbound Rules, for Outbound Host or IP, enter 0.0.0.0/0.

The second adapter connects to an air-gapped local network instance for internal protocol traffic between the runtime and ZEDEDA Cloud.

1. Select Add Interface.
2. Enter a Name for the interface, such as eth1.
3. Select an interface Type of Virtual Network Interface.
4. In Outbound Rules, for Outbound Host or IP, enter 0.0.0.0/0.
5. Select Next.

WARNING: Skipping this step or leaving the interface list empty means the deployment wizard cannot complete. The deployment wizard does not let you add interfaces to a Compose Runtime at deploy time. Define them here.

Configure the custom config template

The custom configuration template defines the fields that appear during deployment, including the Compose Runtime SSH credentials and the optional static IP settings. For general information, see Custom Configuration Edge Application.

The template is provided with the Compose Runtime image distribution and is already present on edge apps imported from the Global Marketplace. Do not author it from scratch. The ZFS variant's template contains two additional files, zvol-mounts.sh and zvol-mounts.conf, that you must edit before deployment. See Attach an Existing ZFS Pool to the Compose Runtime.

1. Select Add Custom Config Template.
2. Paste the configuration template provided with your Compose Runtime image distribution, or review the pre-filled template if you duplicated an imported edge app.
3. Select Next.

Configure the developer info and review

1. Confirm or enter the Developer Name and Developer Email.
2. Review the configuration. Confirm that two virtual network interfaces, eth0 and eth1, are listed. For the ZFS variant, confirm that a second drive with the ZFS pool's volume label is listed.
3. Select Add.

Verify the Configuration

1. From the Marketplace, select Edge Apps and open the Local Edge Apps tab.
2. Locate the Compose Runtime edge app and open it.
3. Confirm that the manifest shows two interfaces, eth0 and eth1, and that the drives list shows the runtime image first, followed by any data disks.
4. If you added the image yourself, select Library > Edge App Images and confirm that the Compose Runtime image status is Ready.

If either verification fails, the deployment wizard does not function correctly. Resolve image status errors before proceeding, and re-create the edge app if the interfaces are missing.

Next Steps

This is a series of articles. You will likely follow them in this order.

1. Docker Compose Overview.
2. Add a Compose Runtime Image (you are here).
3. Deploy the Compose Runtime Application.
4. Attach an Existing ZFS Pool to the Compose Runtime (ZFS variant only).
5. Compose App Instance Control Overview.
6. Add a Docker Compose as an Edge App Type.
7. Troubleshooting Docker Compose.