add java_link.html for javadoc+src, tidy up and expand locations docs
Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/5cf0666f Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/5cf0666f Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/5cf0666f Branch: refs/heads/master Commit: 5cf0666f8e42bfbad720032bb4889265af0dd171 Parents: fa257f6 Author: Alex Heneveld <[email protected]> Authored: Mon Jan 19 22:51:13 2015 +0000 Committer: Alex Heneveld <[email protected]> Committed: Mon Jan 19 22:59:44 2015 +0000 ---------------------------------------------------------------------- docs/_includes/java_link.html | 18 ++ docs/_includes/sitemap-item.html | 2 +- docs/_plugins/brooklyn_metadata.rb | 16 +- docs/guide/ops/index.md | 3 +- docs/guide/ops/locations/configuring.md | 105 -------- docs/guide/ops/locations/index.md | 267 ++++++++++++++++---- docs/guide/ops/locations/more-locations.md | 55 ++++ docs/guide/ops/locations/ssh-keys.md | 60 +++++ docs/guide/ops/persistence/index.md | 23 +- docs/style/css/_code_blocks.scss | 3 + docs/website/documentation/increase-entropy.md | 2 +- 11 files changed, 378 insertions(+), 176 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_includes/java_link.html ---------------------------------------------------------------------- diff --git a/docs/_includes/java_link.html b/docs/_includes/java_link.html new file mode 100644 index 0000000..b296652 --- /dev/null +++ b/docs/_includes/java_link.html @@ -0,0 +1,18 @@ +{% comment %} + +includes a code-formatted class name with link to its javadoc and optionally its source code + +usage: + +{ % include java_link.html class_name="JcloudsLocationConfig" package_path="brooklyn/location/jclouds" project_subpath="location/jclouds" % } + + +{% endcomment %}{% if include.project_subpath %}<code>{{ include.class_name }}</code> + (<a href="{{ site.guide.path }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name }}.html">javadoc</a>, + <a href="{{ site.brooklyn.url.git }}/{{ include.project_subpath }}/src/main/java/{{ include.package_path }}/{{ include.class_name }}.java">src</a>) +{% else %}<a href="{{ site.guide.path }}/misc/javadoc/{{ include.package_path }}/{{ include.class_name }}.html"> +<code>{{ include.class_name }}</code></a> +{% endif %}{% comment %} + +must NOT have a newline at the end here, as the include is often done inline +{% endcomment %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_includes/sitemap-item.html ---------------------------------------------------------------------- diff --git a/docs/_includes/sitemap-item.html b/docs/_includes/sitemap-item.html index 247fc5d..eebc513 100644 --- a/docs/_includes/sitemap-item.html +++ b/docs/_includes/sitemap-item.html @@ -1,6 +1,6 @@ {% pop site_items item %} {% set_hash_entry item path item_path %} - {% set_hash_entry item url item_url %} +{% set_hash_entry item url item_url %} {% unless item_path %} {% unless item_url %} http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/_plugins/brooklyn_metadata.rb ---------------------------------------------------------------------- diff --git a/docs/_plugins/brooklyn_metadata.rb b/docs/_plugins/brooklyn_metadata.rb index b5fe81d..89d82aa 100644 --- a/docs/_plugins/brooklyn_metadata.rb +++ b/docs/_plugins/brooklyn_metadata.rb @@ -1,17 +1,18 @@ # Inserts several useful fields that can be referenced using {{ name }} syntax # -# TODO: remove, no need for a plugin i think, this is already set in fields.md -# (although doing it in ruby might be better!) +# TODO: move things from fields.md to here # -# site.data.brooklyn.version: brooklyn version, such as 0.7.0-M1 -# site.data.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false +# site.brooklyn.version: brooklyn version, such as 0.7.0-M1 (taken from brooklyn-version in _config.yml) +# site.brooklyn.is_snapshot: true if this is a snapshot version, otherwise false # module BrooklynMetadata - BROOKLYN_VERSION = "0.7.0-M2-incubating" unless defined? BROOKLYN_VERSION + BROOKLYN_VERSION = "0.7.0-SNAPSHOT" unless defined? BROOKLYN_VERSION class Generator < Jekyll::Generator def generate(site) + raise "Brooklyn version mismatch" if BrooklynMetadata::BROOKLYN_VERSION != site.config['brooklyn-version'] + is_snapshot = BrooklynMetadata::BROOKLYN_VERSION.end_with?('-SNAPSHOT') if is_snapshot @@ -55,14 +56,11 @@ module BrooklynMetadata url_set["git"] = "https://github.com/apache/incubator-brooklyn/tree/#{ git_branch }" - site.data['brooklyn'] = { + site.config['brooklyn'] = { "version" => BrooklynMetadata::BROOKLYN_VERSION, "is_snapshot" => is_snapshot, "url" => url_set } - - # TODO check that "#{ brooklyn['url']['git'] }/core/src/main/java/brooklyn/BrooklynVersion.java" - # exists AND contains "versionFromStatic = \"#{ brooklyn['version'] }\"" end end http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/index.md b/docs/guide/ops/index.md index 60b7c6e..b224852 100644 --- a/docs/guide/ops/index.md +++ b/docs/guide/ops/index.md @@ -2,8 +2,7 @@ title: Operations layout: website-normal children: -- locations/index.md -- locations/configuring.md +- locations/ - persistence/ - launching/ - catalog/ http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/configuring.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/configuring.md b/docs/guide/ops/locations/configuring.md deleted file mode 100644 index cb3ee16..0000000 --- a/docs/guide/ops/locations/configuring.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Configuring Locations -layout: website-normal ---- - -<a id="locations"></a> - -Brooklyn supports deploying to any machine which admits SSH access, as well as to -a huge variety of external and on-premise clouds. You can also connect to services, -or use whatever technique for deployment suits you best (such as Xebia Overthere, in development!). - -Configuration is typically set in `~/.brooklyn/brooklyn.properties` using keys such as the following: - -{% highlight bash %} -# use this key for localhost (this is the default, although if you have a passphrase you must set it) -brooklyn.location.localhost.privateKeyFile=~/.ssh/id_rsa - -brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE - -# use a special key when connecting to public clouds, and a particularly special one for AWS -brooklyn.location.jclouds.privateKeyFile=~/.ssh/public_clouds/id_rsa -brooklyn.location.jclouds.aws-ec2.privateKeyFile=~/.ssh/public_clouds/aws_id_rsa - -# AWS credentials (when deploying to location jclouds:aws-ec2) -brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST -brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l - -# credentials for 'geoscaling' service -brooklyn.geoscaling.username=cloudsoft -brooklyn.geoscaling.password=xxx -{% endhighlight %} - -These can also be set as environment variables (in the shell) or system properties (java command line). -(There are also ``BROOKLYN_JCLOUDS_PRIVATE_KEY_FILE`` variants accepted.) - -For any jclouds provider you will typically need to set ``identity`` and ``credential`` -in the ``brooklyn.location.jclouds.provider`` namespace. - -To deploy to sets of machines with known IP's, assuming you have the credentials, -use the syntax ``byon:(hosts="[email protected],[email protected],[email protected]")`` -(this requires your default private key to have access; -see the ``prod1`` example below for specifying other credentials). - -A wide range of other fields is available, because in the real world sometimes things do get complicated. -The following is supported from the configuration file (with whatever customization you might want available in code): - -- 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``. - -- Hardware requirements such as ``minRam`` and ``minCores`` can be supplied, or a ``hardwareId`` (jclouds only) - -- Specific Secury Groups can be specified using `securityGroups`, if you want to reuse set of existing ones (jclouds only) - -- Specific KeyPair can be specified using `keyPair`, if you want to reuse an existing keypair (jclouds only). - -- Specific VM images can be specified using ``imageId`` or ``imageNameRegex`` (jclouds only) - -- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"`` (jclouds only) - -- A ``user`` can be specified, with the property that -- in a jclouds world -- the user will be *created* on the machine, - with admin rights, authorizing the relevant public key (corresponding to the private key, or as described below). - Login for the root account will be disabled, as will login by password if a public key is supplied. - (This is skipped if ``user`` is the ``root`` or other initial login user.) - -- You can specify the user account to use to login to jclouds initially with the ``loginUser`` property. - Typically this is auto-detected by jclouds - (often ``root``, or ``ubuntu`` or ``ec2-user`` for known Ubuntu or Amazon Linux images), - but the strategy isn't foolproof, particularly in some private cloud setups. (jclouds only). In some cases, you may need to specify a `loginUser.privateKeyFile` if the image you are using doesn't allow ssh password login. - -- 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 in order to log in.) - -- You can specify the number of attempts Brooklyn should make to create - machines with ``machineCreateAttempts`` (jclouds only). This is useful for - working around the rare occasions in which cloud providers give machines that - are dead on arrival. - -You can also define named locations 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 more advanced examples 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,[email protected].{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 -{% endhighlight %} - http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md index 3d2b99a..b5e5afd 100644 --- a/docs/guide/ops/locations/index.md +++ b/docs/guide/ops/locations/index.md @@ -1,101 +1,268 @@ --- -title: Locations Intro +title: Locations layout: website-normal +children: +- { section: Clouds } +- { section: Inheritance and Named Locations, title: Named Locations } +- { section: Localhost } +- { section: BYON } +- more-locations.md +- ssh-keys.md --- -Locations are the environments to which Brooklyn deploys applications. -These can be clouds (public or private), fixed infrastructure environments, or your laptop. +Locations are the environments to which Brooklyn deploys applications, including: -Brooklyn looks for Location configuration in `~/.brooklyn/brooklyn.properties`. +Brooklyn supports a wide range of locations: -## Setting up an SSH key +* <a href="#clouds">Clouds</a>, where it will provision machines +* <a href="#localhost">Localhost</a> (e.g. your laptop), + where it will deploy via `ssh` to `localhost` for rapid testing +* <a href="#byon">BYON</a>, where you "bring your own nodes", + specifying already-existing hosts to use +* And many others, including object stores and online services -While some locations can be accessed using *user:password* credentials it is more common to use authentication keys. +Configuration can be set in `~/.brooklyn/brooklyn.properties` +or directly in YAML when specifying a location. +On some entities, config keys determining maching selection and provisioning behavior +can also be set `in `provisioning.properties`. -To use keyfile based authentication, Brooklyn requires that the management machine has an SSH key. By default Brooklyn looks for a key at `~/.ssh/id_rsa` and `~/.ssh/id_dsa`. -If you do not already have an SSH key installed, create a new id_rsa key: +### Clouds -{% highlight bash %} -$ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa -{% endhighlight %} +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/)): -If you wish to use an existing key SSH, or an SSH key -that has a passphrase, or a location other than `~/.ssh`, you can specify this in -`brooklyn.properties` using `brooklyn.location.localhost.privateKeyFile` and -`brooklyn.location.localhost.privateKeyPassphrase`. +* `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) -## Localhost +For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`: -Brooklyn can access localhost if there is an SSH key on the machine and if the SSH key has been added to the list of `authorized_keys` on that machine. +{% 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, these can be set instead in `brooklyn.properties` +in the `jclouds.<provider>` namespace: {% highlight bash %} -# _Appends_ id_rsa.pub to authorized_keys. Other keys are unaffected. -$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys +brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST +brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l {% endhighlight %} -MacOS user? In addition to the above, enable 'Remote Login' in System Preferences > - Sharing. +And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`. +The Getting Started [template brooklyn.properties](../start/brooklyn.properties) contains more examples +of configuring cloud endpoints, including information on credential types used in different clouds. -## Cloud Endpoints (via jclouds) -[Apache jclouds](http://www.jclouds.org) is a multi-cloud library that Brooklyn uses to access many clouds. The [full list of supported providers](http://jclouds.apache.org/reference/providers/) is available on jclouds.apache.org. +#### OS Initial Login and Setup -Add your cloud provider's (API) credentials to `brooklyn.properties` and create an SSH key on the management machine. +Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly. -Some clouds provide both API keys and SSH keys. In this case add only the API credentials to `brooklyn.properties`. (jclouds will transparently use the API credentials to setup access using the management machine's SSH key.) +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 is particularly useful when using a custom image templates where the cloud-side account management logic is not enabled.) -### Example: AWS Virginia Large Centos +Following a successful logon, Brooklyn performs the following steps to configure the machine: -{% highlight bash %} -## Snippet from ~/.brooklyn/brooklyn.properties. +1. to create a new user with the same name as the user `brooklyn` is running as locally + (this can be overridden with `user`, below) + +1. to 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; + 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="brooklyn/location/jclouds" project_subpath="locations/jclouds" %}. + +###### 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 in order to log in.) + +- 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`) + + +###### 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) -# Provide jclouds with AWS API credentials. -brooklyn.location.jclouds.aws-ec2.identity = AKA_YOUR_ACCESS_KEY_ID -brooklyn.location.jclouds.aws-ec2.credential = YourSecretKeyWhichIsABase64EncodedString +- A specific existing key pair for the cloud to set for `loginUser` can be specified using `keyPair` + (selected clouds only) -# Name this location 'AWS Virginia Large Centos' and wire to AWS US-East-1 -brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2:us-east-1 +- User metadata can be attached, using the syntax ``userMetadata=key=value,key2="value 2"`` -# (Using the same name) specify image, user and minimum ram size (ie instance size) +- You can specify the number of attempts Brooklyn should make to create + machines with ``machineCreateAttempts`` (jclouds only). This is useful for + working around the rare occasions in which cloud providers give machines that + are dead on arrival. + +- If you want to investigate failures, set `destroyOnFailure` to `false` + to keep failed VM's around. (You'll have to manually clean them up.) + + +### 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,[email protected].{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 %} +If you are confused about inheritance order, the following test may be useful: +{% highlight bash %} +brooklyn.location.jclouds.KEY=VAL1 +brooklyn.location.jclouds.aws-ec2.KEY=VAL2 +brooklyn.location.named.my-aws=jclouds:aws-ec2 +brooklyn.location.named.my-aws.KEY=VAL3 {% endhighlight %} -This will appear as 'AWS Virginia Large Centos' in the web console, but will need to be escaped on the command line as: `AWS\ Virginia\ Large\ Centos`. +In the above example, if you deploy to `location: named:my-aws`, +Brooklyn will get `VAL3` for `KEY`; +this overrides `VAL2` which applies by default to all `aws-ec2` locations, +which in turn overrides `VAL1`, which applies to all jclouds locations. -See the Getting Started [template brooklyn.properties](../start/brooklyn.properties) for more examples of using cloud endpoints. +### Localhost -## Fixed Infrastructure +If passwordless ssh login to `localhost` is enabled on your machine, +you should be able to deploy blueprints with no special configuration, +just by specifying `location: localhost` in YAML. -Bringing your own nodes (BYON) to Brooklyn is straightforward. +If you use a passpharse or prefer a different key, these can be configured as follows: -You will need the IP addresses of the nodes and the access credentials. Both SSH and password based login are supported. +{% highlight bash %} +brooklyn.location.localhost.privateKeyFile=~/.ssh/brooklyn_key +brooklyn.location.localhost.privateKeyPassphrase=s3cr3tPASSPHRASE +{% endhighlight %} -### Example: On-Prem Iron +If you encounter issues or for more information, see [SSH Keys Localhost Setup](ssh-keys.html#localhost-setup). -{% highlight bash %} -## Snippet from ~/.brooklyn/brooklyn.properties. -# Use the byon prefix, and provide the IP addresss (or IP ranges) -brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,[email protected].{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 +### BYON + +"Bring-your-own-nodes" mode is useful in production, were machines have been provisioned by someone else, +and during testing, to cut down provisioning time. + +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. -## Advanced Options +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. -Unusual provider? 'Featureful' API? Brooklyn can cope. +{% highlight bash %} +brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,[email protected].{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 %} -[This spreadsheet](https://docs.google.com/a/cloudsoftcorp.com/spreadsheet/ccc?key=0Avy7Tdf2EOIqdGQzSlNiT2M0V19SejBScDhSdzMtT2c) provides explanation, guidance, and examples for the majority of location options. +### Other Location Topics +* [More Locations](more-locations.md) +* [SSH Keys](ssh-keys.md) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/more-locations.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/more-locations.md b/docs/guide/ops/locations/more-locations.md new file mode 100644 index 0000000..35e2398 --- /dev/null +++ b/docs/guide/ops/locations/more-locations.md @@ -0,0 +1,55 @@ +--- +title: More Locations +layout: website-normal +children: +- { section: Single Host } +- { section: The Multi Location } +- { section: The Server Pool } +--- + +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: 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 package_path="brooklyn/entity/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/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/locations/ssh-keys.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/ssh-keys.md b/docs/guide/ops/locations/ssh-keys.md new file mode 100644 index 0000000..6839f62 --- /dev/null +++ b/docs/guide/ops/locations/ssh-keys.md @@ -0,0 +1,60 @@ +--- +title: SSH Keys +layout: website-normal +--- + +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 %} + +You should be able to run `ssh localhost` without any password required. + +**Got a passphrase?** Set `brooklyn.location.localhost.privateKeyPassphrase` +as described [here](index.html#os-setup) + +**MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing". + + +### Potential Problems + +* `~/.ssh/` or files in that directory too open: they should be visible only to the user (apart from public keys), + both on the source machine and the target machine + +* 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/incubator-brooklyn/blob/5cf0666f/docs/guide/ops/persistence/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/persistence/index.md b/docs/guide/ops/persistence/index.md index 819e182..cbb3112 100644 --- a/docs/guide/ops/persistence/index.md +++ b/docs/guide/ops/persistence/index.md @@ -1,6 +1,13 @@ --- title: Persistence layout: website-normal +children: +- { section: Command Line Options } +- { section: File-based Persistence } +- { section: Object Store Persistence } +- { section: Rebinding to State } +- { section: High Availability } +- { section: Writing Persistable Code } --- Brooklyn can be configured to persist its state so that the Brooklyn server can be restarted, @@ -92,8 +99,8 @@ brooklyn launch --persist auto --persistenceDir myContainerName --persistenceLoc {% endhighlight %} -Rebind ------- +Rebinding to State +------------------ When Brooklyn starts up pointing at existing state, it will recreate the entities, locations and policies based on that persisted state. @@ -104,8 +111,7 @@ HTTP or JMX). This new state will be reported in the web-console and can also tr any registered policies. -Copying Persistence State -------------------------- +## CLI Commands for Copying State Brooklyn includes a command to copy persistence state easily between two locations. The `copy-state` CLI command takes the following arguments: @@ -122,10 +128,11 @@ The `copy-state` CLI command takes the following arguments: The local transformations file to be applied to the copy of the data before uploading it. -Handling Rebind Failures ------------------------- -If rebind were to fail for any reason, details of the underlying failures will be reported -in the brooklyn.debug.log. There are several approaches to resolving problems. +## Handling Rebind Failures + +If rebind fails fail for any reason, details of the underlying failures will be reported +in the `brooklyn.debug.log`. There are several approaches to resolving problems. + ### Determine Underlying Cause http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/style/css/_code_blocks.scss ---------------------------------------------------------------------- diff --git a/docs/style/css/_code_blocks.scss b/docs/style/css/_code_blocks.scss index 269c6a0..dd39dd8 100644 --- a/docs/style/css/_code_blocks.scss +++ b/docs/style/css/_code_blocks.scss @@ -41,6 +41,9 @@ code { padding: 4px 4px 2px 4px; border-radius: 3px; } +a code { + color: inherit; +} .nowrap { @include nowrap(); } http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/5cf0666f/docs/website/documentation/increase-entropy.md ---------------------------------------------------------------------- diff --git a/docs/website/documentation/increase-entropy.md b/docs/website/documentation/increase-entropy.md index bd0e8ea..53d5768 100644 --- a/docs/website/documentation/increase-entropy.md +++ b/docs/website/documentation/increase-entropy.md @@ -1,5 +1,5 @@ --- -title: Increase entropy +title: Increase Entropy layout: website-normal --- If you are installing AMP on a virtual machine, you may find it useful to increase the Linux kernel entropy to speed up the ssh connections to the managed entities. You can install and configure `rng-tools` or just use /dev/urandom`.
