====
    Licensed to jclouds, Inc. (jclouds) under one or more
    contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  jclouds licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
====

= Bring Your Own Nodes to the jclouds ComputeService =
The bring your own node provider (byon) allows you to specify a source which jclouds will read
nodes from.  Using this, you can have jclouds control your standalone machines, or even cloud
hosts that are sitting idle.

== Constraints ==
The byon provider only supports the following functions of ComputeService:
  * listNodes
  * listNodesDetailsMatching
  * getNodeMetadata
  * runScriptOnNodesMatching

== How to use the byon provider == 
The byon provider requires you supply a list of nodes using a property.  Here are 
the valid properties you can use:
  * byon.endpoint - url to access the list, can be http://, file://, classpath://
  * byon.nodes    - inline defined yaml in string form.

Note:

The identity and credential fields of the ComputeServiceContextFactory are ignored.

=== Java example ===

Properties props = new Properties();

// if you built the yaml string by hand
props.setProperty("byon.nodes", stringLiteral);

// or you can specify an external reference
props.setProperty("byon.endpoint", "file://path/to/byon.yaml");

// or you can specify a file in your classpath
props.setProperty("byon.endpoint", "classpath:///byon.yaml");

context = new ComputeServiceContextFactory().createContext("byon", "foo", "bar", 
               ImmutableSet.<Module> of(new JschSshClientModule()), props);

== File format == 
You must define your nodes in yaml, and they must be in a collection called nodes.

Here are the properties:

  * id             - opaque unique id
  * name           - optional; user specified name
  * description    - optional; long description of this node 
                               * note this is not yet in jclouds NodeMetadata
  * hostname       - name or ip address to contact the node on
  * location_id    - optional; correlates to a ZONE-scoped Location
                               * note that if present for one node, must be present for all
  * os_arch        - ex. x86 
  * os_family      - must conform to org.jclouds.compute.domain.OsFamily in lower-hyphen format
                     ex. rhel, ubuntu, centos, debian, amzn-linux
  * os_description - long description of the os ex. Ubuntu with lamp stack 
  * os_version     - normalized to numbers when possible. ex. for centos: 5.3, ubuntu: 10.10 
  * login_port     - optional; alternate port for ssh access
  * group          - primary group of the machine. ex. hadoop 
  * tags           - optional; list of arbitrary tags. 
                               * note this list is not yet in jclouds NodeMetadata 
  * username       - primary login user. ex. ubuntu, vcloud, toor, root 
  * sudo_password  - optional; when a script is run with the "runAsRoot" option true, yet the
                               username is not root, a sudo command is invoked. If sudo_password
                               is set, the contents will be passed to sudo -S.  
                               Ex. echo 'foobar'| sudo -S init 5
 
  one of:
  
    * credential     - RSA private key or password 
    * credential_url - location of plain-text RSA private key or password.
                       ex. file:///home/me/.ssh/id_rsa
                           classpath:///id_rsa

Note that username and credentials are optional if a CredentialStoreModule is configured in 
jclouds.

=== Example File ===

nodes:
    - id: i-sdfkjh7
      name: cluster-1
      description: accounting analytics cluster
      hostname: cluster-1.mydomain.com
      location_id: virginia
      os_arch: x86
      os_family: rhel
      os_description: redhat with CDH
      os_version: 5.3
      group: hadoop
      tags:
          - vanilla
      username: myUser
      credential: |
                  -----BEGIN RSA PRIVATE KEY-----
                  MIIEowIBAAKCAQEAuzaE6azgUxwESX1rCGdJ5xpdrc1XC311bOGZBCE8NA+CpFh2
                  u01Vfv68NC4u6LFgdXSY1vQt6hiA5TNqQk0TyVfFAunbXgTekF6XqDPQUf1nq9aZ
                  lMvo4vlaLDKBkhG5HJE/pIa0iB+RMZLS0GhxsIWerEDmYdHKM25o
                  -----END RSA PRIVATE KEY-----
      sudo_password: go panthers!