Enactment Engine
Table of content
Introduction
The Enactment Engine (EE) automatically deploys the choreography based on the concrete choreography description document received from the Synthesis Processor (via Identity Manager). The EE also interfaces with the Identity Manager to include into the concrete choreography description the actual deployment and runtime details. Then, once a choreography is deployed and running, the EE listens for command requests from the IdM for runtime choreography control.
The EE is based on top of Apache Brooklyn, and we will document the installation and configuration features that has been added with respect to Brooklyn.
Installation Guide
Requirements
The hardware requirements depend greatly on the given deployment, in particular the total number of managed choreographies.
- CPU: dual core, 2 GHz (minimum)
- RAM: 1 GB (minimum)
- Disk: 250 MB (minimum)
The software requirements can be summarized as:
- Oracle JDK 8 or OpenJDK 8
Download information
From the Download section of the CHOReVOLUTION project website you can grab the enactment-engine-1.0.0.tar.gz package.
Installation steps
Unpack the binaries into a directory, then create the configuration file for the Enactment Engine, which must be placed inside $HOME/.brooklyn/brooklyn.properties . At the time of writing, EE has been tested on CentOS, Debian 8 and Ubuntu 16.04. There is still no Microsoft Windows support.
Configuring the enactment target
Locations are server resources which the Enactment Engine can use to deploy applications. These locations may be servers or cloud providers. The EE is configured for deploying on a fixed location, named “chorevolution”. You are free to configure such location to match your needs. To access the locations configuration, access http://enactment_engine_host:8081/#v1/catalog and click on the “ + “ sign near “Catalog”, then click on the “Location” button, as explained in the image below.
Once the editors opens, you’ll be asked to insert the YAML configuration for the Location. In the following you will find some examples about how to configure EE to deploy on localhost, on a remote physical host or on a cloud infrastructure. Other details can be found on the official Apache Brooklyn documentation available here https://brooklyn.apache.org/v/latest/yaml/setting-locations.html.
CHOReVOLUTION Config Keys
The "chorevolution" Location MUST contain the following keys, which have been added to integrate with the other CHOReVOLUTION components:
- autoAssignNeutronFloatingIp: when using OpenStack with Neutron networking, set this configuration key to “true” to enable auto assignment of IPs.
- neutronNetworkID: OpenStack Neutron network 7f390079-4eb7-4e93-a72d-d957846c8846
- identityManagerEndpoint: endpoint of the Identity Manager REST interface
- identityManagerEndpointUsername: Identity Manager username
- identityManagerEndpointPassword: Identity Manager password
Deploying choreographies on localhost
If neither a remote physical host nor a cloud provider account are available, a viable option is to configure the Enactment Engine to deploy and run choreographies on localhost. The only prerequisite is a passwordless sudo access for the specified user. More details about configuring a localhost Location are available here https://brooklyn.apache.org/v/latest/locations/index.html#localhost . A sample configuration for specifying a localhost location is reported in the image below.
Deploying choreographies on a physical host
As explained here https://brooklyn.apache.org/v/latest/locations/index.html#byon, the Enactment Engine can deploy application on a location consisting of one or more existing physical hosts. You can find an example of how to configure a “Bring your own node” (BYON) location in the figure below. Both username/password or username/ssh key access are possible. The only prerequisite is a passwordless sudo access for the specified user.
The following figure reports a localhost configuration example:
Deploying choreographies on a cloud infrastructure
Enactment Engine configuration file example
The file ~/.brooklyn/brooklyn.properties is read when the Enactment Engine starts to load server configuration values. A different properties file can be specified either additionally or instead through CLI options.
# It should be located at "~~/.brooklyn/brooklyn.properties" for automatic loading,
# or can be specified as a CLI option with ~-~-localProperties /path/to/these.properties.
~#~# GUI Security
~#~# NOTE: in production it is highly recommended to set this, as otherwise it will not require login,
~#~# not will it be encrypted (though for safety if security is not set it will only bind to loopback)
~#~# Edit the name(s) and passwords as appropriate to your system:
brooklyn.webconsole.security.users=admin_username
brooklyn.webconsole.security.user.admin.password=admin_password
~#~# If you prefer to run with https (on port 8443 by default), uncomment this:
# brooklyn.webconsole.security.https.required=true
# Beware of trailing spaces in your cloud credentials. This will cause unexpected
# 401: unauthorized responses.
~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~# Getting Started Complete! ~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~##
# That's it, although you may want to read through these options...
~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~# Enactment Engine Options ~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#
~#~# Enactment Engine Management Base Directory: specify where management data should be stored on this server;
~#~# ~~/.brooklyn/ is the default but you could use something like /opt/brooklyn/state/
~#~# (provided this process has write permissions)
# brooklyn.base.dir=~~/.brooklyn/
~#~# Enactment Engine On-Box Directory: specify where data should be stored on managed hosts;
~#~# for most locations a directory off home is the default (but using /tmp/brooklyn-user/ on localhost),
~#~# however you could specify something like /opt/brooklyn-managed-process/ (creation and permissions are handled)
onbox.base.dir=/opt/brooklyn-managed-process/
~#~# Additional security: Allow all - if you know what you are doing!
~#~# (Or you can also plug in e.g. LDAP security etc here)
# brooklyn.webconsole.security.provider = org.apache.brooklyn.rest.security.provider.AnyoneSecurityProvider
~#~# Optionally disallow deployment to localhost (or any other location)
brooklyn.location.localhost.enabled=false
~#~# Scripting Behaviour
~#~# keep scripts around after running them (usually in /tmp)
# brooklyn.ssh.config.noDeleteAfterExec = true
~#~# Misc Cloud Settings
~#~# brooklyn will fail a node if the cloud machine doesn't come up, but you can tell it to retry:
brooklyn.location.jclouds.machineCreateAttempts = 3
~#~# many cloud machines don't have sufficient entropy for lots of encrypted networking, so fake it:
brooklyn.location.jclouds.installDevUrandom=true
~#~# Sets a minimium ram property for all jclouds locations. Recommended to avoid getting m1.micros on AWS!
brooklyn.location.jclouds.minRam = 2048
~#~# When setting up a new cloud machine Enactment Engine creates a user with the same name as the user running Enactment Engine on the management server, but you can force a different user here:
#brooklyn.location.jclouds.user=chorevolution
~#~# And you can force a password or key (by default it will use the keys in ~~/.ssh/id_rsa{,.pub}
#brooklyn.location.jclouds.password=admin
~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~# Named Locations ~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#
~#~# OpenStack Nova access information can be downloaded from the openstack web interface; for example, as openrc.sh file
brooklyn.location.named.chorevolution=jclouds:openstack-nova:https:~/~/<IP or hostname>:<port>/v2.0/
brooklyn.location.named.chorevolution.identity=chorevolution:<username>
brooklyn.location.named.chorevolution.credential=**********
#brooklyn.location.named.chorevolution.credential=**********
brooklyn.location.named.chorevolution.endpoint=http:~/~/<IP or hostname>:<port>/v2.0
~#~# The ID of the image must be configured according to the local OpenStack settings
~#~# Use the command nova image-list to list all the available images
~#~# Use the command nova show <image-name> to get more details
brooklyn.location.named.chorevolution.imageId=RegionOne/af036b89-0ef4-48e9-99ac-51b0cf9c314e
~#~# (Optional) Configurations
brooklyn.location.named.chorevolution.user=ubuntu
~#~# The keyPair must by created upfront. Both the following two options are required at the same time.
brooklyn.location.named.chorevolution.keyPair=eeKey
brooklyn.location.named.chorevolution.loginUser.privateKeyFile=/etc/enactment-engine/eekey.pem
~#~# Security groups must be created upfront (TBC - How to specify many security groups at one ?)
brooklyn.location.named.chorevolution.securityGroups=permit_all
brooklyn.location.named.chorevolution.dontCreateUser=true
brooklyn.location.named.chorevolution.selinux.disabled=true
brooklyn.location.named.chorevolution.autoAssignNeutronFloatingIp=true
brooklyn.location.named.chorevolution.openstack-nova.auto-generate-keypairs=false
brooklyn.location.named.chorevolution.neutronNetworkID=7f390079-4eb7-4e93-a72d-d957846c8846
brooklyn.location.named.chorevolution.identityManagerEndpoint=http://192.168.150.132:8080/syncope/rest
brooklyn.location.named.chorevolution.openstack-nova.identityManagerEndpointUsername= **********
brooklyn.location.named.chorevolution.openstack-nova.identityManagerEndpointPassword= **************
Uninstalling steps
Delete the directory and $HOME/.brooklyn to uninstall the EE and its temporary data.
User Guide
The Enactment Engine comes with a CLI tool, allowing complete control over the managed choreographies. You can find a document explaining the commands at https://brooklyn.apache.org/v/latest/ops/cli/cli-ref-guide.html.
Managing a choreography
Managing a choreography is achieved by using the "Choreographies" section of the CHOReVOLUTION console, as explained in http://www.chorevolution.eu/bin/view/Documentation/CHOReVOLUTION+Console+and+Identity+Manager#HChoreographies .
Checking the choreography logs
Whenever a choreography is deployed, a full stack of Logstash, ElasticSearch and Kibana is installed. Such configuration is tailored to collecting the application logs from all the Tomcat nodes running the choreography, and to show them to the choreography operator/developer.