From c93a77f6766a332bcd688d76e7fed888cd87b8b2 Mon Sep 17 00:00:00 2001
From: Mark McLoughlin <markmc@redhat.com>
Date: Wed, 27 Nov 2013 11:58:13 +0000
Subject: [PATCH] Add some more details about os-collect-config

Flesh out some details about the hoops you need to jump through to
integrate the cfn collector into a heat template. This info could
probably live somewhere else, but I figure adding here is a reasonable
starting point.

Change-Id: I163a4a7cc665292a814a693f83f947bb2b280970
---
 elements/os-collect-config/README.md | 84 ++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)

diff --git a/elements/os-collect-config/README.md b/elements/os-collect-config/README.md
index 5774b22a9..e61b367bb 100644
--- a/elements/os-collect-config/README.md
+++ b/elements/os-collect-config/README.md
@@ -30,3 +30,87 @@ parameters. All of the others are required for the cfn data source
 to function.
 
 `ec2` and `heat_local` do not require any configuration to work.
+
+Typically the cfn collector is configured via EC2 metadata in a Heat
+template:
+
+    Resources:
+      myserver:
+        Type: OS::Nova::Server
+        Properties:
+          ...
+        Metadata:
+          os-collect-config:
+            cfn:
+              access_key_id:
+                Ref: Key
+              path: MyServerConfig.Metadata
+              secret_access_key:
+                Fn::GetAtt:
+                - Key
+                - SecretAccessKey
+              stack_name:
+                Ref: AWS::StackName
+
+The EC2 collector takes this metadata, passes it to os-apply-config
+which in turn writes it out to /etc/os-collect-config.conf.
+
+Note that the configuration references some other resources - a key
+and access key, which are declared using:
+
+    Resources:
+      Key:
+        Properties:
+          UserName:
+            Ref: User
+        Type: AWS::IAM::AccessKey
+      User:
+        Properties:
+          Policies:
+          - Ref: AccessPolicy
+        Type: AWS::IAM::User
+
+Note also that the IAM::User references an access policy which should
+look like:
+
+    Resources:
+      AccessPolicy:
+        Properties:
+          AllowedResources:
+          - MyServerConfig
+        Type: OS::Heat::AccessPolicy
+
+and, finally, the crucial bit is the MyServerConfig policy which is
+referenced in the cfn collector configuration and the access policy:
+
+    Resources:
+      MyServerConfig:
+        Metadata:
+          os-collect-config:
+            cfn:
+              access_key_id:
+                Ref: Key
+              path: MyServerConfig.Metadata
+              secret_access_key:
+                Fn::GetAtt:
+                - Key
+                - SecretAccessKey
+              stack_name:
+                Ref: AWS::StackName
+          nova:
+            ...
+          keystone:
+            ...
+        Properties:
+          ImageId: '0'
+          InstanceType: foo
+        Type: AWS::AutoScaling::LaunchConfiguration
+
+Essentially, this AutoScaling::LaunchConfiguration resource is a bunch
+of boilerplate gunk to provide a metadata container from where the
+os-collect-config cfn collector can pull configuration which will be
+applied by os-apply-config. There's a os-collect-config section to
+ensure the configuration from the EC2 metadata doesn't get
+overwritten. And the rest is dummy values for the
+LaunchConfiguration's required properties.
+