Chapter 2. Deploying an Identity Management Server in a Container

This chapter describes how you can install a fresh Identity Management server to start a new topology.

Before you begin, read Section 2.1, “Prerequisites” and Section 2.2, “Available Configuration in Server and Replica Containers”.

Choose one of the following installation procedures. If you are not sure which certificate authority (CA) configuration fits your situation, see Determining What CA Configuration to Use in the Linux Domain Identity, Authentication, and Policy Guide.

After you are done, read Section 2.6, “Next Steps After Installation”.

2.1. Prerequisites

  • Upgrade the Atomic Host system before installing the container. See Upgrading and Downgrading in the Red Hat Enterprise Linux Atomic Host 7 Installation and Configuration Guide.

2.2. Available Configuration in Server and Replica Containers

What Is Available

Domain level 1 or higher

Domain level 0 is not available for containers. See also Displaying and Raising the Domain Level.

As a consequence, servers running in containers can be joined in a replication agreement only with Identity Management servers based on Red Hat Enterprise Linux 7.3 or later.

Mixed container and non-container deployments
A single Identity Management domain topology can include both container-based and RPM-based servers.

What Is Not Available

Changing server components in a deployed container
Do not make runtime modifications of deployed containers. If you need to change or reinstall a server component, such as integrated DNS or Vault, create a new replica.
Upgrading between different Linux distributions

Do not change the platform on which an ipa-server container image runs. For example, do not change an image running on Red Hat Enterprise Linux to Fedora, Ubuntu, or CentOS. Similarly, do not change an image running on Fedora, Ubuntu, or CentOS to Red Hat Enterprise Linux.

Identity Management supports only upgrades to later versions of Red Hat Enterprise Linux.

Downgrading the system with a running container
Do not downgrade the system on which an ipa-server container image runs.
Upstream containers on Atomic Host
Do not install upstream container images, such as the FreeIPA ipa-server image, on Atomic Host. Install only the container images available in Red Hat Enterprise Linux.
Multiple containers on a single Atomic Host
Install only one ipa-server container image on a single Atomic Host.

2.3. Installing an Identity Management Server in a Container: Basic Installation

This procedure shows how to install a containerized Identity Management server in the default certificate authority (CA) configuration with an integrated CA.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.

Procedure

  1. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-server-install command to start the installation.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  2. The ipa-server-install setup script starts:

    The log file for this installation can be found in /var/log/ipaserver-install.log
    ========================================
    This program will set up the IPA Server.
    [... output truncated ...]

    The process is the same as when using the ipa-server-install utility to install a non-container server.

Example 2.1. Installation Command Examples

Command syntax for installing the ipa-server container:

$ atomic install [ --name <container_name> ] rhel7/ipa-server [ Atomic options ] [ ipa-server-install | ipa-replica-install ] [ ipa-server-install or ipa-replica-install options ]

To install a server container named server-container and use default values for the Identity Management server settings:

$ atomic install --name server-container rhel7/ipa-server publish --hostname server.example.com ipa-server-install --ip-address 2001:DB8::1111

To install a server with a custom host name (--hostname) and integrated DNS (--setup-dns):

$ atomic install rhel7/ipa-server publish --hostname server.example.com ipa-server-install --setup-dns --ip-address 2001:DB8::1111

2.4. Installing an Identity Management Server in a Container: External CA

This procedure describes how to install a server with an integrated Identity Management certificate authority (CA) that is subordinate to an external CA.

A containerized Identity Management server and the Atomic Host system share only the parts of the file system that are mounted using a bind mount into the container. Therefore, operations related to external files must be performed from within this volume.

The ipa-server container image uses the /var/lib/<container_name>/ directory to store persistent files on the Atomic Host file system. The persistent storage volume maps to the /data/ directory inside the container.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.

Procedure

  1. Use the atomic install rhel7/ipa-server publish --hostname fully_qualified_domain_name ipa-server-install --external-ca command to start the installation.

    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  2. The ipa-server-install setup script starts:

    The log file for this installation can be found in /var/log/ipaserver-install.log
    ========================================
    This program will set up the IPA Server.
    [... output truncated ...]

    The process is the same as when using the ipa-server-install utility to install a non-container server.

  3. The container installation script generates the certificate signing request (CSR) in the /var/lib/<container_name>/root/ipa.csr file. Submit the CSR to the external CA, and retrieve the issued certificate and the CA certificate chain for the issuing CA.

    See Installing a Server with an External CA as the Root CA in the Linux Domain Identity, Authentication, and Policy Guide for details.

  4. Copy the signed CA certificate and the root CA certificate into the /var/lib/<container_name>/ directory.

    $ cp /root/{ipa,ca}.crt /var/lib/server-container/.
  5. Use the atomic run command with the --external-cert-file option to specify the location of the certificates. Specify the location relative to the /data/ directory because the installer performs the call from inside the container

    $ atomic run rhel7/ipa-server ipa-server-install --external-cert-file /data/ipa.crt --external-cert-file /data/ca.crt
  6. The installation resumes. The installer now uses the supplied certificates to set up the subordinate CA.

2.5. Installing an Identity Management Server in a Container: Without a CA

This procedure describes how to install a server without an integrated Identity Management certificate authority (CA).

A containerized Identity Management server and the Atomic Host system share only the parts of the file system that are mounted using a bind mount into the container. Therefore, operations related to external files must be performed from within this volume.

The ipa-server container image uses the /var/lib/<container_name>/ directory to store persistent files on the Atomic Host file system. The persistent storage volume maps to the /data/ directory inside the container.

Before You Start

  • Note that the container installation uses the same default configuration as a non-container installation using ipa-server-install. To specify custom configuration, add additional options to the atomic install command used in the procedure below:

    • Atomic options available for the ipa-server container. For a complete list, see the container help page.
    • Identity Management installer options accepted by ipa-server-install, described in Installing and Uninstalling an Identity Management Server in the Linux Domain Identity, Authentication, and Policy Guide.

Procedure

  1. Manually create the persistent storage directory for the container at /var/lib/<container_name>/:

    $ mkdir -p /var/lib/ipa-server
  2. Copy the files containing the certificate chain into the directory:

    $ cp /root/server-*.p12 /var/lib/ipa-server/.

    See Installing Without a CA in the Linux Domain Identity, Authentication, and Policy Guide for details on the required files.

  3. Use the atomic install command, and provide the required certificates from the third-party authority:

    $ atomic install --name server-container rhel7/ipa-server publish \
       --hostname server.example.com \
       ipa-server-install \
       --dirsrv-cert-file=/data/server-dirsrv-cert.p12 \
       --dirsrv-pin=1234 \
       --http-cert-file=/data/server-http-cert.p12 \
       --http-pin=1234 \
       --pkinit-cert-file=/data/server-pkinit-cert.p12 \
       --pkinit-pin=1234
    • The container requires its own host name. Use a different host name for the container than the host name of the Atomic Host system. The container’s host name must be resolvable via DNS or the /etc/hosts file.

      Note

      Installing a server or replica container does not enroll the Atomic Host system itself to the Identity Management domain. If you use the Atomic Host system’s host name for the server or replica, you will be unable to enroll the Atomic Host system later.

      Important

      Always use the --hostname option with atomic install when installing the server or replica container. Because --hostname is considered an Atomic option in this case, not an Identity Management installer option, use it before the ipa-server-install option. The installation ignores --hostname when used after ipa-server-install.

    • If you are installing a server with integrated DNS, add also the --ip-address option to specify the public IP address of the Atomic Host that is reachable from the network. You can use --ip-address multiple times.
    Warning

    Unless you want to install the container for testing purposes only, always use the publish option. Without publish, no ports will be published to the Atomic Host system, and the server will not be reachable from outside the container.

  4. The ipa-server-install setup script starts:

    The log file for this installation can be found in /var/log/ipaserver-install.log
    ========================================
    This program will set up the IPA Server.
    [... output truncated ...]

    The process is the same as when using the ipa-server-install utility to install a non-container server.

2.6. Next Steps After Installation

  • To run the container, use the atomic run command:

    $ atomic run rhel7/ipa-server

    If you specified a name for the container when you installed it:

    $ atomic run --name server-container rhel7/ipa-server
  • A running ipa-server container works in the same way as in a standard Identity Management deployment on bare-metal or virtual machine systems. For example, you can enroll hosts to the domain or manage the topology using the command-line interface, the web UI, or JSONRPC-API in the same way as RPM-based Identity Management systems.