The minimal and full versions of Photon OS include the cloud-init service as a built-in component. Cloud-init is a set of Python scripts that initialize cloud instances of Linux machines. The cloud-init scripts configure SSH keys and run commands to customize the machine without user interaction. The commands can set the root password, create a hostname, configure networking, write files to disk, upgrade packages, run custom scripts, and restart the system.
This the multi-page printable view of this section. Click here to print.
Cloud-Init on Photon OS
- 1: Cloud-Init Overview
- 2: Deploy Photon OS With 'cloud-init'
- 3: Customizing Guest OS using Cloud-Init
- 4: Creating a Stand-Alone Photon Machine With cloud-init
- 5: Customizing a Photon OS Machine on EC2
- 6: Running a Photon OS Machine on GCE
1 - Cloud-Init Overview
cloud-init
is a multi-distribution package that handles early initialization of a cloud instance.
In-depth documentation for cloud-init is available here:
https://cloudinit.readthedocs.org/en/latest/
Supported installations
Both the full version of and the minimal version of Photon OS support cloud-init.
Supported capabilities
Photon OS supports the following cloud-init capabilities:
- run commands: execute a list of commands with output to console.
- configure ssh keys: add an entry to ~/.ssh/authorized_keys for the configured user.
- install package: install additional packages on first boot.
- configure networking: update /etc/hosts, hostname, etc.
- write files: write arbitrary files to disk.
- add yum repository: add a yum repository to /etc/yum.repos.d.
- create groups and users: add groups and users to the system and set properties for them.
- run yum upgrade: upgrade all packages.
- reboot: reboot or power off when done with cloud-init.
Getting Started
The Amazon Machine Image of Photon OS has an ec2 datasource
turned on by default so an ec2
configuration is accepted.
However, for testing, the following methods provide ways to do cloud-init
with a standalone instance of Photon OS.
Using a Seed ISO
This will be using the nocloud
data source. In order to initialize the system in this way, an ISO file needs to be created with a meta-data file and an user-data file as shown below:
$ { echo instance-id: iid-local01; echo local-hostname: cloudimg; } > meta-data
$ printf "#cloud-config\nhostname: testhost\n" > user-data
$ genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data
Attach the seed.iso
generated above to your machine and reboot for the init to take effect.
In this case, the hostname is set to testhost
.
Using a Seed Disk File
To init using local disk files, do the following:
mkdir /var/lib/cloud/seed/nocloud
cd /var/lib/cloud/seed/nocloud
$ { echo instance-id: iid-local01; echo local-hostname: cloudimg; } > meta-data
$ printf "#cloud-config\nhostname: testhost\n" > user-data
Reboot the machine and the hostname will be set to testhost
.
Frequencies
Cloud-init modules have predetermined frequencies. Based on the frequency setting, multiple runs will yield different results. For the scripts to always run, remove the instances
directory before rebooting.
rm -rf /var/lib/cloud/instances
Module Frequency Info
Name | Frequency |
---|---|
disable_ec2_metadata | Always |
users_groups | Instance |
write_files | Instance |
update_hostname | Always |
final_message | Always |
resolv_conf | Instance |
growpart | Always |
update_etc_hosts | Always |
power_state_change | Instance |
phone_home | Instance |
2 - Deploy Photon OS With 'cloud-init'
You can deploy Photon OS with cloud-init
in the following ways:
- As a stand-alone Photon machine
- In Amazon Elastic Compute Cloud, called EC2
- In the Google cloud through the Google Compute Engine, or GCE
- In a VMware Vsphere private cloud
When a cloud instance of Photon OS starts, cloud-init
requires a data source. The data source can be an EC2 file for Amazon’s cloud platform, a seed.iso
file for a stand-alone instance of Photon OS, or the internal capabilities of a system for managing virtual machines, such as VMware vSphere or vCenter. Cloud-init also includes data sources for OpenStack, Apache CloudStack, and OVF. The data source comprises two parts:
- Metadata
- User data
The metadata gives the cloud service provider instructions on how to implement the Photon OS machine in the cloud infrastructure. Metadata typically includes the instance ID and the local host name.
The user data contains the commands and scripts that Photon OS executes when it starts in the cloud. The user data commonly takes the form of a shell script or a YAML file containing a cloud configuration. The cloud-init overview and cloud-init documentation contains information about the types of data sources and the formats for metadata and user data.
On Photon OS, cloud-init
is enabled and running by default. You can use the following command to check the status:
systemctl status cloud-init
The Photon OS directory that contains the local data and other resources for cloud-init is /var/lib/cloud
.
Photon OS stores the logs for cloud-init in the /var/log/cloud-init.log
file.
The following sections demonstrate how to use cloud-init to customize a stand-alone Photon OS machine, instantiate a Photon OS machine in the Amazon EC2 cloud, and deploy a virtual machine running Photon OS in vSphere. Each section uses a different combination of the available options for the metadata and the user data that make up the data source. Specifications, additional options, and examples appear in the cloud-init documentation.
3 - Customizing Guest OS using Cloud-Init
A guest operating system is an operating system that runs inside a virtual machine. You can install a guest operating system in a virtual machine and control guest operating system customization for virtual machines created from vApp templates.
When you customize your guest OS you can set up a virtual machine with the operating system that you want.
Procedure
- Perform the following steps before cloning or customizing the guest operating system:
- Ensure that
disable_vmware_customization
is set to false in the/etc/cloud/cloud.cfg
file. - Set
manage_etc_hosts: true
in the/etc/cloud/cloud.cfg
file. - Make a backup of the
99-disable-networking-config.cfg
file and delete the file from/etc/cloud/cloud.cfg.d
folder after backup. - Clone the VM or customize the guest operating system.
- After you clone your VM or customize the guest operating system, perform the following steps:
- Ensure that
disable_vmware_customization
is set to true in the/etc/cloud/cloud.cfg
file in the newly created VM and the VM from where cloning was initiated. - Remove
manage_etc_hosts: true
from the/etc/cloud/cloud.cfg
file in the newly created VM and the VM from where cloning was initiated. - Add a copy of the backed up file
99-disable-networking-config.cfg
to its original folder/etc/cloud/cloud.cfg.d
in the newly created VM and the VM from where cloning was initiated.
Note:
- The
disable_vmware_customization
flag in/etc/cloud/cloud.cfg.d
file decides which customization workflow to be initiated.
- Setting this to false invokes the Cloud-Init GOS customization workflow.
- Setting this to true invokes the traditional GOSC script based customization workflow.
When the
manage_etc_hosts
flag is set to true, Cloud-Init can edit the/etc/hosts
file with the updated values.When the flag is set to true Cloud-Init edits the
/etc/hosts
file, even when there is no cloud config metadata available. Remove this entry once the Cloud-Init GOS customization is done, to stop Cloud-Init from editing/etc/hosts
file and set a fallback configuration.The
99-disable-networking-config.cfg
file is packaged as part of Cloud-Init RPM in photon and it prevents Cloud-Init from configuring the network. Delete this file before starting the Cloud-Init customization and then paste the backup of the file in the/etc/cloud/cloud.cfg.d/
folder once the cloud-init workflow is complete. It is important to replace this file after Cloud-Init customization to avoid removal of network configuration in the Cloud-Init instance.
Result
Cloud-Init guest OS customization is now enabled.
4 - Creating a Stand-Alone Photon Machine With cloud-init
Cloud-init can customize a Photon OS virtual machine by using the nocloud
data source. The nocloud
data source bundles the cloud-init
metadata and user data into an ISO that acts as a seed when you boot the machine. The seed.iso
delivers the metadata and the user data without requiring a network connection.
Procedure
Create the metadata file with the following lines in the YAML format and name it
meta-data
:instance-id: iid-local01 local-hostname: cloudimg
Create the user data file with the following lines in YAML and name it
user-data
:#cloud-config hostname: testhost packages: - vim
Generate the ISO that will serve as the seed. The ISO must have the volume ID set to
cidata
. In the following example, the ISO is generated on an Ubuntu 14.04 computer containing the files namedmeta-data
anduser-data
in the local directory:genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data
The ISO now appears in the current directory:
steve@ubuntu:~$ ls meta-data seed.iso user-data
Optionally, check the ISO that you generated on Ubuntu by transferring the ISO to the root directory of your Photon OS machine and then running the following command:
cloud-init --file seed.iso --debug init
After running the
cloud-init
command above, check thecloud-init
log file:more /var/log/cloud-init.log
Attach the ISO to the Photon OS virtual machine as a CD-ROM and reboot it so that the changes specified by seed.iso take effect. In this case,
cloud-init
sets thehostname
and adds thevim
package.
5 - Customizing a Photon OS Machine on EC2
You can upload an ami
image of Photon OS to Amazon Elastic Compute Cloud (EC2) and customize the Photon OS machine by using cloud-init
with an EC2 data source. The Amazon machine image version of Photon OS is available as a free download at the location packages.vmware.com/photon.
The cloud-init
service is commonly used on EC2 to configure the cloud instance of a Linux image. On EC2, cloud-init
sets the .ssh/authorized_keys
file to let you log in with a private key from another computer, that is, a computer besides the workstation that you are already using to connect with the Amazon cloud.
Example
The cloud-config user-data file that appears in the following example contains abridged SSH authorized keys to show you how to set them.
Prerequisites
- To work with EC2, obtain Amazon accounts for both AWS and EC2 with valid payment information. If you execute the below examples, you will be charged by Amazon. You must replace the
<placeholders>
for access keys and other account information in the examples with your account information. - Install and set up the Amazon AWS CLI and the EC2 CLI tools, including
ec2-ami-tools
. For more information, see Installing the AWS Command Line Interface, Setting Up the Amazon EC2 Command Line Interface Tools on Linux and Setting Up the AMI Tools. - Create SSH keys and an RSA user signing certificate and its corresponding private RSA key file.
Procedure
- Upload the Photon OS
.ami
image to the Amazon cloud and configure it with cloud-init. The correct virtualization type for Photon OS ishvm
.
$ mkdir bundled
$ tar -zxvf ./photon-ami.tar.gz
$ ec2-bundle-image -c ec2-certificate.pem -k ec2-privatekey.pem -u <EC2 account id> --arch x86_64 --image photon-ami.raw --destination ./bundled/
$ aws s3 mb s3://<bucket-name>
$ ec2-upload-bundle --manifest ./bundled/photon-ami.manifest.xml --bucket <bucket-name> --access-key <Account Access Key> --secret-key <Account Secret key>
$ ec2-register <bucket-name>/photon-ami.manifest.xml --name photon-ami --architecture x86_64 --virtualization-type hvm
- Import the cloud-config data. In the following command, the
--user-data-file
option instructs cloud-init to import the cloud-config data inuser-data.txt
. The command assumes you have uploaded theuser-data.txt file
and created the keypairmykeypair
and the security groupphoton-sg
.
$ ec2-run-instances <ami-ID> --instance-type m3.medium -g photon-sg --key mykeypair --user-data-file user-data.txt
Describe the instance to see its ID:
$ ec2-describe-instances
- Run the following command to obtain its public IP address, which you can use to connect to the instance with SSH:
$ aws ec2 describe-instances --instance-ids <instance-id> --query 'Reservations[*].Instances[*].PublicIpAddress' --output=text
$ ec2-describe-images
- Run the following commands to terminate the machine. It is important to shut down the machine because Amazon charges you while the host is running down.
$ ec2-deregister <ami-image-identifier>
$ ec2-terminate-instances <instance-id>
Result
The following are the contents of the user-data.txt
file that cloud-init
applies to the machine the first time that it boots up in the cloud:
#cloud-config
hostname: photon-on-01
groups:
- cloud-admins
- cloud-users
users:
- default
- name: photonadmin
gecos: photon test admin user
primary-group: cloud-admins
groups: cloud-users
lock-passwd: false
passwd: vmware
- name: photonuser
gecos: photon test user
primary-group: cloud-users
groups: users
passwd: vmware
packages:
- vim
ssh_authorized_keys:
- ssh-rsa MIIEogIBAAKCAQEAuvHKAjBhpwuomcUTpIzJWRJAe71JyBgAWrwqyN1Mk5N+c9X5
Ru2fazFA7WxQSD1KyTEvcuf8JzdBfrEJ0v3/nT2x63pvJ8fCl6HRkZtHo8zRu8vY
KYTZS/sdvM/ruubHfq1ldRpgtYSqbkykoe6PCQIDAQABAoIBAEgveQtjVzHDhLTr
rmwJmO316ERfkQ/chLaElhi9qwYJG/jqlNIISWFyztqD1b3fxU6m5MOBIujh7Xpg
... ec3test@example.com
You can view the cloud-init output log file on EC2 at /var/log/cloud-init-output.log
.
For more information on using cloud-init user data on EC2, see Running Commands on Your Linux Instance at Launch.
For more information on how to get Photon OS up and running on EC2 and run a containerized application in the Docker engine, see Running Photon OS on Amazon Elastic Cloud Compute.
With Photon OS, you can also build cloud images on Google Compute Engine and other cloud providers. For more information, see Compatible Cloud Images.
6 - Running a Photon OS Machine on GCE
Photon OS comes in a preconfigured image ready for Google Cloud Engine.
Example
The example in this section shows how to create a Photon OS instance on Google Cloud Engine with and without cloud-init user data.
Prerequisites
You must have set up a GCE account and are ready to pay Google for its cloud services. The GCE-ready version of Photon OS is a free image and is free. You can download Photon OS for GCE from https://packages.vmware.com/photon/4.0/GA/gce/.
The GCE-ready image of Photon OS contains packages and scripts that prepare it for the Google cloud to save you time as you implement a compute cluster or develop cloud applications. The GCE-ready version of Photon OS adds the following packages to the packages installed with the minimal version:
sudo, tar, which, google-daemon, google-startup-scripts, kubernetes, perl-DBD-SQLite, perl-DBIx-Simple, perl, ntp
Verify that you have the
gcloud command-line tool
. For more information see, https://cloud.google.com/compute./gcloud-compute.
Procedure
Use the following commands to create an instance of Photon OS from the Photon GCE image without using cloud-init. In the commands, you must replace
<bucket-name>
with the name of your bucket and the path to the Photon GCE tar file.$ gcloud compute instances list $ gcloud compute images list $ gcloud config list $ gsutil mb gs://<bucket-name> $ gsutil cp <path-to-photon-gce-image.tar.gz> gs://<bucket-name>/photon-gce.tar.gz $ gcloud compute images create photon-gce-image --source-uri gs://<bucket-name>/photon-gce.tar.gz $ gcloud compute instances create photon-gce-vm --machine-type "n1-standard-1" --image photon-gce-image $ gcloud compute instances describe photon-gce-vm
To create a new instance of a Photon OS machine and configure it with a cloud-init user data file, replace the
gcloud compute instances create
command in the example above with the following command. Before running this command, you must upload your user-data file to Google’s cloud infrastructure and replace<path-to-userdata-file>
with its path and file name.gcloud compute instances create photon-gce-vm --machine-type "n1-standard-1" --image photon-gce-vm --metadata-from-file=user-data=<path-to-userdata-file>
You can also add a cloud-init user-data file to an existing instance of a Photon OS machine on GCE:
gcloud compute instances add-metadata photon-gce-vm --metadata-from-file=user-data=<path-to-userdata-file>