~ubuntu-branches/ubuntu/saucy/cloud-init/saucy

« back to all changes in this revision

Viewing changes to doc/examples/cloud-config-disk-setup.txt

  • Committer: Scott Moser
  • Date: 2013-09-21 00:45:57 UTC
  • mfrom: (1.4.6)
  • Revision ID: smoser@ubuntu.com-20130921004557-o8zfowviyrqz02sd
* New upstream snapshot.
  * add 'disk_setup' config module for partitioning disks and
    creating filesystems. (LP: #1218506)

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Cloud-init supports the creation of simple partition tables and file systems
 
2
on devices.
 
3
 
 
4
Default disk definitions for AWS
 
5
--------------------------------
 
6
(Not implemented yet, but provided for future documentation)
 
7
 
 
8
 disk_setup:
 
9
    ephmeral0:
 
10
        type: 'mbr'
 
11
        layout: True
 
12
        overwrite: False
 
13
 
 
14
 fs_setup:
 
15
    - label: None,
 
16
      filesystem: ext3
 
17
      device: ephemeral0
 
18
      partition: auto
 
19
 
 
20
Default disk definitions for Windows Azure
 
21
------------------------------------------
 
22
(Not implemented yet due to conflict with WALinuxAgent in Ubuntu)
 
23
 
 
24
disk_setup:
 
25
    /dev/sdb:
 
26
         type: mbr
 
27
         layout: True
 
28
         overwrite: False
 
29
 
 
30
fs_setup:
 
31
    - label: ephemeral0
 
32
      filesystem: ext3
 
33
      device: ephemeral0
 
34
      partition: any
 
35
 
 
36
 
 
37
Default disk definitions for SmartOS
 
38
------------------------------------
 
39
 
 
40
ephemeral_disk: /dev/vdb
 
41
disk_setup:
 
42
    /dev/vdb:
 
43
         type: mbr
 
44
         layout: True
 
45
         overwrite: False
 
46
 
 
47
fs_setup:
 
48
    - label: ephemeral0
 
49
      filesystem: ext3
 
50
      device: /dev/vdb
 
51
      partition: 1
 
52
 
 
53
Cavaut for SmartOS: if ephemeral disk is not defined, then the disk will
 
54
    not be automatically added to the mounts.
 
55
 
 
56
 
 
57
The default definition is used to make sure that the ephemeral storage is
 
58
setup properly.
 
59
 
 
60
"disk_setup": disk partitioning
 
61
--------------------------------
 
62
 
 
63
The disk_setup directive instructs Cloud-init to partition a disk. The format is:
 
64
 
 
65
 disk_setup:
 
66
    ephmeral0:
 
67
        type: 'mbr'
 
68
        layout: 'auto'
 
69
    /dev/xvdh:
 
70
        type: 'mbr'
 
71
        layout:
 
72
            - 33
 
73
            - [33, 82]
 
74
            - 33
 
75
        overwrite: True
 
76
 
 
77
The format is a list of dicts of dicts. The first value is the name of the
 
78
device and the subsequent values define how to create and layout the partition.
 
79
 
 
80
The general format is:
 
81
    disk_setup:
 
82
        <DEVICE>:
 
83
            type: 'mbr'
 
84
            layout: <LAYOUT|BOOL>
 
85
            overwrite: <BOOL>
 
86
 
 
87
Where:
 
88
    <DEVICE>: The name of the device. 'ephemeralX' and 'swap' are special
 
89
                values which are specific to the cloud. For these devices
 
90
                Cloud-init will look up what the real devices is and then
 
91
                use it.
 
92
 
 
93
                For other devices, the kernel device name is used. At this
 
94
                time only simply kernel devices are supported, meaning
 
95
                that device mapper and other targets may not work.
 
96
 
 
97
                Note: At this time, there is no handling or setup of
 
98
                device mapper targets.
 
99
 
 
100
    type=<TYPE>: Currently the following are supported:
 
101
                    'mbr': default and setups a MS-DOS partition table
 
102
 
 
103
                Note: At this time only 'mbr' partition tables are allowed.
 
104
                    It is anticipated in the future that we'll have GPT as
 
105
                    option in the future, or even "RAID" to create a mdadm
 
106
                    RAID.
 
107
 
 
108
    layout={...}: The device layout. This is a list of values, with the
 
109
                percentage of disk that partition will take.
 
110
                Valid options are:
 
111
                    [<SIZE>, [<SIZE>, <PART_TYPE]]
 
112
 
 
113
                Where <SIZE> is the _percentage_ of the disk to use, while
 
114
                <PART_TYPE> is the numerical value of the partition type.
 
115
 
 
116
                The following setups two partitions, with the first
 
117
                partition having a swap label, taking 1/3 of the disk space
 
118
                and the remainder being used as the second partition.
 
119
                    /dev/xvdh':
 
120
                        type: 'mbr'
 
121
                        layout:
 
122
                            - [33,82]
 
123
                            - 66
 
124
                        overwrite: True
 
125
 
 
126
                When layout is "true" it means single partition the entire
 
127
                device.
 
128
 
 
129
                When layout is "false" it means don't partition or ignore
 
130
                existing partitioning.
 
131
 
 
132
                If layout is set to "true" and overwrite is set to "false",
 
133
                it will skip partitioning the device without a failure.
 
134
 
 
135
    overwrite=<BOOL>: This describes whether to ride with saftey's on and
 
136
                everything holstered.
 
137
 
 
138
                'false' is the default, which means that:
 
139
                    1. The device will be checked for a partition table
 
140
                    2. The device will be checked for a file system
 
141
                    3. If either a partition of file system is found, then
 
142
                        the operation will be _skipped_.
 
143
 
 
144
                'true' is cowboy mode. There are no checks and things are
 
145
                    done blindly. USE with caution, you can do things you
 
146
                    really, really don't want to do.
 
147
 
 
148
 
 
149
fs_setup: Setup the file system
 
150
-------------------------------
 
151
 
 
152
fs_setup describes the how the file systems are supposed to look.
 
153
 
 
154
 fs_setup:
 
155
    - label: ephemeral0
 
156
      filesystem: 'ext3'
 
157
      device: 'ephemeral0'
 
158
      partition: 'auto'
 
159
    - label:  mylabl2
 
160
      filesystem: 'ext4'
 
161
      device: '/dev/xvda1'
 
162
    - special:
 
163
      cmd: mkfs -t %(FILESYSTEM)s -L %(LABEL)s %(DEVICE)s
 
164
      filesystem: 'btrfs'
 
165
      device: '/dev/xvdh'
 
166
 
 
167
The general format is:
 
168
    fs_setup:
 
169
        - label: <LABEL>
 
170
          filesystem: <FS_TYPE>
 
171
          device: <DEVICE>
 
172
          partition: <PART_VALUE>
 
173
          overwrite: <OVERWRITE>
 
174
 
 
175
Where:
 
176
    <LABEL>: The file system label to be used. If set to None, no label is
 
177
        used.
 
178
 
 
179
    <FS_TYPE>: The file system type. It is assumed that the there
 
180
        will be a "mkfs.<FS_TYPE>" that behaves likes "mkfs". On a standard
 
181
        Ubuntu Cloud Image, this means that you have the option of ext{2,3,4},
 
182
        and vfat by default.
 
183
 
 
184
    <DEVICE>: The device name. Special names of 'ephemeralX' or 'swap'
 
185
        are allowed and the actual device is acquired from the cloud datasource.
 
186
        When using 'ephemeralX' (i.e. ephemeral0), make sure to leave the
 
187
        label as 'ephemeralX' otherwise there may be issues with the mounting
 
188
        of the ephemeral storage layer.
 
189
 
 
190
    <PART_VALUE>: The valid options are:
 
191
        "auto": auto is a special in the sense that you are telling cloud-init
 
192
            not to care whether there is a partition or not. Auto will put the
 
193
            first partition that does not contain a file system already. In
 
194
            the absence of a partition table, it will put it directly on the
 
195
            disk.
 
196
 
 
197
        "none": Put the partition directly on the disk.
 
198
 
 
199
        <NUM>: where NUM is the actual partition number.
 
200
 
 
201
    <OVERWRITE>: Defines whether or not to overwrite any existing
 
202
        filesystem.
 
203
 
 
204
        "true": Indiscriminately destroy any pre-existing file system. Use at
 
205
            your own peril.
 
206
 
 
207
        "false": If an existing file system exists, skip the creation.
 
208
 
 
209
Behavior Caveat: The default behavior is to _check_ if the file system exists.
 
210
    If a file system matches the specification, then the operation is a no-op.