Permalink
Browse files

readme and metadata updates for chef_environments

  • Loading branch information...
1 parent a1e547c commit 904f9f9794b4ec828d957317bcd1e9b6e3ed3c63 @jtimberman jtimberman committed May 21, 2011
View
@@ -12,13 +12,21 @@ Other application stacks (Rack, WSGI, etc) will be supported as new recipes at a
This cookbook aims to provide primitives to install/deploy any kind of application driven entirely by data defined in an abstract way through a data bag.
----
+Note that as of version 0.99.10, this cookbook uses Chef 0.10's environments instead of the `app_environment` attribute. If you do not set up any environments for your nodes, they will be in the `_default` environment. See __Usage__ below for information on how to set up environments.
+
+Changes
+=======
+
+## v0.99.10:
+
+* Use Chef 0.10's `node.chef_environment` instead of `node['app_environment']`.
+
Requirements
============
-Chef 0.9.14 or higher required.
+Chef 0.10.0 or higher required (for Chef environment use).
-The following Opscode cookbooks are dependencies:
+The following Opscode cookbooks are dependencies, as this cookbook supports automating a large number of web application stacks.
* runit
* unicorn
@@ -29,7 +37,6 @@ The following Opscode cookbooks are dependencies:
* apache2
* php
----
Recipes
=======
@@ -55,7 +62,7 @@ Using the node's `run_state` that contains the current application in the search
This recipe can be used on nodes that are going to run the application, or on nodes that need to have the application code checkout available such as supporting utility nodes or a configured load balancer that needs static assets stored in the application repository.
-For pip requirements.txt files: ensure the requirements.txt file is present in the root of the application code (APP_ROOT/requirements.txt) or named after the node's current app_environment in a directory named requirements (requirements/production.txt) and `pip install -r` will be run before migrations.
+For pip requirements.txt files: ensure the requirements.txt file is present in the root of the application code (APP_ROOT/requirements.txt) or named after the node's current `chef_environment` in a directory named requirements (requirements/production.txt) and `pip install -r` will be run before migrations.
In order to manage running database migrations (python manage.py migrate), you can use a role that sets the `run_migrations` attribute for the application (`my_app`, below) in the correct environment (production, below). Note the data bag item needs to have migrate set to true. See the data bag example below.
@@ -100,8 +107,8 @@ Using the node's `run_state` that contains the current application in the search
The servlet container context configuration (`context.xml`) exposes the following JNDI resources which can be referenced by the webapp's deployment descriptor (web.xml):
-* A JDBC datasource for all databases in the node's current `app_environment`. The datasource uses the information (including JDBC driver) specified in the data bag item for the application.
-* An Environment entry that matches the node's current `app_environment` attribute value. This is useful for loading environment specific properties files in the web application.
+* A JDBC datasource for all databases in the node's current `chef_environment`. The datasource uses the information (including JDBC driver) specified in the data bag item for the application.
+* An Environment entry that matches the node's current `chef_environment` attribute value. This is useful for loading environment specific properties files in the web application.
This recipe assumes some sort of build process, such as Maven or a Continuous Integration server like Hudson, will create a deployable artifact and make it available for download via HTTP (such as S3 or artifactory).
@@ -110,8 +117,8 @@ mod\_php\_apache2
Requires `apache2` cookbook. Sets up a mod_php vhost template for the application using the `apache2` cookbook's `web_app` definition. See data bag example below.
-passenger_apache2
------------------
+passenger\_apache2
+------------------
Requires `apache2` and `passenger_apache2` cookbooks. Sets up a passenger vhost template for the application using the `apache2` cookbook's `web_app` definition. Use this with the `rails` recipe, in the list of recipes for a specific application type. See data bag example below.
@@ -183,22 +190,20 @@ Requires `unicorn` cookbook.
Unicorn is installed, default attributes are set for the node and an app specific unicorn config and runit service are created.
----
Deprecated Recipes
==================
The following recipes are deprecated and have been removed from the cookbook. To retrieve an older version, reference commit 4396ce6.
-`passenger-nginx`
-`rails_nginx_ree_passenger`
+* `passenger-nginx`
+* `rails_nginx_ree_passenger`
----
Application Data Bag
=====================
The applications data bag expects certain values in order to configure parts of the recipe. Below is a paste of the JSON, where the value is a description of the key. Use your own values, as required. Note that this data bag is also used by the `database` cookbook, so it will contain database information as well. Items that may be ambiguous have an example.
-The application used in examples is named `my_app` and the environment is `production`. Most top-level keys are Arrays, and each top-level key has an entry that describes what it is for, followed by the example entries. Entries that are hashes themselves will have the description in the value.
+The application used in examples is named `my_app` and the environment is `production`. Most top-level keys are Arrays, and each top-level key has an entry that describes what it is for, followed by the example entries. Entries that are hashes themselves will have the description in the value. In order to use the environment `production` you must create the environment as described below under __Usage__.
Note about "type": the recipes listed in the "type" will be included in the run list via `include_recipe` in the application default recipe based on the type matching one of the `server_roles` values.
@@ -285,13 +290,12 @@ A few example `local_settings` templates are included in this cookbook at `examp
An example is data bag item is included in this cookbook at `examples/data_bags/apps/php_app.json`.
----
Usage
=====
To use the application cookbook, we recommend creating a role named after the application, e.g. `my_app`. This role should match one of the `server_roles` entries, that will correspond to a `type` entry, in the databag. Create a Ruby DSL role in your chef-repo, or create the role directly with knife.
- % knife role show my_app
+ % knife role show my_app -Fj
{
"name": "my_app",
"chef_type": "role",
@@ -308,27 +312,22 @@ To use the application cookbook, we recommend creating a role named after the ap
Also recommended is a cookbook named after the application, e.g. `my_app`, for additional application specific setup such as other config files for queues, search engines and other components of your application. The `my_app` recipe can be used in the run list of the role, if it includes the `application` recipe.
-You should also have a role for the environment(s) you wish to use this cookbook. Similar to the role above, create the Ruby DSL file in chef-repo, or create with knife directly.
+You should also create an environment. We use `production` in the examples and the documentation above. An example is in the source code's "examples" directory, and the JSON for an environment is below:
- % knife role show production
+ % knife environment show production -Fj
{
"name": "production",
- "chef_type": "role",
- "json_class": "Chef::Role",
+ "description": "",
+ "cookbook_versions": {
+ },
+ "json_class": "Chef::Environment",
+ "chef_type": "environment",
"default_attributes": {
- "app_environment": "production"
},
- "description": "production environment role",
- "run_list": [
-
- ],
"override_attributes": {
}
}
-This role uses a default attribute so nodes can be moved into other environments on the fly simply by modifying their node object directly on the Chef Server.
-
----
License and Author
==================
@@ -0,0 +1,2 @@
+name "production"
+description "Production environment"
View
@@ -3,7 +3,7 @@
license "Apache 2.0"
description "Deploys and configures a variety of applications defined from databag 'apps'"
long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
-version "0.99.9"
+version "0.99.10"
recipe "application", "Loads application databags and selects recipes to use"
recipe "application::django", "Deploys a Django application specified in a data bag with the deploy_revision resource"
recipe "application::gunicorn", "Sets up the deployed Django application with Gunicorn as the web server"
View
@@ -7,10 +7,17 @@ This cookbook is written primarily to use MySQL and the Opscode mysql cookbook.
This cookbook does not automatically restore database dumps, but does install tools to help with that.
+Changes
+=======
+
+## v0.99.1
+
+* Use Chef 0.10's `node.chef_environment` instead of `node['app_environment']`.
+
Requirements
============
-Chef 0.8 or higher required.
+Chef 0.10.0 or higher required (for Chef environment use).
Platform
--------
@@ -29,8 +36,8 @@ The following Opscode cookbooks are dependencies:
Recipes
=======
-`ebs_volume`
-------------
+ebs\_volume
+-----------
Loads the aws information from the data bag. Searches the applications data bag for the database master or slave role and checks that role is applied to the node. Loads the EBS information and the master information from data bags. Uses the aws cookbook LWRP, `aws_ebs_volume` to manage the volume.
@@ -75,8 +82,8 @@ Deprecated Recipes
The following recipe is considered deprecated. It is kept for reference purposes.
-`ebs_backup`
-------------
+ebs\_backup
+-----------
Older style of doing mysql snapshot and replication using Adam Jacob's [ec2_mysql](http://github.com/adamhjk/ec2_mysql) script and library.
@@ -110,7 +117,7 @@ Usage
Aside from the application data bag (see the README in the application cookbook), create a role for the database master. Use a role.rb in your chef-repo, or create the role directly with knife.
- % knife role show my_app_database_master
+ % knife role show my_app_database_master -Fj
{
"name": "my_app_database_master",
"chef_type": "role",
@@ -126,23 +133,22 @@ Aside from the application data bag (see the README in the application cookbook)
}
}
-Also create a `production` role, or other role based on your desired environment. This is also used in the `application` cookbook.
+Create a `production` environment. This is also used in the `application` cookbook.
- % knife role show production
+ % knife environment show production -Fj
{
"name": "production",
- "chef_type": "role",
- "json_class": "Chef::Role",
+ "description": "",
+ "cookbook_versions": {
+ },
+ "json_class": "Chef::Environment",
+ "chef_type": "environment",
"default_attributes": {
- "app_environment": "production"
},
- "description": "production environment role",
- "run_list": [
-
- ],
"override_attributes": {
}
}
+
The cookbook `my_app_database` is recommended to set up any application specific database resources such as configuration templates, trending monitors, etc. It is not required, but you would need to create it separately in `site-cookbooks`. Add it to the `my_app_database_master` role.
View
@@ -3,7 +3,7 @@
license "Apache 2.0"
description "Sets up the database master or slave"
long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
-version "0.99.0"
+version "0.99.1"
recipe "database", "Empty placeholder"
recipe "database::ebs_backup", "Considered deprecated, older way of backing up EBS volumes"
@@ -1,24 +1,35 @@
-= DESCRIPTION:
+Description
+===========
Installs haproxy and prepares the configuration location.
-= REQUIREMENTS:
+Changes
+=======
-== Platform:
+## v1.0.0:
+
+* Use `node.chef_environment` instead of `node['app_environment']`
+
+Requirements
+============
+
+## Platform
Tested on Ubuntu 8.10 and higher.
-== Cookbooks:
+## Cookbooks:
-= ATTRIBUTES:
+Attributes
+==========
* `node['haproxy']['member_port']` - the port that member systems will be listening on, default 80
* `node['haproxy']['enable_admin']` - whether to enable the admin interface. default true. Listens on port 22002.
* `node['haproxy']['app_server_role']` - used by the `app_lb` recipe to search for a specific role of member systems. Default `webserver`.
-= USAGE:
+Usage
+=====
-Use either the default recipe or the app_lb recipe.
+Use either the default recipe or the `app_lb` recipe.
When using the default recipe, modify the haproxy.cfg.erb file with listener(s) for your sites/servers.
@@ -33,20 +44,19 @@ The app_lb recipe is designed to be used with the application cookbook, and prov
}
)
-The search also relies on an attribute "app_environment" being set on the node and a role named with the same value. For example, production:
-
+The search uses the node's `chef_environment`. For example, create `environments/production.rb`, then upload it to the server with knife
+ % cat environments/production.rb
name "production"
description "Nodes in the production environment."
- default_attributes(
- "app_environment" => "production"
- )
+ % knife environment from file production.rb
-= LICENSE and AUTHOR:
+License and Author
+==================
Author:: Joshua Timberman (<joshua@opscode.com>)
-Copyright:: 2009-2010, Opscode, Inc
+Copyright:: 2009-2011, Opscode, Inc
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
View
@@ -2,8 +2,8 @@
maintainer_email "cookbooks@opscode.com"
license "Apache 2.0"
description "Installs and configures haproxy"
-long_description IO.read(File.join(File.dirname(__FILE__), 'README.rdoc'))
-version "0.8.1"
+long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
+version "1.0.0"
recipe "haproxy", "Installs and configures haproxy"
recipe "haproxy::app_lb", "Installs and configures haproxy by searching for nodes of a particular role"
@@ -41,5 +41,5 @@
group "root"
mode 0644
variables :pool_members => pool_members
- notifies :restart, resources(:service => "haproxy")
+ notifies :restart, "service[haproxy]"
end
@@ -38,5 +38,5 @@
owner "root"
group "root"
mode 0644
- notifies :restart, resources(:service => "haproxy")
+ notifies :restart, "service[haproxy]"
end
Oops, something went wrong.

0 comments on commit 904f9f9

Please sign in to comment.