Remove front matter from imported page that it is not processed and therefore displayed in the generated page. Also fix the titles level so that all sections have the same structure, starting with h2
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/f7d48651 Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/f7d48651 Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/f7d48651 Branch: refs/heads/master Commit: f7d486511179c2740118359939419d58a213db27 Parents: 8078623 Author: Thomas Bouron <[email protected]> Authored: Tue Oct 17 11:13:32 2017 +0100 Committer: Thomas Bouron <[email protected]> Committed: Tue Oct 17 11:13:32 2017 +0100 ---------------------------------------------------------------------- guide/locations/_AWS.md | 7 ------ guide/locations/_GCE.md | 7 ------ guide/locations/_azure-ARM.md | 24 ++++++++------------ guide/locations/_azure-classic.md | 22 +++++++----------- guide/locations/_byon.md | 8 +------ guide/locations/_clouds.md | 22 +++++++----------- guide/locations/_cloudstack.md | 7 ------ guide/locations/_ibm-softlayer.md | 7 ------ .../_inheritance-and-named-locations.md | 9 +------- guide/locations/_localhost.md | 10 ++------ .../_location-customizer-security-groups.md | 6 ----- guide/locations/_location-customizers.md | 24 ++++++++------------ guide/locations/_openstack.md | 7 ------ guide/locations/_special-locations.md | 18 +++++---------- guide/locations/_ssh-keys.md | 14 ++++-------- 15 files changed, 48 insertions(+), 144 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_AWS.md ---------------------------------------------------------------------- diff --git a/guide/locations/_AWS.md b/guide/locations/_AWS.md index c4d6bd1..ab01718 100644 --- a/guide/locations/_AWS.md +++ b/guide/locations/_AWS.md @@ -1,10 +1,3 @@ ---- -section: Amazon Web Services (AWS) -title: Amazon Web Services -section_type: inline -section_position: 2 ---- - ## Amazon Web Services (AWS) ### Credentials http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_GCE.md ---------------------------------------------------------------------- diff --git a/guide/locations/_GCE.md b/guide/locations/_GCE.md index 0641d79..1f51877 100644 --- a/guide/locations/_GCE.md +++ b/guide/locations/_GCE.md @@ -1,10 +1,3 @@ ---- -section: Google Compute Engine (GCE) -title: Google Compute Engine -section_type: inline -section_position: 5 ---- - ## Google Compute Engine (GCE) ### Credentials http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_azure-ARM.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-ARM.md b/guide/locations/_azure-ARM.md index 917d4d9..7e97842 100644 --- a/guide/locations/_azure-ARM.md +++ b/guide/locations/_azure-ARM.md @@ -1,16 +1,10 @@ ---- -section: Azure Compute ARM -section_type: inline -section_position: 2 ---- - -### Azure Compute ARM +## Azure Compute ARM Azure Resource Manager (ARM) is a framework for deploying and managing applications across resources and managing groups of resources as single logical units on the Microsoft Azure cloud computing platform. -#### Setup the Azure credentials +### Setup the Azure credentials -##### Azure CLI 2.0 +#### Azure CLI 2.0 Firstly, install and configure Azure CLI following [these steps](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest). @@ -81,7 +75,7 @@ We can now verify this information that this information can be used to log in t az login --service-principal -u <Application-ID> --password abcd --tenant <Tenant-ID> -##### Azure CLI 1.0 +#### Azure CLI 1.0 Firstly, install and configure Azure CLI following [these steps](https://docs.microsoft.com/en-us/azure/cli-install-nodejs). @@ -124,7 +118,7 @@ Verify service principal azure login -u <Application-id> -p <Password> --service-principal --tenant <Tenant-id> -#### Using the Azure ARM Location +### Using the Azure ARM Location Below is an example Azure ARM location in YAML which will launch a Ubuntu instance in south east asia: @@ -168,7 +162,7 @@ The loginUser can be anything, as long as it's specified. The `overrideAuthenticateSudo: true` key tells Apache Brooklyn that default on Azure images do not have passwordless sudo configured by default. -#### Useful configuration options for Azure ARM +### Useful configuration options for Azure ARM You can add these options directly under the `brooklyn.config` element in the example above: @@ -178,7 +172,7 @@ You can add these options into the `templateOptions` element inside the `brookly * `resourceGroup` - select a Resource Group to deploy resources into. If not given, jclouds will generate a new resource group with a partly-random name. -#### Using Windows on Azure ARM +### Using Windows on Azure ARM This section contains material how to create a Windows location on Azure ARM. Some of the used parameters are explained in the section above. @@ -213,7 +207,7 @@ stored in protected .PFX file. It needs to be prepared upfront or created with t * `enableAutomaticUpdates` whether to enable the automatic windows updates. It can be set to `false`, if automatic updates are not desired -###### Sample Windows Blueprint +##### Sample Windows Blueprint Placeholders surrounded with `<>` have to be replcaced with their respective values. @@ -259,7 +253,7 @@ brooklyn.catalog: enableAutomaticUpdates: true ``` -#### Known issues +### Known issues There are currently two known issues with Azure ARM: * It can take a long time for VMs to be provisioned http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_azure-classic.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-classic.md b/guide/locations/_azure-classic.md index e32a6ed..038da26 100644 --- a/guide/locations/_azure-classic.md +++ b/guide/locations/_azure-classic.md @@ -1,10 +1,4 @@ ---- -section: Azure Compute Classic -section_type: inline -section_position: 3 ---- - -### Azure Compute Classic +## Azure Compute Classic Azure is a cloud computing platform and infrastructure created by Microsoft. Apache Brooklyn includes support for both Azure Classic and Azure ARM, as one of the [Apache jclouds](http://jclouds.org) supported clouds `Microsoft Azure Compute`. @@ -14,7 +8,7 @@ model. See [https://azure.microsoft.com/en-gb/documentation/articles/resource-ma for details. -#### Setup the Azure credentials +### Setup the Azure credentials Microsoft Azure requests are signed by SSL certificate. You need to upload one into your account in order to use an Azure location. @@ -36,7 +30,7 @@ Please note, you can find the "myId" value for this link by looking at the URL w **Note**, you will need to use `.p12` format in the `brooklyn.properties`. -#### How to configure Apache Brooklyn to use Azure Compute +### How to configure Apache Brooklyn to use Azure Compute First, in your `brooklyn.properties` define a location as follows: @@ -81,7 +75,7 @@ rather than "classic". * `ExtraSmall`, `Small`, `Medium`, `Large`, `ExtraLarge` -##### Named location +#### Named location For convenience, you can define a named location, like: @@ -102,7 +96,7 @@ On Linux VMs, The `user` and `password` will create a user with that name and se disabling the normal login user and password defined on the `azurecompute` location. -#### Windows VMs on Azure +### Windows VMs on Azure The following configuration options are important for provisioning Windows VMs in Azure: @@ -153,7 +147,7 @@ The following configuration options are important for provisioning Windows VMs i This configuration is subject to change in future releases. -###### Sample Windows Blueprint +##### Sample Windows Blueprint Below is an example for provisioning a Windows-based entity on Azure. Note the placeholder values for the identity, credential and password. @@ -205,7 +199,7 @@ brooklyn.location.named.myazure.password=secretPass1! brooklyn.location.named.myazure.templateOptions={ overrideLoginUser: amp, overrideLoginPassword: secretPass1! } ``` -###### User and Password Configuration +##### User and Password Configuration As described under the configuration options, the username and password must be explicitly supplied in the configuration. @@ -220,7 +214,7 @@ This approach differs from the behaviour of clouds like AWS, where the password by the cloud provider and is then retrieved via the cloud provider's API after provisioning the VM. -###### WinRM Configuration +##### WinRM Configuration The WinRM initialization in Azure is achieved through configuration options in the VM provisioning request. The required configuration is to enabled HTTPS (if Azure is told to use http, the VM comes pre-configured http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_byon.md ---------------------------------------------------------------------- diff --git a/guide/locations/_byon.md b/guide/locations/_byon.md index a571899..fa051a7 100644 --- a/guide/locations/_byon.md +++ b/guide/locations/_byon.md @@ -1,10 +1,4 @@ ---- -section: BYON -section_position: 8 -section_type: inline ---- - -### BYON +## BYON "Bring-your-own-nodes" mode is useful in production, where machines have been provisioned by someone else, and during testing, to cut down provisioning time. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_clouds.md ---------------------------------------------------------------------- diff --git a/guide/locations/_clouds.md b/guide/locations/_clouds.md index 6fe82c2..42ffd3c 100644 --- a/guide/locations/_clouds.md +++ b/guide/locations/_clouds.md @@ -1,10 +1,4 @@ ---- -section: Clouds -section_type: inline -section_position: 1 ---- - -### Clouds +## Clouds For most cloud provisioning tasks, Brooklyn uses <a href="http://jclouds.org";>Apache jclouds</a>. @@ -48,7 +42,7 @@ The configuration options are described in more detail below. In some cases, cloud providers have special features or unusual requirements. These are outlined in **[More Details for Specific Clouds](#more-details-on-specific-clouds)**. -#### OS Initial Login and Setup +### OS Initial Login and Setup Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly. @@ -83,14 +77,14 @@ Following a successful logon, Brooklyn performs the following steps to configure These steps can be skipped or customized as described below. -#### jclouds Config Keys +### jclouds Config Keys The following is a subset of the most commonly used configuration keys used to customize cloud provisioning. For more keys and more detail on the keys below, see [JcloudsLocationConfig]({{book.url.brooklyn_javadoc}}/org/apache/brooklyn/location/jclouds/JcloudsLocationConfig.html). -###### VM Creation +##### VM Creation - Most providers require exactly one of either `region` (e.g. `us-east-1`) or `endpoint` (the URL, usually for private cloud deployments) @@ -146,7 +140,7 @@ For more keys and more detail on the keys below, see - You can set `useMachinePublicAddressAsPrivateAddress` to true to overwrite the VMs private IP with its public IP. This is useful as it can be difficult to get VMs communicating via the private IPs they are assigned in some clouds. Using this config, blueprints which use private IPs can still be deployed to these clouds. - ###### OS Setup +##### OS Setup - `user` and `password` can be used to configure the operating user created on cloud-provisioned machines @@ -230,7 +224,7 @@ For more keys and more detail on the keys below, see This setting prevents scripts executed on the VMs from being deleted on completion. Note that some scripts run periodically so this can eventually fill a disk; it should only be used for dev/test. -###### Custom Template Options +##### Custom Template Options jclouds supports many additional options for configuring how a virtual machine is created and deployed, many of which are for cloud-specific features and enhancements. Brooklyn supports some of these, but if what you are looking for is @@ -272,7 +266,7 @@ Here you can see that we set three template options: If the method call cannot be matched to the template options available - for example if you are trying to set an AWS EC2 specific option but your location is an OpenStack cloud - then a warning is logged and the option is ignored. -###### Cloud Machine Naming +##### Cloud Machine Naming The name that Apache Brooklyn generates for your virtual machine will, by default, be based on your Apache Brooklyn server name and the IDs of the entities involved. This is the name you see in places such as the AWS console and will look something like: @@ -291,7 +285,7 @@ The above example will create a name such as: Allowing you to more easily identify your virtual machines. -### More Details on Specific Clouds +## More Details on Specific Clouds 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 http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_cloudstack.md ---------------------------------------------------------------------- diff --git a/guide/locations/_cloudstack.md b/guide/locations/_cloudstack.md index e2fb52c..c88a113 100644 --- a/guide/locations/_cloudstack.md +++ b/guide/locations/_cloudstack.md @@ -1,10 +1,3 @@ ---- -section: CloudStack -title: Apache CloudStack -section_type: inline -section_position: 4 ---- - ## Apache CloudStack ### Connection Details http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_ibm-softlayer.md ---------------------------------------------------------------------- diff --git a/guide/locations/_ibm-softlayer.md b/guide/locations/_ibm-softlayer.md index 6f1982c..4edccd1 100644 --- a/guide/locations/_ibm-softlayer.md +++ b/guide/locations/_ibm-softlayer.md @@ -1,10 +1,3 @@ ---- -section: IBM Softlayer -title: IBM Softlayer -section_type: inline -section_position: 6 ---- - ## IBM SoftLayer ### Credentials http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_inheritance-and-named-locations.md ---------------------------------------------------------------------- diff --git a/guide/locations/_inheritance-and-named-locations.md b/guide/locations/_inheritance-and-named-locations.md index f7f0d5d..3c74db1 100644 --- a/guide/locations/_inheritance-and-named-locations.md +++ b/guide/locations/_inheritance-and-named-locations.md @@ -1,11 +1,4 @@ ---- -section: Inheritance and Named Locations -title: Named Locations -section_type: inline -section_position: 7 ---- - -### Inheritance and Named Locations +## Inheritance and Named Locations Named locations can be defined for commonly used groups of properties, with the syntax `brooklyn.location.named.your-group-name.` http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_localhost.md ---------------------------------------------------------------------- diff --git a/guide/locations/_localhost.md b/guide/locations/_localhost.md index 726234f..4b90467 100644 --- a/guide/locations/_localhost.md +++ b/guide/locations/_localhost.md @@ -1,10 +1,4 @@ ---- -section: Localhost -section_position: 10 -section_type: inline ---- - -### Localhost +## Localhost If passwordless ssh login to `localhost` and passwordless `sudo` is enabled on your machine, you should be able to deploy some blueprints with no special configuration, @@ -23,7 +17,7 @@ This location will be saved as a [catalog entry](../blueprints/catalog/index.md# for easy reusability. -#### Passwordless Sudo +### Passwordless Sudo If you encounter issues or for more information, see [SSH Keys Localhost Setup](#localhost-setup). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_location-customizer-security-groups.md ---------------------------------------------------------------------- diff --git a/guide/locations/_location-customizer-security-groups.md b/guide/locations/_location-customizer-security-groups.md index 4dac838..caf0de3 100644 --- a/guide/locations/_location-customizer-security-groups.md +++ b/guide/locations/_location-customizer-security-groups.md @@ -1,9 +1,3 @@ ---- -section: Customizing Cloud Security Groups -section_position: 12 -section_type: inline ---- - ## Customizing Cloud Security Groups Before using SharedLocationSecurityGroupCustomizer, please first refer to [Port Inferencing](../blueprints/custom-entities.md#port-inferencing). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_location-customizers.md ---------------------------------------------------------------------- diff --git a/guide/locations/_location-customizers.md b/guide/locations/_location-customizers.md index 351144e..cfa03d3 100644 --- a/guide/locations/_location-customizers.md +++ b/guide/locations/_location-customizers.md @@ -1,10 +1,4 @@ ---- -section: Location Customizers -section_type: inline -section_position: 11 ---- - -### Location Customizers +## Location Customizers 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. @@ -12,7 +6,7 @@ There is also a `MachineLocationCustomizer`, which allows customization of machi from any kind of location (including [Bring Your Own Nodes](index.md#byon)). -#### Usage Guidelines +### Usage Guidelines Clearly there is an overlap for where things can be done. This section describes the recommended separation of responsibilities. @@ -20,7 +14,7 @@ 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 +### 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 @@ -46,7 +40,7 @@ to the entity type, then it should be done within the entity; but if it is to ha 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 +### Location Configuration Options This refers to standard location configuration: explicit config keys, and explicit jclouds template configuration that can be passed through. @@ -57,7 +51,7 @@ 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 +### 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. @@ -65,7 +59,7 @@ 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 +### 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). @@ -76,7 +70,7 @@ 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 +## 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 @@ -143,7 +137,7 @@ where `cidr` can be optionally set to restrict the range that the ports that are -#### Machine Location Customizers +### 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 @@ -171,7 +165,7 @@ To register `MachineLocationCustomizer` instances programmatically, set the conf `CloudLocationConfig.MACHINE_LOCATION_CUSTOMIZERS` on the location, or pass this config option when calling `location.obtain(options)`. -#### Hostname Customizer +### Hostname Customizer [org.apache.brooklyn.entity.machine.SetHostnameCustomizer](https://github.com/apache/brooklyn-server/blob/master/software/base/src/main/java/org/apache/brooklyn/entity/machine/SetHostnameCustomizer.java) Sets the hostname on an ssh'able machine. Currently only CentOS and RHEL are supported. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_openstack.md ---------------------------------------------------------------------- diff --git a/guide/locations/_openstack.md b/guide/locations/_openstack.md index cbad072..84c9f3d 100644 --- a/guide/locations/_openstack.md +++ b/guide/locations/_openstack.md @@ -1,10 +1,3 @@ ---- -section: OpenStack -title: OpenStack -section_type: inline -section_position: 7 ---- - ## OpenStack ### Apache jclouds http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_special-locations.md ---------------------------------------------------------------------- diff --git a/guide/locations/_special-locations.md b/guide/locations/_special-locations.md index 918024d..beaf3d9 100644 --- a/guide/locations/_special-locations.md +++ b/guide/locations/_special-locations.md @@ -1,14 +1,8 @@ ---- -section: Specialized Locations -section_position: 13 -section_type: inline ---- - -### Specialized Locations +## Specialized Locations Some additional location types are supported for specialized situations: -#### Single Host +### Single Host The spec `host`, taking a string argument (the address) or a map (`host`, `user`, `password`, etc.), provides a convenient syntax when specifying a single host. @@ -23,12 +17,12 @@ services: Or, in `brooklyn.properties`, set `brooklyn.location.named.host1=host:(192.168.0.1)`. -#### The Multi Location +### The Multi Location The spec `multi` allows multiple locations, specified as `targets`, to be combined and treated as one location. -##### Sequential Consumption +#### Sequential Consumption In its simplest form, this will use the first target location where possible, and will then switch to the second and subsequent locations when there are no @@ -52,7 +46,7 @@ services: type: org.apache.brooklyn.entity.machine.MachineEntity ``` -##### Round-Robin Consumption and Availability Zones for Clustered Applications +#### Round-Robin Consumption and Availability Zones for Clustered Applications A `DynamicCluster` can be configured to cycle through its deployment targets round-robin when provided with a location that supports the `AvailabilityZoneExtension` -- the `multi` location @@ -110,7 +104,7 @@ Custom alternatives to round-robin are also possible using the configuration opt `dynamiccluster.zone.placementStrategy` on `DynamicCluster`. -#### The Server Pool +### The Server Pool The [ServerPool]({{book.url.brooklyn_javadoc}}/org/apache/brooklyn/entity/machine/pool/ServerPool.html) entity type allows defining an entity which becomes available as a location. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/f7d48651/guide/locations/_ssh-keys.md ---------------------------------------------------------------------- diff --git a/guide/locations/_ssh-keys.md b/guide/locations/_ssh-keys.md index a5d4b9d..f4cacea 100644 --- a/guide/locations/_ssh-keys.md +++ b/guide/locations/_ssh-keys.md @@ -1,10 +1,4 @@ ---- -section: SSH Keys -section_position: 9 -section_type: inline ---- - -### SSH Keys +## SSH Keys SSH keys are one of the simplest and most secure ways to access remote servers. They consist of two parts: @@ -24,7 +18,7 @@ the remote machine can confirm it is you accessing it (if no one else has the pr and no one snooping on the network can decrypt of any of the traffic. -#### Creating an SSH Key +### Creating an SSH Key If you don't have an SSH key, create one with: @@ -33,7 +27,7 @@ $ ssh-keygen -t rsa -N "" -f ~/.ssh/id_rsa ``` -#### Localhost Setup +### Localhost Setup If you want to deploy to `localhost`, ensure that you have a public and private key, and that your key is authorized for ssh access: @@ -62,7 +56,7 @@ If this isn't the case, see below. -#### Potential Problems +### Potential Problems * **MacOS user?** In addition to the above, enable "Remote Login" in "System Preferences > Sharing".
