Audrey Config Server
~~~~~~~~~~~~~~~~~~~~

The Audrey Config Server facilitates the post-boot configuration of instances in
a cloud.  Please see documentation on the aeolus project page:
http://www.aeolusproject.org/page/Audrey.


API
~~~

The Config Server provides a RESTful interface for post-boot configuration
management.  The API provides the following:

* POST /configs/$version/$uuid

  $version: currently, this is ignored...it will eventually constrain the API to
            supported functionality based on the supplied version
  $uuid:    the identifier for the instance generated by Conductor

  This interface informs the Config Server that a new instance is getting
  created.  The post data contains the (cgi-escaped) instance-config.xml
  representing the instance's post-boot configuration.  This file is generated
  from Conductor in the Cloud Engine after processing the Template, Assembly,
  and Deployable files.

  A simple script for generating instance-config.xml files outside of the
  Conductor can be found here:
  - https://github.com/clalancette/audrey/blob/master/audrey.rb

  The instance-config.xml format is defined by the RelaxNG spec here:
  - https://github.com/clalancette/audrey/blob/master/configserver/schema/instance-config.rng

  The example below assumes a few points:
    * the UUID of the instance is b3f127c0-4cc0-012e-afcb-70def1284ca2
    * there is a file in PWD called b3f127c0-4cc0-012e-afcb-70def1284ca2 that
      contains the instance-config.xml
    * the config server is running at localhost:4567

  Example:
    curl -X POST --data-urlencode "data@b3f127c0-4cc0-012e-afcb-70def1284ca2" \
    -w "HTTP_CODE: %{http_code}\n" \
    http://localhost:4567/configs/0/b3f127c0-4cc0-012e-afcb-70def1284ca2

* GET /configs/$version/$uuid

  $version: currently, this is ignored...it will eventually constrain the API to
            supported functionality based on the supplied version
  $uuid:    the identifier for the instance generated by Conductor

  This call is made by the instance to retrieve the instance's post boot
  configuration information.  A detailed discussion about the API and format of
  the data can be found here:
  - http://www.aeolusproject.org/page/Config_Server_Audrey_Script_API

  The information returned from this call is either (depending on the Accept
  HTTP Header value) an XML document or a simple text string describing the
  post-boot configuration for the instance associated with $uuid.

  The example below assumes a couple points:
    * the UUID of the instance is b3f127c0-4cc0-012e-afcb-70def1284ca2
    * the config server is running at localhost:4567

  Example:
    curl -H "Accept: text/plain" -w "HTTP_CODE: %{http_code}\n" \
    http://localhost:4567/configs/0/b3f127c0-4cc0-012e-afcb-70def1284ca2

* GET /params/$version/$uuid

  $version: currently, this is ignored...it will eventually constrain the API to
            supported functionality based on the supplied version
  $uuid:    the identifier for the instance generated by Conductor

  This call is made by the instance to retrieve the list of parameters the
  Config Server expects from the instance.  These "provided parameters" might be
  required by other instances in the same deployable.  A detailed discussion
  about the API and format of the data can be found here:
  - http://www.aeolusproject.org/page/Config_Server_Audrey_Script_API

  The inforamtion returned from this call is either (depending on the Accept
  HTTP Header value) an XML document or a simple text string describing the
  parameters the instance must look up, and return values for (see the PUT API
  call below).

  The example below assumes a couple points:
    * the UUID of the instance is b3f127c0-4cc0-012e-afcb-70def1284ca2
    * the config server is running at localhost:4567

  Example:
    curl -H "Accept: text/plain" -w "HTTP_CODE: ${http_code}\n" \
    http://localhost:4567/params/0/b3f127c0-4cc0-012e-afcb-70def1284ca2

* PUT /params/$version/$uuid

  $version: currently, this is ignored...it will eventually constrain the API to
            supported functionality based on the supplied version
  $uuid:    the identifier for the instance generated by Conductor

  This call is made by the instance to provide the parameter values request by
  the Config Server.  These "provided parameters" might be required by other
  instances in the same deployable.  A detailed discussion about the API and
  format of the data can be found here:
  - http://www.aeolusproject.org/page/Config_Server_Audrey_Script_API

  The Config Server does several things when this call is made:
    * applies the provided values to the instance's configuration information,
      making sure that the instance is no longer told to provide these values
    * searches the deployable information for other instances that require the
      newly provided parameters and applies these values across the deployable
    * captures and stores the IP address of the instance for cloud providers
      that rely on the Config Server for this information
    * responds to the caller with the list of remaining parameters the Config
      Server expects from the instance (this information is returned as
      according to the GET /params/$version/$uuid API call)

  The example below assumes a couple points:
    * the UUID of the instance is b3f127c0-4cc0-012e-afcb-70def1284ca2
    * the config server is running at localhost:4567

  Example:
    curl -X PUT -w "\n\nHTTP_CODE: %{http_code}\n" \
    --data-urlencode "audrey_data=|param1&b64EncodedVal|param2&b64EncodedVal|" \
    http://localhost:4567/params/0/b3f127c0-4cc0-012e-afcb-70def1284ca2

* GET /ip/$version/$uuid

  $version: currently, this is ignored...it will eventually constrain the API to
            supported functionality based on the supplied version
  $uuid:    the identifier for the instance generated by Conductor

  This call is made by a cloud provider to request the IP address of an instance
  associated with $uuid.  The Config Server replies with a plain text string
  containing the IP address of the instance.  If the instance has not completed
  the PUT /params/$version/$uuid call yet, then the Config Server responds with
  an empty response body.

  The example below assumes a couple points:
    * the UUID of the instance is b3f127c0-4cc0-012e-afcb-70def1284ca2
    * the config server is running at localhost:4567

  Example:
    curl -H "Accept: text/plain" -w "HTTP_CODE: ${http_code}\n" \
    http://localhost:4567/ip/0/b3f127c0-4cc0-012e-afcb-70def1284ca2


Client
~~~~~~

A small set of client tools is provided with the config server codebase for
testing with a live config server.  For more information, try:

  $> client/cs-client -h
  $> client/cs-input -h

For generating a bare-bones instance-config file that can be sent to a Config
Server, try:

  $> cd client
  $> ./cs-input $UUID | ./cs-client post $UUID -