Packaging A Swarm Application

An overview of the shipping a Docker Swarm application in Replicated

Using Replicated’s built-in Docker Swarm support allows you to use your existing docker-compose.yml and Swarm Services to deploy your application using the Replicated platform.

Shipping a Swarm application with Replicated involves creating a single YAML file that contains your Docker Swarm services and additional Replicated configuration data. This is packaged as a multi-document YAML file, with a special comment at the top of each included documented to describe it’s structure. Replicated supports Compose 3 versions up to 3.5 depending on the installed version of Docker.

A typical Docker Swarm release in Replicated will contain two documents, and will have the following structure:

---
# kind: replicated
replicated_api_version: 2.26.0
config:
  ...

---
# kind: scheduler-swarm
version: "3.5"
services:
  ...

Replicated API Version

The replicated_api_version key is required as a top level key in every YAML. This should be set to the minimum version of Replicatd required to run this release. The current API version to use is 2.26.0, and the latest version can always be found on our changelog. Replicated will refuse to install an application requiring a newer version of Replicated than available. This is designed so you can rely on newer features of Replicated in your application.

replicated_api_version: 2.26.0

Application Basics

The next section includes some basic information about your application release including the app name.

name: My Enterprise Application

Detailed App Properties Description

The properties section includes definitions of some recommended application properties. For a list of available properties see Application Properties. You will notice the {{repl escape sequence. This invokes a Replicated template function which is a way to pull generated, customer supplied, or other outside values into an installation.

properties:
  app_url: http://{{repl ThisNodePrivateIPAddress }}
  console_title: My Enterprise Application

Snapshots (Backups)

The snapshots key is available to enable and configure Snapshots. The following example will enable snapshots from the Admin Console, using the default behavior.

backup:
  enabled: true

CMD

The Replicated platform has some built in commands that make writing your configuration much more powerful. In the cmds section you can write commands which you can use later. These are useful to generate install-time values such as default TLS certs/keys, randomized passwords, other other values.

cmds:
  - name: jwt_hmac_secret
    cmd: random
    args:
      - "128"

Monitors

When using the Swarm scheduler, services can be monitored for resource usage metrics. The following YAML will show a CPU and a memory graph of the redis service on the Admin Console dashboard page.

monitors:
  cpuacct:
  - redis
  memory:
  - redis

Customer Config Section

This section is where you can configure fields to gather input from the user. This input can be used to further configure your application. The values here can be used as inputs to environment variables and config files by using the template functions. They can also be tested for validity with test procs. These items will render as a form in the Settings screen of the Replicated admin console.

config:
  - name: hostname
    title: Hostname
    description: Ensure this domain name is routable on your network.
    type: text
    required: true
    ...

Container Images

To use private images from an external registry, you need to add the registry to vendor.replicated.com. The guide for integrating a third party registry explains this in further detail.

For Airgapped installations, all images included in your Swarm application must be specified in the images section of your YAML in order to be included in the airgap bundle your customer will download and install.

images:
- source: mythirdpartyprivateregistry
  name: namespace/imagename
  tag: 2.0.0
- source: public
  name: redis
  tag: 3.2-alpine
- source: public
  name: postgres
  tag: 9.4
- source: replicated
  name: app
  tag: v1

There are other keys, not listed here, that are required to enable advanced functionality. To see more, see the Docker Swarm examples.