unistack-org/cloudinit
4
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Update cloud-config.md to include expected file format

Browse Source 
Clarify root-level keys. Use page structure to indicate expected values.
This commit is contained in:
Alex Berg 2014-04-16 11:21:41 -05:00 committed by Alex Berg
parent 7f55876378
commit 0fb5291dd0
1 changed files with 50 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
Documentation/cloud-config.md
View File

@ -1,20 +1,49 @@
# Customize with Cloud-Config # Functionality Overview
CoreOS allows you to configure networking, create users, launch systemd units on startup and more. We've designed our implementation to allow the same cloud-config file to work across all of our supported platforms. CoreOS supports customization of its initialization procedure by specifying values to use when initializing various OS-level items. Such items include network configuration, user accounts, and systemd units to launch on startup. This document defines the full list of initialization items we can configure. The `coreos-cloudinit` program uses these files as it configures the OS after startup or during runtime.
Only a subset of [cloud-config functionality][cloud-config] is implemented. A set of custom parameters were added to the cloud-config format that are specific to CoreOS. An example file containing all available options can be found at the bottom of this page. # Configuration File
The file used by this system initialization program is called a "cloud-config" file, and it aims to implement all of the parameters of the [cloud-init][cloud-init] project's [cloud-config][cloud-config] file, which is "the defacto multi-distribution package that handles early initialization of a cloud instance" ([cloud-init docs][cloud-init-docs]). Currently, however, only a subset of that file's configuration items are implemented.
In addition to the configuration items in the cloud-init project's cloud-config file, we added a few additional items which are specific to CoreOS. These CoreOS-specific items include etcd configuration, OEM definition, and systemd units to launch on startup.
We've designed our implementation to allow the same cloud-config file to work across all of our supported platforms.
[cloud-init]: https://launchpad.net/cloud-init
[cloud-init-docs]: http://cloudinit.readthedocs.org/en/latest/index.html
[cloud-config]: http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data [cloud-config]: http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data
## How to Provide Cloud-Config ## File Format
The cloud-config file uses the [YAML][yaml] file format, which uses whitespace and new-lines to delimit lists, associative arrays, and values.
A cloud-config file should contain an associative array which has zero or more of the following keys:
- `coreos`
- `ssh_authorized_keys`
- `hostname`
- `users`
- `write_files`
- `manage_etc_hosts`
The expected values for these keys are defined in the rest of this document.
[yaml]: https://en.wikipedia.org/wiki/YAML
## Providing Cloud-Config with Config-Drive
CoreOS tries to conform to each platform's native method to provide user data. Each cloud provider tends to be unique, but this complexity has been abstracted by CoreOS. You can view each platform's instructions on their documentation pages. The most universal way to provide cloud-config is [via config-drive](https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/config-drive.md), which attaches a read-only device to the machine, that contains your cloud-config file. CoreOS tries to conform to each platform's native method to provide user data. Each cloud provider tends to be unique, but this complexity has been abstracted by CoreOS. You can view each platform's instructions on their documentation pages. The most universal way to provide cloud-config is [via config-drive](https://github.com/coreos/coreos-cloudinit/blob/master/Documentation/config-drive.md), which attaches a read-only device to the machine, that contains your cloud-config file.
# Configuration Options
## CoreOS Parameters ## CoreOS Parameters
### coreos.etcd ## `coreos`
The `coreos.etcd.*` options are translated to a partial systemd unit acting as an etcd configuration file. ### `etcd`
The `coreos.etcd.*` options will be translated to a partial systemd unit acting as an etcd configuration file.
We can use the templating feature of coreos-cloudinit to automate etcd configuration with the `$private_ipv4` and `$public_ipv4` fields. For example, the following cloud-config document... We can use the templating feature of coreos-cloudinit to automate etcd configuration with the `$private_ipv4` and `$public_ipv4` fields. For example, the following cloud-config document...
``` ```
@ -45,10 +74,9 @@ Note that hyphens in the coreos.etcd.* keys are mapped to underscores.
[etcd-config]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md [etcd-config]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
### coreos.oem ### `oem`
These fields are borrowed from the [os-release spec][os-release] and repurposed The `coreos.oem.*` options are the following fields, which are borrowed from the [os-release spec][os-release] and repurposed as a way for coreos-cloudinit to know about the OEM partition on this machine:
as a way for coreos-cloudinit to know about the OEM partition on this machine:
- **id**: Lowercase string identifying the OEM - **id**: Lowercase string identifying the OEM
- **name**: Human-friendly string representing the OEM - **name**: Human-friendly string representing the OEM
@ -84,9 +112,9 @@ BUG_REPORT_URL="https://github.com/coreos/coreos-overlay"
[os-release]: http://www.freedesktop.org/software/systemd/man/os-release.html [os-release]: http://www.freedesktop.org/software/systemd/man/os-release.html
### coreos.units ### `units`
Arbitrary systemd units may be provided in the `coreos.units` attribute. The `coreos.units.*` options define arbitrary systemd units to start.
`coreos.units` is a list of objects with the following fields: `coreos.units` is a list of objects with the following fields:
- **name**: String representing unit's name. Required. - **name**: String representing unit's name. Required.
@ -135,9 +163,7 @@ coreos:
command: start command: start
``` ```
## Cloud-Config Parameters ## `ssh_authorized_keys`
### ssh_authorized_keys
Provided public SSH keys will be authorized for the `core` user. Provided public SSH keys will be authorized for the `core` user.
@ -151,7 +177,7 @@ ssh_authorized_keys:
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h...
``` ```
### hostname ## `hostname`
The provided value will be used to set the system's hostname. The provided value will be used to set the system's hostname.
This is the local part of a fully-qualified domain name (i.e. `foo` in `foo.example.com`). This is the local part of a fully-qualified domain name (i.e. `foo` in `foo.example.com`).
@ -162,7 +188,7 @@ This is the local part of a fully-qualified domain name (i.e. `foo` in `foo.exam
hostname: coreos1 hostname: coreos1
``` ```
### users ## `users`
Add or modify users with the `users` directive by providing a list of user objects, each consisting of the following fields. Add or modify users with the `users` directive by providing a list of user objects, each consisting of the following fields.
Each field is optional and of type string unless otherwise noted. Each field is optional and of type string unless otherwise noted.
@ -203,7 +229,7 @@ users:
- ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h... - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0g+ZTxC7weoIJLUafOgrm+h...
``` ```
#### Generating a password hash ### Generating a password hash
If you choose to use a password instead of an SSH key, generating a safe hash is extremely important to the security of your system. Simplified hashes like md5crypt are trivial to crack on modern GPU hardware. Here are a few ways to generate secure hashes: If you choose to use a password instead of an SSH key, generating a safe hash is extremely important to the security of your system. Simplified hashes like md5crypt are trivial to crack on modern GPU hardware. Here are a few ways to generate secure hashes:
@ -223,9 +249,11 @@ perl -e 'print crypt("password","\$6\$SALT\$") . "\n"'
Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms. Using a higher number of rounds will help create more secure passwords, but given enough time, password hashes can be reversed. On most RPM based distributions there is a tool called mkpasswd available in the `expect` package, but this does not handle "rounds" nor advanced hashing algorithms.
#### Retrieving ssh authorized keys from a GitHub user ### Retrieving SSH Authorized Keys
Using the field `coreos-ssh-import-github` you can make coreos-cloudinit to add the public ssh keys from a GitHub user as authorized keys to a server. #### From a GitHub User
Using the field `coreos-ssh-import-github`, you can make coreos-cloudinit to add the public ssh keys from a GitHub user as authorized keys to a server.
``` ```
#cloud-config #cloud-config
@ -235,7 +263,7 @@ users:
coreos-ssh-import-github: elroy coreos-ssh-import-github: elroy
``` ```
#### Retrieving ssh authorized keys from an http endpoint #### From an HTTP Endpoint
coreos-cloudinit can also pull public SSH keys from any http endpoint that matches [GitHub's API response format](https://developer.github.com/v3/users/keys/#list-public-keys-for-a-user). coreos-cloudinit can also pull public SSH keys from any http endpoint that matches [GitHub's API response format](https://developer.github.com/v3/users/keys/#list-public-keys-for-a-user).
For example, if you have an installation of GitHub Enterprise, you can provide a complete url with an authentication token: For example, if you have an installation of GitHub Enterprise, you can provide a complete url with an authentication token:
@ -258,7 +286,7 @@ users:
coreos-ssh-import-url: https://example.com/public-keys coreos-ssh-import-url: https://example.com/public-keys
``` ```
### write_files ## `write_files`
Inject an arbitrary set of files to the local filesystem. Inject an arbitrary set of files to the local filesystem.
Provide a list of objects with the following attributes: Provide a list of objects with the following attributes:
@ -271,7 +299,7 @@ Provide a list of objects with the following attributes:
Explicitly not implemented is the **encoding** attribute. Explicitly not implemented is the **encoding** attribute.
The **content** field must represent exactly what should be written to disk. The **content** field must represent exactly what should be written to disk.
### manage_etc_hosts ## `manage_etc_hosts`
Have coreos-cloudinit manage your /etc/hosts file for local name resolution. Have coreos-cloudinit manage your /etc/hosts file for local name resolution.
The only supported value is "localhost" which will cause your system's hostname The only supported value is "localhost" which will cause your system's hostname