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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
.. _datasource_smartos:
SmartOS Datasource
******************
This datasource finds metadata and user data from the SmartOS virtualisation
platform (i.e., Joyent).
Please see http://smartos.org/ for information about SmartOS.
SmartOS platform
================
The SmartOS virtualisation platform uses metadata from the instance via the
second serial console. On Linux, this is :file:`/dev/ttyS1`. The data is
provided via a simple protocol:
* Something queries for the data,
* the console responds with the status, and
* if "SUCCESS" returns until a single ".\n".
New versions of the SmartOS tooling will include support for Base64-encoded
data.
Metadata channels
=================
``Cloud-init`` supports three modes of delivering user data and metadata via
the flexible channels of SmartOS.
1. User data is written to :file:`/var/db/user-data`:
- As per the spec, user data is for consumption by the end user, not
provisioning tools.
- ``Cloud-init`` ignores this channel, other than writing it to disk.
- Removal of the ``meta-data`` key means that :file:`/var/db/user-data`
gets removed.
- A backup of previous metadata is maintained as
:file:`/var/db/user-data.<timestamp>`. ``<timestamp>`` is the epoch time
when ``cloud-init`` ran.
2. ``user-script`` is written to
:file:`/var/lib/cloud/scripts/per-boot/99_user_data`:
- This is executed each boot.
- A link is created to :file:`/var/db/user-script`.
- Previous versions of ``user-script`` is written to
:file:`/var/lib/cloud/scripts/per-boot.backup/99_user_script.<timestamp>.`
- <timestamp> is the epoch time when ``cloud-init`` ran.
- When the ``user-script`` metadata key goes missing, ``user-script`` is
removed from the file system, although a backup is maintained.
- If the script does not start with a shebang (i.e., it starts with
#!<executable>), or it is not an executable, ``cloud-init`` will add a
shebang of "#!/bin/bash".
3. ``Cloud-init`` user data is treated like on other Clouds.
- This channel is used for delivering ``_all_ cloud-init`` instructions.
- Scripts delivered over this channel must be well formed (i.e., they must
have a shebang).
``Cloud-init`` supports reading the traditional metadata fields supported by
the SmartOS tools. These are:
* ``root_authorized_keys``
* ``hostname``
* ``enable_motd_sys_info``
* ``iptables_disable``
.. note::
At this time, ``iptables_disable`` and ``enable_motd_sys_info`` are read
but are not actioned.
Disabling ``user-script``
=========================
``Cloud-init`` uses the per-boot script functionality to handle the execution
of the ``user-script``. If you want to prevent this, use a cloud-config of:
.. code-block:: yaml
#cloud-config
cloud_final_modules:
- scripts-per-once
- scripts-per-instance
- scripts-user
- ssh-authkey-fingerprints
- keys-to-console
- phone-home
- final-message
- power-state-change
Alternatively you can use the JSON patch method:
.. code-block:: yaml
#cloud-config-jsonp
[
{ "op": "replace",
"path": "/cloud_final_modules",
"value": ["scripts-per-once",
"scripts-per-instance",
"scripts-user",
"ssh-authkey-fingerprints",
"keys-to-console",
"phone-home",
"final-message",
"power-state-change"]
}
]
The default cloud-config includes "script-per-boot". ``Cloud-init`` will still
ingest and write the user data, but will not execute it when you disable
the per-boot script handling.
The cloud-config needs to be delivered over the ``cloud-init:user-data``
channel in order for ``cloud-init`` to ingest it.
.. note::
Unless you have an explicit use-case, it is recommended that you do not
disable the per-boot script execution, especially if you are using
any of the life-cycle management features of SmartOS.
Base64
======
The following are exempt from Base64 encoding, owing to the fact that they
are provided by SmartOS:
* ``root_authorized_keys``
* ``enable_motd_sys_info``
* ``iptables_disable``
* ``user-data``
* ``user-script``
This list can be changed through the
:ref:`datasource base configuration<base_config-Datasource>` variable
``no_base64_decode``.
This means that ``user-script``, ``user-data`` and other values can be Base64
encoded. Since ``cloud-init`` can only guess whether or not something
is truly Base64 encoded, the following metadata keys are hints as to whether
or not to Base64 decode something:
* ``base64_all``: Except for excluded keys, attempt to Base64 decode the
values. If the value fails to decode properly, it will be returned in its
text.
* ``base64_keys``: A comma-delimited list of which keys are Base64 encoded.
* ``b64-<key>``: For any key, if an entry exists in the metadata for
``'b64-<key>'``, then ``'b64-<key>'`` is expected to be a plain-text boolean
indicating whether or not its value is encoded.
* ``no_base64_decode``: This is a configuration setting
(i.e., :file:`/etc/cloud/cloud.cfg.d`) that sets which values should not
be Base64 decoded.
``disk_aliases`` and ephemeral disk
===================================
By default, SmartOS only supports a single ephemeral disk. That disk is
completely empty (un-partitioned, with no filesystem).
The SmartOS datasource has built-in cloud-config which instructs the
``disk_setup`` module to partition and format the ephemeral disk.
You can control the ``disk_setup`` in 2 ways:
1. Through the datasource config, you can change the 'alias' of ``ephermeral0``
to reference another device. The default is:
.. code-block::
'disk_aliases': {'ephemeral0': '/dev/vdb'}
This means that anywhere ``disk_setup`` sees a device named 'ephemeral0',
then :file:`/dev/vdb` will be substituted.
2. You can provide ``disk_setup`` or ``fs_setup`` data in ``user-data`` to
overwrite the datasource's built-in values.
See :file:`doc/examples/cloud-config-disk-setup.txt` for information on
``disk_setup``.
|
