239 lines
12 KiB
XML
239 lines
12 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="http://getchef.com">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:4000</literal>,
|
|
and installs Apache:</para>
|
|
<programlisting>#cloud-config
|
|
apt_sources:
|
|
- source: "deb http://apt.opscode.com/ $RELEASE-0.10 main"
|
|
key: |
|
|
-----BEGIN PGP PUBLIC KEY BLOCK-----
|
|
Version: GnuPG v1.4.9 (GNU/Linux)
|
|
|
|
mQGiBEppC7QRBADfsOkZU6KZK+YmKw4wev5mjKJEkVGlus+NxW8wItX5sGa6kdUu
|
|
twAyj7Yr92rF+ICFEP3gGU6+lGo0Nve7KxkN/1W7/m3G4zuk+ccIKmjp8KS3qn99
|
|
dxy64vcji9jIllVa+XXOGIp0G8GEaj7mbkixL/bMeGfdMlv8Gf2XPpp9vwCgn/GC
|
|
JKacfnw7MpLKUHOYSlb//JsEAJqao3ViNfav83jJKEkD8cf59Y8xKia5OpZqTK5W
|
|
ShVnNWS3U5IVQk10ZDH97Qn/YrK387H4CyhLE9mxPXs/ul18ioiaars/q2MEKU2I
|
|
XKfV21eMLO9LYd6Ny/Kqj8o5WQK2J6+NAhSwvthZcIEphcFignIuobP+B5wNFQpe
|
|
DbKfA/0WvN2OwFeWRcmmd3Hz7nHTpcnSF+4QX6yHRF/5BgxkG6IqBIACQbzPn6Hm
|
|
sMtm/SVf11izmDqSsQptCrOZILfLX/mE+YOl+CwWSHhl+YsFts1WOuh1EhQD26aO
|
|
Z84HuHV5HFRWjDLw9LriltBVQcXbpfSrRP5bdr7Wh8vhqJTPjrQnT3BzY29kZSBQ
|
|
YWNrYWdlcyA8cGFja2FnZXNAb3BzY29kZS5jb20+iGAEExECACAFAkppC7QCGwMG
|
|
CwkIBwMCBBUCCAMEFgIDAQIeAQIXgAAKCRApQKupg++Caj8sAKCOXmdG36gWji/K
|
|
+o+XtBfvdMnFYQCfTCEWxRy2BnzLoBBFCjDSK6sJqCu5Ag0ESmkLtBAIAIO2SwlR
|
|
lU5i6gTOp42RHWW7/pmW78CwUqJnYqnXROrt3h9F9xrsGkH0Fh1FRtsnncgzIhvh
|
|
DLQnRHnkXm0ws0jV0PF74ttoUT6BLAUsFi2SPP1zYNJ9H9fhhK/pjijtAcQwdgxu
|
|
wwNJ5xCEscBZCjhSRXm0d30bK1o49Cow8ZIbHtnXVP41c9QWOzX/LaGZsKQZnaMx
|
|
EzDk8dyyctR2f03vRSVyTFGgdpUcpbr9eTFVgikCa6ODEBv+0BnCH6yGTXwBid9g
|
|
w0o1e/2DviKUWCC+AlAUOubLmOIGFBuI4UR+rux9affbHcLIOTiKQXv79lW3P7W8
|
|
AAfniSQKfPWXrrcAAwUH/2XBqD4Uxhbs25HDUUiM/m6Gnlj6EsStg8n0nMggLhuN
|
|
QmPfoNByMPUqvA7sULyfr6xCYzbzRNxABHSpf85FzGQ29RF4xsA4vOOU8RDIYQ9X
|
|
Q8NqqR6pydprRFqWe47hsAN7BoYuhWqTtOLSBmnAnzTR5pURoqcquWYiiEavZixJ
|
|
3ZRAq/HMGioJEtMFrvsZjGXuzef7f0ytfR1zYeLVWnL9Bd32CueBlI7dhYwkFe+V
|
|
Ep5jWOCj02C1wHcwt+uIRDJV6TdtbIiBYAdOMPk15+VBdweBXwMuYXr76+A7VeDL
|
|
zIhi7tKFo6WiwjKZq0dzctsJJjtIfr4K4vbiD9Ojg1iISQQYEQIACQUCSmkLtAIb
|
|
DAAKCRApQKupg++CauISAJ9CxYPOKhOxalBnVTLeNUkAHGg2gACeIsbobtaD4ZHG
|
|
0GLl8EkfA8uhluM=
|
|
=zKAm
|
|
-----END PGP PUBLIC KEY BLOCK-----
|
|
|
|
chef:
|
|
install_type: "packages"
|
|
server_url: "https://chefserver.example.com:4000"
|
|
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>
|