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

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:

1. Metadata
2. 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

1. Perform the following steps before cloning or customizing the guest operating system:
2. Ensure that disable_vmware_customization is set to false in the /etc/cloud/cloud.cfg file.
3. Set manage_etc_hosts: true in the /etc/cloud/cloud.cfg file.
4. Make a backup of the 99-disable-networking-config.cfg file and delete the file from /etc/cloud/cloud.cfg.d folder after backup.
5. Clone the VM or customize the guest operating system.
6. After you clone your VM or customize the guest operating system, perform the following steps:
7. 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.
8. 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.
9. 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:

1. 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.

1. 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.

2. 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

1. Create the metadata file with the following lines in the YAML format and name it meta-data:

    instance-id: iid-local01
       	local-hostname: cloudimg
   

2. Create the user data file with the following lines in YAML and name it user-data:

     #cloud-config
     hostname: testhost
     packages:
      - vim
   

3. 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 named meta-data and user-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

4. 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 the cloud-init log file:

   more /var/log/cloud-init.log
   

5. 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 the hostname and adds the vim 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 on Packages URL at the location https://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

1. Upload the Photon OS .ami image to the Amazon cloud and configure it with cloud-init. The correct virtualization type for Photon OS is hvm.

$ 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

1. Import the cloud-config data. In the following command, the --user-data-file option instructs cloud-init to import the cloud-config data in user-data.txt. The command assumes you have uploaded the user-data.txt file and created the keypair mykeypair and the security group photon-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

1. 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

1. 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 licensed as described in the Photon OS LICENSE guide. GCE and other environment-specific Packages are stored in the open using the following URL pattern: https://packages.vmware.com/photon/<release>/<revision>/gce

For example, the current GA revision of the 4.0 release would be located at the following URL: https://packages.vmware.com/photon/4.0/GA/gce/, and the 3.0 GA version would be located at: https://packages.vmware.com/photon/3.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](https://github.com/vmware/photon/blob/master/common/data/packages_minimal.json): 

```
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/docs/gcloud-compute](https://cloud.google.com/compute/docs/gcloud-compute).

### Procedure 

1. 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

1. 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>