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 <aled.s...@gmail.com> Authored: Thu Jul 28 23:17:13 2016 +0100 Committer: Aled Sage <aled.s...@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=123456789...@developer.gserviceaccount.com - brooklyn.location.jclouds.google-compute-engine.credential=-----BEGIN RSA PRIVATE KEY-----\nabcdefghijklmnopqrstuvwxyznabcdefghijk/lmnopqrstuvwxyzabcdefghij\nabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghij+lm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklm\nnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxy\nzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijk\nlmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\nxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\njklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstu\nvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefg\nhijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrs\ntuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcde\nfghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvw\n-----END RSA PRIVATE KEY----- +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-somet1mesarand0mu1dh...@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
