Removed child pages from locations
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/33bca1b9 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/33bca1b9 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/33bca1b9 Branch: refs/heads/0.9.0 Commit: 33bca1b9e4340154f0b6278dc19acda47c926591 Parents: e7ef680 Author: Duncan Godwin <duncan.god...@cloudsoftcorp.com> Authored: Tue May 10 16:26:28 2016 +0100 Committer: Duncan Godwin <duncan.god...@cloudsoftcorp.com> Committed: Thu May 12 12:10:55 2016 +0100 ---------------------------------------------------------------------- guide/ops/locations/_byon.md | 77 ++++++ guide/ops/locations/_clouds.md | 252 +++++++++++++++++ .../_inheritance-and-named-locations.md | 80 ++++++ guide/ops/locations/_localhost.md | 36 +++ guide/ops/locations/_more-clouds.md | 274 +++++++++++++++++++ guide/ops/locations/_special-locations.md | 54 ++++ guide/ops/locations/_ssh-keys.md | 88 ++++++ guide/ops/locations/byon.md | 77 ------ guide/ops/locations/cloud-credentials.md | 2 +- guide/ops/locations/clouds.md | 252 ----------------- .../inheritance-and-named-locations.md | 80 ------ guide/ops/locations/localhost.md | 36 --- guide/ops/locations/more-clouds.md | 274 ------------------- guide/ops/locations/special-locations.md | 54 ---- guide/ops/locations/ssh-keys.md | 88 ------ 15 files changed, 862 insertions(+), 862 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_byon.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_byon.md b/guide/ops/locations/_byon.md new file mode 100644 index 0000000..38f6595 --- /dev/null +++ b/guide/ops/locations/_byon.md @@ -0,0 +1,77 @@ +--- +section: BYON +section_position: 4 +section_type: inline +--- + +### 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](ssh-keys.html).) + +To deploy to machines with known IP's in a blueprint, use the following syntax: + +{% highlight yaml %} +location: + byon: + user: brooklyn + privateKeyFile: ~/.ssh/brooklyn.pem + hosts: + - 192.168.0.18 + - 192.168.0.19 +{% endhighlight %} + +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. + +{% highlight bash %} +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 +{% endhighlight %} + +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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) 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). + +{% highlight yaml %} +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 +{% endhighlight %} + +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`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_clouds.md b/guide/ops/locations/_clouds.md new file mode 100644 index 0000000..22afd69 --- /dev/null +++ b/guide/ops/locations/_clouds.md @@ -0,0 +1,252 @@ +--- +section: Clouds +section_type: inline +section_position: 1 +--- + +### Clouds + +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 [see the full list](http://jclouds.apache.org/reference/providers/)): + +* `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`: + +{% highlight yaml %} +location: + jclouds:aws-ec2: + identity: ABCDEFGHIJKLMNOPQRST + credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l +{% endhighlight %} + +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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` +in the `jclouds.<provider>` namespace: + +{% highlight bash %} +brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST +brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l +{% endhighlight %} + +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 <a href="http://jclouds.org";>Apache jclouds</a>. +This location will be saved as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) 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](#more-details-on-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 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 `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). + +1. 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) + +1. give `sudo` access to the newly created user (override with `grantUserSudo: false`) + +1. 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 +{% include java_link.html class_name="JcloudsLocationConfig" package_path="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}. + +###### 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 + {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}, + for example + `cloudMachineNamer: CustomMachineNamer`. + {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %} + 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). + <!-- TODO jclouds softlayer includes a 3-char hex suffix --> + +- 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 + {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}. + +- 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](ssh-keys.html).) + +- 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](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java), +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](vpc-issues.html) +- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types) +- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html) +- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs) + \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_inheritance-and-named-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_inheritance-and-named-locations.md b/guide/ops/locations/_inheritance-and-named-locations.md new file mode 100644 index 0000000..53fe904 --- /dev/null +++ b/guide/ops/locations/_inheritance-and-named-locations.md @@ -0,0 +1,80 @@ +--- +section: Inheritance and Named Locations +title: Named Locations +section_type: inline +section_position: 3 +--- + +### 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: + +{% highlight bash %} +# 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 +{% endhighlight %} + +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`: + +<!-- tested in JcloudsLocationResolverTest --> +{% highlight bash %} +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= +{% endhighlight %} + +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`: + +{% highlight bash %} +brooklyn.location.KEY=VAL1 +brooklyn.location.jclouds.KEY=VAL2 +brooklyn.location.jclouds.aws-ec2.KEY=VAL3 +brooklyn.location.jclouds.aws-...@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 +{% endhighlight %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_localhost.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_localhost.md b/guide/ops/locations/_localhost.md new file mode 100644 index 0000000..7ac906a --- /dev/null +++ b/guide/ops/locations/_localhost.md @@ -0,0 +1,36 @@ +--- +section: Localhost +section_position: 6 +section_type: inline +--- + +### 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: + +{% highlight bash %} +brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key +brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE +{% endhighlight %} + +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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) for easy reusability. + +If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#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: +{% highlight bash %} +sudo visudo +{% endhighlight %} +Add this line at the bottom of the file, replacing `username` with your own user: +{% highlight bash %} +username ALL=(ALL) NOPASSWD: ALL +{% endhighlight %} +If executing the following command does not ask for your password, then `sudo` should be setup correctly: +{% highlight bash %} +sudo ls +{% endhighlight %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_more-clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_more-clouds.md b/guide/ops/locations/_more-clouds.md new file mode 100644 index 0000000..acfd274 --- /dev/null +++ b/guide/ops/locations/_more-clouds.md @@ -0,0 +1,274 @@ +--- +section: More Details on Specific Clouds +title: More on Clouds +section_type: inline +section_position: 2 +--- + +### 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]({{ site.path.guide }}/start/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](https://jclouds.apache.org/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](http://jclouds.apache.org/guides/aws) +and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html). + +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](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) + +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](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](https://console.aws.amazon.com/vpc), + making sure it is for the right region, and selecting a "Single Public Subnet". + (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).) +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](https://jclouds.apache.org/guides/google). + +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=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----- + + +### Quotas + +GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas). + +It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en). + + +### 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](https://cloud.google.com/compute/docs/networking#networks_1). + +For example, for dev/demo purposes an "everything" network could be created that opens all ports. + +|| Name || everything | +|| Description || opens all tcp ports | +|| Source IP Ranges || 0.0.0.0/0 | +|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 | + +## 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_special-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_special-locations.md b/guide/ops/locations/_special-locations.md new file mode 100644 index 0000000..8f19fa4 --- /dev/null +++ b/guide/ops/locations/_special-locations.md @@ -0,0 +1,54 @@ +--- +section: Specialized Locations +section_position: 7 +section_type: inline +--- + +### 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: + +{% highlight yaml %} +services: +- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server + location: + host: 192.168.0.1 +{% endhighlight %} + +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: + +{% highlight yaml %} +location: + multi: + targets: + - byon:(hosts=192.168.0.1) + - jclouds:aws-ec2: + identity: acct1 + - jclouds:aws-ec2: + identity: acct2 +{% endhighlight %} + +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 {% include java_link.html class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/pool" project_subpath="software/base" %} +entity type allows defining an entity which becomes available as a location. + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/_ssh-keys.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_ssh-keys.md b/guide/ops/locations/_ssh-keys.md new file mode 100644 index 0000000..03ee84e --- /dev/null +++ b/guide/ops/locations/_ssh-keys.md @@ -0,0 +1,88 @@ +--- +section: SSH Keys +section_position: 5 +section_type: inline +--- + +### 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: + +{% highlight bash %} +$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa +{% endhighlight %} + + +#### 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: + +{% highlight bash %} +# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected. +$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys +{% endhighlight %} + +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: + +<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> + +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](index.html#os-setup). + 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]({{ site.path.website }}/documentation/increase-entropy.html) for more information http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/byon.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/byon.md b/guide/ops/locations/byon.md deleted file mode 100644 index 38f6595..0000000 --- a/guide/ops/locations/byon.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -section: BYON -section_position: 4 -section_type: inline ---- - -### 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](ssh-keys.html).) - -To deploy to machines with known IP's in a blueprint, use the following syntax: - -{% highlight yaml %} -location: - byon: - user: brooklyn - privateKeyFile: ~/.ssh/brooklyn.pem - hosts: - - 192.168.0.18 - - 192.168.0.19 -{% endhighlight %} - -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. - -{% highlight bash %} -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 -{% endhighlight %} - -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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) 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). - -{% highlight yaml %} -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 -{% endhighlight %} - -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`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/cloud-credentials.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/cloud-credentials.md b/guide/ops/locations/cloud-credentials.md index 1594012..36041e0 100644 --- a/guide/ops/locations/cloud-credentials.md +++ b/guide/ops/locations/cloud-credentials.md @@ -3,4 +3,4 @@ title: More Clouds layout: website-normal --- -This page has moved. See [More Clouds](more-clouds.html) instead. +This page has moved. See [More Clouds](index.html#more-details-on-specific-clouds) instead. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/clouds.md b/guide/ops/locations/clouds.md deleted file mode 100644 index 08109e0..0000000 --- a/guide/ops/locations/clouds.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -section: Clouds -section_type: inline -section_position: 1 ---- - -### Clouds - -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 [see the full list](http://jclouds.apache.org/reference/providers/)): - -* `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`: - -{% highlight yaml %} -location: - jclouds:aws-ec2: - identity: ABCDEFGHIJKLMNOPQRST - credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} - -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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` -in the `jclouds.<provider>` namespace: - -{% highlight bash %} -brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST -brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} - -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 <a href="http://jclouds.org";>Apache jclouds</a>. -This location will be saved as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) 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](more-clouds.html)**. - -#### 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 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 `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). - -1. 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) - -1. give `sudo` access to the newly created user (override with `grantUserSudo: false`) - -1. 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 -{% include java_link.html class_name="JcloudsLocationConfig" package_path="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}. - -###### 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 - {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}, - for example - `cloudMachineNamer: CustomMachineNamer`. - {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %} - 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). - <!-- TODO jclouds softlayer includes a 3-char hex suffix --> - -- 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 - {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}. - -- 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](ssh-keys.html).) - -- 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](https://github.com/jclouds/jclouds/blob/jclouds-1.9.0/providers/aws-ec2/src/main/java/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.java), -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](vpc-issues.html) -- [Amazon EC2 and Amazon Virtual Private Cloud](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types) -- [Your Default VPC and Subnets](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html) -- [Amazon VPC FAQs](http://aws.amazon.com/vpc/faqs/#Default_VPCs) - \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/inheritance-and-named-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/inheritance-and-named-locations.md b/guide/ops/locations/inheritance-and-named-locations.md deleted file mode 100644 index 53fe904..0000000 --- a/guide/ops/locations/inheritance-and-named-locations.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -section: Inheritance and Named Locations -title: Named Locations -section_type: inline -section_position: 3 ---- - -### 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: - -{% highlight bash %} -# 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 -{% endhighlight %} - -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`: - -<!-- tested in JcloudsLocationResolverTest --> -{% highlight bash %} -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= -{% endhighlight %} - -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`: - -{% highlight bash %} -brooklyn.location.KEY=VAL1 -brooklyn.location.jclouds.KEY=VAL2 -brooklyn.location.jclouds.aws-ec2.KEY=VAL3 -brooklyn.location.jclouds.aws-...@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 -{% endhighlight %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/localhost.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/localhost.md b/guide/ops/locations/localhost.md deleted file mode 100644 index 7ac906a..0000000 --- a/guide/ops/locations/localhost.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -section: Localhost -section_position: 6 -section_type: inline ---- - -### 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: - -{% highlight bash %} -brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key -brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE -{% endhighlight %} - -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]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) for easy reusability. - -If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#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: -{% highlight bash %} -sudo visudo -{% endhighlight %} -Add this line at the bottom of the file, replacing `username` with your own user: -{% highlight bash %} -username ALL=(ALL) NOPASSWD: ALL -{% endhighlight %} -If executing the following command does not ask for your password, then `sudo` should be setup correctly: -{% highlight bash %} -sudo ls -{% endhighlight %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/more-clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/more-clouds.md b/guide/ops/locations/more-clouds.md deleted file mode 100644 index acfd274..0000000 --- a/guide/ops/locations/more-clouds.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -section: More Details on Specific Clouds -title: More on Clouds -section_type: inline -section_position: 2 ---- - -### 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]({{ site.path.guide }}/start/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](https://jclouds.apache.org/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](http://jclouds.apache.org/guides/aws) -and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html). - -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](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) - -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](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](https://console.aws.amazon.com/vpc), - making sure it is for the right region, and selecting a "Single Public Subnet". - (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).) -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](https://jclouds.apache.org/guides/google). - -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=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----- - - -### Quotas - -GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas). - -It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en). - - -### 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](https://cloud.google.com/compute/docs/networking#networks_1). - -For example, for dev/demo purposes an "everything" network could be created that opens all ports. - -|| Name || everything | -|| Description || opens all tcp ports | -|| Source IP Ranges || 0.0.0.0/0 | -|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 | - -## 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/33bca1b9/guide/ops/locations/special-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/special-locations.md b/guide/ops/locations/special-locations.md deleted file mode 100644 index 8f19fa4..0000000 --- a/guide/ops/locations/special-locations.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -section: Specialized Locations -section_position: 7 -section_type: inline ---- - -### 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: - -{% highlight yaml %} -services: -- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server - location: - host: 192.168.0.1 -{% endhighlight %} - -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: - -{% highlight yaml %} -location: - multi: - targets: - - byon:(hosts=192.168.0.1) - - jclouds:aws-ec2: - identity: acct1 - - jclouds:aws-ec2: - identity: acct2 -{% endhighlight %} - -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 {% include java_link.html class_name="ServerPool" package_path="org/apache/brooklyn/entity/machine/pool" project_subpath="software/base" %} -entity type allows defining an entity which becomes available as a location. -
