Changes between Version 11 and Version 12 of CloudPlugin

Timestamp:

Jan 28, 2011, 10:26:19 PM (13 years ago)

Author:

Rob Guttman

Comment:

--

CloudPlugin

@@ -104 +104 @@
 
 == Example ==
-
-trac.ini config ...
-
-[cloud]
+Each supported AWS resource is configured independently in a separate section in {{{trac.ini}}}.  (The plugin currently only supports ec2 instances.)  Each section must be named as follows:
+{{{
+[cloud.<resource_name>]
 ...
+}}}
+
+For example, a section named {{{[cloud.instance]}}} defines a resource named {{{instance}}}.  The resource name is used in the uri, so for example, this {{{instance}}} resource would be accessed at:
+{{{
+http://trac.domain.com/cloud/instance
+}}}
+
+You can name resources whatever you want as long as they're unique.
+
+=== Instances ===
+Here's how to configure ec2 instance resources.  It's best to explain the configuration piecemeal:
+
+{{{
+[cloud.instance]
+class = Ec2Instance
+title = Instances
+order = 1
+label = Instance
+description = AWS EC2 instances.
+}}}
+
+ * {{{class}}} - must map to the exact python class name for that instance.  For ec2 instances, it's {{{Ec2Instance}}}.
+ * {{{title}}} - used in the sub-navigation (aka contextual) menu - see screenshot above.
+ * {{{order}}} - defines the order in the contextual menu (much like custom field ordering).
+ * {{{label}}} - used in several views to describe a single on of these resources.
+ * {{{description}}} - used in the grid view - see screenshot above.
+
+Now it gets a bit more intense:
+
+{{{
+[cloud.instance]
+..
+fields = name < NameHandler, ec2.instance_id as Instance ID, run_list_ as Roles < RunListHandler, created_by as Created By < AuthorHandler, created_at_ as Created At < EpochHandler, ohai_time_ as Last Check-in < AgoEpochHandler, ec2.instance_type as Instance Type, ec2.hostname as Private Hostname, ec2.public_hostname_ as Public Hostname < SshHandler, ec2.placement_availability_zone as Availability Zone, ec2.ami_id as Image ID, supervisord.ssl_port_ as supervisord < HttpsHandler
+}}}
+
+Whoa!  The {{{fields}}} option is a list if those chef attributes (aka fields) where you want to provide either a display name, a format handler, or both.  So for example, {{{ec2.instance_type as Instance Type}}} above will use 'Instance Type' as the name of the {{{ec2.instance_type}}} attribute's the column or field.  To define a display name (or label) for an attribute, list the attribute name followed by {{{ as }}} followed by the display name.
+
+Only slightly more complicated are handlers to format fields.  So for example, {{{ohai_time_ as Last Check-in < AgoEpochHandler}}} has a display name as we've seen plus the {{{< AgoEpochHandler}}} directs the plugin to use a specific handler to format the {{{ohai_time}}} field's value.  In this example, the {{{AgoEpochHandler}}} handler converts an epoch to a string format such as "0:08:36 ago" meaning "8 minutes and 36 seconds ago" as shown in the screenshot above.  But wait, what's up with the underscore after the {{{ohai_time_}}}?  In most cases when using a handler, you should postfix the field's name with an underscore ({{{_}}}) so that the re-formatted value doesn't get written back to the field's value.  ''[I'm likely to get rid of the underscore business to make it simpler, but that's what it is for now. - rhg]''  See the {{{handlers.py}}} file for a full list of provided field handlers.
+
+{{{
+grid_index = node
+grid_columns = name, run_list_, created_by, ohai_time_, ec2.instance_type, ec2.placement_availability_zone
+grid_sort = created_at_
+grid_asc = 0
+}}}
+
+The {{{grid*}}} options configure the grid view of the resource - i.e., the view shown in the screenshot above:
+ * {{{grid_index}}} - must map to the chef search index name.  For ec2 instances, this is {{{node}}}.
+ * {{{grid_columns}}} - the list of chef attributes to display in order.  The column names will use any display names from {{{fields}}} and its cell values will be formatted using any handlers from {{{fields}}}.
+ * {{{grid_sort}}} - the default sort attribute/field.  You can resort the grid by clicking on the column name.
+ * {{{grid_asc}}} - the default sort direction.  You can change the sort direction by clicking on the same column name.
+
+{{{
+crud_resource = nodes
+crud_view = name, ec2.instance_id, run_list_, created_by, created_at_, ohai_time_, ec2.instance_type, ec2.hostname, ec2.public_hostname_, ec2.placement_availability_zone, ec2.ami_id, supervisord.ssl_port_
+crud_new = run_list_||, created_by, ec2.instance_type|, ec2.ami_id|, ec2.placement_availability_zone|us-east-1a|us-east-1b|us-east-1c|us-east-1d
+crud_edit = run_list_||, created_by, ec2.instance_type*, ec2.ami_id*, ec2.placement_availability_zone*
+}}}
+
+The {{{crud_*}}} options configure aspects for creating, reading updating, and deleting (i.e., CRUD) the resource:
+ * {{{crud_resource}}} - must map to the chef resource name.  For ec2 instances, this is {{{nodes}}}.
+ * {{{crud_view}}} - the list of chef attributes to display in order.  The field names will use any display names from {{{fields}}} and its cell values will be formatted using any handlers from {{{fields}}}.
+ * {{{crud_new}}} and {{{crud_edit}}} - the list of augmented chef attributes to display for editing in order.  The field names will use any display names from {{{fields}}} and its cell values will be formatted using any handlers from {{{fields}}}.
+
+The field names in {{{crud_new}}} and {{{crud_edit}}} are augmented to provide additional metadata so the plugin knows how to properly configure the form.  So for example:
+{{{
+ec2.placement_availability_zone|us-east-1a|us-east-1b|us-east-1c|us-east-1d
+}}}
+
+The pipe ({{{|}}}) after the field name indicates that the form should use a select/dropdown menu for this field.  If the select/dropdown should support multiple selections, then use two pipes instead of one as in {{{run_list_||}}}.  The remainder of the definition is a pipe-delimited list of options for this field (much like how custom field options are defined).  If there's no list of options, then the plugin will search a chefserver data bag of the same name as the field for the list of options.  So for example, {{{ec2.instance_type|}}} will direct the plugin to search for a data bag on the chefserver named {{{ec2_instance_type}}} (periods are invalid and so are replaced with underscores).  The individual data bag items should be formatted like this:
+{{{
+{
+  "id": "m1_large",
+  "value": "m1.large",
+  "name": "m1.large - Large (64-bit)",
+  "order": 3
+}
+}}}
+
+The {{{name}}} will be used as the option's name and the {{{value}}} will be used as the option's value.  If {{{order}}} fields are provided, then it will be used to order the options accordingly (much like custom field ordering).
+
+Lastly, if you want to have a field displayed but as read-only, then the field name should be immediately postfixed with an asterisk as in {{{ec2.ami_id*}}} above.
+
 
 == Recent Changes ==