Chapter 12. Provisioning Containers

With Red Hat Satellite 6, you can create an on-premise registry, import images from various sources and distribute them to containers using Content Views. Satellite Server supports creating one or more Docker compute resources that act as servers for running containers.

You can import an image, start a container based on this image, monitor the container’s activity, and commit its state to a new image layer that can be further propagated.

For information about containers, see the Getting Started with Containers guide for Red Hat Enterprise Linux Atomic Host 7.

Use this chapter to import container images and use these images to create containers.

12.1. Prerequisites for Container Provisioning

Before you can provision a container using Red Hat Enterprise Linux Atomic Host, you must have a source for images, such as a container registry.

Red Hat Satellite 6 uses three sources of container images:

12.2. Importing Container Images

You can import container image repositories from the Red Hat Container Catalog or from other image registries that you connect to Satellite.

This procedure uses repository discovery to find container image repositories to import. For information about creating a product and repository manually, see Creating a Custom Product in the Content Management Guide.

Procedure

To import container image repositories and create or associate them with a product, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Products and click Repo Discovery.
  2. From the Repository Type list, select Container Images.
  3. In the Registry to Discover field, enter the URL of the registry to import images from.
  4. In the Registry Username field, enter the name that corresponds with your user name for the container image registry.
  5. In the Registry Password field, enter the password that corresponds with the user name that you enter.
  6. In the Registry Search Parameter field, enter any search criteria that you want to use to filter your search, and then click Discover.
  7. Optional: To further refine the Discovered Repository list, in the Filter field, enter any additional search criteria that you want to use.
  8. From the Discovered Repository list, select any repositories that you want to import, and then click Create Selected.
  9. Optional: If you want to create a product, from the Product list, select New Product.
  10. In the Name field, enter a product name.
  11. Optional: In the Repository Name and Repository Label columns, you can edit the repository names and labels.
  12. Click Run Repository Creation.
  13. When repository creation is complete, you can click each new repository to view more information.
  14. Optional: To filter the content you import to a repository, click a repository, and then navigate to Limit Sync Tags. Click to edit, and add any tags that you want to limit the content that synchronizes to Satellite.
  15. Navigate to Content > Products and select the name of your product.
  16. Select the new repositories and then click Sync Now to start the synchronization process.

To view the progress of the synchronization navigate to Content > Sync Status and expand the repository tree.

When the synchronization completes, you can click Manage Docker Manifests to list the available manifests. From the list, you can also remove any manifests that you do not require.

For CLI Users

  1. Create the custom Red Hat Container Catalog product:

    # hammer product create \
    --name "Red Hat Container Catalog" \
    --sync-plan "Example Plan" \
    --description "Red Hat Container Catalog content" \
    --organization "My_Organization"
  2. Create the repository for the container images:

    # hammer repository create \
    --name "RHEL7" \
    --content-type "docker" \
    --url "http://registry.access.redhat.com/" \
    --docker-upstream-name "rhel7" \
    --product "Red Hat Container Catalog" \
    --organization "My_Organization"
  3. Synchronize the repository:

    # hammer repository synchronize \
    --name "RHEL7" \
    --product "Red Hat Container Catalog" \
    --organization "My_Organization"

12.3. Adding External Registries to the Satellite Server

If you want to create a container from an image in an external registry, you must first add the registry to Satellite.

To add an external container registry, complete the following steps:

  1. In the Satellite web UI, navigate to Containers > Registries and click Create Registry.
  2. In the Name field, enter a name for the registry.
  3. In the URL field, enter the location of the registry. For example: https://registry.access.redhat.com.
  4. Optional: In the Description field, enter a description for your registry entry.
  5. In the Username field, enter the user name that corresponds with your user account on the registry.
  6. In the Password field, enter the password for your user account on your registry.
  7. Select the Locations tab, and select a location.
  8. Select the Organizations tab, and select an organization.
  9. Click Submit to save the external registry.

For CLI Users

Create the registry with the hammer docker registry create command:

# hammer docker registry create --name "Red Hat" \
--url "https://registry.access.redhat.com" \
--description "Red Hat Container Image Registry" \
--organization "Default_Organization" \
--location "Default_Location"

12.4. Managing Container Name Patterns

When you use Satellite to create and manage your containers, as the container moves through Content View versions and different stages of the Satellite lifecycle environment, the container name changes at each stage. For example, if you synchronize a container image with the name ssh from an upstream repository, when you add it to a Satellite product and organization and then publish as part of a Content View, the container image can have the following name: my_organization_production-custom_spin-my_product-custom_ssh. This can create problems when you want to pull a container image because container registries can contain only one instance of a container name. To avoid problems with Satellite’s naming conventions, you can set a registry name pattern to override the default name to ensure that your container name is clear for future use.

Limitations

If you use a registry name pattern to manage container naming conventions, because registry naming patterns must generate globally unique names, you might experience naming conflict problems. For example:

  • If you set the repository.docker_upstream_name registry name pattern, you cannot publish or promote Content Views with container content with identical repository names to the Production lifecycle.
  • If you set the lifecycle_environment.name registry name pattern, this can prevent the creation of a second container repository with the identical name.

You must proceed with caution when defining registry naming patterns for your containers.

Procedure

To manage container naming with a registry name pattern, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Lifecycle Environments, and either create a lifecycle environment or select a lifecycle environment to edit.
  2. In the Container Image Registry area, click the edit icon to the right of Registry Name Pattern area.
  3. Use the list of variables and examples to determine which registry name pattern you require.
  4. In the Registry Name Pattern field, enter the registry name pattern that you want to use. For example, to use the repository.docker_upstream_name:

    <%= repository.docker_upstream_name %>
  5. Click Save.

The container repositories update immediately and you can use docker pull to pull your container image with the name you specify.

12.5. Managing Container Images in Satellite

To manage container images with Content Views, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Content Views and click Create New View.
  2. In the Name field, enter Containers. This automatically populates the Label field.
  3. In the Description field, enter a description. For example, Container image for Red Hat Enterprise Linux 7.
  4. If you want to use a Composite Content View to hold other Content Views, select the Composite View check box.
  5. Optional: If you select Composite Content View, you can select whether you want to Auto publish a composite view when a new version of a component Content View is created.
  6. Click Save to create the Content View.
  7. Navigate to the Docker Content subtab, then click Add.
  8. Select the container repository for a Red Hat Enterprise Linux 7 Server image.
  9. Click Add Repository.
  10. Navigate to Versions and click Publish New Version.

You can enter a Description for the version; meaningful descriptions can help in logging new content versions.

Satellite Server creates the new version of the view and publishes it to the Library environment.

You can also click Promote to promote this Content View across environments in the application life cycle.

For CLI Users

  1. To obtain a list of repository IDs:

    # hammer repository list --organization "My_Organization"
  2. Create the Content View and add the repository:

    # hammer content-view create \
    --name "Containers" \
    --description "Container image for Red Hat Enterprise Linux 7" \
    --repository-ids 8 \
    --organization "My_Organization"
  3. Publish the view:

    # hammer content-view publish \
    --name "Containers" \
    --description "Initial Content View for our container image" \
    --organization "My_Organization"

12.6. Configuring the Red Hat Enterprise Linux Atomic Host

Configure the Atomic Host before connecting to Satellite. This includes exposing the Red Hat API for Docker-formatted containers to the Satellite Server. For information about containers, see the Getting Started with Containers guide for Red Hat Enterprise Linux Atomic Host 7.

  1. Log on to the Atomic Host and edit the /etc/sysconfig/docker file:

    $ vi /etc/sysconfig/docker
  2. Find the OPTIONS parameter and modify it to expose the API:

    OPTIONS='--selinux-enabled -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375'
    Important

    Use either TCP port 2375 or 2376 for the connection. Satellite Server contains certain SELinux rules to permit access to these ports. Using an alternative port results in authentication failure.

  3. Open port 2375 for the firewall:

    # firewall-cmd --add-port=2375/tcp
    # firewall-cmd --add-port=2375/tcp --permanent
  4. Import the Satellite Server certificate:

    $ curl http://satellite.example.com/pub/katello-server-ca.crt \
    -o /etc/pki/ca-trust/source/anchors/katello-server-ca.crt
    $ update-ca-trust
  5. Restart the docker service:

    # systemctl restart docker

12.7. Adding an Atomic Host Connection to the Satellite Server

To add an Red Hat Enterprise Linux Atomic connection in the Satellite Server’s compute resources, complete the following steps:

  1. In the Satellite web UI, navigate to Infrastructure > Compute Resources and click Create Compute Resource.
  2. In the Name field, enter a name for the resource.
  3. From the Provider list, select Docker.
  4. Optional: In the Description field, you can add a description for the resource.
  5. Select the Locations tab, and select the location that you want to use.
  6. Select the Organizations tab, and select the organization that you want to use.
  7. Click Submit to save.

For CLI Users

Create the connection with the hammer compute-resource create command:

# hammer compute-resource create --provider docker \
--name "Atomic" --url "http://atomic.example.com:2375" \
--organizations 'Default Organization' --locations 'Default Location'

12.8. Creating a Container

Use this procedure to create a container in Satellite. The Satellite web UI contains a wizard that guides you through the creation process. You can select a container image from a Content View, a Docker Hub, or an external registry that you add to Satellite.

  1. In the Satellite web UI, navigate to Containers > Create Container.
  2. From the Deploy on list, select the compute resource that you want to use.
  3. Select the Locations tab, and select a location.
  4. Select the Organizations tab, and select an organization.
  5. Click Next step.

To create a container, you have three options:

  • Create from a container image in Content View
  • Create from an container image in the Docker Hub
  • Create from an container image in an external registry.

Creating a Container from a Content View

  1. From the Lifecycle Environment list, select the lifecycle environment that you want to use.
  2. From the Content View list, select the container image that you want to use.
  3. From the Registry list, select the registry that you want to use.
  4. From the Tag list, select the container image tag that you want to use.
  5. From the Capsule list, select the Capsule that you want to use.
  6. Click Next Step.

Creating a Container from Docker Hub

  1. Select the Docker Hub tab, and in the Search field, enter the Docker container that you want to use.
  2. In the Tag field, enter the name of the container image tag that you want to use, and click Search for images.
  3. Select the container image that you want to use, and click Next Step.

Creating a Container from an External Registry

  1. From the Registry list, select a registry that you want to use.
  2. In the Search field, enter the name of the container image that you want to use.
  3. In the Tag field, enter the tag that is associated with the container image you want to use.
  4. Click Search for images and select the image that you want to use, and click Next step.

Finishing the Container Creation Process

  1. In the Name field, enter a name for the new container.
  2. In the Command field, enter a command that you want to run in the container.
  3. In the Entry point field, enter a command that you want the container to execute automatically when the container starts. The default entrypoint is /bin/sh -c.
  4. Select the Compute options tab.
  5. In the CPU Sets field, assign CPUs to the container. For example, 0-2,16 represents CPUs 0, 1, 2, and 16.
  6. In the CPU share field, assign the CPU share for the container. This sets the share of CPU time available to containerized tasks.
  7. In the Memory field, enter the memory size that you want to allocate to the container.
  8. Click Next Step.
  9. In the Environment variables field, define a set of environmental variables. For example, LANG=en_US.UTF-8.
  10. In the Exposed Ports field, enter the number of ports that you want to open in the container. For example, you can open SSH communication to the container on port 22.
  11. In the DNS field, enter the DNS server for the container.
  12. Select the Run check box to start the container automatically after it is created.
  13. Click Submit to create a container.

For CLI Users

The following are three examples of the hammer docker container create command.

  • To create a container from a Content View:

    # hammer docker container create --compute-resource "Atomic" \
    --repository-name "rhel7" --tag "latest" --name "docker-test1" \
    --command "bash" --organizations "My_Organization" --locations "New York"
  • To provision from the Docker Hub:

    # hammer docker container create --compute-resource "Atomic" \
    --repository-name "docker.io/redhat" --tag latest \
    --name "docker-test2" --command bash --organizations "My_Organization" \
    --locations "New York"
  • To provision from an external registry:

    # hammer docker container create --compute-resource "Atomic" \
    --registry-id 1 --repository-name "rhel" --tag latest \
    --name "docker-test3 --command bash --organizations "My_Organization" \
    --locations "New York"

12.9. Managing Container Registry Authentication

By default, users must authenticate to access containers in the Satellite image registry. Use the docker login command to log on to Satellite. You can then use the docker pull and docker search commands to access containers based on your Satellite permissions.

You can specify whether you want users to authenticate to access container images in a Satellite image registry that you manage in a lifecycle environment. For example, you might want to permit users to pull container images from the Production lifecycle without any authentication requirement and restrict access the Development and QA environments to authenticated users.

Procedure

To manage the authentication settings for your Satellite image registry, complete the following steps:

  1. In the Satellite web UI, navigate to Content > Lifecycle Environments and select the lifecycle environment that you want to manage authentication for.
  2. To permit unauthenticated access to the containers in this lifecycle environment, select the Unauthenticated Pull check box. To restrict unauthenticated access, clear the Unauthenticated Pull check box.
  3. Click Save.

12.10. Starting, Committing, and Removing Containers

Starting or Stopping a Container

When you create a container, its default state is disabled. By enabling a container, you start the processes of the containerized application in the compute resource. Hosts are then able to communicate with the container as with a web application.

  1. In the Satellite web UI, navigate to Containers > All Containers.
  2. From the list of existing containers, select the container that you want, and then click Power On. To stop the container, click Power Off.

Committing a Container

When you launch a container from an image, a writable layer is added on top of this image. Committing a container creates an image layer that stores the status of that container. Every time you commit a container a new image layer is added to store your changes. The container is committed to the repository of the original image. For example, if the container is based on an image pulled from the Docker Hub, the committed changes are pushed back to the Docker Hub.

  1. In the Satellite web UI, navigate to Containers > All Containers.
  2. From the list of existing containers, select the container that you want, and then click Commit.
  3. Enter a repository name, for example user/my-rhel-image.
  4. Assign a tag to the image.
  5. Enter your contact information.
  6. Enter an informative comment about the commit.
  7. Click Submit.

Removing a Container

  1. In the Satellite web UI, navigate to Containers > All Containers.
  2. From the list of existing containers, select the container that you want, and then click Delete.
  3. In the alert window, click OK to confirm the deletion.