. . .

Nomad Deployment Setup

Introduction

If you've decided to use the Executor as facade for a Nomad deployment environment you need some further setup steps that are explained on this page.

Configuration

The general service configuration of Executor is described in [Executor] Installation. This section contains Nomad specific configuration of the Executor:


Key

Description

Example

executor.nomad.allowed-hosts

list of allowed Nomad server instance hosts. If empty the Nomad server instance host will be retrieved from Consul.

This list of Nomad instances is used to protect the endpoint to retrieve the service artifact from Executor.

You can use "*" to allow the access from everywhere, but this may be a security risk and we do not recommend that.

"localhost" or "127.0.0.1"

executor.nomad.job-restart.attempts

Attempts specifies the number of restarts allowed in the configured interval. See https://nomadproject.io/docs/job-specification/restart/ for more details.

2 (default)

executor.nomad.job-restart.delay

Delay specifies the duration to wait before restarting a task. The number is specified in seconds. A random jitter of up to 25% is added to the delay internally by nomad.

15 (default)

executor.nomad.job-restart.interval

Interval specifies the duration which begins when the first task starts and ensures that only attempts number of restarts happens within it. If more than attempts number of failures happen, behavior is controlled by mode. The number is specified in seconds.

1800 (default)

executor.nomad.job-restart.mode

Mode controls the behavior when the task fails more than attempts times in an interval (options: delay, fail). See https://nomadproject.io/docs/job-specification/restart/#mode-values for more details.

"fail" (default)

Setup Nomad

One deployment engine which is integrated with Executor is Nomad (https://nomadproject.io/). In order to use Executor that helps you to deploy your generated services, you need to install and configure Nomad like described in this section.

Nomad consists of a server- and a client component which means, that you will need to configure and run at least one Nomad server- and one Nomad client. The following guide will help you through the installation.

Nomad Installation

  1. Install Nomad (e.g. in version 0.11.0) from ApiOmat repository by using the known commands to get a Nomad package containing the default configuration files:Debian/Ubuntu

    Debian/Ubuntu
    # Install the repo key
    wget -O - https://repo-int.apiomat.com/yambas/rest/web/Key/LIVE/apiomat-archive-keyring.asc | sudo apt-key add -
    # Add the repository
    echo "deb https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/deb ./" | sudo tee /etc/apt/sources.list.d/apiomat.list
     
    # Update APT and install
    apt-get update
    apt-get install -y aom-nomad
    service nomad start

    Centos/Oracle/RedHat

    Centos/Oracle/RedHat
    # Add the repository
    echo "[apiomat]
    name=ApiOmat
    baseurl=https://<USERNAME>:<PASSWORD>@repo.apiomat.com/yambas/rest/web/Repo/LIVE/rpm
    gpgcheck=0
    enabled=1" > /etc/yum.repos.d/apiomat.repo
     
    # Install
    yum -y --nogpgcheck install aom-nomad
    service nomad start

    Suse

    Suse
    # Add the repository
    zypper addrepo --no-gpgcheck https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/suse?token=<TOKEN> "ApiOmat"
     
    # Refresh zypper and install
    zypper refresh
    zypper --no-gpg-checks --non-interactive install aom-nomad
    service nomad start

    Windows

    Windows

    1. Download file: https://repo.apiomat.com/yambas/rest/web/Repo/LIVE/aom-nomad-<VERSION>.zip?token=<TOKEN> and unzip to installation folder

    2. Ensure that the path to your installed jdk\bin is set to the system-environment variable 'Path' (java.exe needs to be accessible for windows' system user!)

    3. Open administrative console and execute 

      aom-nomad-<VERSION>.exe install
      aom-nomad-<VERSION>.exe start

      to install as service and start afterwards.

      For a removal of the service, execute 

      aom-nomad-<VERSION>.exe uninstall


    Alternatively you can download the Nomad zipped binary from Nomad's download page and unzip it into your bin folder, so you can run nomad from a terminal


  2. Make sure Consul is running (default on localhost:8500)

Nomad Configuration

If you installed Nomad via ApiOmat repository like shown above you already have the following configuration files and needed file system access permissions.


If you decided to install nomad from original source you need to do the following configuration:

  1. Create a server configuration file named server.hcl into a directory of your choosing and insert the following content into it:

    server.hcl
    # Increase log verbosity
    #log_level = "DEBUG"
     
    # Setup data dir
    data_dir = "/tmp/server1"
     
    # Explicit bind address, should be reachable by consul, default 127.0.0.1
    bind_addr = "127.0.0.1"
     
    # Enable the server
    server
    {
    enabled = true
     
    # Self-elect, should be 3 or 5 for production
    bootstrap_expect = 3
    }
     
    # Explicit URL of consul, default 127.0.0.1:8500
    consul
    {
    address = "127.0.0.1:8500"
    }

  2. Create a client configuration file named client.hcl into a directory of your choosing and insert the following content into it:

    client.hcl
    # Increase log verbosity
    #log_level = "DEBUG"
     
    # Setup data dir
    data_dir = "/tmp/client1"
     
    # Explicit bind address, should be reachable by consul, default 127.0.0.1
    bind_addr = "127.0.0.1"
     
    # Give the agent a unique name. Defaults to hostname
    name = "client1"
     
    # Enable the client
    client
    {
    enabled = true
     
    # adjust the server host and port if it differs after server setup
      servers = ["localhost:4647"]
     
    chroot_env
    {
    "/etc" = "/etc",
    "/bin" = "/bin",
    "/usr/lib" = "/usr/lib",
    "/lib" = "/lib",
    "/usr/bin" = "/usr/bin",
    "/lib32" = "/lib32",
    "/lib64" = "/lib64",
    # adjust the jdk mappnig to your correct jdk installation path
    "/opt/jdk" = "/opt/jdk",
    }
     
    options = {
    "user.blacklist" = ""
    }
    }
     
    # Modify our port to avoid a collision with server1
    ports
    {
    http = 5660
    }
     
    # Explicit URL of consul, default 127.0.0.1:8500
    consul
    {
    address = "127.0.0.1:8500"
    }

  • Keep in mind that you may have to change the servers URL and the bound address. The nomad server is started in the next step and may get initialized on another port.

Nomad Start and Test

If you installed Nomad via ApiOmat repository like shown above you already have an operating system service that starts a nomad server and client.
You may skip to step 3.


If you decided to install nomad from original source you need to start the nomad components like the following:

  1. Start nomad server with the following configuration files and command:

    Start nomad agent from server config
    nomad agent -config ${path_to_server_conf}/server.hcl

  2. Start nomad client with the following configuration files and command

    Start nomad agent from server config
    nomad agent -config ${path_to_client_conf}/client.hcl

  3. To make sure Nomad is correctly integrated deploy your first generated service via ApiOmat:

  • Start Yambas (default on localhost:8080) and Hosting service Innkeeper (http on localhost:2400, ftp on localhost:3021).

  • Start Executor service (default on localhost:8070)

  • Open Dashboard in your browser and log in as customer

  • Create a new service with some demo classes and click on build

  • Switch to the service overview and press the play button to start your service

  • In background a deployment process is send to Executor which then contacts Nomad

  • Once the Job started more information is available on local Nomad UI (http://localhost:4646/ui/jobs)