Defining Locations

Defining locations

Locations in Cloudsoft AMP are server resources which AMP can use to deploy applications. These locations may be servers or cloud providers which provide access to servers.

A standard location catalog for AWS could look like the following.

brooklyn.catalog:
  version: 1.0.0
  items:
  - id: amazon-anywhere
    itemType: location
    item:
      type: jclouds:aws-ec2
      brooklyn.config:
        displayName: AWS (any region)
        identity: ABCDEFGHIJKLMNOPQRST
        credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l
  - id: amazon-us-east-1
    itemType: location
    item:
      type: amazon-anywhere
      brooklyn.config:
        displayName: AWS Virginia
        region: us-east-1
  - id: amazon-us-west-1
    itemType: location
    item:
      type: amazon-anywhere
      brooklyn.config:
        displayName: AWS California
        region: us-west-1

In here we describe 3 locations. One that can be used to target any amazon location (you would then need to configure a region when you deployed a blueprint). This location has an Amazon key and identity. To use the blueprint replace these values with your own. The other two locations extend this basic location by adding region config.

To add these locations to your catalog save the yaml to a file called amazon-locations.bom and run the following command (which uses the Cloudsoft AMP CLI):

br add-catalog amazon-locations.bom

This location will now be available to any application you launch through Cloudsoft AMP. You can see a list of currently available locations using the CLI with:

br catalog

Included in the list should be the amazon entities you just added.

Id                 Name                       Spec
...
amazon-anywhere    amazon-anywhere            brooklyn.catalog:amazon-anywhere:1.0.0
amazon-us-east-1   amazon-us-east-1           brooklyn.catalog:amazon-us-east-1:1.0.0
amazon-us-west-1   amazon-us-west-1           brooklyn.catalog:amazon-us-west-1:1.0.0
...

As with entity catalogs you can version locations and set readable names, ids, and descriptions.

Using a Location

TOSCA does not natively provide for the use and specification of multiple target environments. Cloudsoft AMP provides conveniences to make working with one location simple, and it also provides the capability to use multiple locations, even within a single blueprint.

TOSCA Default Location

Typically a topology_template does not specify where it should be deployed; Cloudsoft AMP assumes that a tosca.default.location has been defined in the catalog, and will use that location when nothing is specified. For example, add the following to the catalog to use the amazon-us-east-1 location defined above:

brooklyn.catalog:
  version: 1.0.0-SNAPSHOT
  items:
  - id: tosca.default.location
    itemType: location
    item:
      type: amazon-us-east-1

TOSCA topology templates such as the one below will deploy to the location above (unless otherwise configured, as shown further below):

tosca_definitions_version: tosca_simple_yaml_1_3

metadata:
  template_name: demo
  template_version: 1.0.0-SNAPSHOT

topology_template:
  node_templates:
    a_server:
      type: tosca.nodes.Compute
    a_software:
      type: tosca.nodes.SoftwareComponent
      requirements:
      - host: a_server

Configuring Custom Locations in a Topology Template

To indicate that a topology template or individual nodes should deploy to a location other than the tosca.default.location, you can specify a group called add_brooklyn_types of type brooklyn.tosca.groups.initializer, containing properties including a location containing the Cloudsoft AMP location ID. For example, the blueprint above could have the following YAML appended to the topology_template to specify it should deploy to amazon-us-west-1 instead:

groups:
- add_brooklyn_types:
    members: [demo]
    type: brooklyn.tosca.groups.initializer
    properties:
      location: amazon-us-west-1

It is also possible to use the extended location syntax where additional configuration for the location is supplied, as follows:

groups:
- add_brooklyn_types:
    members: [demo]
    type: brooklyn.tosca.groups.initializer
    properties:
      location:
        amazon-us-west-1:
          minRam: 4gb

As a result, a simple demo application deployed to a custom location with additional configuration for minRam can be represented by the following blueprint:

tosca_definitions_version: tosca_simple_yaml_1_3

metadata:
  template_name: demo
  template_version: 1.0.0-SNAPSHOT

topology_template:
  node_templates:
    a_server:
      type: tosca.nodes.Compute
    a_software:
      type: tosca.nodes.SoftwareComponent
      requirements:
      - host: a_server
  groups:
  - add_brooklyn_types:
      members: [demo]
      type: brooklyn.tosca.groups.initializer
      properties:
        location:
          amazon-us-west-1:
            minRam: 4gb

To use one of the locations above, add its ID to your application YAML under a top-level location key:

name: location test
location: amazon-us-east-1
services:
- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
  id: empty

It is also possible to supply custom configuration to extend the location definition, as follows:

name: location test
location:
  amazon-us-east-1:
    minRam: 4gb
services:
- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
  id: empty

Save this YAML to test-amazon-location.yaml and deploy with:

br deploy test-amazon-location.yaml

This will provision and configure a VM then test SSH access.

Catalog and Abbreviated Syntax

Most of the illustrations in this section use location: { parent_id: { config_key: value }} syntax to illustrate configuring locations. To convert this to the catalog item syntax (when adding things to the catalog), use parent_id as the type and provide all the key-pairs underneath brooklyn.config, e.g.:

location:
  amazon-us-east-1:
    minRam: 4gb

becomes

type: amazon-us-east-1
brooklyn.config:
  minRam: 4gb

Testing our deployed application

We should now wait until our application has deployed (or failed to deploy).

br application "location test"

Running the following command will let us know the state of our application.

br application "location test"

Id:              cb69jpljes
Name:            location test
Status:          STARTING
ServiceUp:       false
Type:            org.apache.brooklyn.entity.stock.BasicApplication
CatalogItemId:
LocationId:      gaix92akwi
LocationName:    AWS Virginia
LocationSpec:    jclouds:aws-ec2
LocationType:    org.apache.brooklyn.location.jclouds.JcloudsLocation

As we can see our application has not yet started. We could keep running the same command until we see that our application is ready or we could run something like the following to watch this for us.

br application "location test" | grep STARTING
while [ $? -eq 0 ]; do !!; done ; bp

Now that the application is running we want to make sure that the provisioned VM is accessible. Within our application are the entities that make it up. If an entity has been deployed on a host then it will contain a host.sshAddress sensor with details of how to connect to the host.

To see the entities that make up our app we run:

br application "location test" entity

Id           Name                        Type
mlbnk1bf7e   EmptySoftwareProcess:mlbn   org.apache.brooklyn.entity.software.base.EmptySoftwareProcess

As we might expect there is only a single entity in our app which is an empty software process that has been “deployed” to an AWS VM. We will want to look at its sensors for the host.sshAdress sensor.

br application "location test" entity mlbnk1bf7e sensor

Name                                   Description                                                                                         Value
download.addon.urls                    URL patterns for downloading named add-ons (will substitute things like ${version} automatically)   null
download.url                           URL pattern for downloading the installer (will substitute things like ${version} automatically)    null
expandedinstall.dir                    Directory for installed artifacts (e.g. expanded dir after unpacking .tgz)                          null
host.address                           Host IP address                                                                                     50.19.22.101
host.name                              Host name                                                                                           ec2-50-19-22-101.compute-1.amazonaws.com
host.sshAddress                        user@host:port for SSH'ing (or null if inappropriate)                                               ampuser@ec2-50-19-22-101.compute-1.amazonaws.com:22
host.subnet.address                    Host address as known internally in the subnet where it is running (if different to host.name)      10.165.155.118
host.subnet.hostname                   Host name as known internally in the subnet where it is running (if different to host.name)         ec2-50-19-22-101.compute-1.amazonaws.com
install.dir                            Directory for this software to be installed in                                                      /home/users/ampuser/brooklyn-managed-processes/installs/EmptySoftwareProcess
run.dir                                Directory for this software to be run from                                                          /home/users/ampuser/brooklyn-managed-processes/apps/cb69jpljes/entities/EmptySoftwareProcess_mlbnk1bf7e
service.isUp                           Whether the service is active and availability (confirmed and monitored)                            true
service.notUp.diagnostics              A map of namespaced diagnostics, from when the service is not up                                    {}
service.notUp.indicators               A map of namespaced indicators that the service is not up                                           {}
service.process.isRunning              Whether the process for the service is confirmed as running                                         true
service.state                          Actual lifecycle state of the service                                                               RUNNING
service.state.expected                 Last controlled change to service state, indicating what the expected state should be               running @ 1467965495843 / Fri Jul 08 09:11:35 BST 2016
softwareprocess.pid.file               PID file                                                                                            null
softwareservice.provisioningLocation   Location used to provision a machine where this is running                                          {"id":"gaix92akwi","type":"org.apache.brooklyn.api.location.Location"}

We can see the host.sshAddress value in the above table. If we use the value, replacing the : with -p for ssh, we can run the following command.

ssh ampuser@ec2-50-19-22-101.compute-1.amazonaws.com -p 22

Assuming this works we will see a command prompt on our provisioned VM. At this point we might want to provision a more complex blueprint to further test our location.

This section of the documentation has provided a short introduction into locations.
The following sections provide a reference for locations and the differences between different cloud providers, how to write java to customize locations, and how to troubleshoot issues with a location.