http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/dev/tips/logging.md ---------------------------------------------------------------------- diff --git a/guide/dev/tips/logging.md b/guide/dev/tips/logging.md deleted file mode 100644 index a6e9a71..0000000 --- a/guide/dev/tips/logging.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Logging -layout: website-normal ---- - -## Logging: A Quick Overview - -For logging, we use **logback** which implements the slf4j API. -This means you can use any slf4j compliant logging framework, -with a default configuration which just works out of the box -and bindings to the other common libraries (``java.util.logging``, ``log4j``, ...) -if you prefer one of those. - - -### OSGi based Apache Brooklyn - -While developing it may be useful to change logging level of some of the Apache Brooklyn modules. -The easiest way to do that is via the karaf console which can be started by `bin/client`. -(Details regarding using [Apache Brooklyn Karaf console](../../blueprints/java/bundle-dependencies.html#karaf-console)) -For example if you would like to inspect jclouds API calls, enable jclouds.wire logging just enable it from karaf client. - - log:set DEBUG jclouds.wire - -To check other log levels. - - log:list - -If for some reason log level needs modified before the first start of Karaf -then you can modify the config file `etc/org.ops4j.pax.logging.cfg` before hand. -For more information check -[https://ops4j1.jira.com/wiki/display/paxlogging/Configuration](https://ops4j1.jira.com/wiki/display/paxlogging/Configuration). - - -### Classic - non-OSGI based Apache Brooklyn - -To use: - -* **Users**: -If using a brooklyn binary installation, simply edit the ``logback.xml`` -or ``logback-custom.xml`` supplied in the archive, sometimes in a ``conf/`` -directory. - -* **Developers**: -When setting up a new project, if you want logging it is recommended to include -the ``brooklyn-logback-xml`` project as an *optional* and *provided* maven dependency, -and then to put custom logging configuration in either ``logback-custom.xml`` or ``logback-main.xml``, -as described below. - - -#### Customizing Your Logging - -The project ``brooklyn-logback-xml`` supplies a ``logback.xml`` configuration, -with a mechanism which allows it to be easily customized, consumed, and overridden. -You may wish to include this as an *optional* dependency so that it is not forced -upon downstream projects. This ``logback.xml`` file supplied contains just one instruction, -to include ``logback-main.xml``, and that file in turn includes: - -* ``logback-custom.xml`` -* ``brooklyn/logback-appender-file.xml`` -* ``brooklyn/logback-appender-stdout.xml`` -* ``brooklyn/logback-logger-excludes.xml`` -* ``brooklyn/logback-debug.xml`` - -For the most common customizations, simply create a ``logback-custom.xml`` on your classpath -(ensuring it is loaded *before* brooklyn classes in classpath ordering in the pom) -and supply your customizations there: - -{% highlight xml %} -<included> - <!-- filename to log to --> - <property name="logging.basename" scope="context" value="acme-app" /> - - <!-- additional loggers --> - <logger name="com.acme.app" level="DEBUG"/> -</included> -{% endhighlight %} - -For other configuration, you can override individual files listed above. -For example: - -* To remove debug logging, create a trivial ``brooklyn/logback-debug.xml``, - containing simply ``<included/>``. -* To customise stdout logging, perhaps to give it a threshhold WARN instead of INFO, - create a ``brooklyn/logback-appender-stdout.xml`` which defines an appender STDOUT. -* To discard all brooklyn's default logging, create a ``logback-main.xml`` which - contains your configuration. This should look like a standard logback - configuration file, except it should be wrapped in ``<included>`` XML tags rather - than ``<configuration>`` XML tags (because it is included from the ``logback.xml`` - which comes with ``brooklyn-logback-xml``.) -* To redirect all jclouds logging to a separate file include ``brooklyn/logback-logger-debug-jclouds.xml``. - This redirects all logging from ``org.jclouds`` and ``jclouds`` to one of two files: anything - logged from Brooklyn's persistence thread will end up in a `persistence.log`, everything else - will end up in ``jclouds.log``. - -You should **not** supply your own ``logback.xml`` if you are using ``brooklyn-logback-xml``. -If you do, logback will detect multiple files with that name and will scream at you. -If you wish to supply your own ``logback.xml``, do **not** include ``brooklyn-logback-xml``. -(Alternatively you can include a ``logback.groovy`` which causes logback to ignore ``logback.xml``.) - -You can set a specific logback config file to use with: - -{% highlight bash %} --Dlogback.configurationFile=/path/to/config.xml -{% endhighlight %} - - -#### Assemblies - -When building an assembly, it is recommended to create a ``conf/logback.xml`` which -simply includes ``logback-main.xml`` (which comes from the classpath). Users of the assembly -can then edit the ``logback.xml`` file in the usual way, or they can plug in to the configuration -mechanisms described above, by creating files such as ``logback-custom.xml`` under ``conf/``. - -Including ``brooklyn-logback-xml`` as an *optional* and *provided* dependency means everything -should work correctly in IDE's but it will not include the extra ``logback.xml`` file in the assembly. -(Alternatively if you include the ``conf/`` dir in your IDE build, you should exclude this dependency.) - -With this mechanism, you can include ``logback-custom.xml`` and/or other files underneath -``src/main/resources/`` of a project, as described above (for instance to include custom -logging categories and define the log file name) and it should get picked up, -both in the IDE and in the assembly. - - -#### Tests - -Brooklyn projects ``test`` scope includes the ``brooklyn-utils-test-support`` project -which supplies a ``logback-test.xml``. logback uses this file in preference to ``logback.xml`` -when available (ie when running tests). However the ``logback-test.xml`` Brooklyn uses -includes the same ``logback-main.xml`` call path above, so your configurations should still work. - -The only differences of the ``logback-test.xml`` configuration is that: - -* Debug logging is included for all Brooklyn packages -* The log file is called ``brooklyn-tests.log`` - - -#### Caveats - -* logback uses SLF4J version 1.6 which is **not compatible** with 1.5.x. - If you have dependent projects using 1.5.x (such as older Grails) things may break. - -* If you're not getting the logging you expect in the IDE, make sure - ``src/main/resources`` is included in the classpath. - (In eclipse, right-click the project, the Build Path -> Configure, - then make sure all dirs are included (All) and excluded (None) -- - ``mvn clean install`` should do this for you.) - -* You may find that your IDE logs to a file ``brooklyn-tests.log`` - if it doesn't distinguish between test build classpaths and normal classpaths. - -* Logging configuration using file overrides such as this is very sensitive to - classpath order. To get a separate `brooklyn-tests.log` file during testing, - for example, the `brooklyn-test-support` project with scope `test` must be - declared as a dependency *before* `brooklyn-logback-includes`, due to the way - both files declare `logback-appender-file.xml`. - -* Similarly note that the `logback-custom.xml` file is included *after* - logging categories and levels are declared, but before appenders are declared, - so that logging levels declared in that file dominate, and that - properties from that file apply to appenders. - -* Finally remember this is open to improvement. It's the best system we've found - so far but we welcome advice. In particular if it could be possible to include - files from the classpath with wildcards in alphabetical order, we'd be able - to remove some of the quirks listed above (though at a cost of some complexity!).
http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/glossary.json ---------------------------------------------------------------------- diff --git a/guide/glossary.json b/guide/glossary.json deleted file mode 100644 index b201aba..0000000 --- a/guide/glossary.json +++ /dev/null @@ -1,22 +0,0 @@ -[ - { - "term": "location, !location:", - "description": "A server or resource to which Apache Brooklyn can deploy applications" - }, - { - "term": "blueprint", - "description": "A descriptor or pattern which describes how Apache Brooklyn should deploy applications" - }, - { - "term": "entity", - "description": "A software package or service Apache Brooklyn can interact with" - }, - { - "term": "sensor, !<code>sensor", - "description": "A sensor is a property of an Apache Brooklyn entity, updated in real-time" - }, - { - "term": "effector", - "description": "Effectors are tools Apache Brooklyn provides, that allow you to manipulate the live entities within an application" - } -] \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/index.md ---------------------------------------------------------------------- diff --git a/guide/index.md b/guide/index.md deleted file mode 100644 index 9d9392a..0000000 --- a/guide/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: User Guide -layout: website-normal -breadcrumbs: -- /website/documentation/index.md -- index.md -children: -- { path: /guide/start/index.md } -- { path: /guide/misc/download.md } -- { path: /guide/concepts/index.md } -- { path: /guide/blueprints/index.md } -- { path: /guide/locations/index.md } -- { path: /guide/ops/index.md } -- { path: /guide/misc/index.md } ---- - -This is the Brooklyn User Guide for v{{ site.brooklyn-version }}: - -{% include list-children.html %} - -If you are working with the Brooklyn codebase itself, also see the [Developer Guide](dev/) for this version. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_AWS.md ---------------------------------------------------------------------- diff --git a/guide/locations/_AWS.md b/guide/locations/_AWS.md deleted file mode 100644 index 7f592d2..0000000 --- a/guide/locations/_AWS.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -section: Amazon Web Services (AWS) -title: Amazon Web Services -section_type: inline -section_position: 2 ---- - -## 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: - - 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/). - - -### Common Configuration Options - -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`. You can in-line the region name using the following format: `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 - -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". - - -### 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 -from 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. - -Whilst there is eventual consistency for recording which VMs still reference security groups, after deleting a VM, it can sometimes take several minutes before a security group can be deleted - -There is utility written by [Cloudsoft](http://www.cloudsoft.io/) for deleting these unused resources: -[http://blog.abstractvisitorpattern.co.uk/2013/03/tidying-up-after-jclouds.html](http://blog.abstractvisitorpattern.co.uk/2013/03/tidying-up-after-jclouds.html). http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_GCE.md ---------------------------------------------------------------------- diff --git a/guide/locations/_GCE.md b/guide/locations/_GCE.md deleted file mode 100644 index 8fdf3ed..0000000 --- a/guide/locations/_GCE.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -section: Google Compute Engine (GCE) -title: Google Compute Engine -section_type: inline -section_position: 5 ---- - -## 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 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 request a 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 | - -To configure the location to use this, you can include a location configuration option like: - - templateOptions: - network: https://www.googleapis.com/compute/v1/projects/<project name>/global/networks/everything - http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_azure-ARM.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-ARM.md b/guide/locations/_azure-ARM.md deleted file mode 100644 index 3fced19..0000000 --- a/guide/locations/_azure-ARM.md +++ /dev/null @@ -1,266 +0,0 @@ ---- -section: Azure Compute ARM -section_type: inline -section_position: 2 ---- - -### 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 - -##### 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). - -You will need to obtain your *subscription ID* and *tenant ID* from Azure. To do this using the CLI, first, log in: - - az login - -Or, if you are already logged in, request an account listing: - - az account list - -In either case, this will return a subscription listing, similar to that shown below. - - [ - { - "cloudName": "AzureCloud", - "id": "012e832d-XXXX-XXXX-XXXX-XXXXXXXXXXXX", - "isDefault": true, - "name": "QA Team", - "state": "Enabled", - "tenantId": "ba85e8cd-XXXX-XXXX-XXXX-XXXXXXXXXXXX", - "user": { - "name": "q...@example.com", - "type": "user" - } - }, - { - "cloudName": "AzureCloud", - "id": "341751b0-XXXX-XXXX-XXXX-XXXXXXXXXXXX", - "isDefault": false, - "name": "Developer Team", - "state": "Enabled", - "tenantId": "ba85e8cd-XXXX-XXXX-XXXX-XXXXXXXXXXXX", - "user": { - "name": "d...@example.com", - "type": "user" - } - } - ] - -Choose one of the subscriptions and make a note of its *id* - henceforth the subscription ID - and the *tenantId*. - -Next we need to create an *application* and a *service principle*, and grant permissions to the service principle. Use these commands: - - # Create an AAD application with your information. - az ad app create --display-name <name> --password <Password> --homepage <home-page> --identifier-uris <identifier-uris> - - # For example: az ad app create --display-name "myappname" --password abcd --homepage "https://myappwebsite"; --identifier-uris "https://myappwebsite"; - -Take a note of the *appId* shown. - - # Create a Service Principal - az ad sp create --id <Application-id> - -Take a note of the *objectId* shown - this will be the service principal object ID. (Note that any of the *servicePrincipalNames* can also be used in place of the object ID.) - - # Assign roles for this service principal. The "principal" can be the "objectId" or any one of the "servicePrincipalNames" from the previous step - az role assignment create --assignee <Service-Principal> --role Contributor --scope /subscriptions/<Subscription-ID>/ - -By this stage you should have the following information: - -* A subscription ID -* A tenant ID -* An application ID -* A service principle (either by its object ID, or by any one of its names) - -We can now verify this information that this information can be used to log in to Azure: - - az login --service-principal -u <Application-ID> --password abcd --tenant <Tenant-ID> - -##### Azure CLI 1.0 - -Firstly, install and configure Azure CLI following [these steps](https://docs.microsoft.com/en-us/azure/cli-install-nodejs). - -Using the Azure CLI, run the following commands to create a service principal - - # Set mode to ARM - azure config mode arm - - # Enter your Microsoft account credentials when prompted - azure login - - # Set current subscription to create a service principal - azure account set <Subscription-id> - - # Create an AAD application with your information. - azure ad app create --name <name> --password <Password> --home-page <home-page> --identifier-uris <identifier-uris> - - # For example: azure ad app create --name "myappname" --password abcd --home-page "https://myappwebsite"; --identifier-uris "https://myappwebsite"; - - # Output will include a value for `Application Id`, which will be used for the live tests - - # Create a Service Principal - azure ad sp create --applicationId <Application-id> - - # Output will include a value for `Object Id`, to be used in the next step - - -Run the following commands to assign roles to the service principal - - # Assign roles for this service principal - azure role assignment create --objectId <Object-id> -o Contributor -c /subscriptions/<Subscription-id>/ - -Look up the the tenant Id - - azure account show -s <Subscription-id> --json - - # output will be a JSON which will include the `Tenant id` - -Verify service principal - - azure login -u <Application-id> -p <Password> --service-principal --tenant <Tenant-id> - -#### Using the Azure ARM Location - -Below is an example Azure ARM location in YAML which will launch a Ubuntu instance in south east asia: - - brooklyn.catalog: - id: my-azure-arm-location - name: "My Azure ARM location" - itemType: location - item: - type: jclouds:azurecompute-arm - brooklyn.config: - identity: <Application-id> - credential: <Password> - endpoint: https://management.azure.com/subscriptions/<Subscription-id> - oauth.endpoint: https://login.microsoftonline.com/<Tenant-id>/oauth2/token - - jclouds.azurecompute.arm.publishers: OpenLogic - region: southeastasia - loginUser: brooklyn - templateOptions: - overrideAuthenticateSudo: true - -Fill the values `<Application-id>`, `<Password>`, `<Subscription-id>` and `<Tenant-id>` in from the values generated when -setting up your credentials. In addition; several keys, not required in other locations need to be specified in order to -use the Azure Compute ARM location. These are: - - jclouds.azurecompute.arm.publishers: OpenLogic - -The publishers is any item from the list available here: [https://docs.microsoft.com/en-us/azure/virtual-machines/virtual-machines-linux-cli-ps-findimage](https://docs.microsoft.com/en-us/azure/virtual-machines/virtual-machines-linux-cli-ps-findimage) - - region: southeastasia - -The region is any region from the list available here: [https://azure.microsoft.com/en-us/regions/](https://azure.microsoft.com/en-us/regions/) - - loginUser: brooklyn - -The loginUser can be anything, as long as it's specified. - - templateOptions: - overrideAuthenticateSudo: true - -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 - -You can add these options directly under the `brooklyn.config` element in the example above: - -* `jclouds.compute.resourcename-prefix` and `jclouds.compute.resourcename-delimiter` - defaults to `jclouds` and `-` respectively. If jclouds is choosing the name for a resource (for example, a virtual machine), these properties will alter the way the resource is named. - -You can add these options into the `templateOptions` element inside the `brooklyn.config` element in the example above: - -* `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 - -This section contains material how to create a Windows location on Azure ARM. Some of the used parameters are explained in the section above. - -Windows on Azure ARM requires manually created [Azure KeyVault](https://docs.microsoft.com/en-us/azure/key-vault/key-vault-get-started) -Azure KeyVaults can be created [via Azure cli](https://docs.microsoft.com/en-us/azure/key-vault/key-vault-manage-with-cli2#create-a-key-vault) -or [Azure portal UI](https://docs.microsoft.com/en-us/azure/azure-resource-manager/resource-manager-keyvault-parameter). KeyVault's secret is a key -stored in protected .PFX file. It needs to be prepared upfront or created with the [Add-AzureKeyVaultKey](https://docs.microsoft.com/en-us/powershell/module/azurerm.keyvault/add-azurekeyvaultkey?view=azurermps-4.0.0) cmdlet. - -* `osFamily: windows` tells Apache Brooklyn to consider it as a Windows machine - -* `useJcloudsSshInit: false` tells jclouds to not try to connect to the VM - -* `vmNameMaxLength: 15` tells the cloud client to strip the VM name to maximum 15 characters. - This is the maximum size supported by Azure Windows VMs. - -* `winrm.useHttps` tells Apache Brooklyn to configure the WinRM client to use HTTPS. - -* `secrets` Specifies the KeyVault configuration - - `sourceVault` Resource `id` of the KeyVault - - `vaultCertificates` `certificateStore` has to use `My` as a value. - KeyVault's `certificateUrl`. An URI to the [Secret Identifier](https://docs.microsoft.com/en-us/rest/api/keyvault/about-keys--secrets-and-certificates#BKMK_DataTypes) - -* `windowsConfiguration` - - `provisionVMAgent` whether Azure to install an agent on the VM. It must be set to `true` - - `winRM` It defines the `listeners` section. If `listeners` is `https` then `certificateUrl` needs to be set. Its value must match the one of `secrets`'s `certificateUrl`. - -* `additionalUnattendContent` Additional content. Normally it can be defined as `null` - -* `enableAutomaticUpdates` whether to enable the automatic windows updates. It can be set to `false`, if automatic updates are not desired - -###### Sample Windows Blueprint - -Placeholders surrounded with `<>` have to be replcaced with their respective values. - -{% highlight yaml %} -brooklyn.catalog: - id: my-azure-arm-location - name: "My Azure ARM location" - itemType: location - item: - type: jclouds:azurecompute-arm - brooklyn.config: - identity: <Application-id> - credential: <Password> - endpoint: https://management.azure.com/subscriptions/<Subscription-id> - oauth.endpoint: https://login.microsoftonline.com/<Tenant-id>/oauth2/token - jclouds.azurecompute.arm.publishers: MicrosoftWindowsServer - jclouds.azurecompute.operation.timeout: 120000 - - winrm.useHttps: true - osFamily: windows - imageId: <Azure_location>/MicrosoftWindowsServer/WindowsServer/2012-R2-Datacenter - region: <Azure_location> - vmNameMaxLength: 15 - useJcloudsSshInit: false - destroyOnFailure: false - - templateOptions: - overrideLoginUser: brooklyn - overrideLoginPassword: "secretPass1!" - secrets: - - sourceVault: - id: "/subscriptions/<Subscription-id>/resourceGroups/<ResourceGroup>/providers/Microsoft.KeyVault/vaults/<KeyVault-name>" - vaultCertificates: - - certificateUrl: "<KeyVault-uri>" - certificateStore: My - windowsConfiguration: - provisionVMAgent: true - winRM: - listeners: - - protocol: https - certificateUrl: "<KeyVault-uri>" - additionalUnattendContent: null - enableAutomaticUpdates: true -{% endhighlight %} - -#### Known issues -There are currently two known issues with Azure ARM: - -* It can take a long time for VMs to be provisioned -* The Azure ARM APIs appear to have some fairly strict rate limiting that can result in AzureComputeRateLimitExceededException http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_azure-classic.md ---------------------------------------------------------------------- diff --git a/guide/locations/_azure-classic.md b/guide/locations/_azure-classic.md deleted file mode 100644 index 18604a2..0000000 --- a/guide/locations/_azure-classic.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -section: Azure Compute Classic -section_type: inline -section_position: 3 ---- - -### 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`. - -The two modes of using Azure are the "classic deployment" model and the newer "Azure Resource Manager" (ARM) -model. See [https://azure.microsoft.com/en-gb/documentation/articles/resource-manager-deployment-model/](https://azure.microsoft.com/en-gb/documentation/articles/resource-manager-deployment-model/) -for details. - - -#### 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. - -{% highlight bash %} -# create the certificate request -mkdir -m 700 $HOME/.brooklyn -openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout $HOME/.brooklyn/azure.pem -out $HOME/.brooklyn/azure.pem -# create the p12 file, and note your export password. This will be your test credentials. -openssl pkcs12 -export -out $HOME/.brooklyn/azure.p12 -in $HOME/.brooklyn/azure.pem -name "brooklyn :: $USER" -# create a cer file -openssl x509 -inform pem -in $HOME/.brooklyn/azure.pem -outform der -out $HOME/.brooklyn/azure.cer -{% endhighlight %} - -Finally, upload .cer file to the management console at https://manage.windowsazure.com/@myId#Workspaces/AdminTasks/ListManagementCertificates to authorize this certificate. - -Please note, you can find the "myId" value for this link by looking at the URL when logged into the Azure management portal. - -**Note**, you will need to use `.p12` format in the `brooklyn.properties`. - - -#### How to configure Apache Brooklyn to use Azure Compute - -First, in your `brooklyn.properties` define a location as follows: - -{% highlight properties %} -brooklyn.location.jclouds.azurecompute.identity=$HOME/.brooklyn/azure.p12 -brooklyn.location.jclouds.azurecompute.credential=<P12_EXPORT_PASSWORD> -brooklyn.location.jclouds.azurecompute.endpoint=https://management.core.windows.net/<YOUR_SUBSCRIPTION_ID> -brooklyn.location.jclouds.azurecompute.vmNameMaxLength=45 -brooklyn.location.jclouds.azurecompute.jclouds.azurecompute.operation.timeout=120000 -brooklyn.location.jclouds.azurecompute.user=<USER_NAME> -brooklyn.location.jclouds.azurecompute.password=<PASSWORD> -{% endhighlight %} - -During the VM provisioning, Azure will set up the account with `<USER_NAME>` and `<PASSWORD>` automatically. -Notice, `<PASSWORD>` must be a minimum of 8 characters and must contain 3 of the following: a lowercase character, an uppercase -character, a number, a special character. - -To force Apache Brooklyn to use a particular image in Azure, say Ubuntu 14.04.1 64bit, one can add: - - brooklyn.location.jclouds.azurecompute.imageId=b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-14_04_1-LTS-amd64-server-20150123-en-us-30GB - -From $BROOKLYN_HOME, you can list the image IDs available using the following command: - - ./bin/client "list-images --location azure-west-europe" - -To force Brooklyn to use a particular hardwareSpec in Azure, one can add something like: - - brooklyn.location.jclouds.azurecompute.hardwareId=BASIC_A2 - -From $BROOKLYN_HOME, you can list the hardware profile IDs available using the following command: - - ./bin/client "list-hardware-profiles --location azure-west-europe" - -At the time of writing, the classic deployment model has the possible values shown below. -See https://azure.microsoft.com/en-us/documentation/articles/virtual-machines-size-specs/ -for further details, though that description focuses on the new "resource manager deployment" -rather than "classic". - - * `Basic_A0` to `Basic_A4` - * `Standard_D1` to `Standard_D4` - * `Standard_G1` to `Standard_G5` - * `ExtraSmall`, `Small`, `Medium`, `Large`, `ExtraLarge` - - -##### Named location - -For convenience, you can define a named location, like: - -{% highlight properties %} -brooklyn.location.named.azure-west-europe=jclouds:azurecompute:West Europe -brooklyn.location.named.azure-west-europe.displayName=Azure West Europe -brooklyn.location.named.azure-west-europe.imageId=b39f27a8b8c64d52b05eac6a62ebad85__Ubuntu-14_04_1-LTS-amd64-server-20150123-en-us-30GB -brooklyn.location.named.azure-west-europe.hardwareId=BASIC_A2 -brooklyn.location.named.azure-west-europe.user=test -brooklyn.location.named.azure-west-europe.password=MyPassword1! -{% endhighlight %} - -This will create a location named `azure-west-europe`. It will inherit all the configuration -defined on `brooklyn.location.jclouds.azurecompute`. It will also augment and override this -configuration (e.g. setting the display name, image id and hardware id). - -On Linux VMs, The `user` and `password` will create a user with that name and set its password, -disabling the normal login user and password defined on the `azurecompute` location. - - -#### Windows VMs on Azure - -The following configuration options are important for provisioning Windows VMs in Azure: - -* `osFamily: windows` tells Apache Brooklyn to consider it as a Windows machine - -* `useJcloudsSshInit: false` tells jclouds to not try to connect to the VM - -* `vmNameMaxLength: 15` tells the cloud client to strip the VM name to maximum 15 characters. - This is the maximum size supported by Azure Windows VMs. - -* `winrm.useHttps` tells Apache Brooklyn to configure the WinRM client to use HTTPS. - - This is currently not supported in the default configuration for other clouds, where - Apache Brooklyn is deploying Windows VMs. - - If the parameter value is `false` the default WinRM port is 5985; if `true` the default port - for WinRM will be 5986. Use of default ports is stongly recommended. - -* `winrm.useNtlm` tells Apache Brooklyn to configure the WinRM client to use NTLM protocol. - - For Azure, this is mandatory. - - For other clouds, this value is used in the cloud init script to configure WinRM on the VM. - If the value is `true` then Basic Authentication will be disabled and the WinRM client will only use Negotiate plus NTLM. - If the value is `false` then Basic Authentication will be enabled and the WinRM client will use Basic Authentication. - - NTLM is the default Authentication Protocol. - - The format of this configuration option is subject to change: WinRM supports several - authentication mechanisms, so this may be changed to a prioritised list so as to - provide fallback options. - -* `user` tells Apache Brooklyn which user to login as. The value should match that supplied - in the `overrideLoginUser` of the `templateOptions`. - -* `password`: tells Apache Brooklyn the password to use when connecting. The value should - match that supplied in the `overrideLoginPassword` of the `templateOptions`. - -* `templateOptions: { overrideLoginUser: adminuser, overrideLoginPassword: Pa55w0rd! }` - tells the Azure Cloud to provision a VM with the given admin username and password. Note that - no "Administrator" user will be created. - - If this config is not set then the VM will have a default user named "jclouds" with password - "Azur3Compute!". It is **Strongly Recommended** that these template options are set. - - **Notice**: one cannot use `Administrator` as the user in Azure. - - This configuration is subject to change in future releases. - - -###### 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. - -{% highlight yaml %} -name: Windows Test @ Azure -location: - jclouds:azurecompute:West Europe: - identity: /home/users/brooklyn/.brooklyn/azure.p12 - credential: xxxxxxxp12 - endpoint: https://management.core.windows.net/12345678-1234-1234-1234-123456789abc - imageId: 3a50f22b388a4ff7ab41029918570fa6__Windows-Server-2012-Essentials-20141204-enus - hardwareId: BASIC_A2 - osFamily: windows - useJcloudsSshInit: false - vmNameMaxLength: 15 - winrm.useHttps: true - user: brooklyn - password: secretPass1! - templateOptions: - overrideLoginUser: brooklyn - overrideLoginPassword: secretPass1! -services: -- type: org.apache.brooklyn.entity.software.base.VanillaWindowsProcess - brooklyn.config: - install.command: echo install phase - launch.command: echo launch phase - checkRunning.command: echo launch phase -{% endhighlight %} - -Below is an example named location for Azure, configured in `brooklyn.properties`. Note the -placeholder values for the identity, credential and password. - -{% highlight properties %} -brooklyn.location.named.myazure=jclouds:azurecompute:West Europe -brooklyn.location.named.myazure.displayName=Azure West Europe (windows) -brooklyn.location.named.myazure.identity=$HOME/.brooklyn/azure.p12 -brooklyn.location.named.myazure.credential=<P12_EXPORT_PASSWORD> -brooklyn.location.named.myazure.endpoint=https://management.core.windows.net/<YOUR_SUBSCRIPTION_ID> -brooklyn.location.named.myazure.vmNameMaxLength=15 -brooklyn.location.named.myazure.jclouds.azurecompute.operation.timeout=120000 -brooklyn.location.named.myazure.imageId=3a50f22b388a4ff7ab41029918570fa6__Windows-Server-2012-Essentials-20141204-enus -brooklyn.location.named.myazure.hardwareId=BASIC_A2 -brooklyn.location.named.myazure.osFamily=windows -brooklyn.location.named.myazure.useJcloudsSshInit=false -brooklyn.location.named.myazure.winrm.useHttps=true -brooklyn.location.named.myazure.user=brooklyn -brooklyn.location.named.myazure.password=secretPass1! -brooklyn.location.named.myazure.templateOptions={ overrideLoginUser: amp, overrideLoginPassword: secretPass1! } -{% endhighlight %} - -###### User and Password Configuration - -As described under the configuration options, the username and password must be explicitly supplied -in the configuration. - -This is passed to the Azure Cloud during provisioning, to create the required user. These values -correspond to the options `AdminUsername` and `AdminPassword` in the Azure API. - -If a hard-coded password is not desired, then within Java code a random password could be -auto-generated and passed into the call to `location.obtain(Map<?,?>)` to override these values. - -This approach differs from the behaviour of clouds like AWS, where the password is auto-generated -by the cloud provider and is then retrieved via the cloud provider's API after provisioning the VM. - - -###### 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 -with WinRM encrypted over HTTP). The default is then to support NTLM protocol. - -The setup of Windows VMs on Azure differs from that on other clouds, such as AWS. In contrast, on AWS an -init script is passed to the cloud API to configure WinRM appropriately. - -_Windows initialization scripts in Azure are unfortunately not supported in "classic deployment" -model, but are available in the newer "resource manager deployment" model as an "Azure VM Extension"._ http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_byon.md ---------------------------------------------------------------------- diff --git a/guide/locations/_byon.md b/guide/locations/_byon.md deleted file mode 100644 index 948994d..0000000 --- a/guide/locations/_byon.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -section: BYON -section_position: 8 -section_type: inline ---- - -### 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. - -Your nodes must meet the following prerequisites: - -- A suitable OS must have been installed on all nodes -- The node must be running sshd (or similar) -- the brooklyn user must be able to ssh to each node as root or as a user with passwordless sudo permission. (For more information on SSH keys, see [here](#ssh-keys).) - -To deploy to machines with known IP's in a blueprint, use the following syntax: - -{% highlight yaml %} -location: - byon: - user: brooklyn - privateKeyFile: ~/.ssh/brooklyn.pem - hosts: - - 192.168.0.18 - - 192.168.0.19 -{% endhighlight %} - -Some of the login properties as described above for jclouds are supported, -but not `loginUser` (as no users are created), and not any of the -VM creation parameters such as `minRam` and `imageId`. -(These clearly do not apply in the same way, and they are *not* -by default treated as constraints, although an entity can confirm these -where needed.) -As before, if the brooklyn user and its default key are authorized for the hosts, -those fields can be omitted. - -Named locations can also be configured in your `brooklyn.properties`, -using the format `byon:(key=value,key2=value2)`. -For convenience, for hosts wildcard globs are supported. - -{% highlight bash %} -brooklyn.location.named.On-Prem\ Iron\ Example=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") -brooklyn.location.named.On-Prem\ Iron\ Example.user=produser1 -brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyFile=~/.ssh/produser_id_rsa -brooklyn.location.named.On-Prem\ Iron\ Example.privateKeyPassphrase=s3cr3tpassphrase -{% endhighlight %} - -Alternatively, you can create a specific BYON location through the location wizard tool available within the web console. -This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. - -For more complex host configuration, one can define custom config values per machine. In the example -below, there will be two machines. The first will be a machine reachable on -`ssh -i ~/.ssh/brooklyn.pem -p 8022 myuser@50.51.52.53`. The second is a windows machine, reachable -over WinRM. Each machine has also has a private address (e.g. for within a private network). - -{% highlight yaml %} -location: - byon: - hosts: - - ssh: 50.51.52.53:8022 - privateAddresses: [10.0.0.1] - privateKeyFile: ~/.ssh/brooklyn.pem - user: myuser - - winrm: 50.51.52.54:8985 - privateAddresses: [10.0.0.2] - password: mypassword - user: myuser - osFamily: windows -{% endhighlight %} - -The BYON location also supports a machine chooser, using the config key `byon.machineChooser`. -This allows one to plugin logic to choose from the set of available machines in the pool. For -example, additional config could be supplied for each machine. This could be used (during the call -to `location.obtain()`) to find the config that matches the requirements of the entity being -provisioned. See `FixedListMachineProvisioningLocation.MACHINE_CHOOSER`. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_clouds.md ---------------------------------------------------------------------- diff --git a/guide/locations/_clouds.md b/guide/locations/_clouds.md deleted file mode 100644 index b590014..0000000 --- a/guide/locations/_clouds.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -section: Clouds -section_type: inline -section_position: 1 ---- - -### Clouds - -For most cloud provisioning tasks, Brooklyn uses -<a href="http://jclouds.org";>Apache jclouds</a>. -The identifiers for some of the most commonly used jclouds-supported clouds are -(or [see the full list](http://jclouds.apache.org/reference/providers/)): - -* `jclouds:aws-ec2:<region>`: Amazon EC2, where `:<region>` might be `us-east-1` or `eu-west-1` (or omitted) -* `jclouds:softlayer:<region>`: IBM Softlayer, where `:<region>` might be `dal05` or `ams01` (or omitted) -* `jclouds:google-compute-engine`: Google Compute Engine -* `jclouds:openstack-nova:<endpoint>`: OpenStack, where `:<endpoint>` is the access URL (required) -* `jclouds:cloudstack:<endpoint>`: Apache CloudStack, where `:<endpoint>` is the access URL (required) - -For any of these, of course, Brooklyn needs to be configured with an `identity` and a `credential`: - -{% highlight yaml %} -location: - jclouds:aws-ec2: - identity: ABCDEFGHIJKLMNOPQRST - credential: s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} - -The above YAML can be embedded directly in blueprints, either at the root or on individual services. -If you prefer to keep the credentials separate, you can instead store them as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) or set them in `brooklyn.properties` -in the `jclouds.<provider>` namespace: - -{% highlight bash %} -brooklyn.location.jclouds.aws-ec2.identity=ABCDEFGHIJKLMNOPQRST -brooklyn.location.jclouds.aws-ec2.credential=s3cr3tsq1rr3ls3cr3tsq1rr3ls3cr3tsq1rr3l -{% endhighlight %} - -And in this case you can reference the location in YAML with `location: jclouds:aws-ec2`. - -Alternatively, you can use the location wizard tool available within the web console -to create any cloud location supported by <a href="http://jclouds.org";>Apache jclouds</a>. -This location will be saved as a [catalog entry]({{ site.path.guide }}/blueprints/catalog/index.html#locations-in-catalog) for easy reusability. - -Brooklyn irons out many of the differences between clouds so that blueprints run similarly -in a wide range of locations, including setting up access and configuring images and machine specs. -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 - -Once a machine is provisioned, Brooklyn will normally attempt to log in via SSH and configure the machine sensibly. - -The credentials for the initial OS log on are typically discovered from the cloud, -but in some environments this is not possible. -The keys `loginUser` and either `loginUser.password` or `loginUser.privateKeyFile` can be used to force -Brooklyn to use specific credentials for the initial login to a cloud-provisioned machine. - -(This custom login is particularly useful when using a custom image templates where the cloud-side account -management logic is not enabled. For example, a vCloud (vCD) template can have guest customization that will change -the root password. This setting tells Apache Brooklyn to only use the given password, rather than the initial -randomly generated password that vCD returns. Without this property, there is a race for such templates: -does Brooklyn manage to create the admin user before the guest customization changes the login and reboots, -or is the password reset first (the latter means Brooklyn can never ssh to the VM). With this property, -Brooklyn will always wait for guest customization to complete before it is able to ssh at all. In such -cases, it is also recommended to use `useJcloudsSshInit=false`.) - -Following a successful logon, Brooklyn performs the following steps to configure the machine: - -1. creates a new user with the same name as the user `brooklyn` is running as locally - (this can be overridden with `user`, below). - -1. install the local user's `~/.ssh/id_rsa.pub` as an `authorized_keys` on the new machine, - to make it easy for the operator to `ssh` in - (override with `privateKeyFile`; or if there is no `id_{r,d}sa{,.pub}` an ad hoc keypair will be generated - for the regular Brooklyn user; - if there is a passphrase on the key, this must be supplied) - -1. give `sudo` access to the newly created user (override with `grantUserSudo: false`) - -1. disable direct `root` login to the machine - -These steps can be skipped or customized as described below. - -#### 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 -{% include java_link.html class_name="JcloudsLocationConfig" package_path="org/apache/brooklyn/location/jclouds" project_subpath="locations/jclouds" %}. - -###### VM Creation - -- Most providers require exactly one of either `region` (e.g. `us-east-1`) or `endpoint` (the URL, usually for private cloud deployments) - -- Hardware requirements can be specified, including - `minRam`, `minCores`, `minDisk` and `os64Bit`; or as a specific `hardwareId` - -- VM image constraints can be set using `osFamily` (e.g. `Ubuntu`, `CentOS`, `Debian`, `RHEL`) - and `osVersionRegex`, or specific VM images can be specified using `imageId` or `imageNameRegex` - -- Specific VM images can be specified using `imageId` or `imageNameRegex` - -- Specific Security Groups can be specified using `securityGroups`, as a list of strings (the existing security group names), - or `inboundPorts` can be set, as a list of numeric ports (selected clouds only) - -- Where a key pair is registered with a target cloud for logging in to machines, - Brooklyn can be configured to request this when provisioning VMs by setting `keyPair` (selected clouds only). - Note that if this `keyPair` does not correspond your default `~/.ssh/id_rsa`, you must typically - also specify the corresponding `loginUser.privateKeyFile` as a file or URL accessible from Brooklyn. - -- A specific VM name (often the hostname) base to be used can be specified by setting `groupId`. - By default, this name is constructed based on the entity which is creating it, - including the ID of the app and of the entity. - (As many cloud portals let you filter views, this can help find a specific entity or all machines for a given application.) - For more sophisticated control over host naming, you can supply a custom - {% include java_link.html class_name="CloudMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %}, - for example - `cloudMachineNamer: CustomMachineNamer`. - {% include java_link.html class_name="CustomMachineNamer" package_path="org/apache/brooklyn/core/location/cloud/names" project_subpath="core" %} - will use the entity's name or following a template you supply. - On many clouds, a random suffix will be appended to help guarantee uniqueness; - this can be removed by setting `vmNameSaltLength: 0` (selected clouds only). - <!-- TODO jclouds softlayer includes a 3-char hex suffix --> - -- A DNS domain name where this host should be placed can be specified with `domainName` - (in selected clouds only) - -- User metadata can be attached using the syntax `userMetadata: { key: value, key2: "value 2" }` - (or `userMetadata=key=value,key2="value 2"` in a properties file) - -- By default, several pieces of user metadata are set to correlate VMs with Brooklyn entities, - prefixed with `brooklyn-`. - This user metadata can be omitted by setting `includeBrooklynUserMetadata: false`. - -- You can specify the number of attempts Brooklyn should make to create - machines with `machineCreateAttempts` (jclouds only). This is useful as an efficient low-level fix - for those occasions when cloud providers give machines that are dead on arrival. - You can of course also resolve it at a higher level with a policy such as - {% include java_link.html class_name="ServiceRestarter" package_path="org/apache/brooklyn/policy/ha" project_subpath="policy" %}. - -- If you want to investigate failures, set `destroyOnFailure: false` - to keep failed VM's around. (You'll have to manually clean them up.) - The default is false: if a VM fails to start, or is never ssh'able, then the VM will be terminated. - -- 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 - -- `user` and `password` can be used to configure the operating user created on cloud-provisioned machines - -- The `loginUser` config key (and subkeys) control the initial user to log in as, - in cases where this cannot be discovered from the cloud provider - -- Private keys can be specified using `privateKeyFile`; - these are not copied to provisioned machines, but are required if using a local public key - or a pre-defined `authorized_keys` on the server. - (For more information on SSH keys, see [here](#ssh-keys).) - -- If there is a passphrase on the key file being used, you must supply it to Brooklyn for it to work, of course! - `privateKeyPassphrase` does the trick (as in `brooklyn.location.jclouds.privateKeyPassphrase`, or other places - where `privateKeyFile` is valid). If you don't like keys, you can just use a plain old `password`. - -- Public keys can be specified using `publicKeyFile`, - although these can usually be omitted if they follow the common pattern of being - the private key file with the suffix `.pub` appended. - (It is useful in the case of `loginUser.publicKeyFile`, where you shouldn't need, - or might not even have, the private key of the `root` user when you log in.) - -- Provide a list of URLs to public keys in `extraSshPublicKeyUrls`, - or the data of one key in `extraSshPublicKeyData`, - to have additional public keys added to the `authorized_keys` file for logging in. - (This is supported in most but not all locations.) - -- Use `dontCreateUser` to have Brooklyn run as the initial `loginUser` (usually `root`), - without creating any other user. - -- A post-provisioning `setup.script` can be specified to run an additional script, before making the `Location` - available to entities. This may take the form of a URL of a script or a [data URI](https://en.wikipedia.org/wiki/Data_URI_scheme). - Note that if using a data URI it is usually a good idea to [base64](https://en.wikipedia.org/wiki/Base64) this string to escape problem characters - in more complex scripts. The base64 encoded script should then be prefixed with `data:text/plain;base64,` to denote this. - For example if you wanted to disable a yum repository called `reponame` prior to using the machine, you could use the following command: - - `sudo yum-config-manager --disable reponame` - - Base64 encoding can be done with a with a tool such as [this](https://www.base64encode.org/) or a linux command such as: - - `echo "sudo yum-config-manager --disable reponame" | base64` - - With the base64 prefix this would then look like this: - - `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlIHJlcG9uYW1l` - - The `setup.script` can also take [FreeMarker](http://freemarker.org/) variables in a `setup.script.vars` - property. Variables are set in the format `key1:value1,key2:value2` and used in the form `${key1}`. So for the above example: - - `setup.script.vars: repository:reponame` - - then - - `setup.script: data:sudo yum-config-manager --disable ${repository}` - - or encoded in base64: - - `setup.script: data:text/plain;base64,c3VkbyB5dW0tY29uZmlnLW1hbmFnZXIgLS1kaXNhYmxlICR7cmVwb3NpdG9yeX0=` - - This enables the name of the repository to be passed in to the script. - -- Use `openIptables: true` to automatically configure `iptables`, to open the TCP ports required by - the software process. One can alternatively use `stopIptables: true` to entirely stop the - iptables service. - -- Use Entity configuration flag `effector.add.openInboundPorts: true` to add an effector for opening ports in a cloud Security Group. - The config is supported for all SoftwareProcessImpl implementations. - -- Use `installDevUrandom: true` to fall back to using `/dev/urandom` rather than `/dev/random`. This setting - is useful for cloud VMs where there is not enough random entropy, which can cause `/dev/random` to be - extremely slow (causing `ssh` to be extremely slow to respond). - -- Use `useJcloudsSshInit: false` to disable the use of the native jclouds support for initial commands executed - on the VM (e.g. for creating new users, setting root passwords, etc.). Instead, Brooklyn's ssh support will - be used. Timeouts and retries are more configurable within Brooklyn itself. Therefore this option is particularly - recommended when the VM startup is unusual (for example, if guest customizations will cause reboots and/or will - change login credentials). - -- Use `brooklyn.ssh.config.noDeleteAfterExec: true` to keep scripts on the server after execution. - The contents of the scripts and the stdout/stderr of their execution are available in the Brooklyn web console, - but sometimes it can also be useful to have them on the box. - 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 - -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 -not supported directly by Brooklyn, we instead offer a mechanism to set any parameter that is supported by the jclouds -template options for your cloud. - -Part of the process for creating a virtual machine is the creation of a jclouds `TemplateOptions` object. jclouds -providers extends this with extra options for each cloud - so when using the AWS provider, the object will be of -type `AWSEC2TemplateOptions`. By [examining the source code](https://jclouds.apache.org/reference/javadoc/2.0.x/org/jclouds/aws/ec2/compute/AWSEC2TemplateOptions.html), -you can see all of the options available to you. - -The `templateOptions` config key takes a map. The keys to the map are method names, and Brooklyn will find the method on -the `TemplateOptions` instance; it then invokes the method with arguments taken from the map value. If a method takes a -single parameter, then simply give the argument as the value of the key; if the method takes multiple parameters, the -value of the key should be an array, containing the argument for each parameter. - -For example, here is a complete blueprint that sets some AWS EC2 specific options: - - location: AWS_eu-west-1 - services: - - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess - provisioning.properties: - templateOptions: - subnetId: subnet-041c8373 - mapNewVolumeToDeviceName: ["/dev/sda1", 100, true] - securityGroupIds: ['sg-4db68928'] - -Here you can see that we set three template options: - -- `subnetId` is an example of a single parameter method. Brooklyn will effectively try to run the statement - `templateOptions.subnetId("subnet-041c88373");` -- `mapNewVolumeToDeviceName` is an example of a multiple parameter method, so the value of the key is an array. - Brooklyn will effectively true to run the statement `templateOptions.mapNewVolumeToDeviceName("/dev/sda1", 100, true);` -- `securityGroupIds` demonstrates an ambiguity between the two types; Brooklyn will first try to parse the value as - a multiple parameter method, but there is no method that matches this parameter. In this case, Brooklyn will next try - to parse the value as a single parameter method which takes a parameter of type `List`; such a method does exist so - the operation will succeed. - -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 - -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: - - brooklyn-o8jql4-machinename-rkix-tomcat-wi-nca6-14b - -If you have created a lot of virtual machines, this kind of naming may not be helpful. This can be changed using the following YAML in your location's `brooklyn.config`: - - cloudMachineNamer: org.apache.brooklyn.core.location.cloud.names.CustomMachineNamer - custom.machine.namer.machine: My-Custom-Name-${entity.displayName} - -A [FreeMarker](http://freemarker.org/) format is used in `custom.machine.namer.machine` which can take values from places such as the launching entity or location. - -The above example will create a name such as: - - My-Custom-Name-Tomcat - -Allowing you to more easily identify your virtual machines. - -### 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 -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, - 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. http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_cloudstack.md ---------------------------------------------------------------------- diff --git a/guide/locations/_cloudstack.md b/guide/locations/_cloudstack.md deleted file mode 100644 index 50a7e0c..0000000 --- a/guide/locations/_cloudstack.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -section: CloudStack -title: Apache CloudStack -section_type: inline -section_position: 4 ---- - -## Apache 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 - -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/). - - -### 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: - ... - 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. It gives is an easy way to validate that credentials are correct, and to query -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 -CloudStack 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: - -* Go to 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 an 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, with messages 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 CloudStack 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/58bb3aa0/guide/locations/_ibm-softlayer.md ---------------------------------------------------------------------- diff --git a/guide/locations/_ibm-softlayer.md b/guide/locations/_ibm-softlayer.md deleted file mode 100644 index e1a5d40..0000000 --- a/guide/locations/_ibm-softlayer.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -section: IBM Softlayer -title: IBM Softlayer -section_type: inline -section_position: 6 ---- - -## 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 - -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/). - - -### 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. -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/58bb3aa0/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 deleted file mode 100644 index bf237f3..0000000 --- a/guide/locations/_inheritance-and-named-locations.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -section: Inheritance and Named Locations -title: Named Locations -section_type: inline -section_position: 7 ---- - -### Inheritance and Named Locations - -Named locations can be defined for commonly used groups of properties, -with the syntax `brooklyn.location.named.your-group-name.` -followed by the relevant properties. -These can be accessed at runtime using the syntax `named:your-group-name` as the deployment location. - -Some illustrative examples using named locations and -showing the syntax and properties above are as follows: - -{% highlight bash %} -# Production pool of machines for my application (deploy to named:prod1) -brooklyn.location.named.prod1=byon:(hosts="10.9.1.1,10.9.1.2,produser2@10.9.2.{10,11,20-29}") -brooklyn.location.named.prod1.user=produser1 -brooklyn.location.named.prod1.privateKeyFile=~/.ssh/produser_id_rsa -brooklyn.location.named.prod1.privateKeyPassphrase=s3cr3tCOMPANYpassphrase - -# AWS using my company's credentials and image standard, then labelling images so others know they're mine -brooklyn.location.named.company-jungle=jclouds:aws-ec2:us-west-1 -brooklyn.location.named.company-jungle.identity=BCDEFGHIJKLMNOPQRSTU -brooklyn.location.named.company-jungle.privateKeyFile=~/.ssh/public_clouds/company_aws_id_rsa -brooklyn.location.named.company-jungle.imageId=ami-12345 -brooklyn.location.named.company-jungle.minRam=2048 -brooklyn.location.named.company-jungle.userMetadata=application=my-jungle-app,owner="Bob Johnson" -brooklyn.location.named.company-jungle.machineCreateAttempts=2 - -brooklyn.location.named.AWS\ Virginia\ Large\ Centos = jclouds:aws-ec2 -brooklyn.location.named.AWS\ Virginia\ Large\ Centos.region = us-east-1 -brooklyn.location.named.AWS\ Virginia\ Large\ Centos.imageId=us-east-1/ami-7d7bfc14 -brooklyn.location.named.AWS\ Virginia\ Large\ Centos.user=root -brooklyn.location.named.AWS\ Virginia\ Large\ Centos.minRam=4096 -{% endhighlight %} - -Named locations can refer to other named locations using `named:xxx` as their value. -These will inherit the configuration and can override selected keys. -Properties set in the namespace of the provider (e.g. `b.l.jclouds.aws-ec2.KEY=VALUE`) -will be inherited by everything which extends AWS -Sub-prefix strings are also inherited up to `brooklyn.location.*`, -except that they are filtered for single-word and other -known keys -(so that we exclude provider-scoped properties when looking at sub-prefix keys). -The precedence for configuration defined at different levels is that the value -defined in the most specific context will apply. - -This is rather straightforward and powerful to use, -although it sounds rather more complicated than it is! -The examples below should make it clear. -You could use the following to install -a public key on all provisioned machines, -an additional public key in all AWS machines, -and no extra public key in `prod1`: - -<!-- tested in JcloudsLocationResolverTest --> -{% highlight bash %} -brooklyn.location.extraSshPublicKeyUrls=http://me.com/public_key -brooklyn.location.jclouds.aws-ec2.extraSshPublicKeyUrls="[ \"http://me.com/public_key\";, \"http://me.com/aws_public_key\"; ]" -brooklyn.location.named.prod1.extraSshPublicKeyUrls= -{% endhighlight %} - -And in the example below, a config key is repeatedly overridden. -Deploying `location: named:my-extended-aws` will result in an `aws-ec2` machine in `us-west-1` (by inheritance) -with `VAL6` for `KEY`: - -{% highlight bash %} -brooklyn.location.KEY=VAL1 -brooklyn.location.jclouds.KEY=VAL2 -brooklyn.location.jclouds.aws-ec2.KEY=VAL3 -brooklyn.location.jclouds.aws-...@us-west-1.key=VAL4 -brooklyn.location.named.my-aws=jclouds:aws-ec2:us-west-1 -brooklyn.location.named.my-aws.KEY=VAL5 -brooklyn.location.named.my-extended-aws=named:my-aws -brooklyn.location.named.my-extended-aws.KEY=VAL6 -{% endhighlight %} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/guide/locations/_localhost.md ---------------------------------------------------------------------- diff --git a/guide/locations/_localhost.md b/guide/locations/_localhost.md deleted file mode 100644 index d2daf33..0000000 --- a/guide/locations/_localhost.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -section: Localhost -section_position: 10 -section_type: inline ---- - -### 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, -just by specifying `location: localhost` in YAML. - -If you use a passphrase or prefer a different key, these can be configured as follows: - - 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 }}/blueprints/catalog/index.html#locations-in-the-catalog) -for easy reusability. - - -#### Passwordless Sudo - -If you encounter issues or for more information, see [SSH Keys Localhost Setup](#localhost-setup). - -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` has been setup correctly: - -{% highlight bash %} -sudo whoami -{% endhighlight %} http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/58bb3aa0/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 deleted file mode 100644 index d7a986b..0000000 --- a/guide/locations/_location-customizer-security-groups.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -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.html#port-inferencing). - -A security group is a named collection of network access rules that are use to limit the types of traffic that have access to instances.<br> -Security group is the standard way to set firewall restrictions on the AWS-EC2 environment. -[docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_SecurityGroups.html](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_SecurityGroups.html) - -When deploying to AWS EC2 target, by default Apache Brooklyn creates security group attached to the VM. -It is easy to add additional rules to the initial security group using `org.apache.brooklyn SharedLocationSecurityGroupCustomizer`. - -YAML Example: - - name: ports @ AWS - location: jclouds:aws-ec2:us-west-2: - services: - - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess - brooklyn.config: - provisioning.properties: - customizers: - - $brooklyn:object: - type: org.apache.brooklyn.location.jclouds.networking.SharedLocationSecurityGroupCustomizer - object.fields: {tcpPortRanges: ["900-910", "915", "22"], udpPortRanges: ["100","200-300"], cidr: "82.40.153.101/24"} - - -Make sure that you have rule which makes port 22 accessible from Apache Brooklyn. - -### Opening ports during runtime. - -Apache Brooklyn exposes the SharedLocationSecurityGroupCustomizer functionality after entity is deployed <br> -just by supplying `effector.add.openInboundPorts: true` "brooklyn.config". -Example configuration in effector - - location: jclouds:aws-ec2:us-west-2 - services: - - type: org.apache.brooklyn.entity.software.base.EmptySoftwareProcess - brooklyn.config: - effector.add.openInboundPorts: true - -### Known limitations - -Not all cloud providers support Security Group abstraction. -`SharedLocationSecurityGroupCustomizer` is known to work well with Amazon EC2.<br> -Other clouds which support Security Groups: - -- Openstack -- Azure - jclouds-labs azurecompute implementation uses endpoints rules when creating a VM instance. - jclouds:azurecompute based location do not have security groups so SharedLocationSecurityGroupCustomizer is used it will fail to find a security group. -
