Using Target Environments

Overview

The target environment descriptor (aka "ted" file) is used to configure the Skopos engine to interact with a specific runtime environment.

This document provides an overview of what target enviroment files are for and how to best use them. You can also see the Target Enviroment Reference for the detailed reference of settings and options available.

Why Are They Needed

The Skopos application models do not have direct references to objects in the target environment (such as names of VM image IDs or Load Balancer IDs, etc). This allows the same model to be used in different target setups. The binding to specific resources is provided by the target environment descriptor, which is given to Skopos when loading a model (see the command-line reference ).

For example, if your application has two production instances (e.g., one in the US and one in Europe) and several dev/test/QA instances, all instances can share the same model file but each instance will have its own target environment descriptor.

Target environment descriptors contain the following information:

  • names of external resources to be used by an application instance (e.g., EC2 load balancer names, VPC, docker volumes, etc.)
  • names and options of plugins to be used for service infrastructure: service creation, service discovery, load balancers
  • named quality gates: these associate user defined deployment steps, or actions, to component images
  • additional variables and settings that are specific to an application instance

Target envirnonment descriptors provide the link between the abstract application model and the unique real-world instance of that application. Using multiple target environments (each with its own descriptor), it is possible to use the same application model to run the application independently in each environment.

The descriptor is a YAML file with the following format:

core_plugin : name
service_discovery_plugin: name
service_discovery_auto: false
load_balancer_plugin: name
load_balancer_auto: false
chatops_plugin: name

vars:
    key1: "value1"
    key2: "value2"
    key3: "value2"

plugin_config:
    name1:
        # plugin-specific data/configuration

    name2:
        # plugin-specific data/configuration

quality_gates:
    name1:
        # quality gate specification

    name2:
        # quality gate specification

A typical simple environment file for a docker-based application that uses AWS application-level load balancers can look like this:

core_plugin: docker                 # use Docker for creating instances (containers)
service_discovery_plugin: docker    # may be omitted since docker is the core plugin
service_discovery_auto: true        # should be always true for the docker plugin
load_balancer_plugin: docker-elb    # use AWS application level ELB tied to docker instances
chatops_plugin: slack               # deploy notifications

var:
    env: production
    region: us-west1
    db_user: hellodb
    vault_path: secret/hello
    nginx_ver: "1.11.10"            # or set to "latest" to track the latest release

plugin_config:
    docker:
        volumes:
            myvol: { from: "/hello/vol1", readonly: false }
    docker-elb:
        lb:
            ingress: "hello-lb"     # model lb name mapped to AWS name for the LB for this application instance
    slack:
        url: 'https://hooks.slack.com/services/F0LFL61HF/L45LUWFM1/NlR6Gi4DMiGaWn3efatnpfsD'

Standard target environment files

You can use the following seed environment files for common environments.

For more information on the requirements, capabilities and configuration on each of the plugins referenced below, look at the corresponding plugin reference in the left side bar.

Docker Swarm

core_plugin: docker-swarm
service_discovery_plugin: docker-swarm
service_discovery_auto: true

Docker (single host)

core_plugin: docker
service_discovery_plugin: docker
service_discovery_auto: true

Docker (single host) on AWS EC2 with application level ELB

core_plugin: docker
service_discovery_plugin: docker
service_discovery_auto: true
load_balancer_plugin: docker-elb

EC2 Autoscaling Groups with Docker, Consul and classic ELB load balancer

core_plugin: ec2-asg
service_discovery_plugin: consul
service_discovery_auto: true
load_balancer_plugin: ec2-asg

EC2 Container Service (with classic and application load balancers)

Support for AWS ECS is experimental in this version. For more information, please contact us at support@opsani.com.

core_plugin: ec2-ecs
service_discovery_plugin: ec2-ecs
service_discovery_auto: true

Factoring Environment

When using Skopos for the first time or for a single application's deployment, it is simple and convenient to place all environment configuration in a single target environment file.

When using Skopos to deploy the same application to multiple different environments, it is advantageous to split the target environment file and load each project's deployment with a different set of env files, using them as building blocks to construct the desired environment from the fewest different pieces.

For example, dividing the target environment files in 3 files allows great flexibility while sharing most of the configuration and ensuring its consistency across multiple environments.

Service infrastructure configuration (e.g., docker.yaml):

core_plugin: docker
service_discovery_plugin: docker
service_discovery_auto: true

Application configuration variables:

(for Alice)

vars:
  db_user: alice
  db_passwd: vault/secret-alice
  http_port: 8080

plugin_config:
  docker:
    volumes:
      db_vol: { from: "/mnt/alice-db" }

Image version tags:

vars:
  invoices_ver: 1.12.4
  nginx_ver: 1.11.10
  api_ver: ec43212

In addition, chatops and other auxiliary settings can be placed in yet another file:

chatops_plugin: slack

plugin_config:
  slack:
    url: 'https://hooks.slack.com/services/F0LFL61HF/L45LUWFM1/NlR6Gi4DMiGaWn3efatnpfsD'

Then the load command for a developer may look like this (changing only alice.yaml from developer to developer):

skopos load --env docker.yaml --env alice.yaml --env dev-vers.yaml --env dev-slack.yaml model.yaml

And the load command for a production environment may look like this:

skopos load --env docker.yaml --env prod-emea.yaml --env prod-vers.yaml --env prod-slack.yaml model.yaml

Of course, it is best to design the environment decomposition in a manner that fits your application and different environments you use. A good factoring will have no (or minimal) duplication while ensuring consistency between environments. It is good practice to check in any environment files and the model with your project's source code so they will be tracked together with the application code.

Another common factoring is to separate quality gates into their own environment file. Quality gates associate a list of user defined deployment steps, or actions, to a list of component images. Skopos executes these steps during application deployment, typically to verify a component is fully functional after its creation or modification. By separating these into their own file, quality gates may be applied to any application simply by including this environment file with the application on load.

For more examples and details, see: