273 lines
14 KiB
XML
273 lines
14 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:id="user-data">
|
|
<title>Configure instances at boot</title>
|
|
<para>When you boot instances in an OpenStack cloud, you can use
|
|
user data or <package>cloud-init</package> to automatically
|
|
configure instances at boot time. You might want to install
|
|
some packages, start services, or manage your instance by
|
|
using a <link xlink:href="http://puppetlabs.com/puppet/puppet-open-source">Puppet</link> or <link xlink:href="https://www.chef.io/openstack">Chef</link> server.</para>
|
|
<simplesect>
|
|
<title>User data</title>
|
|
<para>User data is the mechanism by which a user can pass
|
|
information contained in a local file to an instance at
|
|
launch time. The typical use case is to pass something
|
|
like a shell script or a configuration file as user
|
|
data.</para>
|
|
<para>User data is sent using the <literal>--user-data
|
|
<replaceable>/path/to/filename</replaceable></literal>
|
|
option when calling <command>nova boot</command>. This
|
|
example creates a text file and sends its contents as user
|
|
data to the instance:</para>
|
|
<screen><prompt>$</prompt> <userinput>echo "This is some text" > myfile.txt</userinput>
|
|
<prompt>$</prompt> <userinput>nova boot --user-data ./myfile.txt --image myimage myinstance</userinput></screen>
|
|
<para>The instance can get user data by querying the metadata
|
|
service through either the OpenStack metadata API or the
|
|
EC2 compatibility API:</para>
|
|
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/user-data</userinput></screen>
|
|
<screen><computeroutput>This is some text</computeroutput></screen>
|
|
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack/2012-08-10/user_data</userinput></screen>
|
|
<screen><computeroutput>This is some text</computeroutput></screen>
|
|
<note>
|
|
<para>The Compute service treats user data as a blob.
|
|
While the previous example uses a text file, user data
|
|
can be in any format.</para>
|
|
</note>
|
|
<para>For more information, see <xref linkend="config-drive"
|
|
/>.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title><package>cloud-init</package></title>
|
|
<para>To do something useful with the user data, you must
|
|
configure the virtual machine image to run a service on
|
|
boot that gets user data from the metadata service and
|
|
takes some action based on the contents of the data. The
|
|
<package>cloud-init</package> package does exactly
|
|
this. This package is compatible with the Compute metadata
|
|
service and the Compute configuration drive.</para>
|
|
<note>
|
|
<para>The <package>cloud-init</package> package supports
|
|
multiple cloud providers. You can use the same virtual
|
|
machine image in different clouds without
|
|
modification. The <package>cloud-init</package>
|
|
package is an open source project and the source code
|
|
is available on <link
|
|
xlink:href="http://launchpad.net/cloud-init"
|
|
>Launchpad</link>. It is maintained by Canonical,
|
|
the company that runs the Ubuntu project. All Ubuntu
|
|
cloud images come pre-installed with
|
|
<package>cloud-init</package>. However,
|
|
<package>cloud-init</package> is not designed to
|
|
be Ubuntu-specific and has been successfully ported to
|
|
several other platforms including Fedora.</para>
|
|
</note>
|
|
<para>Even if you do not use user data to configure instance
|
|
behavior at boot time, install
|
|
<package>cloud-init</package> on images that you
|
|
create because this package provides useful functionality.
|
|
For example, the <package>cloud-init</package> package
|
|
enables you to copy the public key to an account (the
|
|
<literal>ubuntu</literal> account by default on Ubuntu
|
|
instances, the <literal>ec2-user</literal> by default in
|
|
Fedora instances).</para>
|
|
<para>If you do not have <package>cloud-init</package>
|
|
installed, you must manually configure your image to get
|
|
the public key from the metadata service on boot and copy
|
|
it to the appropriate account.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title><package>cloud-init</package> supported formats and
|
|
documentation</title>
|
|
<para>Look at the <package>cloud-init</package>
|
|
<link
|
|
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/userdata.txt"
|
|
>doc/userdata.txt</link> file the <link
|
|
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/files/head:/doc/examples/"
|
|
>examples</link> directory and the <link
|
|
xlink:href="https://help.ubuntu.com/community/CloudInit"
|
|
>Ubuntu community documentation</link> for details
|
|
about how to use <package>cloud-init</package>. Some basic
|
|
examples are provided here.</para>
|
|
<para><package>cloud-init</package> supports several input
|
|
formats for user data. Two commonly used formats
|
|
are:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Shell scripts (starts with
|
|
<literal>#!</literal>)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Cloud config files (starts with
|
|
<literal>#cloud-config</literal>)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Run a shell script on boot</title>
|
|
<para>Assuming you have <package>cloud-init</package>
|
|
installed, the simplest way to configure an instance on
|
|
boot is to pass a shell script as user data. The shell
|
|
file must begin with <literal>#!</literal> in order for
|
|
<package>cloud-init</package> to recognize it as a
|
|
shell script. This example shows a script that creates a
|
|
<literal>clouduser</literal> account:</para>
|
|
<programlisting language="bash">#!/bin/bash
|
|
adduser --disabled-password --gecos "" clouduser</programlisting>
|
|
<para>Sending a shell script as user data has a similar effect
|
|
to writing an <filename>/etc/rc.local</filename> script:
|
|
it executes very late in the boot sequence as root.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Cloud-config format</title>
|
|
<para><package>cloud-init</package> supports a YAML-based
|
|
config format that allows the user to configure a large
|
|
number of options on a system. User data that begins with
|
|
<literal>#cloud-config</literal> will be interpreted
|
|
by <package>cloud-init</package> as cloud-config
|
|
format.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Example: Set the host name</title>
|
|
<para>This <package>cloud-init</package> user data example
|
|
sets the hostname and the FQDN, as well as updating
|
|
<filename>/etc/hosts</filename> on the
|
|
instance:</para>
|
|
<para>
|
|
<programlisting>#cloud-config
|
|
hostname: mynode
|
|
fqdn: mynode.example.com
|
|
manage_etc_hosts: true</programlisting>
|
|
</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Example: Configure instances with Puppet</title>
|
|
<para>This <package>cloud-init</package> user data example,
|
|
based on <link
|
|
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/examples/cloud-config-puppet.txt"
|
|
>doc/examples/cloud-config-puppet.txt</link>, would
|
|
configure the instance to contact a Puppet server at
|
|
puppetmaster.example.org and verify its identity by using
|
|
a certificate.</para>
|
|
<programlisting>#cloud-config
|
|
puppet:
|
|
conf:
|
|
agent:
|
|
server: "puppetmaster.example.org"
|
|
ca_cert: |
|
|
-----BEGIN CERTIFICATE-----
|
|
MIICCTCCAXKgAwIBAgIBATANBgkqhkiG9w0BAQUFADANMQswCQYDVQQDDAJjYTAe
|
|
Fw0xMDAyMTUxNzI5MjFaFw0xNTAyMTQxNzI5MjFaMA0xCzAJBgNVBAMMAmNhMIGf
|
|
MA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCu7Q40sm47/E1Pf+r8AYb/V/FWGPgc
|
|
b014OmNoX7dgCxTDvps/h8Vw555PdAFsW5+QhsGr31IJNI3kSYprFQcYf7A8tNWu
|
|
1MASW2CfaEiOEi9F1R3R4Qlz4ix+iNoHiUDTjazw/tZwEdxaQXQVLwgTGRwVa+aA
|
|
qbutJKi93MILLwIDAQABo3kwdzA4BglghkgBhvhCAQ0EKxYpUHVwcGV0IFJ1Ynkv
|
|
T3BlblNTTCBHZW5lcmF0ZWQgQ2VydGlmaWNhdGUwDwYDVR0TAQH/BAUwAwEB/zAd
|
|
BgNVHQ4EFgQUu4+jHB+GYE5Vxo+ol1OAhevspjAwCwYDVR0PBAQDAgEGMA0GCSqG
|
|
SIb3DQEBBQUAA4GBAH/rxlUIjwNb3n7TXJcDJ6MMHUlwjr03BDJXKb34Ulndkpaf
|
|
+GAlzPXWa7bO908M9I8RnPfvtKnteLbvgTK+h+zX1XCty+S2EQWk29i2AdoqOTxb
|
|
hppiGMp0tT5Havu4aceCXiy2crVcudj3NFciy8X66SoECemW9UYDCb9T5D0d
|
|
-----END CERTIFICATE-----</programlisting>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Example: Configure instances with Chef</title>
|
|
<para>This <package>cloud-init</package> user data example,
|
|
based on <link
|
|
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/examples/cloud-config-chef.txt"
|
|
>doc/examples/cloud-config/chef.txt</link> and
|
|
intended for use in an Ubuntu image, adds the Chef apt
|
|
repository, installs Chef, connects to a Chef server at
|
|
<literal>https://chefserver.example.com/organizations/myorg/</literal>,
|
|
and installs Apache:</para>
|
|
<programlisting>#cloud-config
|
|
apt_sources:
|
|
- source: "deb https://packagecloud.io/chef/ stable main"
|
|
key: |
|
|
-----BEGIN PGP PUBLIC KEY BLOCK-----
|
|
Version: GnuPG v1.4.9 (GNU/Linux)
|
|
|
|
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
|
|
sA==
|
|
=H60S
|
|
-----END PGP PUBLIC KEY BLOCK-----
|
|
|
|
chef:
|
|
install_type: "packages"
|
|
server_url: "https://chefserver.example.com/organizations/myorg/"
|
|
node_name: "your-node-name"
|
|
environment: "production"
|
|
validation_name: "yourorg-validator"
|
|
validation_key: |
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
YOUR-ORGS-VALIDATION-KEY-HERE
|
|
-----END RSA PRIVATE KEY-----
|
|
run_list:
|
|
- "recipe[apache2]"
|
|
- "role[db]"
|
|
initial_attributes:
|
|
apache:
|
|
prefork:
|
|
maxclients: 100
|
|
keepalive: "off"</programlisting>
|
|
</simplesect>
|
|
</section>
|