1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
.. -*- mode: rst -*-
.. _server-plugins-connectors-awstags:
=========
AWSTags
=========
The AWSTags plugin is a connector that retrieves tags from instances
in EC2, and can optionally assign group membership based on patterns
in the tags. See `Using Tags
<http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html>`_
for details on using tags in EC2.
AWSTags queries EC2 for instances whose ``private-dns-name`` property
matches the hostname of the client.
Setup
=====
#. Add ``AWSTags`` to the ``plugins`` option in ``/etc/bcfg2.conf``
#. Configure AWS credentials in ``/etc/bcfg2.conf`` (See
`Configuration`_ below for details.)
#. Optionally, create ``AWSTags/config.xml`` (See `Assigning Groups`_
below for details.)
#. Restart the Bcfg2 server.
Using Tag Data
==============
AWSTags exposes the data in templates as a dict available as
``metadata.AWSTags``. E.g., in a :ref:`Genshi template
<server-plugins-generators-cfg-genshi>`, you could do:
.. code-block:: genshitext
Known tags on ${metadata.hostname}:
{% for key, val in metadata.AWSTags.items() %}\
${key} ${val}
{% end %}\
This would produce something like::
Known tags on foo.example.com:
Name foo.example.com
some random tag the value
Assigning Groups
================
AWSTags can assign groups based on the tag data. This functionality
is configured in ``AWSTags/config.xml``.
Example
-------
.. code-block:: xml
<AWSTags>
<Tag name="^foo$">
<Group>foo</Group>
</Tag>
<Tag name="^bar$" value="^bar$">
<Group>bar</Group>
</Tag>
<Tag name="^bcfg2 group$" value="(.*)">
<Group>$1</Group>
</Tag>
</AWSTags>
In this example, any machine with a tag named ``foo`` would be added
to the ``foo`` group. Any machine with a tag named ``bar`` whose
value was also ``bar`` would be added to the ``bar`` group. Finally,
any machine with a tag named ``bcfg2 group`` would be added to the
group named in the value of that tag.
Note that both the ``name`` and ``value`` attributes are *always*
regular expressions.
If a ``<Tag/>`` element has only a ``name`` attribute, then it only
checks for existence of a matching tag. If it has both ``name`` and
``value``, then it checks for a matching tag with a matching value.
You can use backreferences (``$1``, ``$2``, etc.) in the group names.
If only ``name`` is specified, then the backreferences will refer to
groups in the ``name`` regex. If ``name`` and ``value`` are both
specified, then backreferences will refer to groups in the ``value``
regex. If you specify both ``name`` and ``value``, it is not possible
to refer to groups in the ``name`` regex.
Schema Reference
----------------
.. xml:schema:: awstags.xsd
Configuration
=============
AWSTags recognizes several options in ``/etc/bcfg2.conf``; at a
minimum, you must configure an AWS access key ID and secret key. All
of the following options are in the ``[awstags]`` section:
+-----------------------+-----------------------------------------------------+
| Option | Description |
+=======================+=====================================================+
| ``access_key_id`` | The AWS access key ID |
+-----------------------+-----------------------------------------------------+
| ``secret_access_key`` | The AWS secret access key |
+-----------------------+-----------------------------------------------------+
| ``cache`` | Whether or not to cache tag lookups. See `Caching`_ |
| | for details. Default is to cache. |
+-----------------------+-----------------------------------------------------+
Caching
=======
Since the AWS API isn't always very quick to respond, AWSTags caches
its results by default. The cache is fairly short-lived: the cache
for each host is expired when it starts a client run, so it will start
the run with fresh data.
If you frequently update tags on your instances, you may wish to
disable caching. That's probably a bad idea, and would tend to
suggest that updating tags frequently is perhaps the Wrong Thing.
|
