Repository: brooklyn-docs Updated Branches: refs/heads/master 44ed222a2 -> 309ceba9f
Expand OpenStack 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/8ed3108f Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/8ed3108f Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/8ed3108f Branch: refs/heads/master Commit: 8ed3108f065514fdeaed35a9126a567d17770cbe Parents: 9f2f0cf Author: Mike Zaccardo <[email protected]> Authored: Mon Jun 27 02:44:14 2016 -0700 Committer: Mike Zaccardo <[email protected]> Committed: Mon Jun 27 02:44:14 2016 -0700 ---------------------------------------------------------------------- guide/ops/locations/_more-clouds.md | 141 +++++++++++++++++++++++++------ 1 file changed, 117 insertions(+), 24 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/8ed3108f/guide/ops/locations/_more-clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_more-clouds.md b/guide/ops/locations/_more-clouds.md index 7d96704..de9e477 100644 --- a/guide/ops/locations/_more-clouds.md +++ b/guide/ops/locations/_more-clouds.md @@ -7,35 +7,35 @@ section_position: 2 ### More Details on Specific Clouds -To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the `identity` and -`credential` in Brooklyn terminology. +To connect to a Cloud, Brooklyn requires appropriate credentials. These comprise the `identity` and +`credential` in Brooklyn terminology. For private clouds (and for some clouds being targeted using a standard API), the `endpoint` -must also be specified, which is the cloud's URL. For public clouds, Brooklyn comes preconfigured -with the endpoints, but many offer different choices of the `region` where you might want to deploy. +must also be specified, which is the cloud's URL. For public clouds, Brooklyn comes preconfigured +with the endpoints, but many offer different choices of the `region` where you might want to deploy. Clouds vary in the format of the identity, credential, endpoint, and region. Some also have their own idiosyncracies. More details for configuring some common clouds is included below. You may also find these sources helpful: -* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file - in the Getting Started guide - contains numerous examples of configuring specific clouds, +* The **[template brooklyn.properties]({{ site.path.guide }}/start/brooklyn.properties)** file + in the Getting Started guide + contains numerous examples of configuring specific clouds, including the format of credentials and options for sometimes-fiddly private clouds. * The **[jclouds guides](https://jclouds.apache.org/guides)** describes low-level configuration sometimes required for various clouds. - + ## Amazon Web Services (AWS) ### Credentials -AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential +AWS has an "access key" and a "secret key", which correspond to Brooklyn's identity and credential respectively. These keys are the way for any programmatic mechanism to access the AWS API. -To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws) +To generate an access key and a secret key, see [jclouds instructions](http://jclouds.apache.org/guides/aws) and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html). An example of the expected format is shown below: @@ -50,7 +50,7 @@ Security groups are not always deleted by jclouds. This is due to a limitation i 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 +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: @@ -69,7 +69,7 @@ Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying: Subnets are typically used in conjunction with security groups. Brooklyn does *not* attempt to open additional ports -when private subnets or security groups are supplied, +when private subnets or security groups are supplied, so the subnet and ports must be configured appropriately for the blueprints being deployed. You can configure a default security group with appropriate (or all) ports opened for access from the appropriate (or all) CIDRs and security groups, @@ -77,9 +77,9 @@ or you can define specific `securityGroups` on the location or as `provisioning.properties` on the entities. Make sure that Brooklyn has access to the machines under management. -This includes SSH, which might be done with a public IP created with inbound access -on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it. -Alternatively you can run Brooklyn on a machine in that same subnet, or +This includes SSH, which might be done with a public IP created with inbound access +on port 22 permitted for a CIDR range including the IP from which Brooklyn contacts it. +Alternatively you can run Brooklyn on a machine in that same subnet, or set up a VPN or jumphost which Brooklyn will use. @@ -92,7 +92,7 @@ For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt fo which is a VPC-only instance type. If you are in a region configured to use "EC2 Classic" mode, you may see a message such as this: - 400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC. + 400 VPCResourceNotSpecified: The specified instance type can only be used in a VPC. A subnet ID or network interface ID is required to carry out the request. This is a limitation of "legacy" accounts. The easiest fixes are either: @@ -103,13 +103,13 @@ This is a limitation of "legacy" accounts. The easiest fixes are either: irrespective of the age of your AWS account) * get a new AWS account -- "VPC" will be the default mode (Amazon recommend this and if you want to migrate existing deployments - they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) + they provide [detailed instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/vpc-migrate.html)) To understand the situation, the following resources may be useful: - + * Background on VPC vs Classic: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html) * Good succinct answers to FAQs: [http://aws.amazon.com/vpc/faqs/#Default_VPCs]() -* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]() +* Check if a region in your account is "VPC" or "Classic": [http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/default-vpc.html#default-vpc-availability]() * Regarding instance types: * All instance types: [https://aws.amazon.com/ec2/instance-types]() * Those which require VPC: [http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-vpc.html#vpc-only-instance-types]() @@ -124,11 +124,11 @@ you can create a VPC and instruct Brooklyn to use it: so that it will "Auto-assign Public IP". 3. Next click on the "Security Groups" and find the `default` security group for that VPC. Modify its "Inbound Rules" to allow "All traffic" from "Anywhere". - (Or for more secure options, see the instructions in the previous section, + (Or for more secure options, see the instructions in the previous section, "Using Subnets".) 4. Finally make a note of the subnet ID (e.g. `subnet-a1b2c3d4`) for use in Brooklyn. -You can then deploy blueprints to the subnet, allowing VPC hardware instance types, +You can then deploy blueprints to the subnet, allowing VPC hardware instance types, by specifying the subnet ID as the `networkName` in your YAML blueprint. This is covered in the previous section, "Using Subnets". @@ -142,7 +142,7 @@ GCE uses a service account e-mail address for the identity and a private key as 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 +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 @@ -154,11 +154,11 @@ with `\n` representing the new line characters: GCE accounts can have low default [quotas](https://cloud.google.com/compute/docs/resource-quotas). It is easy to requesta quota increase by submitting a [quota increase form](https://support.google.com/cloud/answer/6075746?hl=en). - + ### Networks -GCE accounts often have a limit to the number of networks that can be created. One work around +GCE accounts often have a limit to the number of networks that can be created. One work around is to manually create a network with the required open ports, and to refer to that named network in Brooklyn's location configuration. @@ -269,6 +269,12 @@ then this customizer will have no effect. ## Openstack +### Apache jclouds + +Support for OpenStack is provided by Apache jclouds. For more information, see their guide +[here](https://jclouds.apache.org/guides/openstack/). + + ### Networks When multiple networks are available you should indicate which ones machines should join. @@ -300,7 +306,94 @@ Configuration of floating IPs is as networks; specify the pools to use as anothe - "pool name" +### Basic Location Structure + +This is a basic inline YAML template for an OpenStack location: + +``` +location: + jclouds:clouds:openstack-nova: + endpoint: http://x.x.x.x:5000/v2.0/ + identity: "your-tenant:your-username" + credential: your-password + + imageId: your-region-name/your-image-id + hardwareId: your-region-name/your-flavor-id + loginUser: 'ubuntu' + loginUser.privateKeyFile: /path/to/your/privatekey + jclouds.openstack-nova.auto-generate-keypairs: false + jclouds.openstack-nova.auto-create-floating-ips: true + + templateOptions: + networks: [ "your-network-id" ] + floatingIpPoolNames: [ "your-floatingIp-pool" ] + securityGroups: ['your-security-group'] + keyPairName: "your-keypair" +``` + +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.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/ + +brooklyn.location.named.My\ OpenStack.imageId=your-region-name/your-image-id +brooklyn.location.named.My\ OpenStack.hardwareId=your-region-name/your-flavor-id +brooklyn.location.named.My\ OpenStack.loginUser=ubuntu +brooklyn.location.named.My\ OpenStack.loginUser.privateKeyFile=/path/to/your/privatekey +brooklyn.location.named.My\ OpenStack.openstack-nova.auto-generate-keypairs=false +brooklyn.location.named.My\ OpenStack.openstack-nova.auto-create-floating-ips=true + +brooklyn.location.named.My\ OpenStack.networks=your-network-id +brooklyn.location.named.My\ OpenStack.floatingIpPoolNames=your-floatingIp-pool +brooklyn.location.named.My\ OpenStack.securityGroups=your-security-group +brooklyn.location.named.My\ OpenStack.keyPair=your-keypair +``` + +For an even more detailed example location configuration, consult the +[template properties file](https://brooklyn.apache.org/v/latest/start/brooklyn.properties). + +`my-flavor-id` can be chosen from the following options: + +``` ++-----+-----------+-----------+------+ +| 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 | ++-----+-----------+-----------+------+ +``` + + ### 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. + +### Troubleshooting + +#### jclouds Namespace Issue + +A change to Nova's API resulted in all extensions having the same "fake" namespace which +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"; +``` + +If this appears, perform the following steps as a workaround: + +* Generate a patch JAR `openstack-devtest-compute-1.9.2.jar` +by building: https://github.com/cloudsoft/jclouds-openstack-devtest +* Copy the patch JAR into $BROOKLYN_HOME/lib/patch +* Change `jclouds:openstack-nova` to `jclouds:openstack-devtest-compute` in your location +configuration
