diff --git a/README.md b/README.md deleted file mode 100644 index fa73c96..0000000 --- a/README.md +++ /dev/null @@ -1,133 +0,0 @@ -os-apply-config -=============== - -Apply configuration from cloud metadata (JSON). - - -# What does it do? - -It turns metadata from one or more JSON files like this: -```javascript -{"keystone": {"database": {"host": "127.0.0.1", "user": "keystone", "password": "foobar"}}} -``` -into service config files like this: -``` -[sql] -connection = mysql://keystone:foobar@127.0.0.1/keystone -...other settings... -``` - -# Usage - -Just pass it the path to a directory tree of templates: -``` -sudo os-apply-config -t /home/me/my_templates -``` - -By default it will read config files according to the contents of the -file /var/run/os-collect-config/os_config_files.json. This path can be -changed with the command line switch --os-config-files, or the environment -variable OS_CONFIG_FILES_PATH. The list can also be overridden with the -environment variable OS_CONFIG_FILES. If overriding with OS_CONFIG_FILES, -the paths are expected to be colon, ":", separated. Each json file -referred to must have a mapping as their root structure. Keys in files -mentioned later in the list will override keys in earlier files from -this list. - -``` -OS_CONFIG_FILES=/tmp/ec2.json:/tmp/cfn.json os-apply-config -``` - -This will read ec2.json and cfn.json, and if they have any -overlapping keys, the value from cfn.json will be used. That will -populate the tree for any templates found in the template path. See -https://git.openstack.org/cgit/openstack/os-collect-config for a program -that will automatically collect data and populate this list. - -You can also override OS_CONFIG_FILES with the --metadata command line -option, specifying it multiple times instead of colon separating the list. - -Os-apply-config will also always try to read metadata in the old -legacy paths first to populate the tree. These paths can be changed -with --fallback-metadata. - -# Templates - -The template directory structure should mimic a root filesystem, and contain templates for only those files you want configured. - -e.g. -``` -~/my_templates$ tree -. -└── etc - ├── keystone - │   └── keystone.conf - └── mysql - └── mysql.conf -``` - -An example tree [can be found here](http://git.openstack.org/cgit/openstack/tripleo-image-elements/tree/elements/keystone/os-apply-config) - -If a template is executable it will be treated as an **executable template**. -Otherwise, it will be treated as a **mustache template**. - -## Mustache Templates - -If you don't need any logic, just some string substitution, use a mustache template. - -Metadata settings are accessed with dot ('.') notation: - -``` -[sql] -connection = mysql://{{keystone.database.user}}:{{keystone.database.password}@{{keystone.database.host}}/keystone -``` - -## Executable Templates - -Configuration requiring logic is expressed in executable templates. - -An executable template is a script which accepts configuration as a JSON string on standard in, and writes a config file to standard out. - -The script should exit non-zero if it encounters a problem, so that os-apply-config knows what's up. - -The output of the script will be written to the path corresponding to the executable template's path in the template tree. - - -```ruby -#!/usr/bin/env ruby -require 'json' -params = JSON.parse STDIN.read -puts "connection = mysql://#{c['keystone']['database']['user']}:#{c['keystone']['database']['password']}@#{c['keystone']['database']['host']}/keystone" -``` - -You could even embed mustache in a heredoc, and use that: -```ruby -#!/usr/bin/env ruby -require 'json' -require 'mustache' -params = JSON.parse STDIN.read - -template = <<-eos -[sql] -connection = mysql://{{keystone.database.user}}:{{keystone.database.password}}@{{keystone.database.host}}/keystone - -[log] -... -eos - -# tweak params here... - -puts Mustache.render(template, params) -``` - -# Quick Start -```bash -# install it -sudo pip install -U git+git://git.openstack.org/openstack/os-apply-config.git - -# grab example templates -git clone git://git.openstack.org/openstack/tripleo-image-elements /tmp/config - -# run it -os-apply-config -t /tmp/config/elements/nova/os-config-applier/ -m /tmp/config/elements/boot-stack/config.json -o /tmp/config_output -``` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..527df1a --- /dev/null +++ b/README.rst @@ -0,0 +1,136 @@ +=============== +os-apply-config +=============== + +----------------------------------------------- +Apply configuration from cloud metadata (JSON) +----------------------------------------------- + +What does it do? +================ + +It turns metadata from one or more JSON files like this:: + + {"keystone": {"database": {"host": "127.0.0.1", "user": "keystone", "password": "foobar"}}} + +into service config files like this:: + + [sql] + connection = mysql://keystone:foobar@127.0.0.1/keystone + ...other settings... + +Usage +===== + +Just pass it the path to a directory tree of templates:: + + sudo os-apply-config -t /home/me/my_templates + +By default it will read config files according to the contents of the +file `/var/run/os-collect-config/os_config_files.json`. This path can +be changed with the command line switch `--os-config-files`, or the +environment variable `OS_CONFIG_FILES_PATH`. The list can also be +overridden with the environment variable `OS_CONFIG_FILES`. If +overriding with `OS_CONFIG_FILES`, the paths are expected to be colon, +":", separated. Each json file referred to must have a mapping as +their root structure. Keys in files mentioned later in the list will +override keys in earlier files from this list. For example:: + + OS_CONFIG_FILES=/tmp/ec2.json:/tmp/cfn.json os-apply-config + +This will read `ec2.json` and `cfn.json`, and if they have any +overlapping keys, the value from `cfn.json` will be used. That will +populate the tree for any templates found in the template path. See +https://git.openstack.org/cgit/openstack/os-collect-config for a +program that will automatically collect data and populate this list. + +You can also override `OS_CONFIG_FILES` with the `--metadata` command +line option, specifying it multiple times instead of colon separating +the list. + +`os-apply-config` will also always try to read metadata in the old +legacy paths first to populate the tree. These paths can be changed +with `--fallback-metadata`. + +Templates +========= + +The template directory structure should mimic a root filesystem, and +contain templates for only those files you want configured. For +example:: + + ~/my_templates$ tree + . + └── etc + ├── keystone + │ └── keystone.conf + └── mysql + └── mysql.conf + +An example tree can be found `here `_. + +If a template is executable it will be treated as an *executable +template*. Otherwise, it will be treated as a *mustache template*. + +Mustache Templates +------------------ + +If you don't need any logic, just some string substitution, use a +mustache template. + +Metadata settings are accessed with dot ('.') notation:: + + [sql] + connection = mysql://{{keystone.database.user}}:{{keystone.database.password}@{{keystone.database.host}}/keystone + +Executable Templates +-------------------- + +Configuration requiring logic is expressed in executable templates. + +An executable template is a script which accepts configuration as a +JSON string on standard in, and writes a config file to standard out. + +The script should exit non-zero if it encounters a problem, so that +os-apply-config knows what's up. + +The output of the script will be written to the path corresponding to +the executable template's path in the template tree:: + + #!/usr/bin/env ruby + require 'json' + params = JSON.parse STDIN.read + puts "connection = mysql://#{c['keystone']['database']['user']}:#{c['keystone']['database']['password']}@#{c['keystone']['database']['host']}/keystone" + +You could even embed mustache in a heredoc, and use that:: + + #!/usr/bin/env ruby + require 'json' + require 'mustache' + params = JSON.parse STDIN.read + + template = <<-eos + [sql] + connection = mysql://{{keystone.database.user}}:{{keystone.database.password}}@{{keystone.database.host}}/keystone + + [log] + ... + eos + + # tweak params here... + + puts Mustache.render(template, params) + + +Quick Start +=========== +:: + + # install it + sudo pip install -U git+git://git.openstack.org/openstack/os-apply-config.git + + # grab example templates + git clone git://git.openstack.org/openstack/tripleo-image-elements /tmp/config + + # run it + os-apply-config -t /tmp/config/elements/nova/os-config-applier/ -m /tmp/config/elements/boot-stack/config.json -o /tmp/config_output diff --git a/setup.cfg b/setup.cfg index f8d7570..c945120 100644 --- a/setup.cfg +++ b/setup.cfg @@ -4,7 +4,7 @@ author = OpenStack author-email = openstack-dev@lists.openstack.org summary = Config files from cloud metadata description-file = - README.md + README.rst home-page = http://git.openstack.org/cgit/openstack/os-apply-config classifier = Development Status :: 4 - Beta