Skip to content

Commit 3469324

Browse files
sayanchowdhurysayanchowdhury
committed
Add the docs for Cloud init
Signed-off-by: Sayan Chowdhury <[email protected]>
1 parent 15d6b9b commit 3469324

File tree

1 file changed

+299
-0
lines changed

1 file changed

+299
-0
lines changed

‎installation/public_cloud/cloud_init.adoc

+299
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
[[installation-public-cloud-cloud-init]]
2+
= {product-title} Installation using Cloud init
3+
{product-author}
4+
{product-version}
5+
:data-uri:
6+
:icons:
7+
8+
The Atomic Host uses cloud-init to configure the system during installation
9+
and first-boot. `cloud-init` was initially developed to provide
10+
early initialization of cloud instances.
11+
12+
The files used by cloud-init are YAML formatted files.
13+
14+
==== Create users with cloud-init
15+
16+
To create users with cloud-init, you must create two files: *meta-data* and *user-data*,
17+
and then package them into an ISO image.
18+
19+
. Make a directory and move into it:
20+
....
21+
$ mkdir cloudinitiso
22+
$ cd cloudinitiso
23+
....
24+
25+
. Create a file called meta-data. Add the following to the file called meta-data:
26+
....
27+
instance-id: Atomic0
28+
local-hostname: atomic-00
29+
....
30+
31+
. Create a file called user-data. Add the following to the file called user-data:
32+
....
33+
#cloud-config
34+
password: atomic
35+
chpasswd: {expire: False}
36+
ssh_pwauth: True
37+
ssh_authorized_keys:
38+
- ssh-rsa AAA...SDvZ [email protected]
39+
....
40+
41+
Note: The final line of the *user-data* file above is an SSH public key.
42+
SSH public keys are found in *~/.ssh/id_rsa.pub*.
43+
44+
. Create an ISO image that includes *meta-data* and *user-data*:
45+
....
46+
# genisoimage -output atomic0cidata.iso -volid cidata -joliet -rock user-data meta-data
47+
....
48+
49+
. A file named *atomic0cidata.iso* is generated. Attach this file to the machine on
50+
which you plan to install Atomic Host, and your username will be `cloud-user` and
51+
your password will be `atomic`.
52+
53+
54+
* How do I expire the cloud-user's password so that the user must change it during their first login?
55+
56+
To force "cloud-user" to change their password at first login, change the line
57+
`chpasswd: {expire: False}` to `chpasswd: {expire: True}` in the *user-data* file.
58+
59+
....
60+
#cloud-config
61+
password: atomic
62+
chpasswd: {expire: True}
63+
ssh_pwauth: True
64+
ssh_authorized_keys:
65+
- ssh-rsa AAA...SDvz [email protected]
66+
- ssh-rsa AAB...QTuo [email protected]
67+
....
68+
69+
This works because the password and chpasswd operate on the default user unless otherwise indicated.
70+
71+
Note: This is a global setting. If you set this to True all users who are created
72+
(see below) will have to change their password.
73+
74+
* How do I change the default username?
75+
76+
To change the default username from cloud-user to something else, add the
77+
line `user: username` to the *user-data* file:
78+
79+
....
80+
#cloud-config
81+
user: username
82+
password: atomic
83+
chpasswd: {expire: False}
84+
ssh_pwauth: True
85+
ssh_authorized_keys:
86+
- ssh-rsa AAA...SDvz [email protected]
87+
- ssh-rsa AAB...QTuo [email protected]
88+
....
89+
90+
* How do I set the root password?
91+
92+
To set the root password you must create a user list in the `chpasswd` section of
93+
the user-data file. The format of the list is shown below.
94+
Whitespace is significant, so do not include any on either side of the colon
95+
(`:`) as it will set a password with a space in it.
96+
If you use this method to set the user passwords, *all passwords* must be set in
97+
this section. This means that the `password:` line must be moved from the top
98+
and into this section.
99+
100+
....
101+
#cloud-config
102+
ssh_pwauth: True
103+
ssh_authorized_keys:
104+
- ssh-rsa AAA...SDvz [email protected]
105+
- ssh-rsa AAB...QTuo [email protected]
106+
chpasswd:
107+
list: |
108+
root:password
109+
cloud-user:atomic
110+
expire: False
111+
....
112+
113+
* How do I add more users during initial system configuration? How do I set additional user options?
114+
115+
Users are created and described in the users section of the user-data file.
116+
Adding this section requires that options for the default user be set here as well.
117+
118+
If the first entry in the _users_ section is `default`, the default user, _cloud-user_
119+
will be created along with the other users. If the default line is omitted, then
120+
_cloud-user_ is not created.
121+
122+
....
123+
#cloud-config
124+
users:
125+
- default
126+
- name: foobar
127+
gecos: User N. Ame
128+
selinux-user: staff_u
129+
groups: users,wheel
130+
ssh_pwauth: True
131+
ssh_authorized_keys:
132+
- ssh-rsa AA..vz [email protected]
133+
chpasswd:
134+
list: |
135+
root:password
136+
cloud-user:atomic
137+
foobar:foobar
138+
expire: False
139+
....
140+
141+
Note: By default users will be labeled as unconfined_u if there is not an _se-linux-user_ value.
142+
143+
Note: This example places the user _foobar_ into two groups: `users` and `wheel`.
144+
145+
146+
* How do I run first boot commands?
147+
148+
The `runcmd` and `bootcmd` sections of the _user-data_ file can be used to execute
149+
arbitrary commands during startup and initialization. The `bootcmd` section is run
150+
early in the initialization process. The `runcmd` section is executed near the end
151+
of the process by init. These commands are *not* saved for future boots and will
152+
only be executed during the first initialization-boot.
153+
154+
....
155+
#cloud-config
156+
users:
157+
- default
158+
- name: foobar
159+
gecos: User N. Ame
160+
groups: users
161+
chpasswd:
162+
list: |
163+
root:password
164+
fedora:atomic
165+
foobar:foobar
166+
expire: False
167+
bootcmd:
168+
- echo New MOTD >> /etc/motd
169+
runcmd:
170+
- echo New MOTD2 >> /etc/motd
171+
....
172+
173+
* How do I add additional sudoers?
174+
175+
A user can be configured as a sudoer by adding a sudo and groups entry to the
176+
users section of the user-data file, as shown below.
177+
178+
....
179+
#cloud-config
180+
users:
181+
- default
182+
- name: foobar
183+
gecos: User D. Two
184+
sudo: ["ALL=(ALL) NOPASSWD:ALL"]
185+
groups: wheel,adm,systemd-journal
186+
ssh_pwauth: True
187+
ssh_authorized_keys:
188+
- ssh-rsa AA...vz [email protected]
189+
chpasswd:
190+
list: |
191+
root:password
192+
cloud-user:atomic
193+
foobar:foobar
194+
expire: False
195+
....
196+
197+
* How do I set up a static networking configuration?
198+
199+
Add a `network-interfaces` section to the _meta-data_ file. This section contains the
200+
usual set of networking configuration options.
201+
202+
Because of a current https://bugs.launchpad.net/cloud-init/+bug/1225922[bug] in cloud-init,
203+
static networking configurations are not automatically started.
204+
Instead the default DHCP configuration remains active. A suggested work around
205+
is to manually stop and restart the network interface via the `bootcmd` directive.
206+
207+
....
208+
network-interfaces: |
209+
iface eth0 inet static
210+
address 192.168.1.10
211+
network 192.168.1.0
212+
netmask 255.255.255.0
213+
broadcast 192.168.1.255
214+
gateway 192.168.1.254
215+
bootcmd:
216+
- ifdown eth0
217+
- ifup eth0
218+
....
219+
220+
* How do I delete cloud-user and just have root and no other users?
221+
222+
To have only a root user created, create an entry for root in the `users` section of
223+
the _user-data_ file. This section can be as simple as just a `name` option:
224+
225+
....
226+
users:
227+
- name: root
228+
chpasswd:
229+
list: |
230+
root:password
231+
expire: False
232+
....
233+
234+
Optionally, you can set up SSH keys for the root user as follows:
235+
236+
....
237+
users:
238+
- name: root
239+
ssh_pwauth: True
240+
ssh_authorized_keys:
241+
- ssh-rsa AA..vz [email protected]
242+
....
243+
244+
* How do I set up storage with docker-storage-setup?
245+
246+
To set up the size of the root logical volume to 6GB for example instead of the default 3GB,
247+
use the `write_files` directive in _user-data_:
248+
249+
....
250+
write_files:
251+
- path: /etc/sysconfig/docker-storage-setup
252+
permissions: 0644
253+
owner: root
254+
content: |
255+
ROOT_SIZE=6G
256+
....
257+
258+
* How do I enable the Overlay Graph Driver?
259+
260+
The Overlay Graph Driver is enabled through _docker-storage-setup_. Use the `runcmd`
261+
directive to change the STORAGE_DRIVER option to "overlay". You also need to disable
262+
SELinux:
263+
264+
....
265+
runcmd:
266+
- sed -i '/OPTIONS=/s/--selinux-enabled//' /etc/sysconfig/docker
267+
- echo "STORAGE_DRIVER=overlay" >> /etc/sysconfig/docker-storage-setup
268+
....
269+
270+
[NOTE]
271+
Note that changing the backend storage driver is a destructive operation. Furthermore,
272+
OverlayFS is not POSIX-compliant and it can be used with restrictions. For more information,
273+
see https://documentation-devel.engineering.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/7.2_Release_Notes/technology-preview-file_systems.html[RHEL 7.2 Release Notes].
274+
275+
* How do I re-run cloud-init on an instance?
276+
277+
In most situations it is not possible to re-run cloud-init to change the configuration
278+
of a virtual machine that has already been created.
279+
280+
When cloud-init is used in an environment where the Instance ID can be changed
281+
(for instance, from *Atomic0* to *Atomic1*), it is possible to re-configure an
282+
existing virtual machine *by changing the Instance ID and rebooting to re-run
283+
cloud-init*. This is not recommended practice for production environments
284+
because cloud-init is supposed to be set up to create on first boot systems
285+
that are fully and properly configured.
286+
287+
In most IAAS implementations it is not possible to change the Instance ID.
288+
If cloud-init must be re-run, the instance should be cloned in order to obtain a new Instance ID.
289+
290+
* Can I put shell scripts in bootcmd and runcmd?
291+
292+
Yes. If you use a list value for `bootcmd` or `runcmd`, each list item is run in turn
293+
using `execve`. If you use a string value, then the entire string is run as a shell
294+
script. Alternatively, if you want simply to use cloud-init to run a shell script,
295+
you can provide a shell script (complete with shebang (#!) ) instead of providing cloud-init
296+
with a '.yaml' file.
297+
298+
See this http://cloudinit.readthedocs.org/en/latest/topics/examples.html#run-commands-on-first-boot[website]
299+
for examples of how to put shell scripts in `bootcmd` and `runcmd`.

0 commit comments

Comments
 (0)