You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@brooklyn.apache.org by al...@apache.org on 2016/08/03 21:26:59 UTC
[1/5] brooklyn-docs git commit: Improve location docs
Repository: brooklyn-docs
Updated Branches:
refs/heads/master 35153dd11 -> 3f2495a3d
Improve location docs
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/2be644e1
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/2be644e1
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/2be644e1
Branch: refs/heads/master
Commit: 2be644e10c307286fba96c9b0157a55cb888ac7f
Parents: bcad595
Author: Aled Sage <al...@gmail.com>
Authored: Thu Jul 28 23:17:13 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Aug 2 12:52:20 2016 +0100
----------------------------------------------------------------------
guide/ops/locations/_AWS.md | 48 ++++++--
guide/ops/locations/_GCE.md | 63 +++++++++--
guide/ops/locations/_cloudstack.md | 138 +++++++++++++++++++++++
guide/ops/locations/_ibm-softlayer.md | 28 +++++
guide/ops/locations/_localhost.md | 27 +++--
guide/ops/locations/_openstack.md | 169 ++++++++++++++++++++++++-----
6 files changed, 416 insertions(+), 57 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_AWS.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_AWS.md b/guide/ops/locations/_AWS.md
index 5d43a20..cfbc02b 100644
--- a/guide/ops/locations/_AWS.md
+++ b/guide/ops/locations/_AWS.md
@@ -19,21 +19,35 @@ and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/Manag
An example of the expected format is shown below:
- brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST
- brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+ location:
+ jclouds:aws-ec2:
+ region: us-east-1
+ identity: ABCDEFGHIJKLMNOPQRST
+ credential: abcdefghijklmnopqrstu+vwxyzabcdefghijklm
+Users are strongly recommended to use
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
-### 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.
+### Common Configuration Options
-There is utility written by Cloudsoft for deleting these unused resources:
-http://www.cloudsoftcorp.com/blog/2013/03/tidying-up-after-jclouds.
+Below are examples of configuration options that use values specific to AWS EC2:
+
+* The `region` is the [AWS region code](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
+ For example, `region: us-east-1`. One can also in-line this value when such as `jclouds:aws-ec2:us-east-1`.
+ A specific availability zone within the region can be specified by including its letter identifier as a suffix.
+ For example, `region: us-east-1a`.
+
+* The `hardwareId` is the [instance type](https://aws.amazon.com/ec2/instance-types/). For example,
+ `hardwareId: m4.large`.
+
+* The `imageId` is the region-specific [AMI id](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html).
+ For example, `imageId: us-east-1/ami-05ebd06c`.
+
+* The `securityGroups` option takes one or more names of pre-existing
+ [security groups](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html).
+ For example, `securityGroups: mygroup1` or `securityGroups: [ mygroup1, mygroup2 ]`.
### Using Subnets and Security Groups
@@ -111,3 +125,15 @@ You can then deploy blueprints to the subnet, allowing VPC hardware instance typ
by specifying the subnet ID as the `networkName` in your YAML blueprint.
This is covered in the previous section, "Using Subnets".
+
+### 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.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_GCE.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_GCE.md b/guide/ops/locations/_GCE.md
index 10a739d..32d64a5 100644
--- a/guide/ops/locations/_GCE.md
+++ b/guide/ops/locations/_GCE.md
@@ -11,21 +11,60 @@ section_position: 4
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=123456789012@developer.gserviceaccount.com
- brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY-----
+To obtain credentials for GCE, use the GCE web page's "APIs & auth -> Credentials" page,
+creating a "Service Account" of type JSON, then extracting the client_email as the identity and
+private_key as the credential. For more information, 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 can either be one long line with `\n` representing the new line characters,
+or in YAML it can be split over multiple lines as below:
+
+ location:
+ jclouds:google-compute-engine:
+ region: us-central1-a
+ identity: 1234567890-somet1mesArand0mU1Dhere@developer.gserviceaccount.com
+ credential: |
+ -----BEGIN RSA PRIVATE KEY-----
+ abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz
+ 0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmn
+ opqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+ab
+ cdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz01
+ 23456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnop
+ qrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcd
+ efghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123
+ 456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqr
+ stuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdef
+ ghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz012345
+ 6789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrst
+ uvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefgh
+ ijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz01234567
+ 89/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuv
+ wxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghij
+ klmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789
+ /+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwx
+ yz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijkl
+ mnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+
+ abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz
+ 0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+abcdefghijklmn
+ opqrstuvwxyz0123456789/+abcdefghijklmnopqrstuvwxyz0123456789/+ab
+ cdefghijklmnopqrstuvwxyz
+ -----END RSA PRIVATE KEY-----
+
+It is also possible to have the credential be the path of a local file that contains the key.
+However, this can make it harder to setup and manage multiple Brooklyn servers (particularly
+when using high availability mode).
+
+Users are strongly recommended to use
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
### 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).
+It is easy to request a quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en).
### Networks
@@ -43,4 +82,10 @@ For example, for dev/demo purposes an "everything" network could be created that
|| Source IP Ranges || 0.0.0.0/0 |
|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 |
+To configure the location to use this, you can include a location configuration option like
+`networkName: everything`.
+
+
+### Entropy
+GCE images often have little entropy. One option to work around this is to use `installDevUrandom: true`.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_cloudstack.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_cloudstack.md b/guide/ops/locations/_cloudstack.md
new file mode 100644
index 0000000..99b5ea2
--- /dev/null
+++ b/guide/ops/locations/_cloudstack.md
@@ -0,0 +1,138 @@
+---
+section: Openstack
+title: Openstack
+section_type: inline
+section_position: 6
+---
+
+## CloudStack
+
+### Connection Details
+
+The endpoint URI will normally have the suffix `/client/api/`.
+
+The identity is the "api key" and the credential is the "secret key". These can be generated in
+the cloudstack gui: under accounts, select "view users", then "generate key".
+
+ location:
+ jclouds:cloudstack:
+ endpoint: https://cloud.acme.com/client/api
+ identity: abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghij
+ credential: mycred-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abc
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to CloudStack environments:
+
+* The `imageId` is the template id. For example,
+ `imageId: db0bcce3-9e9e-4a87-a953-2f46b603498f`.
+
+* The `region` is CloudStack zone id.
+ For example `region: 84539b9c-078e-458a-ae26-c3ffc5bb1ec9`..
+
+* `networkName` is the network id (within the given zone) to be used. For example,
+ `networkName: 961c03d4-9828-4037-9f4d-3dd597f60c4f`.
+
+For further configuration options, consult
+[jclouds CloudStack template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/cloudstack/compute/options/CloudStackTemplateOptions.html).
+These can be used with the **[templateOptions](#custom-template-options)** configuration option.
+
+
+### Using a Pre-existing Key Pair
+
+The configuration below uses a pre-existing key pair:
+
+ location:
+ jclouds:cloudstack:
+ ...
+ jclouds.openstack-nova.auto-generate-keypairs: false
+ loginUser: root
+ loginUser.privateKeyFile: /path/to/keypair.pem
+ keyPair: my-keypair
+
+
+### Using Pre-existing Security Groups
+
+To specify existing security groups, their ids must be used rather than their names (note this
+differs from the configuration on other clouds!).
+
+The configuration below uses a pre-existing security group:
+
+ location:
+ jclouds:cloudstack:
+ ...
+ templateOptions:
+ generateSecurityGroup: false
+ securityGroupIds:
+ - 12345678-90ab-def0-1234-567890abcdef
+
+
+### Using Static NAT
+
+Assigning a public IP to a VM at provision-time is referred to as "static NAT" in CloudStack
+parlance. To give some consistency across different clouds, the configuration option is named
+`autoAssignFloatingIp`. For example, `autoAssignFloatingIp: false`.
+
+
+### Cloudmonkey CLI
+
+The [CloudStack Cloudmonkey CLI](https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI)
+is a very useful tool for validating that credentials are correct, and for querying the API to find the correct
+zone ids etc.
+
+Useful commands include:
+
+ # for finding the ids of the zones:
+ cloudmonkey api listZones
+
+ # for finding the ids of the networks.
+ cloudmonkey api listNetworks | grep -E "id =|name =|========="
+
+### CloudStack Troubleshooting
+
+These troubleshooting tips are more geared towards problems encountered in old test/dev
+CloudPlatform environment.
+
+#### Resource Garbage Collection Issues
+
+The environment may run out of resources, due to GC issues, preventing the user from creating new
+VMs or allocating IP addresses (May respond with this error message:
+`errorCode=INTERNAL_ERROR, errorText=Job failed due to exception Unable to create a deployment for VM`).
+There are two options worth checking it to enforce clearing up the zombie resources:
+
+* Goto the Accounts tab in the webconsole and tap on the Update Resource Count button.
+* Restart the VPC in question from the Network tab.
+
+
+#### Releasing Allocated Public IP Addresses
+
+Releasing allocated Public IP from the web console did not free up the resources. Instead
+Cloudmonkey can be used to dissociate IPs and expunge VMs.
+
+Here is a cloudmonkey script to dissociate any zombie IPs:
+
+ cloudmonkey set display json;
+ cloudmonkey api listPublicIpAddresses | grep '"id":' > ips.txt;
+ sed -i -e s/' "id": "'/''/g ips.txt;
+ sed -i -e s/'",'/''/g ips.txt
+ for line in $(cat ips.txt); do cloudmonkey api disassociateIpAddress id="$line"; done
+ rm ips.txt;
+ cloudmonkey set display default;
+
+
+#### Restarting VPCs
+
+Errors have been encountered when a zone failed to provision new VMs, giving errors like:
+
+ Job failed due to exception Resource [Host:15] is unreachable: Host 15: Unable to start instance due to null
+
+The workaround was to restart the VPC networks:
+
+* Log into the CloudPlatform web-console.
+* Go to Network -> VPC (from the "select view")
+* For each of the VPCs, click on the "+" in the "quickview" column, and invoke "restart VPC".
+
+Other symptoms of this issue were that: 1) an administrator could still provision VMs using
+the admin account, which used a different network; and 2) the host number was very low, so it
+was likely to be a system host/VM that was faulty.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_ibm-softlayer.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_ibm-softlayer.md b/guide/ops/locations/_ibm-softlayer.md
index 63cdf86..542dd5b 100644
--- a/guide/ops/locations/_ibm-softlayer.md
+++ b/guide/ops/locations/_ibm-softlayer.md
@@ -7,6 +7,34 @@ section_position: 5
## IBM SoftLayer
+### Credentials
+
+Credentials can be obtained from the Softlayer API, under "administrative -> user administration -> api-access".
+
+For example:
+
+ location:
+ jclouds:softlayer:
+ region: ams01
+ identity: my-user-name
+ credential: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to Softlayer:
+
+* The `region` is the [Softlayer datacenter](http://www.softlayer.com/data-centers).
+ For example, `region: dal05`.
+
+* The `hardwareId` is an auto-generated combination of the hardware configuration options.
+ This is because there is no concept of hardwareId or hardware profile names in Softlayer.
+ An example value is `hardwareId: "cpu=1,memory=1024,disk=25,type=LOCAL"`.
+
+* The `imageId` is the [Image template](https://knowledgelayer.softlayer.com/learning/introduction-image-templates).
+ For example, `imageId: CENTOS_6_64`.
+
+
### VLAN Selection
SoftLayer may provision VMs in different VLANs, even within the same region.
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_localhost.md b/guide/ops/locations/_localhost.md
index 6558d9f..ba543c6 100644
--- a/guide/ops/locations/_localhost.md
+++ b/guide/ops/locations/_localhost.md
@@ -7,30 +7,41 @@ 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,
+machine, you should be able to deploy some 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 %}
+ location:
+ localhost:
+ privateKeyFile=~/.ssh/brooklyn_key
+ privateKeyPassphrase=s3cr3tPASSPHRASE
+
Alternatively, you can create a specific localhost location through the location wizard tool available within the web console.
This location will be saved as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-catalog) for easy reusability.
+
+#### Passwordless Sudo
+
If you encounter issues or for more information, see [SSH Keys Localhost Setup](#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:
+For some blueprints, passwordless sudo is required. (Try executing `sudo whoami` to see if it prompts for a password.
+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:
+
+If executing the following command does not ask for your password, then `sudo` has been setup correctly:
+
{% highlight bash %}
-sudo ls
+sudo whoami
{% endhighlight %}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/2be644e1/guide/ops/locations/_openstack.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_openstack.md b/guide/ops/locations/_openstack.md
index cc45e0a..cb331dc 100644
--- a/guide/ops/locations/_openstack.md
+++ b/guide/ops/locations/_openstack.md
@@ -1,11 +1,11 @@
---
-section: Openstack
-title: Openstack
+section: OpenStack
+title: OpenStack
section_type: inline
section_position: 6
---
-## Openstack
+## OpenStack
### Apache jclouds
@@ -13,6 +13,54 @@ Support for OpenStack is provided by Apache jclouds. For more information, see t
[here](https://jclouds.apache.org/guides/openstack/).
+### Connection Details
+
+The endpoint URI is that of keystone (normally on port 5000).
+
+The identity normally consists of the tenant and username, colons-separated. The credential is
+the password. For example:
+
+ location:
+ jclouds:openstack-nova:
+ endpoint: http://x.x.x.x:5000/v2.0/
+ identity: "your-tenant:your-username"
+ credential: your-password
+
+OpenStack Nova access information can be downloaded from the openstack web interface, for example
+as an openrc.sh file. This file will normally contain the identity and credential.
+
+
+### Common Configuration Options
+
+Below are examples of configuration options that use values specific to OpenStack environments:
+
+* The `imageId` is the id of an image. For example,
+ `imageId: RegionOne/08086159-8b0b-4970-b332-a7a929ee601f`.
+ These ids can be found from the the CLI or the web-console, for example in IBM Blue Box,
+ the URL is https://cloudsoft2-lon.openstack.blueboxgrid.com/project/images/.
+
+* The `hardwareId` is the [flavor id](http://docs.openstack.org/admin-guide/compute-flavors.html).
+ For example `hardwareId: RegionOne/1`. These ids can be found from the the CLI or the web-console,
+ for example in IBM Blue Box, the URL is https://tenant-region.openstack.blueboxgrid.com/admin/flavors/.
+
+The default flavors are shown below (though the set of flavors can be
+[managed by the admin](http://docs.openstack.org/admin-guide/cli_manage_flavors.html)):
+
+ +-----+-----------+-----------+------+
+ | ID | Name | Memory_MB | Disk |
+ +-----+-----------+-----------+------+
+ | 1 | m1.tiny | 512 | 1 |
+ | 2 | m1.small | 2048 | 20 |
+ | 3 | m1.medium | 4096 | 40 |
+ | 4 | m1.large | 8192 | 80 |
+ | 5 | m1.xlarge | 16384 | 160 |
+ +-----+-----------+-----------+------+
+
+For further configuration options, consult
+[jclouds Nova template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html).
+These can be used with the **[templateOptions](#custom-template-options)** configuration option.
+
+
### Networks
When multiple networks are available you should indicate which ones machines should join.
@@ -32,12 +80,16 @@ Do this by setting the desired values id as an option in the
### Floating IPs
-Configuration of floating IPs is as networks; specify the pools to use as another
-[template option](#custom-template-options):
+The `autoAssignFloatingIp` option means that a [floating ip](https://www.mirantis.com/blog/configuring-floating-ip-addresses-networking-openstack-public-private-clouds/)
+will be assigned to the VM at provision-time.
+
+A floating IP pool name can also be specified. If not set, a floating IP from any available pool will be chosen.
+This is set using the [template option](#custom-template-options). For example:
location:
jclouds:openstack-nova:
...
+ autoAssignFloatingIp: true
templateOptions:
# Pool names to use when allocating a floating IP
floatingIpPoolNames:
@@ -74,7 +126,7 @@ This is a basic inline YAML template for an OpenStack location:
This is the same OpenStack location in a format that can be added to your
`brooklyn.properties` file:
- brooklyn.location.named.My\ Openstack=jclouds:openstack-nova:http://x.x.x.x:5000/v2.0/
+ brooklyn.location.named.My\ OpenStack=jclouds:openstack-nova:http://x.x.x.x:5000/v2.0/
brooklyn.location.named.My\ OpenStack.identity=your-tenant:your-username
brooklyn.location.named.My\ OpenStack.credential=your-password
brooklyn.location.named.My\ OpenStack.endpoint=http://x.x.x.x:5000/v2.0/
@@ -91,33 +143,95 @@ This is the same OpenStack location in a format that can be added to your
brooklyn.location.named.My\ OpenStack.securityGroups=your-security-group
brooklyn.location.named.My\ OpenStack.keyPair=your-keypair
-Chose a value of `your-flavor-id` from one of the defaults, or create your own flavor if
-you have administrator privileges.
-For for more information, see the
-[OpenStack flavors guide](http://docs.openstack.org/admin-guide/cli_manage_flavors.html).
-The default flavors are:
+### Troubleshooting
- +-----+-----------+-----------+------+
- | ID | Name | Memory_MB | Disk |
- +-----+-----------+-----------+------+
- | 1 | m1.tiny | 512 | 1 |
- | 2 | m1.small | 2048 | 20 |
- | 3 | m1.medium | 4096 | 40 |
- | 4 | m1.large | 8192 | 80 |
- | 5 | m1.xlarge | 16384 | 160 |
- +-----+-----------+-----------+------+
+#### Cloud Credentials Failing
-For an even more detailed example location configuration, consult the
-[template properties file](https://brooklyn.apache.org/v/latest/start/brooklyn.properties).
+If the cloud API calls return `401 Unauthorized` (e.g. in a `org.jclouds.rest.AuthorizationException`),
+then this could be because the credentials are incorrect.
+A good way to check this is to try the same credentials with the
+[OpenStack nova command line client](http://docs.openstack.org/user-guide/common/cli_install_openstack_command_line_clients.html).
-### Other features
-Consult jclouds' [Nova template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html)
-for futher options when configuring Openstack locations.
+#### Unable to SSH: Wrong User
+
+If SSH authentication fails, it could be that the login user is incorrect. For most clouds, this
+is inferred from the image metadata, but if no (or the wrong) login user is specified then it will
+default to root. The correct login user can be specified using the configuration option `loginUser`.
+For example, `loginUser: ubuntu`.
+
+The use of the wrong login user can also result in the obscure error shown below, caused by
+an unexpected response saying to use a different user. For more technical information, see
+this [sshj github issue](https://github.com/hierynomus/sshj/issues/75):
+
+ Received message too long 1349281121
+
+
+#### I Want to Use my Own KeyPair
+
+By default, jclouds will auto-generate a new [key pair](http://docs.openstack.org/user-guide/cli_nova_configure_access_security_for_instances.html)
+for the VM. This key pair will be deleted automatically when the VM is deleted.
+
+Alternatively, you can use a pre-existing key pair. If so, you must also specify the corresponding
+private key (pem file, or data) to be used for the initial login. For example:
+
+ location:
+ jclouds:clouds:openstack-nova:
+ ...
+ jclouds.openstack-nova.auto-generate-keypairs: false
+ keyPair: "my-keypair"
+ loginUser: ubuntu
+ loginUser.privateKeyFile: /path/to/my/privatekey.pem
+
+
+#### Error "doesn't contain ... -----BEGIN"
+
+If using `loginUser.privateKeyFile` (or `loginUser.privateKeyData`), this is expected to be a .pem
+file. If a different format is used (e.g. a .ppk file), it will give an error like that below:
+
+ Error invoking start at EmptySoftwareProcessImpl{id=TrmhitVc}: chars
+ PuTTY-User-Key-File-2: ssh-rsa
+ ...
+ doesn't contain % line [-----BEGIN ]
+
+
+#### Warning Message: "Ignoring request to set..."
+
+If you see a warning log message like that below:
+
+ 2016-06-23 06:05:12,297 WARN o.a.b.l.j.JcloudsLocation [brooklyn-execmanager-XlwkWB3k-312]:
+ Ignoring request to set template option loginUser because this is not supported by
+ org.jclouds.openstack.nova.v2_0.compute.options.NovaTemplateOptions
+
+It can mean that the location configuration option is in the wrong place. The configuration under
+`templateOptions` must correspond to those options on the
+[jclouds Nova template options](https://jclouds.apache.org/reference/javadoc/1.9.x/org/jclouds/openstack/nova/v2_0/compute/options/NovaTemplateOptions.html).
+However, template options such as `loginUser` are top-level configuration options that should not
+be inside the `templateOptions` section.
+
+
+#### HttpResponseException Accessing Compute Endpoint
+
+The Keystone endpoint is first queried to get the API access endpoints for the appropriate services.
+
+Some private OpenStack installs are (mis)configured such that the returned addresses are not always
+directly accessible. It could be that the service is behind a VPN, or that they rely on hostnames
+that are only in a private DNS.
+
+You can find the service endpoints in OpenStack, either using the CLI or the web-console. For
+example, in Blue Box the URL is https://tenant-region.openstack.blueboxgrid.com/project/access_and_security/.
+You can then check if the Compute service endpoint is directly reachable.
+
+
+#### VM Failing to Provision
+
+It can be useful to drop down to the OpenStack nova CLI, or to jclouds, to confirm that VM
+provisioning is working and to check which options are required.
+
+For example, try following [these jclouds instructions](https://github.com/jclouds/jclouds-examples/tree/master/compute-basics#your-own-openstack-nova).
-### Troubleshooting
#### jclouds Namespace Issue
@@ -127,7 +241,6 @@ the current version of jclouds does not yet support.
If you are having problems deploying to OpenStack, consult your Brooklyn debug log and
look for the following:
-
"namespace": "http://docs.openstack.org/compute/ext/fake_xml"
@@ -141,7 +254,6 @@ configuration
Here is a simple example template to be used with this workaround:
-
location:
jclouds:openstack-devtest-compute:
endpoint: http://x.x.x.x:5000/v2.0/
@@ -154,7 +266,6 @@ Here is a simple example template to be used with this workaround:
Note that the following values will be set by default when omitted above:
-
jclouds.keystone.credential-type=passwordCredentials
jclouds.openstack-nova.auto-generate-keypairs: true
jclouds.openstack-nova.auto-create-floating-ips: true
[5/5] brooklyn-docs git commit: This closes #98
Posted by al...@apache.org.
This closes #98
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/3f2495a3
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/3f2495a3
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/3f2495a3
Branch: refs/heads/master
Commit: 3f2495a3da1e818100abb7dd61bf92ba9ca2f372
Parents: 35153dd 5f5fe0d
Author: Aled Sage <al...@gmail.com>
Authored: Wed Aug 3 22:26:46 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Aug 3 22:26:46 2016 +0100
----------------------------------------------------------------------
guide/ops/locations/_AWS.md | 50 ++++--
guide/ops/locations/_GCE.md | 66 ++++++-
guide/ops/locations/_cloudstack.md | 143 +++++++++++++++
guide/ops/locations/_ibm-softlayer.md | 32 ++++
guide/ops/locations/_localhost.md | 30 +++-
guide/ops/locations/_openstack.md | 176 ++++++++++++++++---
guide/ops/locations/index.md | 23 +--
guide/ops/starting-stopping-monitoring.md | 2 +-
.../fabric-with-multiple-locations.yaml | 15 ++
.../simple-appserver-with-location-byon.yaml | 4 +-
...mple-appserver-with-location-per-entity.yaml | 8 +
.../simple-appserver-with-location.yaml | 2 +-
guide/yaml/setting-locations.md | 115 ++++++++++--
guide/yaml/winrm/index.md | 2 +-
website/learnmore/catalog/catalog-item.html | 2 +-
15 files changed, 577 insertions(+), 93 deletions(-)
----------------------------------------------------------------------
[4/5] brooklyn-docs git commit: location docs: incorporate review
comments
Posted by al...@apache.org.
location docs: incorporate review comments
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/5f5fe0d3
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/5f5fe0d3
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/5f5fe0d3
Branch: refs/heads/master
Commit: 5f5fe0d3143cdde579d7e3a7c69d2969ad0d49f0
Parents: de1e235
Author: Aled Sage <al...@gmail.com>
Authored: Wed Aug 3 22:22:39 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Aug 3 22:23:06 2016 +0100
----------------------------------------------------------------------
guide/ops/locations/_AWS.md | 10 +++--
guide/ops/locations/_GCE.md | 7 +++-
guide/ops/locations/_cloudstack.md | 39 +++++++++++---------
guide/ops/locations/_ibm-softlayer.md | 4 ++
guide/ops/locations/_localhost.md | 3 +-
guide/ops/locations/_openstack.md | 23 ++++++++----
guide/ops/locations/index.md | 11 ++++--
.../fabric-with-multiple-locations.yaml | 1 +
guide/yaml/setting-locations.md | 14 +++++--
9 files changed, 72 insertions(+), 40 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_AWS.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_AWS.md b/guide/ops/locations/_AWS.md
index cfbc02b..b70d65a 100644
--- a/guide/ops/locations/_AWS.md
+++ b/guide/ops/locations/_AWS.md
@@ -35,7 +35,7 @@ credential management, for example using [Vault](https://www.vaultproject.io/).
Below are examples of configuration options that use values specific to AWS EC2:
* The `region` is the [AWS region code](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
- For example, `region: us-east-1`. One can also in-line this value when such as `jclouds:aws-ec2:us-east-1`.
+ For example, `region: us-east-1`. You can in-line the region name using the following format: `jclouds:aws-ec2:us-east-1`.
A specific availability zone within the region can be specified by including its letter identifier as a suffix.
For example, `region: us-east-1a`.
@@ -130,10 +130,12 @@ This is covered in the previous section, "Using Subnets".
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
+from 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.
+Whilst there is eventual consistency for recording which VMs still reference security groups, after deleting a VM, it can sometimes take several minutes before a security group can be deleted
+
+There is utility written by [Cloudsoft](http://www.cloudsoft.io/) for deleting these unused resources:
+[http://blog.abstractvisitorpattern.co.uk/2013/03/tidying-up-after-jclouds.html](http://blog.abstractvisitorpattern.co.uk/2013/03/tidying-up-after-jclouds.html).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_GCE.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_GCE.md b/guide/ops/locations/_GCE.md
index 32d64a5..e4d25ea 100644
--- a/guide/ops/locations/_GCE.md
+++ b/guide/ops/locations/_GCE.md
@@ -82,10 +82,13 @@ For example, for dev/demo purposes an "everything" network could be created that
|| Source IP Ranges || 0.0.0.0/0 |
|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 |
-To configure the location to use this, you can include a location configuration option like
-`networkName: everything`.
+To configure the location to use this, you can include a location configuration option like:
+
+ templateOptions:
+ network: https://www.googleapis.com/compute/v1/projects/<project name>/global/networks/everything
### Entropy
GCE images often have little entropy. One option to work around this is to use `installDevUrandom: true`.
+For more information, see [Increase Entropy]({{ site.path.website }}/documentation/increase-entropy.html).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_cloudstack.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_cloudstack.md b/guide/ops/locations/_cloudstack.md
index 99b5ea2..aaa77e9 100644
--- a/guide/ops/locations/_cloudstack.md
+++ b/guide/ops/locations/_cloudstack.md
@@ -1,18 +1,18 @@
---
-section: Openstack
-title: Openstack
+section: CloudStack
+title: Apache CloudStack
section_type: inline
section_position: 6
---
-## CloudStack
+## Apache CloudStack
### Connection Details
The endpoint URI will normally have the suffix `/client/api/`.
The identity is the "api key" and the credential is the "secret key". These can be generated in
-the cloudstack gui: under accounts, select "view users", then "generate key".
+the CloudStack gui: under accounts, select "view users", then "generate key".
location:
jclouds:cloudstack:
@@ -20,6 +20,10 @@ the cloudstack gui: under accounts, select "view users", then "generate key".
identity: abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghij
credential: mycred-abcdefghijklmnopqrstuvwxyz01234567890-abcdefghijklmnopqrstuvwxyz01234567890-abc
+Users are strongly recommended to use
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
+
### Common Configuration Options
@@ -46,7 +50,6 @@ The configuration below uses a pre-existing key pair:
location:
jclouds:cloudstack:
...
- jclouds.openstack-nova.auto-generate-keypairs: false
loginUser: root
loginUser.privateKeyFile: /path/to/keypair.pem
keyPair: my-keypair
@@ -54,7 +57,7 @@ The configuration below uses a pre-existing key pair:
### Using Pre-existing Security Groups
-To specify existing security groups, their ids must be used rather than their names (note this
+To specify existing security groups, their IDs must be used rather than their names (note this
differs from the configuration on other clouds!).
The configuration below uses a pre-existing security group:
@@ -75,11 +78,11 @@ parlance. To give some consistency across different clouds, the configuration op
`autoAssignFloatingIp`. For example, `autoAssignFloatingIp: false`.
-### Cloudmonkey CLI
+### CloudMonkey CLI
-The [CloudStack Cloudmonkey CLI](https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI)
-is a very useful tool for validating that credentials are correct, and for querying the API to find the correct
-zone ids etc.
+The [CloudStack CloudMonkey CLI](https://cwiki.apache.org/confluence/display/CLOUDSTACK/CloudStack+cloudmonkey+CLI)
+is a very useful tool. It gives is an easy way to validate that credentials are correct, and to query
+the API to find the correct zone IDs etc.
Useful commands include:
@@ -89,10 +92,12 @@ Useful commands include:
# for finding the ids of the networks.
cloudmonkey api listNetworks | grep -E "id =|name =|========="
+
### CloudStack Troubleshooting
These troubleshooting tips are more geared towards problems encountered in old test/dev
-CloudPlatform environment.
+CloudStack environment.
+
#### Resource Garbage Collection Issues
@@ -101,16 +106,16 @@ VMs or allocating IP addresses (May respond with this error message:
`errorCode=INTERNAL_ERROR, errorText=Job failed due to exception Unable to create a deployment for VM`).
There are two options worth checking it to enforce clearing up the zombie resources:
-* Goto the Accounts tab in the webconsole and tap on the Update Resource Count button.
+* Go to the Accounts tab in the webconsole and tap on the Update Resource Count button.
* Restart the VPC in question from the Network tab.
#### Releasing Allocated Public IP Addresses
-Releasing allocated Public IP from the web console did not free up the resources. Instead
-Cloudmonkey can be used to dissociate IPs and expunge VMs.
+Releasing an allocated Public IP from the web console did not free up the resources. Instead
+CloudMonkey can be used to dissociate IPs and expunge VMs.
-Here is a cloudmonkey script to dissociate any zombie IPs:
+Here is a CloudMonkey script to dissociate any zombie IPs:
cloudmonkey set display json;
cloudmonkey api listPublicIpAddresses | grep '"id":' > ips.txt;
@@ -123,13 +128,13 @@ Here is a cloudmonkey script to dissociate any zombie IPs:
#### Restarting VPCs
-Errors have been encountered when a zone failed to provision new VMs, giving errors like:
+Errors have been encountered when a zone failed to provision new VMs, with messages like:
Job failed due to exception Resource [Host:15] is unreachable: Host 15: Unable to start instance due to null
The workaround was to restart the VPC networks:
-* Log into the CloudPlatform web-console.
+* Log into the CloudStack web-console.
* Go to Network -> VPC (from the "select view")
* For each of the VPCs, click on the "+" in the "quickview" column, and invoke "restart VPC".
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_ibm-softlayer.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_ibm-softlayer.md b/guide/ops/locations/_ibm-softlayer.md
index 542dd5b..a1e5588 100644
--- a/guide/ops/locations/_ibm-softlayer.md
+++ b/guide/ops/locations/_ibm-softlayer.md
@@ -19,6 +19,10 @@ For example:
identity: my-user-name
credential: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+Users are strongly recommended to use
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
+
### Common Configuration Options
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_localhost.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_localhost.md b/guide/ops/locations/_localhost.md
index ba543c6..32498b3 100644
--- a/guide/ops/locations/_localhost.md
+++ b/guide/ops/locations/_localhost.md
@@ -19,7 +19,8 @@ If you use a passpharse or prefer a different key, these can be configured as fo
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.
+This location will be saved as a [catalog entry]({{ site.path.guide }}/ops/catalog/index.html#locations-in-the-catalog)
+for easy reusability.
#### Passwordless Sudo
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/_openstack.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/_openstack.md b/guide/ops/locations/_openstack.md
index cb331dc..0225824 100644
--- a/guide/ops/locations/_openstack.md
+++ b/guide/ops/locations/_openstack.md
@@ -17,7 +17,7 @@ Support for OpenStack is provided by Apache jclouds. For more information, see t
The endpoint URI is that of keystone (normally on port 5000).
-The identity normally consists of the tenant and username, colons-separated. The credential is
+The identity normally consists of a colon-separated tenant and username. The credential is
the password. For example:
location:
@@ -27,7 +27,12 @@ the password. For example:
credential: your-password
OpenStack Nova access information can be downloaded from the openstack web interface, for example
-as an openrc.sh file. This file will normally contain the identity and credential.
+as an openrc.sh file. It is usually available from API Access tab in "Access & Security" section.
+This file will normally contain the identity and credential.
+
+Users are strongly recommended to use
+[externalized configuration]({{ site.path.guide }}/ops/externalized-configuration.html) for better
+credential management, for example using [Vault](https://www.vaultproject.io/).
### Common Configuration Options
@@ -36,8 +41,8 @@ Below are examples of configuration options that use values specific to OpenStac
* The `imageId` is the id of an image. For example,
`imageId: RegionOne/08086159-8b0b-4970-b332-a7a929ee601f`.
- These ids can be found from the the CLI or the web-console, for example in IBM Blue Box,
- the URL is https://cloudsoft2-lon.openstack.blueboxgrid.com/project/images/.
+ These ids can be found from the the CLI or the web-console, for example in IBM Blue Box London,
+ the URL is https://tenant-region.openstack.blueboxgrid.com/project/images/.
* The `hardwareId` is the [flavor id](http://docs.openstack.org/admin-guide/compute-flavors.html).
For example `hardwareId: RegionOne/1`. These ids can be found from the the CLI or the web-console,
@@ -162,20 +167,22 @@ is inferred from the image metadata, but if no (or the wrong) login user is spec
default to root. The correct login user can be specified using the configuration option `loginUser`.
For example, `loginUser: ubuntu`.
-The use of the wrong login user can also result in the obscure error shown below, caused by
+The use of the wrong login user can also result in the obscure message, caused by
an unexpected response saying to use a different user. For more technical information, see
-this [sshj github issue](https://github.com/hierynomus/sshj/issues/75):
+this [sshj github issue](https://github.com/hierynomus/sshj/issues/75). The message is:
Received message too long 1349281121
-#### I Want to Use my Own KeyPair
+#### I Want to Use My Own KeyPair
By default, jclouds will auto-generate a new [key pair](http://docs.openstack.org/user-guide/cli_nova_configure_access_security_for_instances.html)
for the VM. This key pair will be deleted automatically when the VM is deleted.
Alternatively, you can use a pre-existing key pair. If so, you must also specify the corresponding
-private key (pem file, or data) to be used for the initial login. For example:
+private key (pem file, or data) to be used for the initial login. The name used in the `keyPair`
+configuration must match the name of a key pair that has already been added in OpenStack.
+For example:
location:
jclouds:clouds:openstack-nova:
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index 51f906a..4a8b40d 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -10,9 +10,12 @@ Locations are the environments to which Brooklyn deploys applications. Most comm
are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying
to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
-Also see the [Locations yaml guide]({{ site.path.guide }}/yaml/setting-locations.html),
-use within an entity of [provisioning.properties]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging),
-how to add location definitions to the [Catalog]({{ site.path.guide }}/ops/catalog/),
-and how to use [Externalized Configuration](({{ site.path.guide }}/ops/externalized-configuration.html).
+See also:
+
+* The [Locations yaml guide]({{ site.path.guide }}/yaml/setting-locations.html)
+* Use within an entity of the configuration option
+ [provisioning.properties]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)
+* How to add location definitions to the [Catalog]({{ site.path.guide }}/ops/catalog/); and
+* How to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html).
{% child_content %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
index 3a7d3ab..83aae74 100644
--- a/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
+++ b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
@@ -9,6 +9,7 @@ services:
$brooklyn:entitySpec:
type: org.apache.brooklyn.entity.group.DynamicCluster
brooklyn.config:
+ cluster.initial.size: 3
memberSpec:
$brooklyn:entitySpec:
type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/5f5fe0d3/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/guide/yaml/setting-locations.md b/guide/yaml/setting-locations.md
index 23ce6a4..906a194 100644
--- a/guide/yaml/setting-locations.md
+++ b/guide/yaml/setting-locations.md
@@ -30,7 +30,7 @@ although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/`
(or `client/api/` in the case of CloudStack) instead of the `region`.
-### "Bring Your Own Nodes" Example
+### "Bring Your Own Nodes" (BYON) Example
You can also specify pre-existing servers to use -- "bring-your-own-nodes".
The example below shows a pool of machines that will be used by the entities within the
@@ -78,8 +78,8 @@ locations:
The rules for precedence when defining a location for an entity are:
* The location defined on that specific entity.
-* If no location, then the first ancestor that defines an explicit location.
-* If still no location, then the location defined at the top-level of the blueprint.
+* If no location is defined, then the first ancestor that defines an explicit location.
+* If still no location is defined, then the location defined at the top-level of the blueprint.
This means, for example, that if you define an explicit location on a cluster then it will be used
for all members of that cluster.
@@ -91,12 +91,18 @@ Some entities are written to expect a set of locations. For example, a `DynamicF
create a member entity in each location that it is given. To supply multiple locations, simply
use `locations` with a yaml list.
-In the example below, it will create a cluster of app-servers in each location:
+In the example below, it will create a cluster of app-servers in each location. One location is
+used for each `DynamicCluster`; all app-servers inside that cluster will obtain a machine from
+that given location.
{% highlight yaml %}
{% readj example_yaml/fabric-with-multiple-locations.yaml %}
{% endhighlight %}
+The entity hierarchy at runtime will have a `DynamicFabric` with two children, each of type
+`DynamicCluster` (each running in different locations), each of which initially has three
+app-servers.
+
For brevity, this example excludes the credentials for aws-ec2. These could either be specificed
in-line or defined as named locations in the catalog (see below).
[3/5] brooklyn-docs git commit: improve location yaml-syntax docs
Posted by al...@apache.org.
improve location yaml-syntax docs
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/de1e235b
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/de1e235b
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/de1e235b
Branch: refs/heads/master
Commit: de1e235b4e4689a814112574e7b733b445684b65
Parents: 2be644e
Author: Aled Sage <al...@gmail.com>
Authored: Tue Aug 2 12:44:10 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Wed Aug 3 22:22:55 2016 +0100
----------------------------------------------------------------------
guide/ops/locations/index.md | 22 ++--
.../fabric-with-multiple-locations.yaml | 14 +++
.../simple-appserver-with-location-byon.yaml | 4 +-
...mple-appserver-with-location-per-entity.yaml | 8 ++
.../simple-appserver-with-location.yaml | 2 +-
guide/yaml/setting-locations.md | 109 ++++++++++++++++---
6 files changed, 126 insertions(+), 33 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/ops/locations/index.md
----------------------------------------------------------------------
diff --git a/guide/ops/locations/index.md b/guide/ops/locations/index.md
index fbcf35f..51f906a 100644
--- a/guide/ops/locations/index.md
+++ b/guide/ops/locations/index.md
@@ -6,21 +6,13 @@ children:
check_directory_for_children: true
---
-Locations are the environments to which Brooklyn deploys applications, including:
+Locations are the environments to which Brooklyn deploys applications. Most commonly these
+are cloud services such as AWS, GCE, and IBM Softlayer. Brooklyn also supports deploying
+to a pre-provisioned network or to localhost (primarily useful for testing blueprints).
-Brooklyn supports a wide range of locations:
-
-* <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
-
-Configuration can be set in `~/.brooklyn/brooklyn.properties`, through the
-location wizard tool available within the web console
-or directly in YAML when specifying a location.
-On some entities, config keys determining matching selection and provisioning behavior
-can also be set in `provisioning.properties`.
+Also see the [Locations yaml guide]({{ site.path.guide }}/yaml/setting-locations.html),
+use within an entity of [provisioning.properties]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging),
+how to add location definitions to the [Catalog]({{ site.path.guide }}/ops/catalog/),
+and how to use [Externalized Configuration](({{ site.path.guide }}/ops/externalized-configuration.html).
{% child_content %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
new file mode 100644
index 0000000..3a7d3ab
--- /dev/null
+++ b/guide/yaml/example_yaml/fabric-with-multiple-locations.yaml
@@ -0,0 +1,14 @@
+name: fabric-of-app-server-clusters
+locations:
+- aws-ec2:us-east-1
+- aws-ec2:us-west-1
+services:
+- type: org.apache.brooklyn.entity.group.DynamicFabric
+ brooklyn.config:
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.group.DynamicCluster
+ brooklyn.config:
+ memberSpec:
+ $brooklyn:entitySpec:
+ type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
index 8e9c951..7e4c0ca 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-byon.yaml
@@ -7,6 +7,4 @@ location:
- 192.168.0.18
- 192.168.0.19
services:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
- location:
- byon:(hosts="127.0.0.1")
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
new file mode 100644
index 0000000..a39e27d
--- /dev/null
+++ b/guide/yaml/example_yaml/simple-appserver-with-location-per-entity.yaml
@@ -0,0 +1,8 @@
+name: simple-appserver-with-location-per-entity
+services:
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
+ location:
+ byon(hosts="192.168.0.18",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
+- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+ location:
+ byon(hosts="192.168.0.19",user="brooklyn",privateKeyFile="~/.ssh/brooklyn.pem")
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
----------------------------------------------------------------------
diff --git a/guide/yaml/example_yaml/simple-appserver-with-location.yaml b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
index 79344c8..764eaac 100644
--- a/guide/yaml/example_yaml/simple-appserver-with-location.yaml
+++ b/guide/yaml/example_yaml/simple-appserver-with-location.yaml
@@ -5,4 +5,4 @@ location:
identity: AKA_YOUR_ACCESS_KEY_ID
credential: <access-key-hex-digits>
services:
-- type: org.apache.brooklyn.entity.webapp.jboss.JBoss7Server
+- type: org.apache.brooklyn.entity.webapp.tomcat.Tomcat8Server
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/de1e235b/guide/yaml/setting-locations.md
----------------------------------------------------------------------
diff --git a/guide/yaml/setting-locations.md b/guide/yaml/setting-locations.md
index ab92369..23ce6a4 100644
--- a/guide/yaml/setting-locations.md
+++ b/guide/yaml/setting-locations.md
@@ -7,8 +7,13 @@ categories: [use, guide, defining-applications]
{% include fields.md %}
-Brooklyn supports a very wide range of target locations -- localhost is mainly a convenience for testing.
-With deep integration to [Apache jclouds](http://jclouds.org), most well-known clouds and cloud platforms are supported.
+Brooklyn supports a very wide range of target locations.
+With deep integration to [Apache jclouds](https://jclouds.apache.org), most well-known clouds
+and cloud platforms are supported. See the [Locations guide]({{ site.path.guide }}/ops/locations/)
+for details and more examples.
+
+### Cloud Example
+
The following example is for Amazon EC2:
{% highlight yaml %}
@@ -24,22 +29,98 @@ Private cloud systems including `openstack-nova` and `cloudstack` are also suppo
although for these you'll supply an `endpoint: https://9.9.9.9:9999/v2.0/`
(or `client/api/` in the case of CloudStack) instead of the `region`.
+
+### "Bring Your Own Nodes" Example
+
You can also specify pre-existing servers to use -- "bring-your-own-nodes".
-These can be a global pool or specific to a service.
-Both styles are shown here (though normally only one will be selected,
-<!-- TODO see #1377, currently it is *parent* location which is preferred typically -->
-depending on the blueprint):
+The example below shows a pool of machines that will be used by the entities within the
+application.
{% highlight yaml %}
{% readj example_yaml/simple-appserver-with-location-byon.yaml %}
{% endhighlight %}
-Note in this example that we've used JSON-style notation in the second `location` block.
-YAML supports this, and sometimes that makes more readable plans.
-(Although in this case a simple `location: localhost` is equivalent and even more succinct,
-but this is a tutorial.)
-For more information see the [Operations: Locations]({{ site.path.guide }}/ops/locations) section of the User Guide.
-This includes support for defining locations externally in a [brooklyn.properties]({{ brooklyn_properties_url_path }}) file,
-after which you can deploy to clouds or bring-your-own-nodes
-simply as `location: jclouds:aws-ec2:eu-west-1` or `location: named:my_cloudstack`.
+### Single Line and Multi Line Locations
+
+A simple location can be specified on a single line. Alternatively, it can be split to have one
+configuration option per line (recommended for all but the simplest locations).
+
+For example, the two examples below are equivalent:
+
+{% highlight yaml %}
+location: byon(name="my loc",hosts="1.2.3.4",user="bob",privateKeyFile="~/.ssh/bob_id_rsa")
+{% endhighlight %}
+
+{% highlight yaml %}
+location:
+ byon:
+ name: "my loc"
+ hosts:
+ - "1.2.3.4"
+ user: "bob"
+ privateKeyFile: "~/.ssh/bob_id_rsa"
+{% endhighlight %}
+
+
+### Specific Locations for Specific Entities
+
+One can define specific locations on specific entities within the blueprint (instead of, or as
+well as, defining the location at the top-level of the blueprint).
+
+The example below will deploy Tomcat and JBoss App Server to different Bring Your Own Nodes
+locations:
+
+{% highlight yaml %}
+{% readj example_yaml/simple-appserver-with-location-per-entity.yaml %}
+{% endhighlight %}
+
+The rules for precedence when defining a location for an entity are:
+
+* The location defined on that specific entity.
+* If no location, then the first ancestor that defines an explicit location.
+* If still no location, then the location defined at the top-level of the blueprint.
+
+This means, for example, that if you define an explicit location on a cluster then it will be used
+for all members of that cluster.
+
+
+### Multiple Locations
+
+Some entities are written to expect a set of locations. For example, a `DynamicFabric` will
+create a member entity in each location that it is given. To supply multiple locations, simply
+use `locations` with a yaml list.
+
+In the example below, it will create a cluster of app-servers in each location:
+
+{% highlight yaml %}
+{% readj example_yaml/fabric-with-multiple-locations.yaml %}
+{% endhighlight %}
+
+For brevity, this example excludes the credentials for aws-ec2. These could either be specificed
+in-line or defined as named locations in the catalog (see below).
+
+
+### Adding Locations to the Catalog
+
+The examples above have given all the location details within the application blueprint.
+It is also possible (and indeed preferred) to add the location definitions to the catalog
+so that they can be referenced by name in any blueprint.
+
+For more information see the [Operations: Catalog]({{ site.path.guide }}/ops/catalog/) section of
+the User Guide.
+
+
+### Externalized Configuration
+
+For simplicity, the examples above have included the cloud credentials. For a production system,
+it is strongly recommended to use [Externalized Configuration]({{ site.path.guide }}/ops/externalized-configuration.html)
+to retrieve the credentials from a secure credentials store, such as [Vault](https://www.vaultproject.io).
+
+
+### Use of provisioning.properties
+
+An entity that represents a "software process" can use the configuration option
+`provisioning.properties` to augment the location's configuration. For more information, see
+[Entity Configuration]({{ site.path.guide }}/yaml/entity-configuration.html#entity-provisioningproperties-overriding-and-merging)
+details.
[2/5] brooklyn-docs git commit: Fix some broken links
Posted by al...@apache.org.
Fix some broken links
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/bcad595f
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/bcad595f
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/bcad595f
Branch: refs/heads/master
Commit: bcad595f71cd7d0c98e34a936a71662d0adc91f5
Parents: 1679a90
Author: Aled Sage <al...@gmail.com>
Authored: Thu Jul 28 23:16:42 2016 +0100
Committer: Aled Sage <al...@gmail.com>
Committed: Tue Aug 2 12:52:20 2016 +0100
----------------------------------------------------------------------
guide/ops/starting-stopping-monitoring.md | 2 +-
guide/yaml/winrm/index.md | 2 +-
website/learnmore/catalog/catalog-item.html | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/bcad595f/guide/ops/starting-stopping-monitoring.md
----------------------------------------------------------------------
diff --git a/guide/ops/starting-stopping-monitoring.md b/guide/ops/starting-stopping-monitoring.md
index ffd9084..c931d94 100644
--- a/guide/ops/starting-stopping-monitoring.md
+++ b/guide/ops/starting-stopping-monitoring.md
@@ -68,7 +68,7 @@ tools - the monitoring tool can discover the expected PID, and can execute the
start or stop commands shown above as necessary.
For example, here is a fragment of a `monitrc` file as used by
-[Monit](http://https://mmonit.com/monit/), for a Brooklyn `.tar.gz` distribution
+[Monit](https://mmonit.com/monit/), for a Brooklyn `.tar.gz` distribution
unpacked and installed at `/opt/apache-brooklyn`:
{% highlight text %}
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/bcad595f/guide/yaml/winrm/index.md
----------------------------------------------------------------------
diff --git a/guide/yaml/winrm/index.md b/guide/yaml/winrm/index.md
index 2e5b536..74e751d 100644
--- a/guide/yaml/winrm/index.md
+++ b/guide/yaml/winrm/index.md
@@ -312,7 +312,7 @@ The script works for most of the Windows images out there version 2008 and later
Please ensure that Brooklyn's changes are compatible with your organisation's security policy.
-Check Microsoft Documentation for more information about [Negotiate authenticate mechanism on technet.microsoft.com](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378748\(v=vs.85\).aspx)
+Check Microsoft Documentation for more information about [Negotiate authenticate mechanism on technet.microsoft.com](https://msdn.microsoft.com/en-us/library/windows/desktop/aa378748(v=vs.85).aspx)
Re-authentication also requires that the password credentials are passed in plain text within the
script. Please be aware that it is normal for script files - and therefore the plaintext password -
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/bcad595f/website/learnmore/catalog/catalog-item.html
----------------------------------------------------------------------
diff --git a/website/learnmore/catalog/catalog-item.html b/website/learnmore/catalog/catalog-item.html
index 0d9f1b5..a822289 100644
--- a/website/learnmore/catalog/catalog-item.html
+++ b/website/learnmore/catalog/catalog-item.html
@@ -36,7 +36,7 @@ under the License.
<div id="container">
<div id="header">
<div id="identity">
- <a href="http://brooklyncentral.github.com/" rel="home">Brooklyn</a>
+ <a href="https://brooklyn.apache.org/" rel="home">Brooklyn</a>
</div>
</div>