summaryrefslogtreecommitdiff
path: root/doc/examples/cloud-config-disk-setup.txt
blob: 6ad61c33a91dd6245ae162bca4781efa8ad39123 (plain)
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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
Cloud-init supports the creation of simple partition tables and file systems
on devices.

Default disk definitions for AWS
--------------------------------
(Not implemented yet, but provided for future documentation)

 disk_setup:
    ephmeral0:
        type: 'mbr'
        layout: True
        overwrite: False

 fs_setup:
    - label: None,
      filesystem: ext3
      device: ephemeral0
      partition: auto

Default disk definitions for Windows Azure
------------------------------------------

device_aliases: {'ephemeral0': '/dev/sdb'}
disk_setup:
    ephemeral0:
         type: mbr
         layout: True
         overwrite: False

fs_setup:
    - label: ephemeral0
      filesystem: ext4
      device: ephemeral0.1
      replace_fs: ntfs


Default disk definitions for SmartOS
------------------------------------

device_aliases: {'ephemeral0': '/dev/sdb'}
disk_setup:
    ephemeral0:
         type: mbr
         layout: False
         overwrite: False

fs_setup:
    - label: ephemeral0
      filesystem: ext3
      device: ephemeral0.0

Cavaut for SmartOS: if ephemeral disk is not defined, then the disk will
    not be automatically added to the mounts.


The default definition is used to make sure that the ephemeral storage is
setup properly.

"disk_setup": disk partitioning
--------------------------------

The disk_setup directive instructs Cloud-init to partition a disk. The format is:

 disk_setup:
    ephmeral0:
        type: 'mbr'
        layout: 'auto'
    /dev/xvdh:
        type: 'mbr'
        layout:
            - 33
            - [33, 82]
            - 33
        overwrite: True

The format is a list of dicts of dicts. The first value is the name of the
device and the subsequent values define how to create and layout the partition.

The general format is:
    disk_setup:
        <DEVICE>:
            type: 'mbr'
            layout: <LAYOUT|BOOL>
            overwrite: <BOOL>

Where:
    <DEVICE>: The name of the device. 'ephemeralX' and 'swap' are special
                values which are specific to the cloud. For these devices
                Cloud-init will look up what the real devices is and then
                use it.

                For other devices, the kernel device name is used. At this
                time only simply kernel devices are supported, meaning
                that device mapper and other targets may not work.

                Note: At this time, there is no handling or setup of
                device mapper targets.

    type=<TYPE>: Currently the following are supported:
                    'mbr': default and setups a MS-DOS partition table

                Note: At this time only 'mbr' partition tables are allowed.
                    It is anticipated in the future that we'll have GPT as
                    option in the future, or even "RAID" to create a mdadm
                    RAID.

    layout={...}: The device layout. This is a list of values, with the
                percentage of disk that partition will take.
                Valid options are:
                    [<SIZE>, [<SIZE>, <PART_TYPE]]

                Where <SIZE> is the _percentage_ of the disk to use, while
                <PART_TYPE> is the numerical value of the partition type.

                The following setups two partitions, with the first
                partition having a swap label, taking 1/3 of the disk space
                and the remainder being used as the second partition.
                    /dev/xvdh':
                        type: 'mbr'
                        layout:
                            - [33,82]
                            - 66
                        overwrite: True

                When layout is "true" it means single partition the entire
                device.

                When layout is "false" it means don't partition or ignore
                existing partitioning.

                If layout is set to "true" and overwrite is set to "false",
                it will skip partitioning the device without a failure.

    overwrite=<BOOL>: This describes whether to ride with saftey's on and
                everything holstered.

                'false' is the default, which means that:
                    1. The device will be checked for a partition table
                    2. The device will be checked for a file system
                    3. If either a partition of file system is found, then
                        the operation will be _skipped_.

                'true' is cowboy mode. There are no checks and things are
                    done blindly. USE with caution, you can do things you
                    really, really don't want to do.


fs_setup: Setup the file system
-------------------------------

fs_setup describes the how the file systems are supposed to look.

 fs_setup:
    - label: ephemeral0
      filesystem: 'ext3'
      device: 'ephemeral0'
      partition: 'auto'
    - label:  mylabl2
      filesystem: 'ext4'
      device: '/dev/xvda1'
    - special:
      cmd: mkfs -t %(FILESYSTEM)s -L %(LABEL)s %(DEVICE)s
      filesystem: 'btrfs'
      device: '/dev/xvdh'

The general format is:
    fs_setup:
        - label: <LABEL>
          filesystem: <FS_TYPE>
          device: <DEVICE>
          partition: <PART_VALUE>
          overwrite: <OVERWRITE>
          replace_fs: <FS_TYPE>

Where:
    <LABEL>: The file system label to be used. If set to None, no label is
        used.

    <FS_TYPE>: The file system type. It is assumed that the there
        will be a "mkfs.<FS_TYPE>" that behaves likes "mkfs". On a standard
        Ubuntu Cloud Image, this means that you have the option of ext{2,3,4},
        and vfat by default.

    <DEVICE>: The device name. Special names of 'ephemeralX' or 'swap'
        are allowed and the actual device is acquired from the cloud datasource.
        When using 'ephemeralX' (i.e. ephemeral0), make sure to leave the
        label as 'ephemeralX' otherwise there may be issues with the mounting
        of the ephemeral storage layer.

        If you define the device as 'ephemeralX.Y' then Y will be interpetted
        as a partition value. However, ephermalX.0 is the _same_ as ephemeralX.

    <PART_VALUE>:
        Partition definitions are overwriten if you use the '<DEVICE>.Y' notation.

        The valid options are:
        "auto|any": tell cloud-init not to care whether there is a partition
            or not. Auto will use the first partition that does not contain a
            file system already. In the absence of a partition table, it will
            put it directly on the disk.

            "auto": If a file system that matches the specification in terms of
            label, type and device, then cloud-init will skip the creation of
            the file system.

            "any": If a file system that matches the file system type and device,
            then cloud-init will skip the creation of the file system.

            Devices are selected based on first-detected, starting with partitions
            and then the raw disk. Consider the following:
                NAME     FSTYPE LABEL
                xvdb
                |-xvdb1  ext4
                |-xvdb2
                |-xvdb3  btrfs  test
                \-xvdb4  ext4   test

            If you ask for 'auto', label of 'test, and file system of 'ext4'
            then cloud-init will select the 2nd partition, even though there
            is a partition match at the 4th partition.

            If you ask for 'any' and a label of 'test', then cloud-init will
            select the 1st partition.

            If you ask for 'auto' and don't define label, then cloud-init will
            select the 1st partition.

            In general, if you have a specific partition configuration in mind,
            you should define either the device or the partition number. 'auto'
            and 'any' are specifically intended for formating ephemeral storage or
            for simple schemes.

        "none": Put the file system directly on the device.

        <NUM>: where NUM is the actual partition number.

    <OVERWRITE>: Defines whether or not to overwrite any existing
        filesystem.

        "true": Indiscriminately destroy any pre-existing file system. Use at
            your own peril.

        "false": If an existing file system exists, skip the creation.

    <REPLACE_FS>: This is a special directive, used for Windows Azure that
        instructs cloud-init to replace a file system of <FS_TYPE>. NOTE:
        unless you define a label, this requires the use of the 'any' partition
        directive.

Behavior Caveat: The default behavior is to _check_ if the file system exists.
    If a file system matches the specification, then the operation is a no-op.