Installation and Configuration Guide

The installation configuration options are set with a pair of cloud-init configuration files:

For additional information about these files, see the "Creating a cloud-init ISO File" section.

Once you have created both of the files described above, you must package them into the ISO image. This image will then be used as a virtual configuration CD on the virtual machine. To package the files into an image, use the following command:

# genisoimage -output atomic0-cidata.iso -volid cidata -joliet -rock user-data meta-data

This will create a new ISO image file named atomic0-cidata.iso.

After you unpacked the distributed qcow2 image and created a configuration image as described in the previous section, you can create the virtual machine and begin the installation process. This section will describe creating an instance using the virt-install command; it is also possible to use the virt-manager graphical interface. Both are documented in the Red Hat Enterprise Linux 7 Virtualization Deployment and Administration Guide. See also the Red Hat Enterprise Linux 7 Virtualization Getting Started Guide for introduction to virtualization on Red Hat Enterprise Linux 7.

The following command will create a new virtual machine using the qcow2 image distributed by Red Hat and the configuration image you have created earlier:

# virt-install --import --name Atomic0 --ram 4096 --vcpus 2 --disk path=/path/to/rhel-atomic-host-standard.qcow2,format=qcow2,bus=virtio --disk path=/path/to/atomic0-cidata.iso,device=cdrom --network bridge=virbr0 --graphics vnc

The two --disk-path= options specify locations of the image files and device types which should be created (a virtio device for the main image and a virtual CD drive for the configuration image). It also assigns 4 GB of RAM (--ram 4096) and 2 virtual CPUs (--vcpus 2) to the virtual machine, sets up a VNC graphical interface (--graphics vnc) and a network bridge (--network bridge=virbr0). You can change these settings to suit your needs, but you must always use both of the image files.

At this point, you can log into the Red Hat Enterprise Linux Atomic Host virtual machine using the credentials you set up in your user-data file. To access a root shell, use the sudo -i command. To connect to the virtual machine’s console from the host system, use the following command:

# virsh console Atomic0

Replace Atomic0 with the name of the virtual machine - the --name option of the virt-install command.

For information about working with your new Red Hat Enterprise Linux Atomic Host instance, see the Red Hat Enterprise Linux Atomic Host 7 Getting Started Guide.

The following section explains how to install Red Hat Enterprise Linux Atomic Host in Red Hat Enterprise Virtualization, from an .ova (Open Virtualization Appliance) source. This operation consists of a procedure in three stages. The first stage describes how to unpack the .ova file in the export storage domain of your Red Hat Enterprise Virtualization environment and how to set permissions so that Red Hat Enterprise Virtualization has ownership of the unpacked files. The second stage describes how to import the virtual machine template from the export domain into the Red Hat Enterprise Virtualization environment. The third stage describes how to create a virtual machine from the imported template.

Importing the .ova File with engine-image-uploader

This procedure explains how to use rhevnm-image-uploader to upload the virtual machine template of the Red Hat Enterprise Linux Atomic Host to the Export storage domain. Perform the following steps from within the Red Hat Enterprise Virtualization Manager environment.

Importing the Virtual Machine Template into Red Hat Enterprise Virtualization

After the .ova file has been unpacked and the virtual machine template that it contained has its permissions set so that Red Hat Enterprise Virtualization can operate on it, you must import the virtual machine template into the Red Hat Enterprise Virtualization environment through the Administration Portal user interface. When this procedure is complete, it will be possible to create virtual machines from the imported template.

Adding a cloud-init ISO to the ISO Domain

[a computer that is not the RHEV Manager]# scp atomic-cloud.iso root@rhevm.hostname.com:/

[a computer that is not the RHEV Manager]# ssh root@rhevm.hostname.com

[RHEVM]# cd /

[RHEVM]# rhevm-iso-uploader --iso-domain=domain_name upload atomic-cloud.iso

Creating a Virtual Machine from the Imported Template

Now that your Red Hat Enterprise Linux Atomic Host virtual machine template has been unpacked and imported to your Red Hat Enterprise Virtualization environment and your cloud-init ISO file is present in the Red Hat Enterprise Virtualization ISO domain, you can create Red Hat Enterprise Linux Atomic Host virtual machines using the following procedure.

Updating the RHEV Guest Agent in the Atomic Host VM

To allow the RHEV Manager to control an Atomic Host VM, a guest agent must be running on that VM. The ovirt-guest-agent interfaces with the RHEV Manager to supply run-time data and heart beat information, as well as allowing the RHEV Manager to control the operation of the VM (including shutdown and restart).

The latest Atomic Host ova image for RHEV includes the ovirt-guest-agent in the form of a container named rhevm-guest-agent. When you created a virtual machine from the imported ova image (as described previously), the rhevm-guest-agent container image included in the VM is automatically set to run when the VM starts up.

You can check the status of the rhevm-guest-agent container (and update the container if needed) by logging into the Atomic Host VM on the RHEV environment and running the following commands:

# runc list
ID                PID  STATUS  BUNDLE                                           CREATED
rhevm-guest-agent 674  running /var/lib/containers/atomic/rhevm-guest-agent.0   2017-06-...

# systemctl status rhevm-guest-agent
● rhevm-guest-agent.service - oVirt Guest Agent Container
   Loaded: loaded (/etc/systemd/system/rhevm-guest-agent.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2017-06-19 19:06:58 UTC; 1 weeks 0 days ago
 Main PID: 644 (runc)
   Memory: 5.8M
   CGroup: /system.slice/rhevm-guest-agent.service
           └─644 /bin/runc --systemd-cgroup run rhevm-guest-agent

# atomic containers update rhevm-guest-agent
Latest version already installed.

Uploading ISO

For more information on uploading ISO files to ISO domains in Red Hat Enterprise Virtualization, see the Red Hat Enterprise Virtualization Installation Guide.

Creating a Red Hat Enterprise Linux Atomic Virtual Machine

The steps for running a Red Hat Enterprise Linux Atomic Host on a VMware vSphere client include the following:

Add image to the Datastore

Deploy OVF template

Attach ISO image as a CD/DVD to Virtual Machine

Run the Red Hat Enterprise Linux Atomic Host virtual machine

If you configured Red Hat Enterprise Linux Atomic Host as described here, you should be able to log into the virtual machine with the user name cloud-user and password atomic that you defined when you created the cloud-init ISO.

Creating a Project and Setting Up Billing

Perform the following steps to create a project and set up billing for Google Compute Engine:

Downloading and Setting Up GCE tools

To manage your Google Compute Engine resources, first download and install the gcloud command-line tool:

Authenticating to GCE

Authenticate to the Google Cloud platform by running:

$ gcloud auth login

The above command launches a web browser with a sign-up dialog for your Google account. Sign in to proceed. During the sign-in process you will need to allow Google Compute Engine to access some information about your Google Account. It is possible to authenticate without launching the browser by using the --no-launch-browser option, see https://cloud.google.com/compute/docs/gcloud-compute/#auth for details.

Setting Up Project Defaults

Using the command template, gcloud config set default default_value it is possible to set project defaults so that command options for commonly used flags do not have to be passed to every command. To list the current defaults execute the gcloud config list command. The template, gcloud config unset default will remove a project default. Execute the following command to set the default project:

$ gcloud config set project project_id

Where project_id stands for the id of the project you created in Creating a Project and Setting Up Billing.

Execute the following command to set the default zone:

$ gcloud config set compute/zone zone

Where zone determines a geographical location where your instance should live. See https://developers.google.com/compute/docs/zones#available for a list of available zones.

Before the Red Hat Enterprise Linux Atomic Host image can be used in GCE, it needs to be transformed from a qcow2 file into a RAW image. This is done by downloading the qcow2 file and then transforming it into a tar file. This file is uploaded to GCE and then an instance is created.

Creating a Red Hat Enterprise Linux Atomic Host RAW File

Perform the following steps to create a RAW file that can be uploaded to GCE.

$ xz -d rhel-atomic-cloud-7.1-0.x86_64.qcow2.xz

$ qemu-img convert -S 4096 -f qcow2 -O raw rhel-atomic-cloud-7.1-0.x86_64.qcow2 disk.raw

$ tar -Szcf rhel-atomic-cloud-7.1-0.x86_64.tar.gz disk.raw

$ gsutil mb gs://bucketname

$ gsutil cp rhel-atomic-cloud-7.1-0.x86_64.tar.gz gs://bucketname

$ gcloud compute images create GCE_IMAGE_NAME --source-uri gs://bucketname/rhel-atomic-cloud-7.1-0.x86_64.tar.gz

Creating a Red Hat Enterprise Linux Atomic Host Instance

Execute the following command to create an Atomic Host Instance:

$ gcloud compute instances create my-atomic-instance --machine-type n1-standard-1 --image GCE_IMAGE_NAME --metadata-from-file startup-script=<your-statup-script>

where:

my-atomic-instance is a name of an instance for this example. Instance names can contain only lowercase letters, digits, and dashes (except the last character, which cannot be a dash).

--machine-type sets your desired machine types. A machine type determines the memory, number of virtual cores, and persistent disk limits that your instance will have. Refer to https://developers.google.com/compute/docs/machine-types for details.

--image sets the image to be used. An image contains the operating system and root file system that is necessary for starting an instance. GCE automatically creates a root persistent disk to store the root file system. The GCE_IMAGE_NAME is the image you created in the previous step.

--metadata-from-file specifies the metadata to be made available in the instance environment through the local metadata server. Use this flag to specify a script to be executed automatically when the Red Hat Enterprise Linux Atomic Host instance launches for the first time. See “Executing a Custom Script on Instance Creation” section for more information. Note that the user-data key is required and cannot be replaced with a custom key, since the startup scripts for Red Hat Enterprise Linux Atomic Host instance are processed by the cloud-init utility and not by the GCE agent.

Executing a Custom Script on Instance Creation

As mentioned above, you can use the --metadata-from-file option when creating the instance to a specify custom script to be executed in that instance on its first start. You can run any system commands necessary from this script, as these commands are executed with root permissions. For example:

--metadata-from-file startup-script=<your-startup-script>

Invokes the startup.sh script with the following content:

#! /bin/sh
touch newfile

This line creates a new file called newfile.

As an alternative to locally-stored startup script, you can upload your script to Google Cloud Storage and then access it with the --metadata option. This is required if your script exceeds the metadata value length limit of 32,768 bytes. See http://developers.google.com/compute/docs/howtos/startupscript#googlecloudstorage for more details.

The gcloud tool has a built-in ssh command that enables you to log into an instance using the instance name.

To log into your instance, execute the following command:

$ gcloud compute ssh cloud-user@my-atomic-instance

Here, cloud-user is the default user name. If you have not yet created an SSH key, you will be prompted to create one. Further information is available in Password Protecting Your SSH Keys.

+

Agent admitted failure to sign using the key

+ when trying to connect to the GCE instance trough SSH. This is caused by the GNOME keyring management that tries to use a wrong SSH key. It is specific to the rhel-atomic-host-20141111 image for the GCE environment.

+ To work around this problem, enter the following command before executing gcutil:

+

$ ssh-add ~/.ssh/google_compute_engine

Once you have logged in, you can work as you would on other Red Hat Enterprise Linux machines. You have root permissions on your instance and full control over everything. To become root, execute:

cloud-user@my-atomic-instance$ sudo -i

If you need to log out of your instance, you can execute the following command:

cloud-user@my-atomic-instance$ exit

Once you have installed Red Hat Enterprise Linux Atomic Host, it is ready to run Linux containers.

Password Protecting Your SSH Keys

The first time you log into an instance with SSH, gcloud creates an ssh public/private key pair on your local machine, and copies the public key to your project. These keys are needed to log into your instance using ssh. When creating these keys for the first time, gcutil will ask you to enter and confirm a passphrase:

WARNING: You don't have an ssh key for Google Compute Engine. Creating one now...
Enter passphrase (empty for no passphrase):

Although you can leave the passphrase empty, we highly recommend entering a passphrase to protect your SSH keys. You will rarely be asked to enter your passphrase, and if you do not password protect these keys, a malicious user could use them to access your instances as you.

The Google Cloud SDK provides several ways to monitor parameters of your instances. To view general information about the current gcloud environment, run:

$ gcloud info

Execute the describe command to find detailed information about a specific instance:

$ gcloud compute instances describe my-atomic-instance
canIpForward: false
creationTimestamp: '2014-11-11T02:15:58.372-08:00'
disks:
- autoDelete: true
  boot: true
  deviceName: persistent-disk-0
  index: 0
  interface: SCSI
  kind: compute#attachedDisk
  mode: READ_WRITE
  source: https://www.googleapis.com/compute/v1/projects/eighth-saga-761/zones/europe-west1-b/disks/my-atomic-instance2
  type: PERSISTENT
id: '6632858316955862880'
kind: compute#instance
machineType: https://www.googleapis.com/compute/v1/projects/eighth-saga-761/zones/europe-west1-b/machineTypes/n1-standard-1
metadata:
  fingerprint: owFsCDPRlkY=
  kind: compute#metadata
name: my-atomic-instance2
networkInterfaces:
- accessConfigs:
  - kind: compute#accessConfig
	name: external-nat
	natIP: 23.251.142.75
	type: ONE_TO_ONE_NAT
  name: nic0
  network: https://www.googleapis.com/compute/v1/projects/eighth-saga-761/global/networks/default
  networkIP: 10.240.184.150
scheduling:
  automaticRestart: true
  onHostMaintenance: MIGRATE
selfLink: https://www.googleapis.com/compute/v1/projects/eighth-saga-761/zones/europe-west1-b/instances/my-atomic-instance2
serviceAccounts:
- email: 464767924601-compute@developer.gserviceaccount.com
  scopes:
  - https://www.googleapis.com/auth/devstorage.read_only
status: RUNNING
tags:
  fingerprint: 42WmSpB8rSM=
zone: https://www.googleapis.com/compute/v1/projects/eighth-saga-761/zones/europe-west1-b

To get data from the serial port of your Red Hat Enterprise Linux Atomic Host instance, run:

$ gcloud compute instances get-serial-port-output my-atomic-instance

This command returns the output of the GCE instance’s serial port. With this command, you get information about the instance without logging into it, which is useful for diagnostic purposes.

Finding the External IP Address of an Instance

By default, your instance is assigned a new ephemeral external IP address. You can to find this address along with other information in the output of gcutil getinstance shown above. Alternatively, you can enter the following command to get addresses of all your instances:

$ gcloud compute instances list
NAME                ZONE           MACHINE_TYPE  INTERNAL_IP    EXTERNAL_IP   STATUS
my-atomic-instance  us-central1-a  n1-standard-1 10.240.184.150 23.251.142.75 RUNNING

By default, Google Compute Engine blocks all connections to and from an instance to the Internet. To open ports for services like httpd, you must manually create a firewall rule. Every project comes with three default firewalls:

For example, to permit HTTP requests to your instance, create a new firewall using the following gcutil command:

$ gcloud compute firewall-rules create http-allow --allow tcp:80

By executing the above command, you have:

To review information about your firewall, run:

$ gcloud compute firewall-rules list
NAME                   NETWORK SRC_RANGES    RULES                        SRC_TAGS TARGET_TAGS
default-allow-icmp     default 0.0.0.0/0     icmp
default-allow-internal default 10.240.0.0/16 tcp:1-65535,udp:1-65535,icmp
default-allow-rdp      default 0.0.0.0/0     tcp:3389
default-allow-ssh      default 0.0.0.0/0     tcp:22
http-allow             default 0.0.0.0/0     tcp:80

It is possible to restrict the sources and targets to specific callers and instances using appropriate addfirewall flags. To see a complete list of supported flags, run the command gcutil help addfirewall, or see https://cloud.google.com/sdk/gcloud/reference/compute/firewall-rules/.

Firewalls only regulate incoming traffic to an instance; they cannot block outgoing packets. Once a connection has been established with an instance, traffic is permitted in both directions over that connection. To prevent an instance from sending outgoing packets, use another technology such as iptables.

Execute the following command to remove my-atomic-instance:

$ gcloud compute instances delete my-atomic-instance

You are prompted to confirm your decision before the instance is deleted. Deleting the instance may take several seconds time. As a part of the deletion confirmation dialog, gcloud informs you that disks will be deleted unless also used by another instance.