Create the Compose Runtime Application

Updated

Introduction

Docker Compose is a tool for defining and managing multi-container Docker applications. It allows developers to configure all application services—including their dependencies, networks, and storage settings—within a single declarative YAML file, typically named compose.yaml.

By consolidating configuration and orchestration into one file, Docker Compose simplifies the deployment process. Rather than launching each container manually with individual commands, Compose enables you to bring up the entire application stack with a single command, ensuring consistency and ease of management across development and production environments. 

Primarily, the ZEDEDA Compose Runtime app includes:

  1. The ZEDEDA Agent: The agent translates the edge app instance management operations into compose app instance actions: start, stop, restart, purge and update command, delete. The agent uses a closed-loop management system for applications. The Agent process running on the edge node continuously monitors the status of the running app instances.
     
  2. The Runtime Stack: The container runtime stack is the core software running on the host machine that creates and manages the containers.
     
  3. The Compose Tool (or equivalent logic): This is the command-line tool (docker-compose) or built-in Docker command (docker compose) that reads your YAML file.

In summary, the Compose Runtime includes both the Container Runtime Stack (a.k.a, the Docker Engine) and the ability to translate and execute the instructions in your compose.yaml file.

Create the Runtime App in ZEDEDA Cloud

ZEDEDA will provide a runtime app in the global marketplace, and you must import that app into the local marketplace for the Docker Compose app to work. 

The runtime package includes the translator required to parse the compose.yaml file, as well as a component that interacts with the local container runtime stack. These components are packaged as a separate Compose Runtime app. The compose runtime must be created and deployed like any other app in the ZEDEDA Marketplace.

The runtime must be deployed with the Docker Compose App for the following reasons: 

  1. Provides the Capability: The Compose Runtime app installs the translator/executor for compose.yaml files on the edge nodes.
     
  2. Integration: It integrates this capability with ZEDEDA's management system, allowing ZEDEDA to deploy, monitor, and manage applications defined by compose.yaml files.

Therefore, you must deploy the Compose Runtime app from ZEDEDA Marketplace to use the Docker Compose edge app type. Once the compose runtime app is up and running, ZEDEDA Cloud can deploy the compose applications, whose services are defined in the compose.yaml file, because the necessary ZEDEDA agents and container runtime will now be present on the device.

This article describes the process of adding the Compose Runtime as a Virtual Machine edge app type and deploying the runtime as an edge app instance on your node.   

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

  1. Docker Compose Overview 
  2. Create the Compose Runtime Application - You are here!
  3. Compose App Instance Control Overview
  4. Add a Docker Compose as an Edge App Type
  5. Troubleshooting Docker Compose

Prerequisites

  • You have the SysManager role in your enterprise.
  • You have stored the application details in a place the edge node can access. Check Data Stores for details.
  • You have an Edge App Image for Compose Runtime.
  • Your edge node is running EVE-OS version 14.5.0 or greater.
  • You have created a Switch network instance and a Local air-gapped network instance.

Create a Virtual Machine for Compose Runtime

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. 

Configure the identity

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

Configure the resources & drives

After configuring the identity, configure the resources and drives.

  1. For Resource, select one of the predefined resource profiles such as:  Tiny, Small, Typical, X-Large, XX-Large. This selection will auto-populate the fields, determining the amount of CPU and Memory allocated to your runtime app. You can also select Custom if you prefer to specify the CPU and Memory fields yourself.
  2. For Storage, specify the size of a dedicated blank disk. This is the maximum size (capacity) defined for a specific virtual drive (or volume instance) attached to your runtime app. This space holds the app image (OS and binaries) and potentially its runtime data.
  3. For Persistence Storage Size, specify the size of a dedicated blank disk for storing persistent Docker volumes, such as 20 GB.
  4. Select the VM Mode. This is the virtualization technique used to run the VM. For example, the HVM type of virtualization is where the guest operating system doesn't need to change its kernel drivers. This approach is mainly used in KVM.
  5. Select a Drive Type of HDD to assign a virtual hard drive to the VM, and allocate a specific amount of storage space.
  6. Select a Target of Disk, which refers to the virtual hard drive (HDD) where the VM's operating system is installed.
  7. Choose the existing Compose Runtime Edge App Image that you created in the prerequisites.
  8. For Max Size, select the size of your drive (sometimes called a volume), such as 10 GB. 
  9. Click Next.

Configure the interfaces

After configuring the drives, configure the interfaces. Each runtime must have at least two non-direct attach Ethernet adapters:

The first adapter connects to a switch network instance for data traffic. This ensures the container has access to the network, and ensures that the services exposed in the container are externally accessible.

  1. Click 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.

  1. Click 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. Click Next.

Configure the custom config template

After configuring the interfaces, determine if you need to add a custom configuration template. For information, see Custom Configuration Edge Application.

  1. Click Add Custom Config Template.
  2. Customize the config template. For example:
#cloud-config
hostname: $zri.system.edge-instance.name
manage_etc_hosts: true
groups:
- zrun
users:
- name: ###DC_USER_NAME###
gecos: ZEDEDA Docker Compose User
shell: /bin/bash
sudo: ALL=(ALL) NOPASSWD:ALL
lock_passwd: False
plain_text_passwd: ###DC_USER_PASSWORD###
chpasswd:
expire: False
groups: zrun, users, admin, docker
runcmd:
# create and map the UserData partition
- echo 'root:###DC_USER_PASSWORD###' | chpasswd -c SHA512 -s 1000000
- /home/zededa/bin/disk-partition.sh
- /home/zededa/bin/setup_dcompose.sh
- echo "[Service]" > /etc/systemd/system/zrun-agent.service.d/zrun-env.conf
- echo 'Environment=COLLECTSTATSIPADDR="$zri.system.edge-app.stat"' >> /etc/systemd/system/zrun-agent.service.d/zrun-env.conf
- cd /home/zededa && chown -R zededa . && chgrp -R users .
- sed -i -e 's/\(^Defaults secure_path.*\)"$/\1:\/usr\/local\/bin\/"/' /etc/sudoers
- /home/zededa/bin/last_things.sh
- systemctl enable zrun-agent
- systemctl daemon-reload
- systemctl start zrun-agent
# removes bothersome logs
- echo "ListenAddress ""$(ip -4 -o a l eth2 | awk -F'/| +' '{print $4}')" >> /etc/ssh/sshd_config
- systemctl restart sshd
final_message: "Docker Compose has been setup, after $UPTIME seconds"

NOTE: The username and password are highlighted in the cloud-config sample to draw attention to the fact that, if you are already logged into EVE-OS, you can establish an SSH connection to the runtime. You can do this using Edge View to establish an SSH connection to the air-gapped ethernet port (eth2). See Initial User Setup and Connecting to the Edge App for details.

  1. Click Next.

Configure the developer Info & review

  1. Review the info and click Add.
  2. Verify your new addition by checking for it in the ZEDEDA Marketplace.

Deploy the Compose Runtime App

NOTE: While multiple Docker Compose apps can be deployed on an edge node, you can deploy only one Compose Runtime app per edge node. 

Configure the edge app & edge nodes

This process is based on Deploy an Edge Application Instance. See that article if you need further details about deployment in general. 

  1. From the ZEDEDA Marketplace, click Edge Apps.
  2. Click the Deploy icon (at bottom right) of your Compose Runtime edge app card.
  3. As the Edge App, select your Compose Runtime edge app image, if not auto-populated. 
  4. Select your Project from the drop down. 
  5. Select the Name for your edge node(s) where you want to deploy the app instance.
  6. Click Next.

Configure the edge app instance identity

  1. There are no specific requirements for the Name and Title of the edge app instance, so configure as you wish.
  2. For the Persistence Storage Size, make sure that the size is equivalent to your VM drive size, such as 20 GB, since the default might be higher than some smaller nodes.
    NOTE: A persistent data volume is created as part of this process of deploying the runtime image. This ensures the persistent volume data will be maintained across upgrades of the runtime software.
  3. Click Next.

Configure the adapters & networks

  1. Select your Switch network instance for the first adapter.
  2. Select your Local air-gapped network instance for the second adapter.
  3. Click Next.

Configure the custom configuration

  1. In the Compose User Parameters fields, enter the Compose user name and
    Compose user password. 
    NOTE: These credentials enable users who are already logged into EVE-OS to be able to establish an SSH connection into the runtime for troubleshooting purposes. You will use Edge View to establish an SSH connection to the air-gapped Ethernet port (eth2). 
    See Initial User Setup and Connecting to the Edge App in the Troubleshooting Docker Compose article for details.
  2. Click Next.

Review & deploy

  1. Review the deployment details, such as checking the image name, max size, and edge nodes appears correct.
  2. Click Deploy.

Next Steps

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

  1. Docker Compose Overview 
  2. Create the Compose Runtime Application - You are here!
  3. Compose App Instance Control Overview
  4. Add a Docker Compose as an Edge App Type
  5. Troubleshooting Docker Compose

After you’ve completed the series, you might be interested in the following articles. 

Manage your edge nodes and edge apps.

Was this article helpful?
0 out of 0 found this helpful