When you boot instances in an OpenStack cloud, you can use user data or cloud-init 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.
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.
User data is sent using the --user-data
option when calling nova boot. This
example creates a text file and sends its contents as user
data to the instance:/path/to/filename
$ echo "This is some text" > myfile.txt $ nova boot --user-data ./myfile.txt --image myimage myinstance
The instance can get user data by querying the metadata service through either the OpenStack metadata API or the EC2 compatibility API:
$ curl http://169.254.169.254/2009-04-04/user-data
This is some text
$ curl http://169.254.169.254/openstack/2012-08-10/user_data
This is some text
Note | |
---|---|
The Compute service treats user data as a blob. While the previous example uses a text file, user data can be in any format. |
For more information, see the section called “Store metadata on a configuration drive”.
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 cloud-init package does exactly this. This package is compatible with the Compute metadata service and the Compute configuration drive.
Note | |
---|---|
The cloud-init package supports multiple cloud providers. You can use the same virtual machine image in different clouds without modification. The cloud-init package is an open source project and the source code is available on Launchpad. It is maintained by Canonical, the company that runs the Ubuntu project. All Ubuntu cloud images come pre-installed with cloud-init. However, cloud-init is not designed to be Ubuntu-specific and has been successfully ported to several other platforms including Fedora. |
Even if you do not use user data to configure instance
behavior at boot time, install
cloud-init on images that you
create because this package provides useful functionality.
For example, the cloud-init package
enables you to copy the public key to an account (the
ubuntu
account by default on Ubuntu
instances, the ec2-user
by default in
Fedora instances).
If you do not have cloud-init 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.
Look at the cloud-init doc/userdata.txt file the examples directory and the Ubuntu community documentation for details about how to use cloud-init. Some basic examples are provided here.
cloud-init supports several different input formats for user data. Two commonly used formats are:
Shell scripts (starts with
#!
)Cloud config files (starts with
#cloud-config
)
Assuming you have cloud-init
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 #!
in order for
cloud-init to recognize it as a
shell script. This example shows a script that creates a
clouduser
account:
#!/bin/bash adduser --disabled-password --gecos "" clouduser
Sending a shell script as user data has a similar effect
to writing an /etc/rc.local
script:
it executes very late in the boot sequence as root.
cloud-init 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
#cloud-config
will be interpreted
by cloud-init as cloud-config
format.
This cloud-init user data example
sets the hostname and the FQDN, as well as updating
/etc/hosts
on the
instance:
#cloud-config hostname: mynode fqdn: mynode.example.com manage_etc_hosts: true
This cloud-init user data example, based on doc/examples/cloud-config-puppet.txt, would configure the instance to contact a Puppet server at puppetmaster.example.org and verify its identity using a certificate.
#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-----
This cloud-init user data example,
based on doc/examples/cloud-config/chef.txt and
intended for use in an Ubuntu image, adds the Chef apt
repository, installs Chef, connects to a Chef server at
https://chefserver.example.com:4000
,
and installs
Apache:
#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"