Locations

Locations are the environments to which Brooklyn deploys applications, including:

Brooklyn supports a wide range of locations:

• Clouds, where it will provision machines
• Localhost (e.g. your laptop), where it will deploy via ssh to localhost for rapid testing
• BYON, where you “bring your own nodes”, specifying already-existing hosts to use
• And many others, including object stores and online services

Configuration can be set in ~/.brooklyn/brooklyn.properties, through the location wizard tool available within the web console or directly in YAML when specifying a location. On some entities, config keys determining matching selection and provisioning behavior can also be set in provisioning.properties.

Clouds

For most cloud provisioning tasks, Brooklyn uses Apache jclouds. The identifiers for some of the most commonly used jclouds-supported clouds are (or see the full list):

• jclouds:aws-ec2:<region>: Amazon EC2, where :<region> might be us-east-1 or eu-west-1 (or omitted)
• jclouds:softlayer:<region>: IBM Softlayer, where :<region> might be dal05 or ams01 (or omitted)
• jclouds:google-compute-engine: Google Compute Engine
• jclouds:openstack-nova:<endpoint>: OpenStack, where :<endpoint> is the access URL (required)
• jclouds:cloudstack:<endpoint>: Apache CloudStack, where :<endpoint> is the access URL (required)

For any of these, of course, Brooklyn needs to be configured with an identity and a credential:

location:
  jclouds:aws-ec2:
    identity: ABCDEFGHIJKLMNOPQRST
    credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l

The above YAML can be embedded directly in blueprints, either at the root or on individual services. If you prefer to keep the credentials separate, you can instead store them as a catalog entry or set them in brooklyn.properties in the jclouds.<provider> namespace:

brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST  
brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l

And in this case you can reference the location in YAML with location: jclouds:aws-ec2.

Alternatively, you can use the location wizard tool available within the web console to create any cloud location supported by Apache jclouds. This location will be saved as a catalog entry for easy reusability.

Brooklyn irons out many of the differences between clouds so that blueprints run similarly in a wide range of locations, including setting up access and configuring images and machine specs. The configuration options are described in more detail below.

In some cases, cloud providers have special features or unusual requirements. These are outlined in More Details for Specific Clouds.

OS Initial Login and Setup

Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.

The credentials for the initial OS log on are typically discovered from the cloud, but in some environments this is not possible. The keys loginUser and either loginUser.password or loginUser.privateKeyFile can be used to force Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.

(This custom login is particularly useful when using a custom image templates where the cloud-side account management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change the root password. This setting tells Apache Brooklyn to only use the given password, rather than the initial randomly generated password that vCD returns. Without this property, there is a race for such templates: does Brooklyn manage to create the admin user before the guest customization changes the login and reboots, or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property, Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such cases, it is also recommended to use useJcloudsSshInit=false.)

Following a successful logon, Brooklyn performs the following steps to configure the machine:

1. creates a new user with the same name as the user brooklyn is running as locally (this can be overridden with user, below).

2. install the local user’s ~/.ssh/id_rsa.pub as an authorized_keys on the new machine, to make it easy for the operator to ssh in (override with privateKeyFile; or if there is no id_{r,d}sa{,.pub} an ad hoc keypair will be generated for the regular Brooklyn user; if there is a passphrase on the key, this must be supplied)

3. give sudo access to the newly created user (override with grantUserSudo: false)

4. disable direct root login to the machine

These steps can be skipped or customized as described below.

jclouds Config Keys

The following is a subset of the most commonly used configuration keys used to customize cloud provisioning. For more keys and more detail on the keys below, see JcloudsLocationConfig (javadoc, src) .

VM Creation

• Most providers require exactly one of either region (e.g. us-east-1) or endpoint (the URL, usually for private cloud deployments)

• Hardware requirements can be specified, including minRam, minCores, and os64Bit; or as a specific hardwareId

• VM image constraints can be set using osFamily (e.g. Ubuntu, CentOS, Debian, RHEL) and osVersionRegex, or specific VM images can be specified using imageId or imageNameRegex

• Specific VM images can be specified using imageId or imageNameRegex

• Specific Security Groups can be specified using securityGroups, as a list of strings (the existing security group names), or inboundPorts can be set, as a list of numeric ports (selected clouds only)

• Where a key pair is registered with a target cloud for logging in to machines, Brooklyn can be configured to request this when provisioning VMs by setting keyPair (selected clouds only). Note that if this keyPair does not correspond your default ~/.ssh/id_rsa, you must typically also specify the corresponding loginUser.privateKeyFile as a file or URL accessible from Brooklyn.

• A specific VM name (often the hostname) base to be used can be specified by setting groupId. By default, this name is constructed based on the entity which is creating it, including the ID of the app and of the entity. (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.) For more sophisticated control over host naming, you can supply a custom CloudMachineNamer (javadoc, src) , for example cloudMachineNamer: CustomMachineNamer. CustomMachineNamer (javadoc, src)

  will use the entity’s name or following a template you supply. On many clouds, a random suffix will be appended to help guarantee uniqueness; this can be removed by setting vmNameSaltLength: 0 (selected clouds only).

• A DNS domain name where this host should be placed can be specified with domainName (in selected clouds only)

• User metadata can be attached using the syntax userMetadata: { key: value, key2: "value 2" } (or userMetadata=key=value,key2="value 2" in a properties file)

• By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities, prefixed with brooklyn-. This user metadata can be omitted by setting includeBrooklynUserMetadata: false.

• You can specify the number of attempts Brooklyn should make to create machines with machineCreateAttempts (jclouds only). This is useful as an efficient low-level fix for those occasions when cloud providers give machines that are dead on arrival. You can of course also resolve it at a higher level with a policy such as ServiceRestarter (javadoc, src) .

• If you want to investigate failures, set destroyOnFailure: false to keep failed VM’s around. (You’ll have to manually clean them up.) The default is false: if a VM fails to start, or is never ssh’able, then the VM will be terminated.

  OS Setup

• user and password can be used to configure the operating user created on cloud-provisioned machines

• The loginUser config key (and subkeys) control the initial user to log in as, in cases where this cannot be discovered from the cloud provider

• Private keys can be specified using privateKeyFile; these are not copied to provisioned machines, but are required if using a local public key or a pre-defined authorized_keys on the server. (For more information on SSH keys, see here.)

• If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course! privateKeyPassphrase does the trick (as in brooklyn.location.jclouds.privateKeyPassphrase, or other places where privateKeyFile is valid). If you don’t like keys, you can just use a plain old password.

• Public keys can be specified using publicKeyFile, although these can usually be omitted if they follow the common pattern of being the private key file with the suffix .pub appended. (It is useful in the case of loginUser.publicKeyFile, where you shouldn’t need, or might not even have, the private key of the root user when you log in.)

• Provide a list of URLs to public keys in extraSshPublicKeyUrls, or the data of one key in extraSshPublicKeyData, to have additional public keys added to the authorized_keys file for logging in. (This is supported in most but not all locations.)

• Use dontCreateUser to have Brooklyn run as the initial loginUser (usually root), without creating any other user.

• A post-provisioning setup.script can be specified (as a URL) to run an additional script, before making the Location available to entities, optionally also using setup.script.vars (set as key1:value1,key2:value2)

• Use openIptables: true to automatically configure iptables, to open the TCP ports required by the software process. One can alternatively use stopIptables: true to entirely stop the iptables service.

• Use installDevUrandom: true to fall back to using /dev/urandom rather than /dev/random. This setting is useful for cloud VMs where there is not enough random entropy, which can cause /dev/random to be extremely slow (causing ssh to be extremely slow to respond).

• Use useJcloudsSshInit: false to disable the use of the native jclouds support for initial commands executed on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn’s ssh support will be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will change login credentials).

• Use brooklyn.ssh.config.noDeleteAfterExec: true to keep scripts on the server after execution. The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console, but sometimes it can also be useful to have them on the box. This setting prevents scripts executed on the VMs from being deleted on completion. Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test.

Custom Template Options

jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds template options for your cloud.

Part of the process for creating a virtual machine is the creation of a jclouds TemplateOptions object. jclouds providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of type AWSEC2TemplateOptions. By examining the source code, you can see all of the options available to you.

The templateOptions config key takes a map. The keys to the map are method names, and Brooklyn will find the method on the TemplateOptions instance; it then invokes the method with arguments taken from the map value. If a method takes a single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the value of the key should be an array, containing the argument for each parameter.

For example, here is a complete blueprint that sets some AWS EC2 specific options:

location: AWS_eu-west-1
services:
- type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess
  provisioningProperties:
    templateOptions:
      subnetId: subnet-041c8373
      mapNewVolumeToDeviceName: ["/dev/sda1", 100, true]
      securityGroupIds: ['sg-4db68928']

Here you can see that we set three template options:

• subnetId is an example of a single parameter method. Brooklyn will effectively try to run the statement templateOptions.subnetId("subnet-041c88373");
• mapNewVolumeToDeviceName is an example of a multiple parameter method, so the value of the key is an array. Brooklyn will effectively true to run the statement templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);
• securityGroupIds demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try to parse the value as a single parameter method which takes a parameter of type List; such a method does exist so the operation will succeed.

If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2 specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored.

See the following resources for more information:

• AWS VPC issues which may affect users with older AWS accounts
• Amazon EC2 and Amazon Virtual Private Cloud
• Your Default VPC and Subnets
• Amazon VPC FAQs

More Details on Specific Clouds

To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the identity and credential in Brooklyn terminology.

For private clouds (and for some clouds being targeted using a standard API), the endpoint must also be specified, which is the cloud’s URL. For public clouds, Brooklyn comes preconfigured with the endpoints, but many offer different choices of the region where you might want to deploy.

Clouds vary in the format of the identity, credential, endpoint, and region. Some also have their own idiosyncracies. More details for configuring some common clouds is included below. You may also find these sources helpful:

• The template brooklyn.properties file in the Getting Started guide contains numerous examples of configuring specific clouds, including the format of credentials and options for sometimes-fiddly private clouds.
• The jclouds guides describes low-level configuration sometimes required for various clouds.

Amazon Web Services (AWS)

Credentials

AWS has an “access key” and a “secret key”, which correspond to Brooklyn’s identity and credential respectively.

These keys are the way for any programmatic mechanism to access the AWS API.

To generate an access key and a secret key, see jclouds instructions and AWS IAM instructions.

An example of the expected format is shown below:

brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm

Tidying up after jclouds

Security groups are not always deleted by jclouds. This is due to a limitation in AWS (see https://issues.apache.org/jira/browse/JCLOUDS-207). In brief, AWS prevents the security group being deleted until there are no VMs using it. However, there is eventual consistency for recording which VMs still reference those security groups: after deleting the VM, it can sometimes take several minutes before the security group can be deleted. jclouds retries for 3 seconds, but does not block for longer.

There is utility written by Cloudsoft for deleting these unused resources: http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.

Using Subnets and Security Groups

Apache Brooklyn can run with AWS VPC and both public and private subnets. Simply provide the subnet-a1b2c3d4 as the networkName when deploying:

location:
  jclouds:aws-ec2:
    region: us-west-1
    networkName: subnet-a1b2c3d4   # use your subnet ID

Subnets are typically used in conjunction with security groups. Brooklyn does not attempt to open additional ports when private subnets or security groups are supplied, so the subnet and ports must be configured appropriately for the blueprints being deployed. You can configure a default security group with appropriate (or all) ports opened for access from the appropriate (or all) CIDRs and security groups, or you can define specific securityGroups on the location or as provisioning.properties on the entities.

Make sure that Brooklyn has access to the machines under management. This includes SSH, which might be done with a public IP created with inbound access on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it. Alternatively you can run Brooklyn on a machine in that same subnet, or set up a VPN or jumphost which Brooklyn will use.

EC2 “Classic” Problems with VPC-only Hardware Instance Types

If you have a pre-2014 Amazon account, it is likely configured in some regions to run in “EC2 Classic” mode by default, instead of the more modern “VPC” default mode. This can cause failures when requesting certain hardware configurations because many of the more recent hardware “instance types” only run in “VPC” mode. For instance when requesting an instance with minRam: 8gb, Brooklyn may opt for an m4.large, which is a VPC-only instance type. If you are in a region configured to use “EC2 Classic” mode, you may see a message such as this:

400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC. 
A subnet ID or network interface ID is required to carry out the request.

This is a limitation of “legacy” accounts. The easiest fixes are either:

• specify an instance type which is supported in classic, such as m3.xlarge (see below)
• move to a different region where VPC is the default (eu-central-1 should work as it only offers VPC mode, irrespective of the age of your AWS account)
• get a new AWS account – “VPC” will be the default mode (Amazon recommend this and if you want to migrate existing deployments they provide detailed instructions)

To understand the situation, the following resources may be useful:

• Background on VPC vs Classic: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html
• Good succinct answers to FAQs: http://aws.amazon.com/vpc/faqs/#Default_VPCs
• Check if a region in your account is “VPC” or “Classic”: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability
• Regarding instance types:
  • All instance types: https://aws.amazon.com/ec2/instance-types
  • Those which require VPC: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types

If you want to solve this problem with your existing account, you can create a VPC and instruct Brooklyn to use it:

1. Use the “Start VPC Wizard” option in the VPC dashboard, making sure it is for the right region, and selecting a “Single Public Subnet”. (More information is in these AWS instructions.)
2. Once the VPC is created, open the “Subnets” view and modify the “Public subnet” so that it will “Auto-assign Public IP”.
3. Next click on the “Security Groups” and find the default security group for that VPC. Modify its “Inbound Rules” to allow “All traffic” from “Anywhere”. (Or for more secure options, see the instructions in the previous section, “Using Subnets”.)
4. Finally make a note of the subnet ID (e.g. subnet-a1b2c3d4) for use in Brooklyn.

You can then deploy blueprints to the subnet, allowing VPC hardware instance types, by specifying the subnet ID as the networkName in your YAML blueprint. This is covered in the previous section, “Using Subnets”.

Google Compute Engine (GCE)

Credentials

GCE uses a service account e-mail address for the identity and a private key as the credential.

To obtain these from GCE, see the jclouds instructions.

An example of the expected format is shown below. Note that when supplying the credential in a properties file, it should be one long line with \n representing the new line characters:

brooklyn.location.jclouds.google-compute-engine.identity=123456789012@developer.gserviceaccount.com
brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----

Quotas

GCE accounts can have low default quotas.

It is easy to requesta quota increase by submitting a quota increase form.

Networks

GCE accounts often have a limit to the number of networks that can be created. One work around is to manually create a network with the required open ports, and to refer to that named network in Brooklyn’s location configuration.

To create a network, see GCE network instructions.

For example, for dev/demo purposes an “everything” network could be created that opens all ports.

IBM SoftLayer

VLAN Selection

SoftLayer may provision VMs in different VLANs, even within the same region. Some applications require VMs to be on the same internal subnet; blueprints for these can specify this behaviour in SoftLayer in one of two ways.

The VLAN ID can be set explicitly using the fields primaryNetworkComponentNetworkVlanId and primaryBackendNetworkComponentNetworkVlanId of SoftLayerTemplateOptions when specifying the location being used in the blueprint, as follows:

YAML location: jclouds:softlayer: region: ams01 templateOptions: # Enter your preferred network IDs primaryNetworkComponentNetworkVlanId: 1153481 primaryBackendNetworkComponentNetworkVlanId: 1153483

This method requires that a VM already exist and you look up the IDs of its VLANs, for example in the SoftLayer console UI, and that subsequently at least one VM in that VLAN is kept around. If all VMs on a VLAN are destroyed SoftLayer may destroy the VLAN. Creating VLANs directly and then specifying them as IDs here may not work. Add a line note

The second method tells Brooklyn to discover VLAN information automatically: it will provision one VM first, and use the VLAN information from it when provisioning subsequent machines. This ensures that all VMs are on the same subnet without requiring any manual VLAN referencing, making it very easy for end-users.

To use this method, we tell brooklyn to use SoftLayerSameVlanLocationCustomizer as a location customizer. This can be done on a location as follows:

YAML location: jclouds:softlayer: region: lon02 customizers: - $brooklyn:object: type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer softlayer.vlan.scopeUid: "my-custom-scope" softlayer.vlan.timeout: 10m

Usually you will want the scope to be unique to a single application, but if you need multiple applications to share the same VLAN, simply configure them with the same scope identifier.

It is also possible with many blueprints to specify this as one of the provisioning.properties on an application:

YAML services: - type: org.apache.brooklyn.entity.stock.BasicApplication id: same-vlan-application brooklyn.config: provisioning.properties: customizers: - $brooklyn:object: type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer softlayer.vlan.scopeUid: "my-custom-scope" softlayer.vlan.timeout: 10m

If you are writing an entity in Java, you can also use the helper method forScope(String) to create the customizer. Configure the provisioning flags as follows:

Java JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope"); flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans));

Configuration Options

The allowed configuration keys for the SoftLayerSameVlanLocationCustomizer are:

• softlayer.vlan.scopeUid The scope identifier for locations whose VMs will have the same VLAN.

• softlayer.vlan.timeout The amount of time to wait for a VM to be configured before timing out without setting the VLAN ids.

• softlayer.vlan.publicId A specific public VLAN ID to use for the specified scope.

• softlayer.vlan.privateId A specific private VLAN ID to use for the specified scope.

An entity being deployed to a customized location will have the VLAN ids set as sensors, with the same names as the last two configuration keys.

NOTE If the SoftLayer location is already configured with specific VLANs then this customizer will have no effect.

Inheritance and Named Locations

Named locations can be defined for commonly used groups of properties, with the syntax brooklyn.location.named.your-group-name. followed by the relevant properties. These can be accessed at runtime using the syntax named:your-group-name as the deployment location.

Some illustrative examples using named locations and showing the syntax and properties above are as follows:

# Production pool of machines for my application (deploy to named:prod1)
brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
brooklyn.location.named.prod1.user=produser1
brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa
brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase

# AWS using my company's credentials and image standard, then labelling images so others know they're mine
brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1
brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU  
brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa
brooklyn.location.named.company-jungle.imageId=ami-12345
brooklyn.location.named.company-jungle.minRam=2048
brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson"
brooklyn.location.named.company-jungle.machineCreateAttempts=2

brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2
brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1
brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14
brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root
brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096

Named locations can refer to other named locations using named:xxx as their value. These will inherit the configuration and can override selected keys. Properties set in the namespace of the provider (e.g. b.l.jclouds.aws-ec2.KEY=VALUE) will be inherited by everything which extends AWS Sub-prefix strings are also inherited up to brooklyn.location.*, except that they are filtered for single-word and other known keys (so that we exclude provider-scoped properties when looking at sub-prefix keys). The precedence for configuration defined at different levels is that the value defined in the most specific context will apply.

This is rather straightforward and powerful to use, although it sounds rather more complicated than it is! The examples below should make it clear. You could use the following to install a public key on all provisioned machines, an additional public key in all AWS machines, and no extra public key in prod1:

brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key
brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"
brooklyn.location.named.prod1.extraSshPublicKeyUrls=

And in the example below, a config key is repeatedly overridden. Deploying location: named:my-extended-aws will result in an aws-ec2 machine in us-west-1 (by inheritance) with VAL6 for KEY:

brooklyn.location.KEY=VAL1
brooklyn.location.jclouds.KEY=VAL2
brooklyn.location.jclouds.aws-ec2.KEY=VAL3
brooklyn.location.jclouds.aws-ec2@us-west-1.KEY=VAL4
brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1
brooklyn.location.named.my-aws.KEY=VAL5
brooklyn.location.named.my-extended-aws=named:my-aws
brooklyn.location.named.my-extended-aws.KEY=VAL6

BYON

“Bring-your-own-nodes” mode is useful in production, where machines have been provisioned by someone else, and during testing, to cut down provisioning time.

Your nodes must meet the following prerequisites:

• A suitable OS must have been installed on all nodes
• The node must be running sshd (or similar)
• the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see here.)

To deploy to machines with known IP’s in a blueprint, use the following syntax:

location:
  byon:
    user: brooklyn
    privateKeyFile: ~/.ssh/brooklyn.pem
    hosts:
    - 192.168.0.18
    - 192.168.0.19

Some of the login properties as described above for jclouds are supported, but not loginUser (as no users are created), and not any of the VM creation parameters such as minRam and imageId. (These clearly do not apply in the same way, and they are not by default treated as constraints, although an entity can confirm these where needed.) As before, if the brooklyn user and its default key are authorized for the hosts, those fields can be omitted.

Named locations can also be configured in your brooklyn.properties, using the format byon:(key=value,key2=value2). For convenience, for hosts wildcard globs are supported.

brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}")
brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1
brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa
brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase

Alternatively, you can create a specific BYON location through the location wizard tool available within the web console. This location will be saved as a catalog entry for easy reusability.

For more complex host configuration, one can define custom config values per machine. In the example below, there will be two machines. The first will be a machine reachable on ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53. The second is a windows machine, reachable over WinRM. Each machine has also has a private address (e.g. for within a private network).

location:
  byon:
    hosts:
    - ssh: 50.51.52.53:8022
      privateAddresses: [10.0.0.1]
      privateKeyFile: ~/.ssh/brooklyn.pem
      user: myuser
    - winrm: 50.51.52.54:8985
      privateAddresses: [10.0.0.2]
      password: mypassword
      user: myuser
      osFamily: windows

The BYON location also supports a machine chooser, using the config key byon.machineChooser. This allows one to plugin logic to choose from the set of available machines in the pool. For example, additional config could be supplied for each machine. This could be used (during the call to location.obtain()) to find the config that matches the requirements of the entity being provisioned. See FixedListMachineProvisioningLocation.MACHINE_CHOOSER.

SSH Keys

SSH keys are one of the simplest and most secure ways to access remote servers. They consist of two parts:

• A private key (e.g. id_rsa) which is known only to one party or group

• A public key (e.g. id_rsa.pub) which can be given to anyone and everyone, and which can be used to confirm that a party has a private key (or has signed a communication with the private key)

In this way, someone – such as you – can have a private key, and can install a public key on a remote machine (in an authorized_keys file) for secure automated access. Commands such as ssh (and Brooklyn) can log in without revealing the private key to the remote machine, the remote machine can confirm it is you accessing it (if no one else has the private key), and no one snooping on the network can decrypt of any of the traffic.

Creating an SSH Key

If you don’t have an SSH key, create one with:

$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa

Localhost Setup

If you want to deploy to localhost, ensure that you have a public and private key, and that your key is authorized for ssh access:

# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.
$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

Now verify that your setup by running the command: ssh localhost echo hello world

If your setup is correct, you should see hello world printed back at you.

On the first connection, you may see a message similar to this:

The authenticity of host 'localhost (::1)' can't be established.
RSA key fingerprint is 7b:e3:8e:c6:5b:2a:05:a1:7c:8a:cf:d1:6a:83:c2:ad.
Are you sure you want to continue connecting (yes/no)?

Simply answer ‘yes’ and then repeat the command again.

If this isn’t the case, see below.

Potential Problems

• MacOS user? In addition to the above, enable “Remote Login” in “System Preferences > Sharing”.

• Got a passphrase? Set brooklyn.location.localhost.privateKeyPassphrase as described here. If you’re not sure, or you don’t know what a passphrase is, you can test this by executing ssh-keygen -y. If it does not ask for a passphrase, then your key has no passphrase. If your key does have a passphrase, you can remove it by running ssh-keygen -p.

• Check that you have an ~/.ssh/id_rsa file (or id_dsa) and a corresponding public key with a .pub extension; if not, create one as described above

• ~/.ssh/ or files in that directory may have permissions they shouldn’t: they should be visible only to the user (apart from public keys), both on the source machine and the target machine. You can verify this with ls -l ~/.ssh/: lines should start with -rw------- or -r-------- (or -rwx------ for directories). If it does not, execute chmod go-rwx ~/.ssh ~/.ssh/*.

• Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers; if command-line ssh and scp work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.

• Missing entropy: creating and using ssh keys requires randomness available on the servers, usually in /dev/random; see here for more information

Localhost

If passwordless ssh login to localhost and passwordless sudo is enabled on your machine, you should be able to deploy blueprints with no special configuration, just by specifying location: localhost in YAML.

If you use a passpharse or prefer a different key, these can be configured as follows:

brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key
brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE

Alternatively, you can create a specific localhost location through the location wizard tool available within the web console. This location will be saved as a catalog entry for easy reusability.

If you encounter issues or for more information, see SSH Keys Localhost Setup.

If you are normally prompted for a password when executing sudo commands, passwordless sudo must also be enabled. To enable passwordless sudo for your account, a line must be added to the system /etc/sudoers file. To edit the file, use the visudo command: <div class="highlight"><pre>sudo visudo</pre></div> Add this line at the bottom of the file, replacing username with your own user: <div class="highlight"><pre>username ALL=(ALL) NOPASSWD: ALL</pre></div> If executing the following command does not ask for your password, then sudo should be setup correctly: <div class="highlight"><pre>sudo ls</pre></div>

Specialized Locations

Some additional location types are supported for specialized situations:

Single Host

The spec host, taking a string argument (the address) or a map (host, user, password, etc.), provides a convenient syntax when specifying a single host. For example:

services:
- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server 
  location:
    host: 192.168.0.1

Or, in brooklyn.properties, set brooklyn.location.named.host1=host:(192.168.0.1).

The Multi Location

The spec multi allows multiple locations, specified as targets, to be combined and treated as one location. When the first target is full, the next is tried, and so on:

location:
  multi:
    targets:
    - byon:(hosts=192.168.0.1)
    - jclouds:aws-ec2:
      identity: acct1
    - jclouds:aws-ec2:
      identity: acct2

The example above provisions the first node to 192.168.0.1, then it provisions into acct1 at Amazon if possible, and then to acct2.

The Server Pool

The ServerPool (javadoc, src)

entity type allows defining an entity which becomes available as a location.