Repository: incubator-brooklyn Updated Branches: refs/heads/master f380b5836 -> ddc3dd9ff
Adds docs for location customizers Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/4a3987e8 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/4a3987e8 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/4a3987e8 Branch: refs/heads/master Commit: 4a3987e880846a50db93a014f13e55b8c3b39dd6 Parents: 49eabd1 Author: Aled Sage <[email protected]> Authored: Thu Oct 15 15:33:18 2015 +0200 Committer: Aled Sage <[email protected]> Committed: Thu Oct 15 20:37:24 2015 +0100 ---------------------------------------------------------------------- docs/guide/ops/locations/index.md | 4 +- .../guide/ops/locations/location-customizers.md | 152 +++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4a3987e8/docs/guide/ops/locations/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/index.md b/docs/guide/ops/locations/index.md index 60dd2e0..6cb5ec3 100644 --- a/docs/guide/ops/locations/index.md +++ b/docs/guide/ops/locations/index.md @@ -8,6 +8,7 @@ children: - { section: BYON } - cloud-credentials.md - more-locations.md +- location-customizers.md - ssh-keys.md --- @@ -430,6 +431,7 @@ provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`. ### Other Location Topics +* [Cloud Credentials](cloud-credentials.html) * [More Locations](more-locations.html) +* [Location Customizers](location-customizers.html) * [SSH Keys](ssh-keys.html) -* [Cloud Credentials](cloud-credentials.html) http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/blob/4a3987e8/docs/guide/ops/locations/location-customizers.md ---------------------------------------------------------------------- diff --git a/docs/guide/ops/locations/location-customizers.md b/docs/guide/ops/locations/location-customizers.md new file mode 100644 index 0000000..ad1f17e --- /dev/null +++ b/docs/guide/ops/locations/location-customizers.md @@ -0,0 +1,152 @@ +--- +title: Location customizers +layout: website-normal +--- + +Apache Brooklyn supports a number of ways to configure and customize locations. These include +the `JcloudsLocationCustomizer`, which is for advanced customization of VM provisioning through jclouds. +There is also a `MachineLocationCustomizer`, which allows customization of machines being obtained +from any kind of location (including [Bring Your Own Nodes](index.html#byon)). + + +## Usage Guidelines + +Clearly there is an overlap for where things can be done. This section describes the recommended +separation of responsibilities. + +These are guidelines only - users are obviously free to make alternative usage decisions based on +their particular use-cases. + +### Responsibilities of Entity versus Location + +From an entity's perspective, it calls `location.obtain(options)` and gets back a usable +`MachineLocation` that has a standard base operating system that gives remote access +(e.g. for Linux it expects credentials for a user with `sudo` rights, and ssh access). + +However, there are special cases - for example the `location.obtain(options)` could return +a Docker container with the software pre-installed, and no remote access (see the +[Clocker project](http://clocker.io) for more information on use of Docker with Brooklyn). + +The entity is then responsible for configuring that machine according to the needs of the software +to be installed. + +For example, the entity may install software packages, upload/update configuration files, launch +processes, etc. + +The entity may also configure `iptables`. This is also possible through the `JcloudsLocation` +configuration. However, it is preferable to do this in the entity because it is part of +configuring the machine in the way required for the given software component. + +The entity may also perform custom OS setup, such as installing security patches. However, whether +this is appropriate depends on the nature of the security patch: if the security patch is specific +to the entity type, then it should be done within the entity; but if it is to harden the base OS +to make it comply with an organisation's standards (e.g. to overcome shortcomings of the base +image, or to install security patches) then a `MachineLocationCustomizer` is more appropriate. + +### Location Configuration Options + +This refers to standard location configuration: explicit config keys, and explicit jclouds template +configuration that can be passed through. + +This kind of configuration is simplest to use. It is the favoured mechanism when it comes to VM +provisioning, and should be used wherever possible. + +Note that a jclouds `TemplateBuilder` and cloud-specific `TemplateOptions` are the generic mechanisms +within jclouds for specifying the details of the compute resource to be provisioned. + +### Jclouds Location Customizer +A `JcloudsLocationCustomizer` has customization hooks to execute code at the various points of building +up the jclouds template and provisioning the machine. Where jclouds is being used and where the required +use of jclouds goes beyond simple configuration, this is an appropriate solution. + +For example, there is a `org.apache.brooklyn.location.jclouds.networking.JcloudsLocationSecurityGroupCustomizer` +which gives more advanced support for setting up security groups (e.g. in AWS-EC2). + +### Machine Customizer + +The `MachineLocationCustomizer` allows customization of machines being obtained from any kind of location. +For example, this includes for jclouds and for Bring Your Own Nodes (BYON). + +It provides customization hooks for when the machine has been provisioned (before it is returned by the location) +and when the machine is about to be released by the location. + +An example use would be to register (and de-register) the machine in a CMDB. + + +## Jclouds Location Customizers + +*Warning: additional methods (i.e. customization hooks) may be added to the `JcloudsLocationCustomizer` +interface in future releases. Users are therefore strongly encouraged to sub-class +`BasicJcloudsLocationCustomizer`, rather than implementing JcloudsLocationCustomizer directly.* + +The `JcloudsLocationCustomizer` provides customization hooks at various points of the Brooklyn's +use of jclouds. These can be used to adjust the configuration, to do additional setup, to do +custom logging, etc. + +* Customize the `org.jclouds.compute.domain.TemplateBuilder`, before it is used to build the template. + This is used to influence the choice of VM image, hardware profile, etc. This hook is not normally + required as the location configuration options can be used in instead. + +* Customize the `org.jclouds.compute.domain.Template`, to be used when creating the machine. This + hook is most often used for performing custom actions - for example to create or modify a security + group or volume, and to update the template's options to use that. + +* Customize the `org.jclouds.compute.options.TemplateOptions` to be used when creating the machine. + The `TemplateOptions` could be cast to a cloud-specific sub-type (if this does not have to work + across different clouds). Where the use-case is to just set simple configuration on the + `TemplateOptions`, consider instead using the config key `templateOptions`, which takes a map + of type String to Object - the strings should match the method names in the `TemplateOptions`. + +* Customize the `org.apache.brooklyn.location.jclouds.JcloudsMachineLocation` that has been + created. For Linux-based VMs, if the config `waitForSshable` was not false, then this machine + is guaranteed to be ssh'able. Similarly for WinRM access to Windows machines, if + `waitForWinRmAvailable` was not false. + +* Pre-release of the machine. If the actions required are specific to jclouds (e.g. using jclouds + to make calls to the cloud provider) then this should be used; otherwise one should use the more + generic `MachineLocationCustomizer`. + +* Post-release of the machine (i.e. after asking jclouds to destroying the machine). + +To register a `JcloudsLocationCustomizer` in YAML, the config key `customizers` can be used to +provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate +the type and its configuration. For example: + + location: + jclouds:aws-ec2:us-east-1: + customizers: + - $brooklyn:object: + type: com.acme.brooklyn.MyJcloudsLocationCustomizer + +To register `JcloudsLocationCustomizer` instances programmatically, set the config key +`JcloudsLocationConfig.JCLOUDS_LOCATION_CUSTOMIZERS` on the location, or pass this +config option when calling `location.obtain(options)`. + + +## Machine Location Customizers + +*Warning: additional methods (i.e. customization hooks) may be added to the `MachineLocationCustomizer` +interface in future releases. Users are therefore strongly encouraged to sub-class +`BasicMachineLocationCustomizer`, rather than implementing `MachineLocationCustomizer` directly.* + +The `MachineLocationCustomizer` provides customization hooks for when a machine is obtained/released +from a `MachineProvisioningLocation`. The following hooks are supported: + +* After the machine has been provisioned/allocated, but before it has been returned. + +* When the machine is about to be released, but prior to actually destroying/unallocating the + machine. + +To register a `MachineLocationCustomizer` in YAML, the config key `machineCustomizers` can be used +to provide a list of instances. Each instance can be defined using `$brooklyn:object` to indicate +the type and its configuration. For example: + + location: + jclouds:aws-ec2:us-east-1: + machineCustomizers: + - $brooklyn:object: + type: com.acme.brooklyn.MyMachineLocationCustomizer + +To register `MachineLocationCustomizer` instances programmatically, set the config key +`CloudLocationConfig.MACHINE_LOCATION_CUSTOMIZERS` on the location, or pass this +config option when calling `location.obtain(options)`.
