Repository: brooklyn-docs Updated Branches: refs/heads/master c600163fb -> 921210ad7
Split locations docs into more sections It is difficult to find the details for AWS softlayer in the locations doc as you have to scroll a long way so this commit splits them into separate sections Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/7d7c8f79 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/7d7c8f79 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/7d7c8f79 Branch: refs/heads/master Commit: 7d7c8f795a4ae7ec37b49cf1ab7f029c4fcebc2b Parents: 20ac9f6 Author: Duncan Grant <[email protected]> Authored: Mon Jul 4 15:50:54 2016 +0100 Committer: Duncan Grant <[email protected]> Committed: Mon Jul 4 15:50:54 2016 +0100 ---------------------------------------------------------------------- guide/ops/locations/_AWS.md | 113 ++++++ guide/ops/locations/_GCE.md | 46 +++ guide/ops/locations/_byon.md | 2 +- guide/ops/locations/_ibm-softlayer.md | 103 +++++ .../_inheritance-and-named-locations.md | 2 +- guide/ops/locations/_localhost.md | 2 +- guide/ops/locations/_more-clouds.md | 401 ------------------- guide/ops/locations/_openstack.md | 169 ++++++++ guide/ops/locations/_special-locations.md | 2 +- guide/ops/locations/_ssh-keys.md | 2 +- 10 files changed, 436 insertions(+), 406 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_AWS.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_AWS.md b/guide/ops/locations/_AWS.md new file mode 100644 index 0000000..5d43a20 --- /dev/null +++ b/guide/ops/locations/_AWS.md @@ -0,0 +1,113 @@ +--- +section: Amazon Web Services (AWS) +title: Amazon Web Services +section_type: inline +section_position: 3 +--- + +## Amazon Web Services (AWS) + +### Credentials + +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) +and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html). + +An example of the expected format is shown below: + + brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST + brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm + + +### 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. + + +### Using Subnets and Security Groups + +Apache Brooklyn can run with AWS VPC and both public and private subnets. +Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying: + + location: + jclouds:aws-ec2: + region: us-west-1 + networkName: subnet-a1b2c3d4 # use your subnet ID + +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, +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, +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 +set up a VPN or jumphost which Brooklyn will use. + + +### EC2 "Classic" Problems with VPC-only Hardware Instance Types + +If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode +by default, instead of the more modern "VPC" default mode. This can cause failures when requesting certain hardware +configurations because many of the more recent hardware "instance types" only run in "VPC" mode. +For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`, +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. + 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: + +* specify an instance type which is supported in classic, such as `m3.xlarge` (see below) +* move to a different region where VPC is the default + (`eu-central-1` should work as it *only* offers VPC mode, + 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)) + +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]() +* 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]() + +If you want to solve this problem with your existing account, +you can create a VPC and instruct Brooklyn to use it: + +1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc), + making sure it is for the right region, and selecting a "Single Public Subnet". + (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).) +2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet" + 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, + "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, +by specifying the subnet ID as the `networkName` in your YAML blueprint. +This is covered in the previous section, "Using Subnets". + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_GCE.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_GCE.md b/guide/ops/locations/_GCE.md new file mode 100644 index 0000000..10a739d --- /dev/null +++ b/guide/ops/locations/_GCE.md @@ -0,0 +1,46 @@ +--- +section: Google Compute Engine (GCE) +title: Google Compute Engine +section_type: inline +section_position: 4 +--- + +## Google Compute Engine (GCE) + +### Credentials + +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----- + + +### 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). + + +### Networks + +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. + +To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1). + +For example, for dev/demo purposes an "everything" network could be created that opens all ports. + +|| Name || everything | +|| Description || opens all tcp ports | +|| Source IP Ranges || 0.0.0.0/0 | +|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 | + + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_byon.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_byon.md b/guide/ops/locations/_byon.md index a7ab71b..525916d 100644 --- a/guide/ops/locations/_byon.md +++ b/guide/ops/locations/_byon.md @@ -1,6 +1,6 @@ --- section: BYON -section_position: 4 +section_position: 8 section_type: inline --- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_ibm-softlayer.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_ibm-softlayer.md b/guide/ops/locations/_ibm-softlayer.md new file mode 100644 index 0000000..63cdf86 --- /dev/null +++ b/guide/ops/locations/_ibm-softlayer.md @@ -0,0 +1,103 @@ +--- +section: IBM Softlayer +title: IBM Softlayer +section_type: inline +section_position: 5 +--- + +## IBM SoftLayer + +### VLAN Selection + +SoftLayer may provision VMs in different VLANs, even within the same region. +Some applications require VMs to be on the *same* internal subnet; blueprints +for these can specify this behaviour in SoftLayer in one of two ways. + +The VLAN ID can be set explicitly using the fields +`primaryNetworkComponentNetworkVlanId` and +`primaryBackendNetworkComponentNetworkVlanId` of `SoftLayerTemplateOptions` +when specifying the location being used in the blueprint, as follows: + + location: + jclouds:softlayer: + region: ams01 + templateOptions: + # Enter your preferred network IDs + primaryNetworkComponentNetworkVlanId: 1153481 + primaryBackendNetworkComponentNetworkVlanId: 1153483 + +This method requires that a VM already exist and you look up the IDs of its +VLANs, for example in the SoftLayer console UI, and that subsequently at least +one VM in that VLAN is kept around. If all VMs on a VLAN are destroyed +SoftLayer may destroy the VLAN. Creating VLANs directly and then specifying +them as IDs here may not work. Add a line note + +The second method tells Brooklyn to discover VLAN information automatically: it +will provision one VM first, and use the VLAN information from it when +provisioning subsequent machines. This ensures that all VMs are on the same +subnet without requiring any manual VLAN referencing, making it very easy for +end-users. + +To use this method, we tell brooklyn to use `SoftLayerSameVlanLocationCustomizer` +as a location customizer. This can be done on a location as follows: + + location: + jclouds:softlayer: + region: lon02 + customizers: + - $brooklyn:object: + type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer + softlayer.vlan.scopeUid: "my-custom-scope" + softlayer.vlan.timeout: 10m + +Usually you will want the scope to be unique to a single application, but if you +need multiple applications to share the same VLAN, simply configure them with +the same scope identifier. + +It is also possible with many blueprints to specify this as one of the +`provisioning.properties` on an *application*: + + services: + - type: org.apache.brooklyn.entity.stock.BasicApplication + id: same-vlan-application + brooklyn.config: + provisioning.properties: + customizers: + - $brooklyn:object: + type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer + softlayer.vlan.scopeUid: "my-custom-scope" + softlayer.vlan.timeout: 10m + +If you are writing an entity in Java, you can also use the helper +method `forScope(String)` to create the customizer. Configure the +provisioning flags as follows: + + JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope"); + flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans)); + + +### Configuration Options + +The allowed configuration keys for the `SoftLayerSameVlanLocationCustomizer` +are: + +- **softlayer.vlan.scopeUid** The scope identifier for locations whose + VMs will have the same VLAN. + +- **softlayer.vlan.timeout** The amount of time to wait for a VM to + be configured before timing out without setting the VLAN ids. + +- **softlayer.vlan.publicId** A specific public VLAN ID to use for + the specified scope. + +- **softlayer.vlan.privateId** A specific private VLAN ID to use for + the specified scope. + +An entity being deployed to a customized location will have the VLAN ids set as +sensors, with the same names as the last two configuration keys. + +***NOTE*** If the SoftLayer location is already configured with specific VLANs +then this customizer will have no effect. + + + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_inheritance-and-named-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_inheritance-and-named-locations.md b/guide/ops/locations/_inheritance-and-named-locations.md index 53fe904..bf237f3 100644 --- a/guide/ops/locations/_inheritance-and-named-locations.md +++ b/guide/ops/locations/_inheritance-and-named-locations.md @@ -2,7 +2,7 @@ section: Inheritance and Named Locations title: Named Locations section_type: inline -section_position: 3 +section_position: 7 --- ### Inheritance and Named Locations http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_localhost.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_localhost.md b/guide/ops/locations/_localhost.md index 8743be5..6558d9f 100644 --- a/guide/ops/locations/_localhost.md +++ b/guide/ops/locations/_localhost.md @@ -1,6 +1,6 @@ --- section: Localhost -section_position: 6 +section_position: 10 section_type: inline --- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_more-clouds.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_more-clouds.md b/guide/ops/locations/_more-clouds.md index d576744..7107fa0 100644 --- a/guide/ops/locations/_more-clouds.md +++ b/guide/ops/locations/_more-clouds.md @@ -26,404 +26,3 @@ is included below. You may also find these sources helpful: 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 -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) -and [AWS IAM instructions](http://docs.aws.amazon.com/IAM/latest/UserGuide/ManagingCredentials.html). - -An example of the expected format is shown below: - - brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST - brooklyn.location.jclouds.aws-ec2.credential=abcdefghijklmnopqrstu+vwxyzabcdefghijklm - - -### 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. - - -### Using Subnets and Security Groups - -Apache Brooklyn can run with AWS VPC and both public and private subnets. -Simply provide the `subnet-a1b2c3d4` as the `networkName` when deploying: - - location: - jclouds:aws-ec2: - region: us-west-1 - networkName: subnet-a1b2c3d4 # use your subnet ID - -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, -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, -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 -set up a VPN or jumphost which Brooklyn will use. - - -### EC2 "Classic" Problems with VPC-only Hardware Instance Types - -If you have a pre-2014 Amazon account, it is likely configured in some regions to run in "EC2 Classic" mode -by default, instead of the more modern "VPC" default mode. This can cause failures when requesting certain hardware -configurations because many of the more recent hardware "instance types" only run in "VPC" mode. -For instance when requesting an instance with `minRam: 8gb`, Brooklyn may opt for an `m4.large`, -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. - 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: - -* specify an instance type which is supported in classic, such as `m3.xlarge` (see below) -* move to a different region where VPC is the default - (`eu-central-1` should work as it *only* offers VPC mode, - 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)) - -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]() -* 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]() - -If you want to solve this problem with your existing account, -you can create a VPC and instruct Brooklyn to use it: - -1. Use the "Start VPC Wizard" option in [the VPC dashboard](https://console.aws.amazon.com/vpc), - making sure it is for the right region, and selecting a "Single Public Subnet". - (More information is in [these AWS instructions](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-a-vpc).) -2. Once the VPC is created, open the "Subnets" view and modify the "Public subnet" - 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, - "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, -by specifying the subnet ID as the `networkName` in your YAML blueprint. -This is covered in the previous section, "Using Subnets". - - -## Google Compute Engine (GCE) - -### Credentials - -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----- - - -### 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). - - -### Networks - -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. - -To create a network, see [GCE network instructions](https://cloud.google.com/compute/docs/networking#networks_1). - -For example, for dev/demo purposes an "everything" network could be created that opens all ports. - -|| Name || everything | -|| Description || opens all tcp ports | -|| Source IP Ranges || 0.0.0.0/0 | -|| Allowed protocols and ports || tcp:0-65535 and udp:0-65535 | - - -## IBM SoftLayer - -### VLAN Selection - -SoftLayer may provision VMs in different VLANs, even within the same region. -Some applications require VMs to be on the *same* internal subnet; blueprints -for these can specify this behaviour in SoftLayer in one of two ways. - -The VLAN ID can be set explicitly using the fields -`primaryNetworkComponentNetworkVlanId` and -`primaryBackendNetworkComponentNetworkVlanId` of `SoftLayerTemplateOptions` -when specifying the location being used in the blueprint, as follows: - - location: - jclouds:softlayer: - region: ams01 - templateOptions: - # Enter your preferred network IDs - primaryNetworkComponentNetworkVlanId: 1153481 - primaryBackendNetworkComponentNetworkVlanId: 1153483 - -This method requires that a VM already exist and you look up the IDs of its -VLANs, for example in the SoftLayer console UI, and that subsequently at least -one VM in that VLAN is kept around. If all VMs on a VLAN are destroyed -SoftLayer may destroy the VLAN. Creating VLANs directly and then specifying -them as IDs here may not work. Add a line note - -The second method tells Brooklyn to discover VLAN information automatically: it -will provision one VM first, and use the VLAN information from it when -provisioning subsequent machines. This ensures that all VMs are on the same -subnet without requiring any manual VLAN referencing, making it very easy for -end-users. - -To use this method, we tell brooklyn to use `SoftLayerSameVlanLocationCustomizer` -as a location customizer. This can be done on a location as follows: - - location: - jclouds:softlayer: - region: lon02 - customizers: - - $brooklyn:object: - type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer - softlayer.vlan.scopeUid: "my-custom-scope" - softlayer.vlan.timeout: 10m - -Usually you will want the scope to be unique to a single application, but if you -need multiple applications to share the same VLAN, simply configure them with -the same scope identifier. - -It is also possible with many blueprints to specify this as one of the -`provisioning.properties` on an *application*: - - services: - - type: org.apache.brooklyn.entity.stock.BasicApplication - id: same-vlan-application - brooklyn.config: - provisioning.properties: - customizers: - - $brooklyn:object: - type: org.apache.brooklyn.location.jclouds.softlayer.SoftLayerSameVlanLocationCustomizer - softlayer.vlan.scopeUid: "my-custom-scope" - softlayer.vlan.timeout: 10m - -If you are writing an entity in Java, you can also use the helper -method `forScope(String)` to create the customizer. Configure the -provisioning flags as follows: - - JcloudsLocationCustomizer vlans = SoftLayerSameVlanLocationCustomizer.forScope("my-custom-scope"); - flags.put(JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS.getName(), ImmutableList.of(vlans)); - - -### Configuration Options - -The allowed configuration keys for the `SoftLayerSameVlanLocationCustomizer` -are: - -- **softlayer.vlan.scopeUid** The scope identifier for locations whose - VMs will have the same VLAN. - -- **softlayer.vlan.timeout** The amount of time to wait for a VM to - be configured before timing out without setting the VLAN ids. - -- **softlayer.vlan.publicId** A specific public VLAN ID to use for - the specified scope. - -- **softlayer.vlan.privateId** A specific private VLAN ID to use for - the specified scope. - -An entity being deployed to a customized location will have the VLAN ids set as -sensors, with the same names as the last two configuration keys. - -***NOTE*** If the SoftLayer location is already configured with specific VLANs -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. -Do this by setting the desired values id as an option in the -**[templateOptions](#custom-template-options)** configuration: - - location: - jclouds:openstack-nova: - ... - templateOptions: - # Assign the node to all networks in the list. - networks: - - network-one-id - - network-two-id - - ... - - -### Floating IPs - -Configuration of floating IPs is as networks; specify the pools to use as another -[template option](#custom-template-options): - - location: - jclouds:openstack-nova: - ... - templateOptions: - # Pool names to use when allocating a floating IP - floatingIpPoolNames: - - "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, hardwareId, and loginUser* are optional - 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'] - - # Optional if 'jclouds.openstack-nova.auto-generate-keypairs' is assigned to 'true' - 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 -``` - -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: - -``` -+-----+-----------+-----------+------+ -| 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 an even more detailed example location configuration, consult the -[template properties file](https://brooklyn.apache.org/v/latest/start/brooklyn.properties). - - -### 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 - -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/ - identity: "your-tenant:your-username" - credential: your-password - templateOptions: - networks: [ "your-network-id" ] - floatingIpPoolNames: [ "your-floatingIp-pool" ] -``` - -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 -``` http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_openstack.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_openstack.md b/guide/ops/locations/_openstack.md new file mode 100644 index 0000000..242e7aa --- /dev/null +++ b/guide/ops/locations/_openstack.md @@ -0,0 +1,169 @@ +--- +section: Openstack +title: Openstack +section_type: inline +section_position: 6 +--- + +## 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. +Do this by setting the desired values id as an option in the +**[templateOptions](#custom-template-options)** configuration: + + location: + jclouds:openstack-nova: + ... + templateOptions: + # Assign the node to all networks in the list. + networks: + - network-one-id + - network-two-id + - ... + + +### Floating IPs + +Configuration of floating IPs is as networks; specify the pools to use as another +[template option](#custom-template-options): + + location: + jclouds:openstack-nova: + ... + templateOptions: + # Pool names to use when allocating a floating IP + floatingIpPoolNames: + - "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, hardwareId, and loginUser* are optional + 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'] + + # Optional if 'jclouds.openstack-nova.auto-generate-keypairs' is assigned to 'true' + 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 +``` + +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: + +``` ++-----+-----------+-----------+------+ +| 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 an even more detailed example location configuration, consult the +[template properties file](https://brooklyn.apache.org/v/latest/start/brooklyn.properties). + + +### 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 + +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/ + identity: "your-tenant:your-username" + credential: your-password + templateOptions: + networks: [ "your-network-id" ] + floatingIpPoolNames: [ "your-floatingIp-pool" ] +``` + +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 +``` + + http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_special-locations.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_special-locations.md b/guide/ops/locations/_special-locations.md index df38d1f..a3a69c6 100644 --- a/guide/ops/locations/_special-locations.md +++ b/guide/ops/locations/_special-locations.md @@ -1,6 +1,6 @@ --- section: Specialized Locations -section_position: 7 +section_position: 11 section_type: inline --- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/7d7c8f79/guide/ops/locations/_ssh-keys.md ---------------------------------------------------------------------- diff --git a/guide/ops/locations/_ssh-keys.md b/guide/ops/locations/_ssh-keys.md index 03ee84e..a929acf 100644 --- a/guide/ops/locations/_ssh-keys.md +++ b/guide/ops/locations/_ssh-keys.md @@ -1,6 +1,6 @@ --- section: SSH Keys -section_position: 5 +section_position: 9 section_type: inline ---
