| 8 | | * Launch an ec2 instance, bootstrap it with chef and apply one or more chef roles |
| 9 | | * Terminate ec2 instances and delete its chef node (and client) |
| 10 | | * Execute commands (e.g., deployments) to ec2 instances based on environment or role |
| | 9 | * Launch an ec2 instance, bootstrap it with chef and apply one or more chef roles. |
| | 10 | * Terminate ec2 instances and delete its chef node and client. |
| | 11 | * Execute commands (e.g., deployments) to ec2 instances based on environment or role. |
| 70 | | === AWS access configuration === |
| 71 | | The {{{aws_*}}} and {{{rds_*}}} options (see example above) are for your AWS credentials and security information. For more info, see [http://docs.amazonwebservices.com/AWSSecurityCredentials/1.0/AboutAWSCredentials.html here]. |
| 72 | | |
| 73 | | === Chef access configuration === |
| 74 | | Your Trac instance must already have been configured using {{{knife configure}}}. For more info see [http://wiki.opscode.com/display/chef/Bootstrap+Chef+RubyGems+Installation#BootstrapChefRubyGemsInstallation-CreateaKnifeClientforYourLaptop%2FDesktop here]. Set the {{{chef_base_path}}} option to the standard chef directory that contains the {{{knife.rb}}} and client pem files needed to connect with the chef server. Common settings for this option are {{{/etc/chef}}} or {{{/home/<username>/.chef}}}. Be sure that the {{{validation.pem}}} file is located where the {{{knife.rb}}} file says it should be. |
| 75 | | |
| 76 | | === Jabber configuration === |
| 77 | | You can optionally configure notifications to jabber/xmpp for commands and environments via the {{{jabber_*}}} options. To enable for only deployments, for example, set a {{{notify_jabber}}} param in the {{{[cloud.environments]}}} section as follows: |
| 78 | | {{{ |
| 79 | | #!ini |
| | 67 | === AWS access configuration |
| | 68 | |
| | 69 | The {{{aws_*}}} and {{{rds_*}}} options (see example above) are for your AWS credentials and security information. For more info, see [http://docs.amazonwebservices.com/AWSSecurityCredentials/1.0/AboutAWSCredentials.html here]. |
| | 70 | |
| | 71 | === Chef access configuration |
| | 72 | |
| | 73 | Your Trac instance must already have been configured using {{{knife configure}}}. For more info see [http://wiki.opscode.com/display/chef/Bootstrap+Chef+RubyGems+Installation#BootstrapChefRubyGemsInstallation-CreateaKnifeClientforYourLaptop%2FDesktop here]. Set the {{{chef_base_path}}} option to the standard chef directory that contains the {{{knife.rb}}} and client pem files needed to connect with the chef server. Common settings for this option are {{{/etc/chef}}} or {{{/home/<username>/.chef}}}. Be sure that the {{{validation.pem}}} file is located where the {{{knife.rb}}} file says it should be. |
| | 74 | |
| | 75 | === Jabber configuration |
| | 76 | |
| | 77 | You can configure notifications to jabber/xmpp for commands and environments via the {{{jabber_*}}} options. To enable for only deployments, for example, set a {{{notify_jabber}}} param in the {{{[cloud.environments]}}} section as follows: |
| | 78 | {{{#!ini |
| 132 | | The {{{title}}} and {{{order}}} options are used for contextual navigation - see screenshot above. The {{{order}}} should start with {{{1}}}. If {{{order}}} is set to an empty string then the resource will not be shown in the contextual menu (but is still accessible by its url). The {{{label}}} value is displayed in various buttons and forms for the name of a single resource item. The {{{description}}} option is displayed in the grid view - see screenshot above - much like a Trac report description. |
| 133 | | |
| 134 | | ==== Field Definitions ==== |
| 135 | | The fields shown in each view can be configured. Fields are first defined much like Trac custom fields but prefixed with {{{field.}}}: |
| 136 | | {{{ |
| 137 | | |
| | 132 | The {{{title}}} and {{{order}}} options are used for contextual navigation, see screenshot above. The {{{order}}} should start with {{{1}}}. If {{{order}}} is set to an empty string, then the resource will not be shown in the contextual menu (but is still accessible by its url). The {{{label}}} value is displayed in various buttons and forms for the name of a single resource item. The {{{description}}} option is displayed in the grid view - see screenshot above - much like a Trac report description. |
| | 133 | |
| | 134 | ==== Field Definitions |
| | 135 | |
| | 136 | The fields shown in each view can be configured. Fields are first defined much like Trac custom fields but prefixed with {{{field.}}}: |
| | 137 | {{{#!ini |
| 154 | | Each {{{field.*}}} option must map exactly to its chef [http://wiki.opscode.com/display/chef/Attributes attribute] name. For example, {{{ec2.placement_availability_zone}}} above maps to the {{{ec2}}} attribute namespace and the {{{placement_availability_zone}}} attribute within that namespace in chef. This field is defined as a {{{select}}} field with a display label and several options separated by a pipe ({{{|}}}) just like Trac custom fields. There are some important differences to Trac custom fields, however: |
| 155 | | |
| 156 | | * A field can define a search index instead of options |
| 157 | | * A field can define a "field handler" |
| 158 | | |
| 159 | | ===== Search indexes for options ===== |
| 160 | | You may prefer to define a select (or multiselect) field's options by using a chef search index (e.g., the built-in {{{node}}} or {{{role}}}, or a [http://wiki.opscode.com/display/chef/Data+Bags data bag]) instead of listing them in the {{{trac.ini}}} file. For example, a field defined like this: |
| 161 | | {{{ |
| 162 | | |
| | 154 | Each {{{field.*}}} option must map exactly to its chef [http://wiki.opscode.com/display/chef/Attributes attribute] name. For example, {{{ec2.placement_availability_zone}}} above maps to the {{{ec2}}} attribute namespace and the {{{placement_availability_zone}}} attribute within that namespace in chef. This field is defined as a {{{select}}} field with a display label and several options separated by a pipe ({{{|}}}) just like Trac custom fields. There are some important differences to Trac custom fields, however: |
| | 155 | |
| | 156 | * A field can define a search index instead of options. |
| | 157 | * A field can define a "field handler". |
| | 158 | |
| | 159 | ===== Search indexes for options |
| | 160 | |
| | 161 | You may prefer to define a select (or multiselect) field's options by using a chef search index (e.g., the built-in {{{node}}} or {{{role}}}, or a [http://wiki.opscode.com/display/chef/Data+Bags data bag]) instead of listing them in the {{{trac.ini}}} file. For example, a field defined like this: |
| | 162 | {{{#!ini |
| 180 | | The {{{name}}} will be used as the option's displayed name and the {{{value}}} will be used as the option's value. If an {{{order}}} field is provided, it will be used to order the options accordingly (much like custom field ordering). |
| 181 | | |
| 182 | | ===== Field handlers ===== |
| 183 | | A field handler converts a raw chef attribute value into something more human-readable and vice-versa. For example, the {{{RunListHandler}}} defined above for the {{{run_list}}} field extracts roles from a chef node's run_list and displays them in an easy-to-read way. It also converts data the other direction - i.e., it converts the list of roles from a web form into the correct format to set the node's {{{run_list}}}. |
| 184 | | |
| 185 | | Other field handler examples include displaying a url to a web site at a specific port, converting epoch's to dates and times, etc. See [browser:cloudplugin/0.12/cloud/handlers.py handlers.py] for the full list of provided field handlers and [browser:cloudplugin/0.12/cloud/defaults.py defaults.py] for examples of which fields they're used for by default |
| 186 | | |
| 187 | | ==== Views ==== |
| 188 | | In addition to field definitions, you can define which fields should be viewed in which views, their order, and whether or not a field should be read-only in that view. Example: |
| 189 | | {{{ |
| 190 | | #!ini |
| | 180 | The {{{name}}} will be used as the option's displayed name and the {{{value}}} will be used as the option's value. If an {{{order}}} field is provided, it will be used to order the options accordingly (much like custom field ordering). |
| | 181 | |
| | 182 | ===== Field handlers |
| | 183 | |
| | 184 | A field handler converts a raw chef attribute value into something more human-readable and vice-versa. For example, the {{{RunListHandler}}} defined above for the {{{run_list}}} field extracts roles from a chef node's run_list and displays them in an easy-to-read way. It also converts data the other direction, ie it converts the list of roles from a web form into the correct format to set the node's {{{run_list}}}. |
| | 185 | |
| | 186 | Other field handler examples include displaying a url to a web site at a specific port, converting epoch's to dates and times, etc. See [browser:cloudplugin/0.12/cloud/handlers.py handlers.py] for the full list of provided field handlers and [browser:cloudplugin/0.12/cloud/defaults.py defaults.py] for examples of which fields they're used for by default |
| | 187 | |
| | 188 | ==== Views |
| | 189 | |
| | 190 | In addition to field definitions, you can define which fields should be viewed in which views, their order, and whether or not a field should be read-only in that view. Example: |
| | 191 | {{{#!ini |
| 202 | | The {{{crud_view}}}, {{{crud_new}}}, {{{crud_edit}}}, and {{{grid_columns}}} options are lists of field names in the order to be displayed in their respective views. ("crud" stands for "create, read, update, delete".) An asterisk ({{{*}}}) appended to a field name (only applicable for {{{crud_new}}} and {{{crud_edit}}}) indicates that the field should be read-only in that view. All fields in the {{{crud_new}}} and {{{crud_edit}}} views will be used to set or update the chef resource item. |
| | 203 | The {{{crud_view}}}, {{{crud_new}}}, {{{crud_edit}}}, and {{{grid_columns}}} options are lists of field names in the order to be displayed in their respective views. "crud" stands for "create, read, update, delete". An asterisk ({{{*}}}) appended to a field name (only applicable for {{{crud_new}}} and {{{crud_edit}}}) indicates that the field should be read-only in that view. All fields in the {{{crud_new}}} and {{{crud_edit}}} views will be used to set or update the chef resource item. |
| 208 | | |
| 209 | | === RDS Instances === |
| 210 | | RDS instances can be created and deleted using this plugin. The rds instance resource type is configured almost identically to ec2 instances (see above). One important difference is that the list of rds instances and their attributes are saved in a chef data bag. This makes their attributes available to chef recipes. In order to ensure that this data is up-to-date, you can click on the "Audit" button in the grid view. |
| 211 | | |
| 212 | | === EIP Addresses === |
| 213 | | EIP Addresses can be created, associated with instances, and deleted using this plugin. The eip address resource type is configured identically to rds instances (see above). |
| 214 | | |
| 215 | | === EBS Volumes === |
| 216 | | EBS Volumes can be created, attached or detached to instances, and deleted using this plugin. The ebs volume resource type is configured identically to rds instances (see above). The plugin will also allow you to optionally attach an EBS volume upon launching an ec2 instance. |
| 217 | | |
| 218 | | === Commands === |
| 219 | | To help manage many ec2 instances, you can define commands to be run on them in the "Commands" section. The command resource type is configured similarly to ec2 and rds instances. Their data is maintained in a chef data bag. An example command may look this this: |
| 220 | | {{{ |
| 221 | | #!sh |
| | 209 | === RDS Instances |
| | 210 | |
| | 211 | RDS instances can be created and deleted using this plugin. The rds instance resource type is configured almost identically to ec2 instances (see above). One important difference is that the list of rds instances and their attributes are saved in a chef data bag. This makes their attributes available to chef recipes. To ensure that this data is up-to-date, you can click on the "Audit" button in the grid view. |
| | 212 | |
| | 213 | === EIP Addresses |
| | 214 | |
| | 215 | EIP Addresses can be created, associated with instances, and deleted using this plugin. The eip address resource type is configured identically to rds instances (see above). |
| | 216 | |
| | 217 | === EBS Volumes |
| | 218 | |
| | 219 | EBS Volumes can be created, attached or detached to instances, and deleted using this plugin. The ebs volume resource type is configured identically to rds instances (see above). The plugin will also allow you to attach an EBS volume upon launching an ec2 instance. |
| | 220 | |
| | 221 | === Commands |
| | 222 | |
| | 223 | To help manage many ec2 instances, you can define commands to be run on them in the "Commands" section. The command resource type is configured similarly to ec2 and rds instances. Their data is maintained in a chef data bag. An example command may look this this: |
| | 224 | {{{#!sh |
| 225 | | The {{{%(keypair_pem)s}}} will get replaced with the {{{aws_keypair_pem}}} as defined in {{{trac.ini's [cloud]}}} section (see above). Also, {{{%(host)s}}} will get replaced with the public DNS name of each host. Hosts are selected by environment and/or role. |
| 226 | | |
| 227 | | === Environments === |
| 228 | | With Chef 0.10 comes support for environments. This plugin ~~builds on~~ complements this support by allowing AWS resources belong to one and only one environment. For example, there's a default {{{env}}} field (which is currently distinct from the {{{chef_environment}}} built-in field in chef 10.x) that can get set when creating a new ec2 or rds instance. The environment resource type also allows you to define and set attributes per environment via the plugin's webui. For example, you can set different version control repo branch names and/or changesets per environment so that the right source code gets deployed to each environment. |
| 229 | | |
| 230 | | ==== Deploy and Audit ==== |
| 231 | | There are two special commands that can be defined: "deploy" and "audit". A command with a "deploy" ID will cause a "Deploy" button to appear in an environment's View along with widgets to select which role(s) should be used to identify the instances to which to deploy. The 'deploy' script itself is left for you to define as such scripts often require significant logic specific to your system. |
| 232 | | |
| 233 | | Similarly, a command with an "audit" ID will cause an "Audit" button to appear in an environment's View along with widgets to select which role(s) should be used to identify the instances of which to audit. The 'audit' script itself is left for you to define as such scripts often require significant logic specific to your system. If a JSON list of HTML strings is returned, then these HTML snippets are concatenated at the end of each listed node in the progress view (see below) thus providing the audit details. For example, you can return links to the diffs between the target repo changeset and the node's current repo changeset (which is how we use this audit feature). |
| 234 | | |
| 235 | | === Progress views === |
| 236 | | Actions such as launching or bootstrapping an ec2 instance or deploying code to an environment can take a variably long time - usually longer than the default Apache timeouts (e.g., {{{FcgidIOTimeout}}}). Instead of wrestling with Apache timeout configurations, this plugin executes each of these actions in a separate, spawned process (an orphaned daemon) that survives Apache timeouts and restarts. Surviving Apache restarts is also helpful when Trac itself is chef-managed and may be restarted by the {{{chef-client}}} upon config changes. Creating a new ec2 instance, executing remote commands, etc. now brings up a new 'Progress' page that tracks the spawned process' progress: |
| | 228 | The {{{%(keypair_pem)s}}} will get replaced with the {{{aws_keypair_pem}}} as defined in {{{trac.ini's [cloud]}}} section (see above). Also, {{{%(host)s}}} will get replaced with the public DNS name of each host. Hosts are selected by environment and/or role. |
| | 229 | |
| | 230 | === Environments |
| | 231 | |
| | 232 | With Chef 0.10 comes support for environments. This plugin ~~builds on~~ complements this support by allowing AWS resources belong to one and only one environment. For example, there's a default {{{env}}} field (which is currently distinct from the {{{chef_environment}}} built-in field in chef 10.x) that can get set when creating a new ec2 or rds instance. The environment resource type also allows you to define and set attributes per environment via the plugin's webui. For example, you can set different version control repo branch names and/or changesets per environment so that the right source code gets deployed to each environment. |
| | 233 | |
| | 234 | ==== Deploy and Audit |
| | 235 | |
| | 236 | There are two special commands that can be defined: "deploy" and "audit". A command with a "deploy" ID will cause a "Deploy" button to appear in an environment's View along with widgets to select which role(s) should be used to identify the instances to which to deploy. The 'deploy' script itself is left for you to define as such scripts often require significant logic specific to your system. |
| | 237 | |
| | 238 | Similarly, a command with an "audit" ID will cause an "Audit" button to appear in an environment's View along with widgets to select which role(s) should be used to identify the instances of which to audit. The 'audit' script itself is left for you to define as such scripts often require significant logic specific to your system. If a JSON list of HTML strings is returned, then these HTML snippets are concatenated at the end of each listed node in the progress view (see below) thus providing the audit details. For example, you can return links to the diffs between the target repo changeset and the node's current repo changeset (which is how we use this audit feature). |
| | 239 | |
| | 240 | === Progress views |
| | 241 | |
| | 242 | Actions such as launching or bootstrapping an ec2 instance or deploying code to an environment can take a variably long time - usually longer than the default Apache timeouts (e.g., {{{FcgidIOTimeout}}}). Instead of wrestling with Apache timeout configurations, this plugin executes each of these actions in a separate, spawned process (an orphaned daemon) that survives Apache timeouts and restarts. Surviving Apache restarts is also helpful when Trac itself is chef-managed and may be restarted by the {{{chef-client}}} upon config changes. Creating a new ec2 instance, executing remote commands, etc. now brings up a new 'Progress' page that tracks the spawned process' progress: |
