Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Getting Started Guide

Red Hat Enterprise Linux Atomic Host 7

Getting Started Guide

Red Hat Atomic Host Documentation Team

Abstract

Red Hat Getting Started Guide for RHEL Atomic Host

Chapter 1. Installing RHEL Atomic Host

1.1. Overview

Red Hat Enterprise Linux Atomic host is a variation of Red Hat Enterprise Linux 7 optimized to run Linux containers in the Docker format. It has been modified to be light-weight and efficient, making it a particularly optimal operating system to use as a docker run-time system for cloud environments.

Red Hat Enterprise Linux Atomic Host uses SELinux to provide strong safeguards in multi-tenant environments, and provides the ability to perform atomic upgrades and rollbacks, enabling quicker and easier maintenance with less downtime. Red Hat Enterprise Linux Atomic Host uses the same upstream projects delivered via the same RPM packaging as Red Hat Enterprise Linux 7.

Red Hat Enterprise Linux Atomic Host is pre-installed with the following tools to support Linux containers:

  • docker
  • Kubernetes

Red Hat Enterprise Linux Atomic Host makes use of the following technologies:

  • OSTree and rpm-OSTree - These projects provide atomic upgrades and the ability to roll back upgrades.
  • systemd - The powerful new init system for Linux systems that enables faster boot times and easier system orchestration.
  • SELinux - Enabled by default to provide complete multi-tenant security. You’ll also find Integrity Measurement Architecture (IMA), audit and libwrap available from systemd.

IMPORTANT: Red Hat Enterprise Linux Atomic Host is not managed in the same way that other Red Hat Enterprise Linux 7 variants are managed. Specifically:

  • You do not use yum to upgrade the system.
  • There are only two writable directories for local system configuration: /etc/ and /var/. The /usr/ directory is mounted read-only. Other directories are symlinks to a writable location. For example, the /home/ directory is a symlink to the /var/home/ directory.
  • The default partitioning dedicates most of the available space for the containers, using direct LVM instead of the default loopback.
  • RHEL Atomic Host provides a choice between docker and docker-latest, but Red Hat does not support running both docker and docker-latest on the same machine at the same time.

User and Host specific data should be stored only in the /var/ directory. Only configuration files in the /etc/ directory should be modified.

1.2. System Requirements

Red Hat Enterprise Linux Atomic Host should run on any computer or cloud environment that supports 64-bit Red Hat Enterprise Linux systems. The most recent list of supported hardware can be found in the Red Hat Hardware Compatibility List. Also see Red Hat Enterprise Linux technology capabilities and limits for general information about system requirements.

Keep in mind that though Atomic Host can run on bare metal, it is particularly suited for running in cloud environments where its size and efficiency as a container run-time environment are particularly useful.

1.3. Installing and Registering RHEL Atomic Host

Red Hat Enterprise Linux Atomic Host comes in several different forms. Those forms include:

  • A DVD ISO installation image you can use for traditional bare metal or VM installs by launching an installer and selecting options (disk formatting, language, network configuration, user accounts, and so on).
  • A variety of cloud and virtualization environment images that you can configure using cloud-init. These cloud images include those made to run on Red Hat Enterprise Virtualization, OpenStack, VMware, KVM, AWS, Microsoft Hyper-V and others.

All images are available from the Download RHEL Atomic Host page (the ISO images aren’t delivered with every version, so you may need to look at earlier versions). To learn about different ways of installing RHEL Atomic Host, the following document describes how to install for different environments using both cloud and traditional ISO images:

Installing RHEL Atomic Host in Virtualized Environments

Once your Atomic Host system is installed and running, you should enable software updates by registering your Red Hat Enterprise Linux Atomic Host system. This is done with the subscription-manager command as described below. If your system is located on a network that requires the use of an HTTP proxy, please see the Red Hat Knowledge Base Article on configuring subscription manager to use an HTTP proxy. The --name= option may be included if you wish to provide an easy to remember name to be used when reviewing subscription records. 

$ sudo subscription-manager register --username=<username> --auto-attach

NOTE: Red Hat Enterprise Linux Atomic Host works only with Red Hat Subscription Manager (RHSM). Red Hat Enterprise Linux Atomic Host does not work with the older RHN subscription model.

Red Hat Enterprise Linux Atomic Host registers two product IDs. The first is Product ID 271, Red Hat Enterprise Linux Atomic Host. The second is Product ID 69, Red Hat Enterprise Linux Server. They both use the same entitlement. A properly registered system will display both IDs as is shown below: 

$ sudo subscription-manager list
+-------------------------------------------+
    Installed Product Status
+-------------------------------------------+
Product Name:   Red Hat Enterprise Linux Atomic Host
Product ID:     271
Version:        7
Arch:           x86_64
Status:         Subscribed
Status Details:
Starts:         02/27/2015
Ends:           02/26/2016

Product Name:   Red Hat Enterprise Linux Server
Product ID:     69
Version:        7.1
Arch:           x86_64
Status:         Subscribed
Status Details:
Starts:         02/27/2015
Ends:           02/26/2016

The subscription-manager command is also documented in section 3.2. Registering from the Command Line of the Red Hat Subscription Management guide.

1.4. Configuring RHEL Atomic Host

Red Hat Enterprise Linux Atomic Host is configured in a manner similar to Red Hat Enterprise Linux 7, using the configuration files in the /etc/ directory. Red Hat Enterprise Linux Atomic Host is a minimal server product without a desktop. This means that the graphical configuration tools found in the GUI are not available.

1.4.1. Managing User Accounts

Currently, some system users that in Red Hat Enterprise Linux 7 would be listed in the /etc/passwd file have been relocated into the read-only /usr/lib/passwd file. Because applications on Red Hat Enterprise Linux Atomic Host are run inside of Linux containers, this will not affect deployment. The traditional user management tools, such as useradd, will write locally added users to the /etc/passwd file as expected.

1.4.2. Configuring Networking

If you did not configure networking during the installation you may configure it post-installation using the nmcli tool. The following commands create a network connection called atomic, set up a host name and then activate that connection. 

# nmcli con add type ethernet con-name atomic ifname eth0
# nmcli con modify atomic ipv4.dhcp-hostname atomic ipv6.dhcp-hostname atomic
# nmcli con up atomic

For more details on how to use the nmcli tool, see Section 2.3.2. Connecting to a Network Using nmcli in the Red Hat Enterprise Linux 7 Networking Guide.

For more information on configuring Red Hat Enterprise Linux 7, see the Red Hat Enterprise Linux 7 System Administrator’s Guide.

1.5. Upgrading and Downgrading Installations

RHEL Atomic Host uses rpm-OSTree, an open source tool, to manage bootable, immutable, versioned file system trees made of RPM content. In comparison to other variants of Red Hat Enterprise Linux 7 which use yum and have a traditional package management model, RHEL Atomic Host uses OSTree and is upgraded by preparing a new operating system root, and making it the default for the next boot.

1.5.1. Upgrading to a New Version

To perform an upgrade, execute the following commands: 

$ sudo atomic host upgrade
$ sudo systemctl reboot

If you are using a system that requires an HTTP proxy, the proxy is configured with an environment variable. To configure the environment variable, use a command similar to the following one: 

$ sudo env http_proxy=http://proxy.example.com:port/ atomic host upgrade

1.5.2. Rolling Back to a Previous Version

To revert to a previous installation of Red Hat Enterprise Linux Atomic Host, execute the following commands: 

$ sudo atomic host rollback
$ sudo systemctl reboot

Two versions of Red Hat Enterprise Linux Atomic Host are available on the system after the initial upgrade. One is the currently running version. The other is either a new version recently installed from an upgrade or the version that was in place prior to the last upgrade.

Important

Configuration is preserved across updates, but is only forward-preserved. This means that if you make a configuration change and then later roll back to a previous version, the configuration change you made is reverted.

Note

Running the atomic host upgrade command will replace the non-running version of Red Hat Enterprise Linux Atomic Host. This version will also be configured to be used during the next boot.

To determine which version of the operating system is running, execute the following command. 

$ sudo atomic host status

The output that includes the hash name of the directory in the /ostree/deploy/rhel-atomic-host/ directory looks like this: 

$ sudo atomic host status
  TIMESTAMP (UTC)         VERSION   ID             OSNAME               REFSPEC
* 2015-05-07 19:00:48     7.1.2     203dd666d3     rhel-atomic-host     rhel-atomic-host:rhel-atomic-host/7/x86_64/standard
  2015-04-02 20:14:06     7.1.1-1   21bd99f9f3     rhel-atomic-host     rhel-atomic-host:rhel-atomic-host/7/x86_64/standard

This fictional sample output shows that version 7.1.1-1 will be booted into on the next restart. The version to be booted on the next restart is printed first.

This fictional sample also shows that version 7.1.2 is the currently running version. The currently running version is marked with an asterisk (*).

This output was created just after the atomic host upgrade command was executed, and that means that a new version has been staged to be applied at the next restart.

Chapter 2. Get Started with Containers

2.1. Install and Deploy an Apache Web Server Container

2.1.1. Overview

A Web server is one of the most basic examples used to illustrate how containers work. The procedure in this topic does the following:

  • Builds an Apache (httpd) Web server inside a container
  • Exposes the service on port 80 of the host
  • Serves a simple index.html file
  • Displays data from a backend server (needs additional MariaDB container described later)

2.1.2. Creating and running the Apache Web Server Container

  1. Install system: Install a RHEL 7 or RHEL Atomic system that includes the docker package and start the docker service.

  2. Pull image: Pull the rhel7 image by typing the following: 

    # docker pull rhel7:latest

  3. Get tarball with supporting files: Download the tarball file attached to this article (get it here: web_cont_3.tgz), download it to a new mywebcontainer directory, and untar it as follows: 

    # mkdir ~/mywebcontainer
# cp web_cont*.tgz ~/mywebcontainer
# cd ~/mywebcontainer
# tar xvf web_cont*.tgz
action
Dockerfile

  4. Modify action CGI script: Edit the action file as needed, which will be used to get data from the backend database server container. This script assumes that the docker0 interface on the host system is at IP address 172.17.42.1, you can login to the database with the dbuser1 user account and redhat as the password, and use the database named gss. If that is the IP address and you use the database container described later, you don’t need to modify this script. (You can also just ignore this script and just use the Web server to get HTML content.) 

    #!/usr/bin/python
# -*- coding: utf-8 -*-
import MySQLdb as mdb
import os

con = mdb.connect(os.getenv('DB_SERVICE_SERVICE_HOST','172.17.42.1'), 'dbuser1', 'redhat', 'gss')

with con:

    cur = con.cursor()
    cur.execute("SELECT MESSAGE FROM atomic_training")

    rows = cur.fetchall()

    print 'Content-type:text/html\r\n\r\n'
    print '<html>'
    print '<head>'
    print '<title>My Application</title>'
    print '</head>'
    print '<body>'

    for row in rows:
        print '<h2>' + row[0] + '</h2>'

    print '</body>'
    print '</html>'

    con.close()

  5. Check the Dockerfile: Modify the Dockerfile file in the ~/mywebcontainer directory as needed (perhaps only modify Maintainer_Name to add your name). Here are the contents of that file: 

    # Webserver container with CGI python script
# Using RHEL 7 base image and Apache Web server
# Version 1

# Pull the rhel image from the local registry
FROM rhel7:latest
USER root

MAINTAINER Maintainer_Name

# Fix per https://bugzilla.redhat.com/show_bug.cgi?id=1192200
RUN yum -y install deltarpm yum-utils --disablerepo=*-eus-* --disablerepo=*-htb-* *-sjis-*\
    --disablerepo=*-ha-* --disablerepo=*-rt-* --disablerepo=*-lb-* --disablerepo=*-rs-* --disablerepo=*-sap-*

RUN yum-config-manager --disable *-eus-* *-htb-* *-ha-* *-rt-* *-lb-* *-rs-* *-sap-* *-sjis* > /dev/null

# Update image
RUN yum update -y
RUN yum install httpd procps-ng MySQL-python -y

# Add configuration file
ADD action /var/www/cgi-bin/action
RUN echo "PassEnv DB_SERVICE_SERVICE_HOST" >> /etc/httpd/conf/httpd.conf
RUN chown root:apache /var/www/cgi-bin/action
RUN chmod 755 /var/www/cgi-bin/action
RUN echo "The Web Server is Running" > /var/www/html/index.html
EXPOSE 80

# Start the service
CMD mkdir /run/httpd ; /usr/sbin/httpd -D FOREGROUND

  6. Build Web server container: From the directory containing the Dockerfile file and other content, type the following: 

    # docker build -t webwithdb .
Sending build context to Docker daemon 4.096 kB
Sending build context to Docker daemon
Step 0 : FROM rhel7:latest
 ---> bef54b8f8a2f
Step 1 : USER root
 ---> Running in 00c28d347131
 ---> cd7ef0fcaf55
...

  7. Start the Web server container: To start the container image, run the following command: 

    # docker run -d -p 80:80 --name=mywebwithdb webwithdb

  8. Test the Web server container: To check that the Web server is operational, run the first curl command below. If you have the backend database container running, try the second command: 

    # curl http://localhost/index.html
The Web Server is Running
# curl http://localhost/cgi-bin/action
<html>
<head>
<title>My Application</title>
</head>
<body>
<h2>RedHat rocks</h2>
<h2>Success</h2>
</body>
</html>
</tt></pre>

    If you have a Web browser installed on the localhost, you can open a Web browser to see as better representation of the few lines of output. Just open the browser to this URL: http://localhost/cgi-bin/action

2.1.3. Tips for this container

Here are some tips to help you use the Web Server container:

  • Modify for MariaDB: To use this container with the MariaDB container (described later), you may need to edit the action script and change the IP address from 172.17.42.1 to the host IP on the docker0 interface. To find what that address is on your host, type the following: 
# ip a | grep docker0 | grep inet
    inet 172.17.42.1/16 scope global docker0
  • Adding content: You can include your own content, mounted from the local host, by using the -v option on the docker run command line. For example: 
# docker run -d -p 80:80 -v /var/www/html:/var/www/html \
     --name=mywebwithdb webwithdb

2.1.4. Attachments

2.2. Install and Deploy a MariaDB Container

2.2.1. Overview

Using MariaDB, you can set up a basic database in a container that can be accessed by other applications. The procedure in this topic does the following:

  • Builds a MariaDB database server inside a docker formatted container
  • Exposes the service on port 3306 of the host
  • Starts up the database service to share a few pieces of information
  • Allows a script from Web server to query the database (needs additional Web server container described later)
  • Offers tips on how to use and extend this container

2.2.2. Creating and running the MariaDB Database Server Container

  1. Install system: Install a Red Hat Enterprise Linux 7 or Red Hat Enterprise Linux Atomic Host system that includes the docker package and start the docker service.

  2. Pull image: Pull the rhel7 image by typing the following: 

    # docker pull rhel7:latest

  3. Get tarball with supporting files: Download the tarball file attached to this article (mariadb_cont_2.tgz), download it to a new mydbcontainer directory, and untar it as follows: 

    # mkdir ~/mydbcontainer
# cp mariadb_cont*.tgz ~/mydbcontainer
# cd ~/mydbcontainer
# tar xvf mariadb_cont*.tgz
gss_db.sql
Dockerfile

  4. Check the Dockerfile: Modify the Dockerfile file in the ~/mydbcontainer directory as needed (perhaps only modify Maintainer_Name to add your name). Here are the contents of that file: 

    # Database container with simple data for a Web application
# Using RHEL 7 base image and MariahDB database
# Version 1

# Pull the rhel image from the local repository
FROM rhel7:latest
USER root

MAINTAINER Maintainer_Name

# Update image
RUN yum update -y --disablerepo=*-eus-* --disablerepo=*-htb-* --disablerepo=*sjis* \
    --disablerepo=*-ha-* --disablerepo=*-rt-* --disablerepo=*-lb-* \
    --disablerepo=*-rs-* --disablerepo=*-sap-*

RUN yum-config-manager --disable *-eus-* *-htb-* *-ha-* *-rt-* *-lb-* \
    *-rs-* *-sap-* *-sjis-* > /dev/null

# Add Mariahdb software
RUN yum -y install net-tools mariadb-server

# Set up Mariahdb database
ADD gss_db.sql /tmp/gss_db.sql
RUN /usr/libexec/mariadb-prepare-db-dir
RUN test -d /var/run/mariadb || mkdir /var/run/mariadb; \
    chmod 0777 /var/run/mariadb; \
    /usr/bin/mysqld_safe --basedir=/usr & \
    sleep 10s && \
    /usr/bin/mysqladmin -u root password 'redhat' && \
    mysql --user=root --password=redhat < /tmp/gss_db.sql && \
    mysqladmin shutdown --password=redhat

# Expose Mysql port 3306
EXPOSE 3306

# Start the service
CMD test -d /var/run/mariadb || mkdir /var/run/mariadb; chmod 0777 /var/run/mariadb;/usr/bin/mysqld_safe --basedir=/usr

  5. Build database server container: From the directory containing the Dockerfile file and other content, type the following: 

    # docker build -t dbforweb .
Sending build context to Docker daemon 528.4 kB
Sending build context to Docker daemon
Step 0 : FROM rhel7:latest
 ---> bef54b8f8a2f
Step 1 : USER root
...

  6. Start the database server container: To start the container image, run the following command: 

    # docker run -d -p 3306:3306 --name=mydbforweb dbforweb

  7. Test the database server container: Assuming the docker0 interface on the host is 172.17.42.1 (yours may be different), check that the database container is operational by running the nc command (in RHEL 7, type yum install nc to get it) as shown here: 

    # nc -v 172.17.42.1 3306
Ncat: Version 6.40 ( http://nmap.org/ncat )
Ncat: Connected to 172.17.42.1:3306.
R
5.5.44-MariaDB?acL3YF31?X?FWbiiTIO2Kd6mysql_native_password Ctrl-C

2.2.3. Tips for this container

Here are some tips to help you use the Web Server container:

  • Adding your own database: You can include your own MariaDB content by copying your database file to the build directory and changing the name of the database file from gss_db.sql to the name of your database (in several places in the Dockerfile file).
  • Orchestrate containers: A better way to manage this container with other containers is to use Kubernetes to orchestrate them into pods.

2.2.4. Attachments

Legal Notice

Copyright © 2017 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.