openstack/openstack-manuals
Code Issues Proposed changes
bf0d3f65d7
openstack-manuals/doc/common/section_user-data.xml
Matt Ray 8837bbf75e Updates for Chef 12 and Chef.io TLD 
New key and apt repo for Packagecloud.io. Update URL from getchef.com to
chef.io.

Change-Id: I225590d3410524480ce12aabe8a4805ec16b005e
2015-03-03 13:31:52 -06:00

273 lines
14 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 <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>
View Git Blame Copy Permalink