Modified: brooklyn/site/v/latest/ops/locations/index.html URL: http://svn.apache.org/viewvc/brooklyn/site/v/latest/ops/locations/index.html?rev=1740156&r1=1740155&r2=1740156&view=diff ============================================================================== --- brooklyn/site/v/latest/ops/locations/index.html (original) +++ brooklyn/site/v/latest/ops/locations/index.html Wed Apr 20 15:19:21 2016 @@ -395,6 +395,895 @@ or directly in YAML when specifying a lo On some entities, config keys determining maching selection and provisioning behavior can also be set <code>in </code>provisioning.properties`. </p> +<h3 id="clouds">Clouds</h3> + +<p>For most cloud provisioning tasks, Brooklyn uses +<a href="http://jclouds.org">Apache jclouds</a>. +The identifiers for some of the most commonly used jclouds-supported clouds are +(or <a href="http://jclouds.apache.org/reference/providers/">see the full list</a>):</p> + +<ul> + <li><code>jclouds:aws-ec2:<region></code>: Amazon EC2, where <code>:<region></code> might be <code>us-east-1</code> or <code>eu-west-1</code> (or omitted)</li> + <li><code>jclouds:softlayer:<region></code>: IBM Softlayer, where <code>:<region></code> might be <code>dal05</code> or <code>ams01</code> (or omitted)</li> + <li><code>jclouds:google-compute-engine</code>: Google Compute Engine</li> + <li><code>jclouds:openstack-nova:<endpoint></code>: OpenStack, where <code>:<endpoint></code> is the access URL (required)</li> + <li><code>jclouds:cloudstack:<endpoint></code>: Apache CloudStack, where <code>:<endpoint></code> is the access URL (required)</li> +</ul> + +<p>For any of these, of course, Brooklyn needs to be configured with an <code>identity</code> and a <code>credential</code>:</p> + +<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">ABCDEFGHIJKLMNOPQRST</span> + <span class="l-Scalar-Plain">credential</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l</span></code></pre></div> + +<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> or set them in <code>brooklyn.properties</code> +in the <code>jclouds.<provider></code> namespace:</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.jclouds.aws-ec2.identity<span class="o">=</span>ABCDEFGHIJKLMNOPQRST +brooklyn.location.jclouds.aws-ec2.credential<span class="o">=</span>s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l</code></pre></div> + +<p>And in this case you can reference the location in YAML with <code>location: jclouds:aws-ec2</code>.</p> + +<p>Alternatively, you can use the location wizard tool available within the web console +to create any cloud location supported by <a href="http://jclouds.org">Apache jclouds</a>. +This location will be saved as a <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p> + +<p>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.</p> + +<p>In some cases, cloud providers have special features or unusual requirements. +These are outlined in <strong><a href="more-clouds.html">More Details for Specific Clouds</a></strong>.</p> + +<h4 id="os-initial-login-and-setup">OS Initial Login and Setup</h4> + +<p>Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly.</p> + +<p>The credentials for the initial OS log on are typically discovered from the cloud, +but in some environments this is not possible. +The keys <code>loginUser</code> and either <code>loginUser.password</code> or <code>loginUser.privateKeyFile</code> can be used to force +Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine.</p> + +<p>(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 AMP 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 <code>useJcloudsSshInit=false</code>.)</p> + +<p>Following a successful logon, Brooklyn performs the following steps to configure the machine:</p> + +<ol> + <li> + <p>creates a new user with the same name as the user <code>brooklyn</code> is running as locally + (this can be overridden with <code>user</code>, below).</p> + </li> + <li> + <p>install the local userâs <code>~/.ssh/id_rsa.pub</code> as an <code>authorized_keys</code> on the new machine, +to make it easy for the operator to <code>ssh</code> in +(override with <code>privateKeyFile</code>; or if there is no <code>id_{r,d}sa{,.pub}</code> an ad hoc keypair will be generated +for the regular Brooklyn user; +if there is a passphrase on the key, this must be supplied) </p> + </li> + <li> + <p>give <code>sudo</code> access to the newly created user (override with <code>grantUserSudo: false</code>)</p> + </li> + <li> + <p>disable direct <code>root</code> login to the machine</p> + </li> +</ol> + +<p>These steps can be skipped or customized as described below.</p> + +<h4 id="jclouds-config-keys">jclouds Config Keys</h4> + +<p>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 +<code>JcloudsLocationConfig</code> + (<a href="/v/latest/misc/javadoc/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.html">javadoc</a>, + <a href="https://github.com/apache/brooklyn/tree/0.9.0/locations/jclouds/src/main/java/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.java">src</a>) +.</p> + +<h6 id="vm-creation">VM Creation</h6> + +<ul> + <li> + <p>Most providers require exactly one of either <code>region</code> (e.g. <code>us-east-1</code>) or <code>endpoint</code> (the URL, usually for private cloud deployments)</p> + </li> + <li> + <p>Hardware requirements can be specified, including +<code>minRam</code>, <code>minCores</code>, and <code>os64Bit</code>; or as a specific <code>hardwareId</code></p> + </li> + <li> + <p>VM image constraints can be set using <code>osFamily</code> (e.g. <code>Ubuntu</code>, <code>CentOS</code>, <code>Debian</code>, <code>RHEL</code>) +and <code>osVersionRegex</code>, or specific VM images can be specified using <code>imageId</code> or <code>imageNameRegex</code></p> + </li> + <li> + <p>Specific VM images can be specified using <code>imageId</code> or <code>imageNameRegex</code></p> + </li> + <li> + <p>Specific Security Groups can be specified using <code>securityGroups</code>, as a list of strings (the existing security group names), +or <code>inboundPorts</code> can be set, as a list of numeric ports (selected clouds only)</p> + </li> + <li> + <p>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 <code>keyPair</code> (selected clouds only). +Note that if this <code>keyPair</code> does not correspond your default <code>~/.ssh/id_rsa</code>, you must typically +also specify the corresponding <code>loginUser.privateKeyFile</code> as a file or URL accessible from Brooklyn.</p> + </li> + <li> + <p>A specific VM name (often the hostname) base to be used can be specified by setting <code>groupId</code>. +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 +<code>CloudMachineNamer</code> +(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CloudMachineNamer.html">javadoc</a>, + <a href="https://github.com/apache/brooklyn/tree/0.9.0/core/src/main/java/org/apache/brooklyn/core/location/cloud/names/CloudMachineNamer.java">src</a>) +, +for example +<code>cloudMachineNamer: CustomMachineNamer</code>. +<code>CustomMachineNamer</code> +(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/core/location/cloud/names/CustomMachineNamer.html">javadoc</a>, + <a href="https://github.com/apache/brooklyn/tree/0.9.0/core/src/main/java/org/apache/brooklyn/core/location/cloud/names/CustomMachineNamer.java">src</a>)</p> + + <p>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 <code>vmNameSaltLength: 0</code> (selected clouds only). +<!-- TODO jclouds softlayer includes a 3-char hex suffix --></p> + </li> + <li> + <p>A DNS domain name where this host should be placed can be specified with <code>domainName</code> +(in selected clouds only)</p> + </li> + <li> + <p>User metadata can be attached using the syntax <code>userMetadata: { key: value, key2: "value 2" }</code> +(or <code>userMetadata=key=value,key2="value 2"</code> in a properties file)</p> + </li> + <li> + <p>By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities, +prefixed with <code>brooklyn-</code>. +This user metadata can be omitted by setting <code>includeBrooklynUserMetadata: false</code>.</p> + </li> + <li> + <p>You can specify the number of attempts Brooklyn should make to create +machines with <code>machineCreateAttempts</code> (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 +<code>ServiceRestarter</code> +(<a href="/v/latest/misc/javadoc/org/apache/brooklyn/policy/ha/ServiceRestarter.html">javadoc</a>, + <a href="https://github.com/apache/brooklyn/tree/0.9.0/policy/src/main/java/org/apache/brooklyn/policy/ha/ServiceRestarter.java">src</a>) +.</p> + </li> + <li> + <p>If you want to investigate failures, set <code>destroyOnFailure: false</code> +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.</p> + + <h6 id="os-setup">OS Setup</h6> + </li> + <li> + <p><code>user</code> and <code>password</code> can be used to configure the operating user created on cloud-provisioned machines</p> + </li> + <li> + <p>The <code>loginUser</code> config key (and subkeys) control the initial user to log in as, +in cases where this cannot be discovered from the cloud provider</p> + </li> + <li> + <p>Private keys can be specified using <code>privateKeyFile</code>; +these are not copied to provisioned machines, but are required if using a local public key +or a pre-defined <code>authorized_keys</code> on the server. +(For more information on SSH keys, see <a href="ssh-keys.html">here</a>.) </p> + </li> + <li> + <p>If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course! +<code>privateKeyPassphrase</code> does the trick (as in <code>brooklyn.location.jclouds.privateKeyPassphrase</code>, or other places +where <code>privateKeyFile</code> is valid). If you donât like keys, you can just use a plain old <code>password</code>.</p> + </li> + <li> + <p>Public keys can be specified using <code>publicKeyFile</code>, +although these can usually be omitted if they follow the common pattern of being +the private key file with the suffix <code>.pub</code> appended. +(It is useful in the case of <code>loginUser.publicKeyFile</code>, where you shouldnât need, +or might not even have, the private key of the <code>root</code> user when you log in.)</p> + </li> + <li> + <p>Provide a list of URLs to public keys in <code>extraSshPublicKeyUrls</code>, +or the data of one key in <code>extraSshPublicKeyData</code>, +to have additional public keys added to the <code>authorized_keys</code> file for logging in. +(This is supported in most but not all locations.)</p> + </li> + <li> + <p>Use <code>dontCreateUser</code> to have Brooklyn run as the initial <code>loginUser</code> (usually <code>root</code>), +without creating any other user.</p> + </li> + <li> + <p>A post-provisioning <code>setup.script</code> can be specified (as a URL) to run an additional script, +before making the <code>Location</code> available to entities, +optionally also using <code>setup.script.vars</code> (set as <code>key1:value1,key2:value2</code>)</p> + </li> + <li> + <p>Use <code>openIptables: true</code> to automatically configure <code>iptables</code>, to open the TCP ports required by +the software process. One can alternatively use <code>stopIptables: true</code> to entirely stop the +iptables service.</p> + </li> + <li> + <p>Use <code>installDevUrandom: true</code> to fall back to using <code>/dev/urandom</code> rather than <code>/dev/random</code>. This setting +is useful for cloud VMs where there is not enough random entropy, which can cause <code>/dev/random</code> to be +extremely slow (causing <code>ssh</code> to be extremely slow to respond).</p> + </li> + <li> + <p>Use <code>useJcloudsSshInit: false</code> 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).</p> + </li> + <li> + <p>Use <code>brooklyn.ssh.config.noDeleteAfterExec: true</code> 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. </p> + </li> +</ul> + +<h6 id="custom-template-options">Custom Template Options</h6> + +<p>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.</p> + +<p>Part of the process for creating a virtual machine is the creation of a jclouds <code>TemplateOptions</code> object. jclouds +providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of +type <code>AWSEC2TemplateOptions</code>. By <a href="https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java">examining the source code</a>, +you can see all of the options available to you.</p> + +<p>The <code>templateOptions</code> config key takes a map. The keys to the map are method names, and Brooklyn will find the method on +the <code>TemplateOptions</code> 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.</p> + +<p>For example, here is a complete blueprint that sets some AWS EC2 specific options:</p> + +<pre><code>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'] +</code></pre> + +<p>Here you can see that we set three template options:</p> + +<ul> + <li><code>subnetId</code> is an example of a single parameter method. Brooklyn will effectively try to run the statement +<code>templateOptions.subnetId("subnet-041c88373");</code></li> + <li><code>mapNewVolumeToDeviceName</code> 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 <code>templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);</code></li> + <li><code>securityGroupIds</code> 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 <code>List</code>; such a method does exist so +the operation will succeed.</li> +</ul> + +<p>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.</p> + +<p>See the following resources for more information:</p> + +<ul> + <li><a href="vpc-issues.html">AWS VPC issues which may affect users with older AWS accounts</a></li> + <li><a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types">Amazon EC2 and Amazon Virtual Private Cloud</a></li> + <li><a href="http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html">Your Default VPC and Subnets</a></li> + <li><a href="http://aws.amazon.com/vpc/faqs/#Default_VPCs">Amazon VPC FAQs</a></li> +</ul> + +<h3 id="more-details-on-specific-clouds">More Details on Specific Clouds</h3> + +<p>To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the <code>identity</code> and +<code>credential</code> in Brooklyn terminology. </p> + +<p>For private clouds (and for some clouds being targeted using a standard API), the <code>endpoint</code> +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 <code>region</code> where you might want to deploy. </p> + +<p>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:</p> + +<ul> + <li>The <strong><a href="/v/latest/start/brooklyn.properties">template brooklyn.properties</a></strong> 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.</li> + <li>The <strong><a href="https://jclouds.apache.org/guides">jclouds guides</a></strong> describes low-level configuration +sometimes required for various clouds.</li> +</ul> + +<h2 id="amazon-web-services-aws">Amazon Web Services (AWS)</h2> + +<h3 id="credentials">Credentials</h3> + +<p>AWS has an âaccess keyâ and a âsecret keyâ, which correspond to Brooklynâs identity and credential +respectively.</p> + +<p>These keys are the way for any programmatic mechanism to access the AWS API.</p> + +<p>To generate an access key and a secret key, see <a href="http://jclouds.apache.org/guides/aws">jclouds instructions</a> +and <a href="http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html">AWS IAM instructions</a>.</p> + +<p>An example of the expected format is shown below:</p> + +<pre><code>brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST +brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm +</code></pre> + +<h3 id="tidying-up-after-jclouds">Tidying up after jclouds</h3> + +<p>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.</p> + +<p>There is utility written by Cloudsoft for deleting these unused resources: +http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.</p> + +<h3 id="using-subnets-and-security-groups">Using Subnets and Security Groups</h3> + +<p>Apache Brooklyn can run with AWS VPC and both public and private subnets. +Simply provide the <code>subnet-a1b2c3d4</code> as the <code>networkName</code> when deploying:</p> + +<pre><code>location: + jclouds:aws-ec2: + region: us-west-1 + networkName: subnet-a1b2c3d4 # use your subnet ID +</code></pre> + +<p>Subnets are typically used in conjunction with security groups. +Brooklyn does <em>not</em> 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 <code>securityGroups</code> on the location +or as <code>provisioning.properties</code> on the entities.</p> + +<p>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.</p> + +<h3 id="ec2-classic-problems-with-vpc-only-hardware-instance-types">EC2 âClassicâ Problems with VPC-only Hardware Instance Types</h3> + +<p>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 <code>minRam: 8gb</code>, Brooklyn may opt for an <code>m4.large</code>, +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:</p> + +<pre><code>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. +</code></pre> + +<p>This is a limitation of âlegacyâ accounts. The easiest fixes are either:</p> + +<ul> + <li>specify an instance type which is supported in classic, such as <code>m3.xlarge</code> (see below)</li> + <li>move to a different region where VPC is the default +(<code>eu-central-1</code> should work as it <em>only</em> offers VPC mode, +irrespective of the age of your AWS account)</li> + <li>get a new AWS account â âVPCâ will be the default mode +(Amazon recommend this and if you want to migrate existing deployments +they provide <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html">detailed instructions</a>) </li> +</ul> + +<p>To understand the situation, the following resources may be useful:</p> + +<ul> + <li>Background on VPC vs Classic: <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html">http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html</a></li> + <li>Good succinct answers to FAQs: <a href="">http://aws.amazon.com/vpc/faqs/#Default_VPCs</a></li> + <li>Check if a region in your account is âVPCâ or âClassicâ: <a href="">http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability</a> </li> + <li>Regarding instance types: + <ul> + <li>All instance types: <a href="">https://aws.amazon.com/ec2/instance-types</a></li> + <li>Those which require VPC: <a href="">http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types</a></li> + </ul> + </li> +</ul> + +<p>If you want to solve this problem with your existing account, +you can create a VPC and instruct Brooklyn to use it:</p> + +<ol> + <li>Use the âStart VPC Wizardâ option in <a href="https://console.aws.amazon.com/vpc">the VPC dashboard</a>, + making sure it is for the right region, and selecting a âSingle Public Subnetâ. + (More information is in <a href="http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc">these AWS instructions</a>.)</li> + <li>Once the VPC is created, open the âSubnetsâ view and modify the âPublic subnetâ +so that it will âAuto-assign Public IPâ.</li> + <li>Next click on the âSecurity Groupsâ and find the <code>default</code> 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â.)</li> + <li>Finally make a note of the subnet ID (e.g. <code>subnet-a1b2c3d4</code>) for use in Brooklyn.</li> +</ol> + +<p>You can then deploy blueprints to the subnet, allowing VPC hardware instance types, +by specifying the subnet ID as the <code>networkName</code> in your YAML blueprint. +This is covered in the previous section, âUsing Subnetsâ.</p> + +<h2 id="google-compute-engine-gce">Google Compute Engine (GCE)</h2> + +<h3 id="credentials-1">Credentials</h3> + +<p>GCE uses a service account e-mail address for the identity and a private key as the credential.</p> + +<p>To obtain these from GCE, see the <a href="https://jclouds.apache.org/guides/google">jclouds instructions</a>.</p> + +<p>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 <code>\n</code> representing the new line characters:</p> + +<pre><code>brooklyn.location.jclouds.google-compute-engine.identity=123456789...@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----- +</code></pre> + +<h3 id="quotas">Quotas</h3> + +<p>GCE accounts can have low default <a href="https://cloud.google.com/compute/docs/resource-quotas">quotas</a>.</p> + +<p>It is easy to requesta quota increase by submitting a <a href="https://support.google.com/cloud/answer/6075746?hl=en">quota increase form</a>.</p> + +<h3 id="networks">Networks</h3> + +<p>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.</p> + +<p>To create a network, see <a href="https://cloud.google.com/compute/docs/networking#networks_1">GCE network instructions</a>.</p> + +<p>For example, for dev/demo purposes an âeverythingâ network could be created that opens all ports.</p> + +<table> + <tbody> + <tr> + <td>Â </td> + <td>Name</td> + <td>Â </td> + <td>everything</td> + </tr> + <tr> + <td>Â </td> + <td>Description</td> + <td>Â </td> + <td>opens all tcp ports</td> + </tr> + <tr> + <td>Â </td> + <td>Source IP Ranges</td> + <td>Â </td> + <td>0.0.0.0/0</td> + </tr> + <tr> + <td>Â </td> + <td>Allowed protocols and ports</td> + <td>Â </td> + <td>tcp:0-65535 and udp:0-65535</td> + </tr> + </tbody> +</table> + +<h2 id="ibm-softlayer">IBM SoftLayer</h2> + +<h3 id="vlan-selection">VLAN Selection</h3> + +<p>SoftLayer may provision VMs in different VLANs, even within the same region. +Some applications require VMs to be on the <em>same</em> internal subnet; blueprints +for these can specify this behaviour in SoftLayer in one of two ways.</p> + +<p>The VLAN ID can be set explicitly using the fields +<code>primaryNetworkComponentNetworkVlanId</code> and +<code>primaryBackendNetworkComponentNetworkVlanId</code> of <code>SoftLayerTemplateOptions</code> +when specifying the location being used in the blueprint, as follows:</p> + +<p><code>YAML +location: + jclouds:softlayer: + region: ams01 + templateOptions: + # Enter your preferred network IDs + primaryNetworkComponentNetworkVlanId: 1153481 + primaryBackendNetworkComponentNetworkVlanId: 1153483 +</code></p> + +<p>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</p> + +<p>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.</p> + +<p>To use this method, we tell brooklyn to use <code>SoftLayerSameVlanLocationCustomizer</code> +as a location customizer. This can be done on a location as follows:</p> + +<p><code>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 +</code></p> + +<p>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.</p> + +<p>It is also possible with many blueprints to specify this as one of the +<code>provisioning.properties</code> on an <em>application</em>:</p> + +<p><code>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 +</code></p> + +<p>If you are writing an entity in Java, you can also use the helper +method <code>forScope(String)</code> to create the customizer. Configure the +provisioning flags as follows:</p> + +<p><code>Java +JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope"); +flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans)); +</code></p> + +<h3 id="configuration-options">Configuration Options</h3> + +<p>The allowed configuration keys for the <code>SoftLayerSameVlanLocationCustomizer</code> +are:</p> + +<ul> + <li> + <p><strong>softlayer.vlan.scopeUid</strong> The scope identifier for locations whose +VMs will have the same VLAN.</p> + </li> + <li> + <p><strong>softlayer.vlan.timeout</strong> The amount of time to wait for a VM to +be configured before timing out without setting the VLAN ids.</p> + </li> + <li> + <p><strong>softlayer.vlan.publicId</strong> A specific public VLAN ID to use for +the specified scope.</p> + </li> + <li> + <p><strong>softlayer.vlan.privateId</strong> A specific private VLAN ID to use for +the specified scope.</p> + </li> +</ul> + +<p>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.</p> + +<p><strong><em>NOTE</em></strong> If the SoftLayer location is already configured with specific VLANs +then this customizer will have no effect.</p> + +<h3 id="inheritance-and-named-locations">Inheritance and Named Locations</h3> + +<p>Named locations can be defined for commonly used groups of properties, +with the syntax <code>brooklyn.location.named.your-group-name.</code> +followed by the relevant properties. +These can be accessed at runtime using the syntax <code>named:your-group-name</code> as the deployment location.</p> + +<p>Some illustrative examples using named locations and +showing the syntax and properties above are as follows:</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Production pool of machines for my application (deploy to named:prod1)</span> +brooklyn.location.named.prod1<span class="o">=</span>byon:<span class="o">(</span><span class="nv">hosts</span><span class="o">=</span><span class="s2">"10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}"</span><span class="o">)</span> +brooklyn.location.named.prod1.user<span class="o">=</span>produser1 +brooklyn.location.named.prod1.privateKeyFile<span class="o">=</span>~/.ssh/produser_id_rsa +brooklyn.location.named.prod1.privateKeyPassphrase<span class="o">=</span>s3cr3tCOMPANYpassphrase + +<span class="c"># AWS using my company's credentials and image standard, then labelling images so others know they're mine</span> +brooklyn.location.named.company-jungle<span class="o">=</span>jclouds:aws-ec2:us-west-1 +brooklyn.location.named.company-jungle.identity<span class="o">=</span>BCDEFGHIJKLMNOPQRSTU +brooklyn.location.named.company-jungle.privateKeyFile<span class="o">=</span>~/.ssh/public_clouds/company_aws_id_rsa +brooklyn.location.named.company-jungle.imageId<span class="o">=</span>ami-12345 +brooklyn.location.named.company-jungle.minRam<span class="o">=</span>2048 +brooklyn.location.named.company-jungle.userMetadata<span class="o">=</span><span class="nv">application</span><span class="o">=</span>my-jungle-app,owner<span class="o">=</span><span class="s2">"Bob Johnson"</span> +brooklyn.location.named.company-jungle.machineCreateAttempts<span class="o">=</span>2 + +brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span><span class="nv">Centos</span> <span class="o">=</span> jclouds:aws-ec2 +brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.region <span class="o">=</span> us-east-1 +brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.imageId<span class="o">=</span>us-east-1/ami-7d7bfc14 +brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.user<span class="o">=</span>root +brooklyn.location.named.AWS<span class="se">\ </span>Virginia<span class="se">\ </span>Large<span class="se">\ </span>Centos.minRam<span class="o">=</span>4096</code></pre></div> + +<p>Named locations can refer to other named locations using <code>named:xxx</code> as their value. +These will inherit the configuration and can override selected keys. +Properties set in the namespace of the provider (e.g. <code>b.l.jclouds.aws-ec2.KEY=VALUE</code>) +will be inherited by everything which extends AWS +Sub-prefix strings are also inherited up to <code>brooklyn.location.*</code>, +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.</p> + +<p>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 <code>prod1</code>: </p> + +<!-- tested in JcloudsLocationResolverTest --> +<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.extraSshPublicKeyUrls<span class="o">=</span>http://me.com/public_key +brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls<span class="o">=</span><span class="s2">"[ \"http://me.com/public_key\", \"http://me.com/aws_public_key\" ]"</span> +brooklyn.location.named.prod1.extraSshPublicKeyUrls<span class="o">=</span></code></pre></div> + +<p>And in the example below, a config key is repeatedly overridden. +Deploying <code>location: named:my-extended-aws</code> will result in an <code>aws-ec2</code> machine in <code>us-west-1</code> (by inheritance) +with <code>VAL6</code> for <code>KEY</code>:</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.KEY<span class="o">=</span>VAL1 +brooklyn.location.jclouds.KEY<span class="o">=</span>VAL2 +brooklyn.location.jclouds.aws-ec2.KEY<span class="o">=</span>VAL3 +brooklyn.location.jclouds.aws-...@us-west-1.key<span class="o">=</span>VAL4 +brooklyn.location.named.my-aws<span class="o">=</span>jclouds:aws-ec2:us-west-1 +brooklyn.location.named.my-aws.KEY<span class="o">=</span>VAL5 +brooklyn.location.named.my-extended-aws<span class="o">=</span>named:my-aws +brooklyn.location.named.my-extended-aws.KEY<span class="o">=</span>VAL6</code></pre></div> + +<h3 id="byon">BYON</h3> + +<p>â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.</p> + +<p>Your nodes must meet the following prerequisites:</p> + +<ul> + <li>A suitable OS must have been installed on all nodes</li> + <li>The node must be running sshd (or similar)</li> + <li>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 <a href="ssh-keys.html">here</a>.) </li> +</ul> + +<p>To deploy to machines with known IPâs in a blueprint, use the following syntax:</p> + +<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">byon</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">brooklyn</span> + <span class="l-Scalar-Plain">privateKeyFile</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">~/.ssh/brooklyn.pem</span> + <span class="l-Scalar-Plain">hosts</span><span class="p-Indicator">:</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">192.168.0.18</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">192.168.0.19</span></code></pre></div> + +<p>Some of the login properties as described above for jclouds are supported, +but not <code>loginUser</code> (as no users are created), and not any of the +VM creation parameters such as <code>minRam</code> and <code>imageId</code>. +(These clearly do not apply in the same way, and they are <em>not</em> +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.</p> + +<p>Named locations can also be configured in your <code>brooklyn.properties</code>, +using the format <code>byon:(key=value,key2=value2)</code>. +For convenience, for hosts wildcard globs are supported.</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span><span class="nv">Example</span><span class="o">=</span>byon:<span class="o">(</span><span class="nv">hosts</span><span class="o">=</span><span class="s2">"10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}"</span><span class="o">)</span> +brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.user<span class="o">=</span>produser1 +brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.privateKeyFile<span class="o">=</span>~/.ssh/produser_id_rsa +brooklyn.location.named.On-Prem<span class="se">\ </span>Iron<span class="se">\ </span>Example.privateKeyPassphrase<span class="o">=</span>s3cr3tpassphrase</code></pre></div> + +<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p> + +<p>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 +<code>ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53</code>. The second is a windows machine, reachable +over WinRM. Each machine has also has a private address (e.g. for within a private network).</p> + +<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">byon</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">hosts</span><span class="p-Indicator">:</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">ssh</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">50.51.52.53:8022</span> + <span class="l-Scalar-Plain">privateAddresses</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="nv">10.0.0.1</span><span class="p-Indicator">]</span> + <span class="l-Scalar-Plain">privateKeyFile</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">~/.ssh/brooklyn.pem</span> + <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">myuser</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">winrm</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">50.51.52.54:8985</span> + <span class="l-Scalar-Plain">privateAddresses</span><span class="p-Indicator">:</span> <span class="p-Indicator">[</span><span class="nv">10.0.0.2</span><span class="p-Indicator">]</span> + <span class="l-Scalar-Plain">password</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">mypassword</span> + <span class="l-Scalar-Plain">user</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">myuser</span> + <span class="l-Scalar-Plain">osFamily</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">windows</span></code></pre></div> + +<p>The BYON location also supports a machine chooser, using the config key <code>byon.machineChooser</code>. +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 <code>location.obtain()</code>) to find the config that matches the requirements of the entity being +provisioned. See <code>FixedListMachineProvisioningLocation.MACHINE_CHOOSER</code>.</p> + +<h3 id="ssh-keys">SSH Keys</h3> + +<p>SSH keys are one of the simplest and most secure ways to access remote servers. +They consist of two parts:</p> + +<ul> + <li> + <p>A private key (e.g. <code>id_rsa</code>) which is known only to one party or group</p> + </li> + <li> + <p>A public key (e.g. <code>id_rsa.pub</code>) 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)</p> + </li> +</ul> + +<p>In this way, someone â such as you â can have a private key, +and can install a public key on a remote machine (in an <code>authorized_keys</code> file) +for secure automated access. +Commands such as <code>ssh</code> (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.</p> + +<h4 id="creating-an-ssh-key">Creating an SSH Key</h4> + +<p>If you donât have an SSH key, create one with:</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>ssh-keygen -t rsa -N <span class="s2">""</span> -f ~/.ssh/id_rsa</code></pre></div> + +<h4 id="localhost-setup">Localhost Setup</h4> + +<p>If you want to deploy to <code>localhost</code>, ensure that you have a public and private key, +and that your key is authorized for ssh access:</p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected.</span> +<span class="nv">$ </span>cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys</code></pre></div> + +<p>Now verify that your setup by running the command: <code>ssh localhost echo hello world</code></p> + +<p>If your setup is correct, you should see <code>hello world</code> printed back at you.</p> + +<p>On the first connection, you may see a message similar to this:</p> + +<pre> +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)? +</pre> + +<p>Simply answer âyesâ and then repeat the command again.</p> + +<p>If this isnât the case, see below. </p> + +<h4 id="potential-problems">Potential Problems</h4> + +<ul> + <li> + <p><strong>MacOS user?</strong> In addition to the above, enable âRemote Loginâ in âSystem Preferences > Sharingâ.</p> + </li> + <li> + <p><strong>Got a passphrase?</strong> Set <code>brooklyn.location.localhost.privateKeyPassphrase</code> +as described <a href="index.html#os-setup">here</a>. +If youâre not sure, or you donât know what a passphrase is, you can test this by executing <code>ssh-keygen -y</code>. +If it does <em>not</em> ask for a passphrase, then your key has no passphrase. +If your key does have a passphrase, you can remove it by running <code>ssh-keygen -p</code>.</p> + </li> + <li> + <p>Check that you have an <code>~/.ssh/id_rsa</code> file (or <code>id_dsa</code>) and a corresponding public key with a <code>.pub</code> extension; +if not, create one as described above</p> + </li> + <li> + <p><code>~/.ssh/</code> 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 <code>ls -l ~/.ssh/</code>: lines should start with <code>-rw-------</code> or <code>-r--------</code> (or <code>-rwx------</code> for directories). +If it does not, execute <code>chmod go-rwx ~/.ssh ~/.ssh/*</code>.</p> + </li> + <li> + <p>Sometimes machines are configured with different sets of support SSL/TLS versions and ciphers; +if command-line <code>ssh</code> and <code>scp</code> work, but Brooklyn/java does not, check the versions enabled in Java and on both servers.</p> + </li> + <li> + <p>Missing entropy: creating and using ssh keys requires randomness available on the servers, +usually in <code>/dev/random</code>; see <a href="/documentation/increase-entropy.html">here</a> for more information</p> + </li> +</ul> + +<h3 id="localhost">Localhost</h3> + +<p>If passwordless ssh login to <code>localhost</code> and passwordless <code>sudo</code> is enabled on your +machine, you should be able to deploy blueprints with no special configuration, +just by specifying <code>location: localhost</code> in YAML.</p> + +<p>If you use a passpharse or prefer a different key, these can be configured as follows: </p> + +<div class="highlight"><pre><code class="language-bash" data-lang="bash">brooklyn.location.localhost.privateKeyFile<span class="o">=</span>~/.ssh/brooklyn_key +brooklyn.location.localhost.privateKeyPassphrase<span class="o">=</span>s3cr3tPASSPHRASE</code></pre></div> + +<p>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 <a href="/v/latest/ops/catalog/index.html#locations-in-catalog">catalog entry</a> for easy reusability.</p> + +<p>If you encounter issues or for more information, see <a href="ssh-keys.html#localhost-setup">SSH Keys Localhost Setup</a>. </p> + +<p>If you are normally prompted for a password when executing <code>sudo</code> commands, passwordless <code>sudo</code> must also be enabled. To enable passwordless <code>sudo</code> for your account, a line must be added to the system <code>/etc/sudoers</code> file. To edit the file, use the <code>visudo</code> command: +<div class="highlight"><pre><code class="language-bash" data-lang="bash">sudo visudo</code></pre></div> +Add this line at the bottom of the file, replacing <code>username</code> with your own user: +<div class="highlight"><pre><code class="language-bash" data-lang="bash">username <span class="nv">ALL</span><span class="o">=(</span>ALL<span class="o">)</span> NOPASSWD: ALL</code></pre></div> +If executing the following command does not ask for your password, then <code>sudo</code> should be setup correctly: +<div class="highlight"><pre><code class="language-bash" data-lang="bash">sudo ls</code></pre></div></p> + +<h3 id="specialized-locations">Specialized Locations</h3> + +<p>Some additional location types are supported for specialized situations:</p> + +<h4 id="single-host">Single Host</h4> + +<p>The spec <code>host</code>, taking a string argument (the address) or a map (<code>host</code>, <code>user</code>, <code>password</code>, etc.), +provides a convenient syntax when specifying a single host. +For example:</p> + +<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">services</span><span class="p-Indicator">:</span> +<span class="p-Indicator">-</span> <span class="l-Scalar-Plain">type</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">org.apache.brooklyn.entity.webapp.jboss.JBoss7Server</span> + <span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">host</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">192.168.0.1</span></code></pre></div> + +<p>Or, in <code>brooklyn.properties</code>, set <code>brooklyn.location.named.host1=host:(192.168.0.1)</code>.</p> + +<h4 id="the-multi-location">The Multi Location</h4> + +<p>The spec <code>multi</code> allows multiple locations, specified as <code>targets</code>, +to be combined and treated as one location. +When the first target is full, the next is tried, and so on:</p> + +<div class="highlight"><pre><code class="language-yaml" data-lang="yaml"><span class="l-Scalar-Plain">location</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">multi</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">targets</span><span class="p-Indicator">:</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">byon:(hosts=192.168.0.1)</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">acct1</span> + <span class="p-Indicator">-</span> <span class="l-Scalar-Plain">jclouds:aws-ec2</span><span class="p-Indicator">:</span> + <span class="l-Scalar-Plain">identity</span><span class="p-Indicator">:</span> <span class="l-Scalar-Plain">acct2</span></code></pre></div> + +<p>The example above provisions the first node to <code>192.168.0.1</code>, +then it provisions into <code>acct1</code> at Amazon if possible, +and then to <code>acct2</code>.</p> + +<h4 id="the-server-pool">The Server Pool</h4> + +<p>The <code>ServerPool</code> + (<a href="/v/latest/misc/javadoc/org/apache/brooklyn/entity/machine/pool/ServerPool.html">javadoc</a>, + <a href="https://github.com/apache/brooklyn/tree/0.9.0/software/base/src/main/java/org/apache/brooklyn/entity/machine/pool/ServerPool.java">src</a>)</p> + +<p>entity type allows defining an entity which becomes available as a location.</p> + </div> @@ -453,6 +1342,41 @@ can also be set <code>in </code>provisio <div class="sub-item"> + <a href="/v/latest/ops/locations/index.html#clouds" class="list-group-item sub-item section" section-target="#clouds"> + Clouds + </a> + + + <a href="/v/latest/ops/locations/index.html#more-details-on-specific-clouds" class="list-group-item sub-item section" section-target="#more-details-on-specific-clouds"> + More on Clouds + </a> + + + <a href="/v/latest/ops/locations/index.html#inheritance-and-named-locations" class="list-group-item sub-item section" section-target="#inheritance-and-named-locations"> + Named Locations + </a> + + + <a href="/v/latest/ops/locations/index.html#byon" class="list-group-item sub-item section" section-target="#byon"> + BYON + </a> + + + <a href="/v/latest/ops/locations/index.html#ssh-keys" class="list-group-item sub-item section" section-target="#ssh-keys"> + SSH Keys + </a> + + + <a href="/v/latest/ops/locations/index.html#localhost" class="list-group-item sub-item section" section-target="#localhost"> + Localhost + </a> + + + <a href="/v/latest/ops/locations/index.html#specialized-locations" class="list-group-item sub-item section" section-target="#specialized-locations"> + Specialized Locations + </a> + + <a href="/v/latest/ops/locations/location-customizers.html" class="list-group-item sub-item " > Location Customizers </a>
Modified: brooklyn/site/v/latest/ops/locations/location-customizers.html URL: http://svn.apache.org/viewvc/brooklyn/site/v/latest/ops/locations/location-customizers.html?rev=1740156&r1=1740155&r2=1740156&view=diff ============================================================================== --- brooklyn/site/v/latest/ops/locations/location-customizers.html (original) +++ brooklyn/site/v/latest/ops/locations/location-customizers.html Wed Apr 20 15:19:21 2016 @@ -566,6 +566,55 @@ config option when calling <code>locatio + <a href="/v/latest/ops/locations/index.html#clouds" class="list-group-item">Clouds + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#more-details-on-specific-clouds" class="list-group-item">More on Clouds + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#inheritance-and-named-locations" class="list-group-item">Named Locations + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#byon" class="list-group-item">BYON + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#ssh-keys" class="list-group-item">SSH Keys + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#localhost" class="list-group-item">Localhost + </a> + + + + + + <a href="/v/latest/ops/locations/index.html#specialized-locations" class="list-group-item">Specialized Locations + </a> + + + + + <a href="/v/latest/ops/locations/location-customizers.html" class="list-group-item active">Location Customizers </a>