openstack/openstack-manuals
Code Issues Proposed changes
69a73be103
openstack-manuals/doc/common/section_user-data.xml
Diane Fleming 5ab33d32b3 Clean up End User Guide - sentence style headings and other edits 
Closes-Bug: #1249837

backport: none

Change-Id: Ie5068452b8596b0625e680ddd6f4eb6851e41927
author: diane fleming
2013-11-12 08:41:13 -06:00

237 lines
12 KiB
XML
Raw Blame History

<?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 Puppet or Chef 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 different
input formats for user data. Two commonly used formats are:<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></para>
</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 using a
certificate.
<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></para>
</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:<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></para>
</simplesect>
</section>
View Git Blame Copy Permalink