brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [4/5] brooklyn-docs git commit: location docs: incorporate review comments
Date Wed, 03 Aug 2016 21:27:02 GMT
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 <aled.sage@gmail.com>
Authored: Wed Aug 3 22:22:39 2016 +0100
Committer: Aled Sage <aled.sage@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).
 


Mime
View raw message