Docker Enterprise¶

Client certificate to PKCS12 file conversion¶

From the command line, switch to the directory of your client bundle and run the following command to convert the client bundle public and private key pair to a .p12 file.

openssl pkcs12 -export -out cert.p12 -inkey key.pem -in cert.pem

Create with a simple password, you will be prompted for it when you import the certificate into the browser or Mac’s Keychain Access.

PKCS12 file browser import¶

Instructions on how to import a certificate into a web browser vary according to your platform, OS, preferred browser and browser version. As a general rule, refer to one of the following how-to articles: - Firefox: https://www.sslsupportdesk.com/how-to-import-a-certificate-into-firefox/ - Chrome: https://www.comodo.com/support/products/authentication_certs/setup/win_chrome.php - Internet Explorer: https://www.comodo.com/support/products/authentication_certs/setup/ie7.php

Add your DTR server CA certificate to system level¶

You have the option to add your DTR server CA certificate to your system’s trusted root certificate pool. This is MacOS Keychain or /etc/ca-certificates/ on Ubuntu. Note that you will have to remove the certificate if your DTR public address changes.

DTR authentication via client Certificates¶

Hit your DTR’s basic_info endpoint via curl:

curl --cert cert.pem --key key.pem -X GET "https://<dtr-external-url>/basic_info"

If successfully configured, you should see TLSClientCertificate listed as the AuthnMethod in the JSON response.

{
"CurrentVersion": "2.7.0",
"User": {
"name": "admin",
"id": "30f53dd2-763b-430d-bafb-dfa361279b9c",
"fullName": "",
"isOrg": false,
"isAdmin": true,
"isActive": true,
"isImported": false
},
"IsAdmin": true,
"AuthnMethod": "TLSClientCertificate"
}

DTR as an insecure registry¶

Avoid adding DTR to Docker Engine’s list of insecure registries as a workaround. This has the side effect of disabling the use of TLS certificates.

DTR server certificate errors¶

Error response from daemon: Get https://35.165.223.150/v2/: x509: certificate is valid for 172.17.0.1, not 35.165.223.150

Intermediate certificates¶

For chain of trust which includes intermediate certificates, you may optionally add those certificates when installing or reconfiguring DTR with --enable-client-cert-auth and --client-cert-auth-ca. You can do so by combining all of the certificates into a single PEM file.

curl on certain macOS versions¶

Some versions of macOS include curl which only accepts .p12 files and specifically requires a ./ prefix in front of the file name if running curl from the same directory as the .p12 file:

curl --cert ./client.p12  -X GET \
"https://<dtr-external-url>/api/v0/repositories?pageSize=10&count=false" \
-H "accept:application/json"

Use Universal Control Plane¶

If you use Universal Control Plane with Docker Engine - Enterprise, do not use the Docker CLI to disable the telemetry plugin. Instead, you can manage the information sent to Docker by going to Admin Settings and choosing Usage.

To disable the telemetry plugin, disable all three options and click Save. Enabling either or both of the top two options will enable the telemetry plugin. You can find out more about an individual option by clicking the ? icon.

Docker Enterprise Engine 18.03 or older¶

For Docker Enterprise Engine 18.03 or older, the telemetry module ran as a Docker Plugin. To disable the telemetry plugin, use the docker plugin disable with either the plugin NAME or ID:

$ docker plugin ls
ID                  NAME                                           [..]
114dbeaa400c        docker/telemetry:1.0.0.linux-x86_64-stable     [..]

$ docker plugin disable docker/telemetry:1.0.0.linux-x86_64-stable

This command must be run on each Docker host.

To re-enable the telemetry plugin, you can use docker plugin enable with either the plugin NAME or ID:

$ docker plugin ls
ID                  NAME                                           [..]
114dbeaa400c        docker/telemetry:1.0.0.linux-x86_64-stable     [..]

$ docker plugin enable docker/telemetry:1.0.0.linux-x86_64-stable

Determine if the network is in danger of exhaustion¶

Starting with a cluster with one or more services configured, determine whether some networks may require updating the IP address space in order to function correctly after an Docker Engine - Enterprise 18.09 upgrade.

1. SSH into a manager node on a cluster where your applications are running.
2. Run the following:

$ docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock docker/ip-util-check

If the network is in danger of exhaustion, the output will show similar warnings or errors:

Overlay IP Utilization Report
   ----
   Network ex_net1/XXXXXXXXXXXX has an IP address capacity of 29 and uses 28 addresses
           ERROR: network will be over capacity if upgrading Docker engine version 18.09
                  or later.
   ----
   Network ex_net2/YYYYYYYYYYYY has an IP address capacity of 29 and uses 24 addresses
           WARNING: network could exhaust IP addresses if the cluster scales to 5 or more nodes
   ----
   Network ex_net3/ZZZZZZZZZZZZ has an IP address capacity of 61 and uses 52 addresses
           WARNING: network could exhaust IP addresses if the cluster scales to 9 or more nodes

3. Once you determine all networks are sized appropriately, start the upgrade on the Swarm managers.

ID                  NAME                MODE                REPLICAS   IMAGE               PORTS
wn3x4lu9cnln        ex_service          replicated          19/24      nginx:latest

ID                  NAME                IMAGE               NODE                DESIRED STATE       CURRENT STATE              ERROR               PORTS
    ...
i64lee19ia6s         \_ ex_service.11   nginx:latest        tk1706-ubuntu-1     Shutdown            Rejected 7 minutes ago     "node is missing network attac…"
    ...

...
            "Status": {
                "Timestamp": "2018-08-24T21:03:37.885405884Z",
                "State": "rejected",
                "Message": "preparing",
                **"Err": "node is missing network attachments, ip addresses may be exhausted",**
                "ContainerStatus": {
                    "ContainerID": "",
                    "PID": 0,
                    "ExitCode": 0
                },
                "PortStatus": {}
            },
    ...

Manager upgrades when moving to Docker Engine - Enterprise 18.09 and later¶

The following is a constraint introduced by architectural changes to the Swarm overlay networking when upgrading to Docker Engine - Enterprise 18.09 or later. It only applies to this one-time upgrade and to workloads that are using the Swarm overlay driver. Once upgraded to Docker Engine - Enterprise 18.09, this constraint does not impact future upgrades.

When upgrading to Docker Engine - Enterprise 18.09, manager nodes cannot reschedule new workloads on the managers until all managers have been upgraded to the Docker Engine - Enterprise 18.09 (or higher) version. During the upgrade of the managers, there is a possibility that any new workloads that are scheduled on the managers will fail to schedule until all of the managers have been upgraded.

In order to avoid any impactful application downtime, it is advised to reschedule any critical workloads on to Swarm worker nodes during the upgrade of managers. Worker nodes and their network functionality will continue to operate independently during any upgrades or outages on the managers. Note that this restriction only applies to managers and not worker nodes.

Drain the node¶

If you are running live application on the cluster while upgrading, remove applications from nodes being upgrades as to not create unplanned outages.

Start by draining the node so that services get scheduled in another node and continue running without downtime.

For that, run this command on a manager node:

$ docker node update --availability drain <node>

Perform the upgrade¶

To upgrade a node individually by operating system, please follow the instructions listed below:

• `Windows Server
• Ubuntu
• RHEL
• CentOS
• Oracle Linux
• SLES

Post-Upgrade steps for Docker Engine - Enterprise¶

After all manager and worker nodes have been upgrades, the Swarm cluster can be used again to schedule new workloads. If workloads were previously scheduled off of the managers, they can be rescheduled again. If any worker nodes were drained, they can be undrained again by setting --availability active.

Architectures and storage drivers¶

Docker EE supports CentOS 64-bit, latest version, running on x86_64.

On CentOS, Docker EE supports storage drivers, overlay2 and devicemapper. In Docker EE 17.06.2-ee-5 and higher, overlay2 is the recommended storage driver. The following limitations apply:

• OverlayFS: If selinux is enabled, the overlay2 storage driver is supported on CentOS 7.4 or higher. If selinux is disabled, overlay2 is supported on CentOS 7.2 or higher with kernel version 3.10.0-693 and higher.
• Device Mapper: On production systems using devicemapper, you must use direct-lvm mode, which requires one or more dedicated block devices. Fast storage such as solid-state media (SSD) is recommended.

Find your Docker EE repo URL¶

To install Docker EE, you will need the URL of the Docker EE repository associated with your trial or subscription:

1. Go to https://hub.docker.com/my-content. All of your subscriptions and trials are listed.
2. Click the Setup button for Docker Enterprise Edition for Centos.
3. Copy the URL from Copy and paste this URL to download your Edition and save it for later use.

You will use this URL in a later step to create a variable called, DOCKERURL.

Uninstall old Docker versions¶

The Docker EE package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks. If you are upgrading from Docker Engine - Community to Docker EE, remove the Docker Engine - Community package as well.

$ sudo yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine

Set up the repository¶

You only need to set up the repository once, after which you can install Docker EE from the repo and repeatedly upgrade as necessary.

1. Remove existing Docker repositories from /etc/yum.repos.d/:

   $ sudo rm /etc/yum.repos.d/docker*.repo
   

2. Temporarily store the URL (that you copied above) in an environment variable. Replace <DOCKER-EE-URL> with your URL in the following command. This variable assignment does not persist when the session ends:

   $ export DOCKERURL="<DOCKER-EE-URL>"
   

3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

   $ sudo -E sh -c 'echo "$DOCKERURL/centos" > /etc/yum/vars/dockerurl'
   

4. Install required packages: yum-utils provides the yum-config-manager utility, and device-mapper-persistent-data and lvm2 are required by the devicemapper storage driver:

   $ sudo yum install -y yum-utils \
     device-mapper-persistent-data \
     lvm2
   

5. Add the Docker EE stable repository:

   $ sudo -E yum-config-manager \
       --add-repo \
       "$DOCKERURL/centos/docker-ee.repo"
   

Install from the repository¶

1. Install the latest patch release, or go to the next step to install a specific version:

   $ sudo yum -y install docker-ee docker-ee-cli containerd.io
   

   If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

2. To install a specific version of Docker EE (recommended in production), list versions and install:

   1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      $ sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      19.03.ee.2-1.el7.entos     docker-ee-stable-18.09
      
      The list returned depends on which repositories you enabled, and is
      specific to your version of CentOS (indicated by ``.el7`` in this
      example).
      

   2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-18.09.1.

      $ sudo yum -y install docker-ee-<VERSION_STRING> docker-ee-cli-<VERSION_STRING> containerd.io
      

      For example, if you want to install the 18.09 version run the following:

      sudo yum-config-manager --enable docker-ee-stable-18.09
      

      Docker is installed but not started. The docker group is created, but no users are added to the group.

3. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker.

   $ sudo systemctl start docker
   

4. Verify that Docker EE is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker EE is installed and running. Use sudo to run Docker commands.

Upgrade from the repository¶

1. Add the new repository.
2. Follow the installation instructions and install a new version.

Install with a package¶

1. Go to the Docker EE repository URL associated with your trial or subscription in your browser. Go to centos/7/x86_64/stable-<VERSION>/Packages and download the .rpm file for the Docker version you want to install.

2. Install Docker Enterprise, changing the path below to the path where you downloaded the Docker package.

   $ sudo yum install /path/to/package.rpm
   

   Docker is installed but not started. The docker group is created, but no users are added to the group.

3. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker.

   $ sudo systemctl start docker
   

4. Verify that Docker EE is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker EE is installed and running. Use sudo to run Docker commands.

Architectures and storage drivers¶

Docker Engine - Enterprise supports Oracle Linux 64-bit, versions 7.3 and higher, running the Red Hat Compatible kernel (RHCK) 3.10.0-514 or higher. Older versions of Oracle Linux are not supported.

On Oracle Linux, Docker Engine - Enterprise only supports the devicemapper storage driver. In production, you must use it in direct-lvm mode, which requires one or more dedicated block devices. Fast storage such as solid-state media (SSD) is recommended.

Find your Docker EE repo URL¶

To install Docker EE, you will need the URL of the Docker EE repository associated with your trial or subscription:

1. Go to https://hub.docker.com/my-content. All of your subscriptions and trials are listed.
2. Click the Setup button for Docker Enterprise Edition for Oracle Linux.
3. Copy the URL from Copy and paste this URL to download your Edition and save it for later use.

You will use this URL in a later step to create a variable called, DOCKERURL.

Uninstall old Docker versions¶

The Docker Engine - Enterprise package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks.

$ sudo yum remove docker \
                  docker-engine \
                  docker-engine-selinux

Set up the repository¶

You only need to set up the repository once, after which you can install Docker Engine - Enterprise from the repo and repeatedly upgrade as necessary.

1. Remove existing Docker repositories from /etc/yum.repos.d/:

   $ sudo rm /etc/yum.repos.d/docker*.repo
   

2. Temporarily store the URL (that you copied above) in an environment variable. Replace <DOCKER-EE-URL> with your URL in the following command. This variable assignment does not persist when the session ends:

   $ export DOCKERURL="<DOCKER-EE-URL>"
   

3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

   $ sudo -E sh -c 'echo "$DOCKERURL/oraclelinux" > /etc/yum/vars/dockerurl'
   

4. Install required packages: yum-utils provides the yum-config-manager utility, and device-mapper-persistent-data and lvm2 are required by the devicemapper storage driver:

   $ sudo yum install -y yum-utils \
     device-mapper-persistent-data \
     lvm2
   

5. Enable the ol7_addons Oracle repository. This ensures access to the container-selinux package required by docker-ee.

   $ sudo yum-config-manager --enable ol7_addons
   

6. Add the Docker Engine - Enterprise stable repository:

   $ sudo -E yum-config-manager \
       --add-repo \
       "$DOCKERURL/oraclelinux/docker-ee.repo"
   

Install from the repository¶

1. Install the latest patch release, or go to the next step to install a specific version:

   $ sudo yum -y install docker-ee docker-ee-cli containerd.io
   

   If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

2. To install a specific version of Docker Engine - Enterprise (recommended in production), list versions and install:

   1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      $ sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      19.03.ee.2-1.el7.oraclelinuix     docker-ee-stable-18.09
      

      The list returned depends on which repositories you enabled, and is specific to your version of Oracle Linux (indicated by .el7 in this example).

   2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-18.09.1.

      $ sudo yum -y install docker-ee-<VERSION_STRING> docker-ee-cli-<VERSION_STRING> containerd.io
      

      For example, if you want to install the 18.09 version run the following:

      sudo yum-config-manager --enable docker-ee-stable-18.09
      

      Docker is installed but not started. The docker group is created, but no users are added to the group.

3. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker.

   $ sudo systemctl start docker
   

4. Verify that Docker Engine - Enterprise is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker Engine - Enterprise is installed and running. Use sudo to run Docker commands.

Install with a package¶

1. Go to the Docker Engine - Enterprise repository URL associated with your trial or subscription in your browser. Go to oraclelinux/. Choose your Oracle Linux version, architecture, and Docker version. Download the .rpm file from the Packages directory.

2. Install Docker Enterprise, changing the path below to the path where you downloaded the Docker package.

   $ sudo yum install /path/to/package.rpm
   

   Docker is installed but not started. The docker group is created, but no users are added to the group.

3. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker.

   $ sudo systemctl start docker
   

4. Verify that Docker Engine - Enterprise is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker Engine - Enterprise is installed and running. Use sudo to run Docker commands.

Upgrade with a package¶

1. Download the newer package file.
2. Repeat the installation procedure, using yum -y upgrade instead of yum -y install, and point to the new file.

Architectures and storage drivers¶

Docker EE supports Red Hat Enterprise Linux 64-bit, versions 7.4 and higher running on x86_64.

On Red Hat Enterprise Linux, Docker EE supports storage drivers, overlay2 and devicemapper. In Docker EE 17.06.2-ee-5 and higher, overlay2 is the recommended storage driver. The following limitations apply:

• OverlayFS: If selinux is enabled, the overlay2 storage driver is supported on RHEL 7.4 or higher. If selinux is disabled, overlay2 is supported on RHEL 7.2 or higher with kernel version 3.10.0-693 and higher.
• Device Mapper: On production systems using devicemapper, you must use direct-lvm mode, which requires one or more dedicated block devices. Fast storage such as solid-state media (SSD) is recommended.

FIPS 140-2 cryptographic module support¶

Federal Information Processing Standards (FIPS) Publication 140-2 is a United States Federal security requirement for cryptographic modules.

With Docker EE Basic license for versions 18.03 and later, Docker provides FIPS 140-2 support in RHEL 7.3, 7.4 and 7.5. This includes a FIPS supported cryptographic module. If the RHEL implementation already has FIPS support enabled, FIPS is also automatically enabled in the Docker engine.

To verify the FIPS 140-2 module is enabled in the Linux kernel, confirm the file /proc/sys/crypto/fips_enabled contains 1.

$ cat /proc/sys/crypto/fips_enabled
1

To enable FIPS 140-2 compliance on a system that is not in FIPS 140-2 mode, do the following:

Create a file called /etc/systemd/system/docker.service.d/fips-module.conf. Add the following:

[Service]
Environment="DOCKER_FIPS=1"

Reload the Docker configuration to systemd.

$ sudo systemctl daemon-reload

Restart the Docker service as root.

$ sudo systemctl restart docker

To confirm Docker is running with FIPS 140-2 enabled, run the docker info command.

docker info --format {{.SecurityOptions}}
[name=selinux name=fips]

Disabling FIPS 140-2¶

If the system has the FIPS 140-2 cryptographic module installed on the operating system, it is possible to disable FIPS 140-2 compliance.

To disable FIPS 140-2 in Docker but not the operating system, set the value DOCKER_FIPS=0 in the /etc/systemd/system/docker.service.d/fips-module.conf.

Reload the Docker configuration to systemd.

$ sudo systemctl daemon-reload

Restart the Docker service as root.

$ sudo systemctl restart docker

Find your Docker EE repo URL¶

To install Docker Enterprise, you will need the URL of the Docker Enterprise repository associated with your trial or subscription:

1. Go to https://hub.docker.com/my-content. All of your subscriptions and trials are listed.
2. Click the Setup button for Docker Enterprise Edition for Red Hat Enterprise Linux.
3. Copy the URL from Copy and paste this URL to download your Edition and save it for later use.

You will use this URL in a later step to create a variable called, DOCKERURL.

Uninstall old Docker versions¶

The Docker EE package is called docker-ee. Older versions were called docker or docker-engine. Uninstall all older versions and associated dependencies. The contents of /var/lib/docker/ are preserved, including images, containers, volumes, and networks.

$ sudo yum remove docker \
                  docker-client \
                  docker-client-latest \
                  docker-common \
                  docker-latest \
                  docker-latest-logrotate \
                  docker-logrotate \
                  docker-selinux \
                  docker-engine-selinux \
                  docker-engine

Set up the repository¶

You only need to set up the repository once, after which you can install Docker EE from the repo and repeatedly upgrade as necessary.

1. Remove existing Docker repositories from /etc/yum.repos.d/:

   $ sudo rm /etc/yum.repos.d/docker*.repo
   

2. Temporarily store the URL (that you copied above) in an environment variable. Replace <DOCKER-EE-URL> with your URL in the following command. This variable assignment does not persist when the session ends:

   $ export DOCKERURL="<DOCKER-EE-URL>"
   

3. Store the value of the variable, DOCKERURL (from the previous step), in a yum variable in /etc/yum/vars/:

   $ sudo -E sh -c 'echo "$DOCKERURL/rhel" > /etc/yum/vars/dockerurl'
   

   Also, store your OS version string in /etc/yum/vars/dockerosversion. Most users should use 7, but you can also use the more specific minor version, starting from 7.2.

   $ sudo sh -c 'echo "7" > /etc/yum/vars/dockerosversion'
   

4. Install required packages: yum-utils provides the yum-config-manager utility, and device-mapper-persistent-data and lvm2 are required by the devicemapper storage driver:

   $ sudo yum install -y yum-utils \
     device-mapper-persistent-data \
     lvm2
   

5. Enable the extras RHEL repository. This ensures access to the container-selinux package required by docker-ee.

   The repository can differ per your architecture and cloud provider, so review the options in this step before running:

   For all architectures except IBM Power:

   $ sudo yum-config-manager --enable rhel-7-server-extras-rpms
   

   For IBM Power only (little endian):

   $ sudo yum-config-manager --enable extras
   $ sudo subscription-manager repos --enable=rhel-7-for-power-le-extras-rpms
   $ sudo yum makecache fast
   $ sudo yum -y install container-selinux
   

   Depending on cloud provider, you may also need to enable another repository:

   For AWS (where REGION is a literal, and does not represent the region your machine is running in):

   $ sudo yum-config-manager --enable rhui-REGION-rhel-server-extras
   

   For Azure:

   $ sudo yum-config-manager --enable rhui-rhel-7-server-rhui-extras-rpms
   

6. Add the Docker EE stable repository:

   $ sudo -E yum-config-manager \
      --add-repo \
      "$DOCKERURL/rhel/docker-ee.repo"
   

Install from the repository¶

1. Install the latest patch release, or go to the next step to install a specific version:

   $ sudo yum -y install docker-ee docker-ee-cli containerd.io
   

   If prompted to accept the GPG key, verify that the fingerprint matches 77FE DA13 1A83 1D29 A418 D3E8 99E5 FF2E 7668 2BC9, and if so, accept it.

2. To install a specific version of Docker EE (recommended in production), list versions and install:

   1. List and sort the versions available in your repo. This example sorts results by version number, highest to lowest, and is truncated:

      $ sudo yum list docker-ee  --showduplicates | sort -r
      
      docker-ee.x86_64      19.03.ee.2-1.el7.rhel      docker-ee-stable-18.09
      

      The list returned depends on which repositories you enabled, and is specific to your version of Red Hat Enterprise Linux (indicated by .el7 in this example).

   2. Install a specific version by its fully qualified package name, which is the package name (docker-ee) plus the version string (2nd column) starting at the first colon (:), up to the first hyphen, separated by a hyphen (-). For example, docker-ee-18.09.1.

      $ sudo yum -y install docker-ee-<VERSION_STRING> docker-ee-cli-<VERSION_STRING> containerd.io
      

      For example, if you want to install the 18.09 version run the following:

      sudo yum-config-manager --enable docker-ee-stable-18.09
      

      Docker is installed but not started. The docker group is created, but no users are added to the group.

3. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker.

   $ sudo systemctl start docker
   

4. Verify that Docker EE is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker EE is installed and running. Use sudo to run Docker commands.

Upgrade from the repository¶

1. Add the new repository.
2. Follow the installation instructions and install a new version.

Install with a package¶

1. Enable the extras RHEL repository. This ensures access to the container-selinux package which is required by docker-ee:

   $ sudo yum-config-manager --enable rhel-7-server-extras-rpms
   

   Alternately, obtain that package manually from Red Hat. There is no way to publicly browse this repository.

2. Go to the Docker EE repository URL associated with your trial or subscription in your browser. Go to rhel/. Choose your Red Hat Enterprise Linux version, architecture, and Docker version. Download the .rpm file from the Packages directory.

   Note

   If you have trouble with selinux using the packages under the 7 directory, try choosing the version-specific directory instead, such as 7.3.

3. Install Docker EE, changing the path below to the path where you downloaded the Docker package.

   $ sudo yum install /path/to/package.rpm
   

   Docker is installed but not started. The docker group is created, but no users are added to the group.

4. Start Docker:

   Note

   If using devicemapper, ensure it is properly configured before starting Docker, per the storage guide.

   $ sudo systemctl start docker
   

5. Verify that Docker EE is installed correctly by running the hello-world image. This command downloads a test image, runs it in a container, prints an informational message, and exits:

   $ sudo docker run hello-world
   

   Docker EE is installed and running. Use sudo to run Docker commands. See Linux postinstall to allow non-privileged users to run Docker commands.

Docker EE URL¶

To install Docker Engine - Enterprise (Docker EE), you need to know the Docker EE repository URL associated with your trial or subscription. These instructions work for Docker on SLES and for Docker on Linux, which includes access to Docker EE for all Linux distributions. To get this information, do the following:

• Go to https://hub.docker.com/my-content.
• Each subscription or trial you have access to is listed. Click the Setup button for Docker Enterprise Edition for SUSE Linux Enterprise Server.
• Copy the URL from the field labeled Copy and paste this URL to download your Edition.

Use this URL when you see the placeholder text <DOCKER-EE-URL>.

OS requirements¶

To install Docker EE, you need the 64-bit version of SLES 12.x, running on the x86_64 architecture, s390x (IBM Z), or ppc64le (IBM Power) architectures. Docker EE is not supported on OpenSUSE.

The only supported storage driver for Docker EE on SLES is Btrfs, which is used by default if the underlying filesystem hosting /var/lib/docker/ is a BTRFS filesystem.

WARNING: IPv4 forwarding is disabled. Networking will not work.
docker: Error response from daemon: driver failed programming external
        connectivity on endpoint adoring_ptolemy
        (0bb5fa80bc476f8a0d343973929bb3b7c039fc6d7cd30817e837bc2a511fce97):
        (iptables failed: iptables --wait -t nat -A DOCKER -p tcp -d 0/0 --dport 80 -j DNAT --to-destination 172.17.0.2:80 ! -i docker0: iptables: No chain/target/match by that name.
 (exit status 1)).

Uninstall old versions¶

Older versions of Docker were called docker or docker-engine. If you use OS images from a cloud provider, you may need to remove the runc package, which conflicts with Docker. If these are installed, uninstall them, along with associated dependencies.

$ sudo zypper rm docker docker-engine runc

If removal of the docker-engine package fails, use the following command instead:

$ sudo rpm -e docker-engine

It’s OK if zypper reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved. The Docker EE package is now called docker-ee.

Install using the repository¶

Before you install Docker EE for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker from the repository.

Install from a package¶

If you cannot use the official Docker repository to install Docker EE, you can download the .rpm file for your release and install it manually. You need to download a new file each time you want to upgrade Docker.

1. Go to the Docker EE repository URL associated with your trial or subscription in your browser. Go to sles/12.3/ choose the directory corresponding to your architecture and desired Docker EE version. Download the .rpm file from the Packages directory.

2. Import Docker’s official GPG key.

   $ sudo rpm --import <DOCKER-EE-URL>/sles/gpg
   

3. Install Docker EE, changing the path below to the path where you downloaded the Docker package.

   $ sudo zypper install /path/to/package.rpm
   

   Docker is installed but not started. The docker group is created, but no users are added to the group.

4. Configure Docker to use the Btrfs filesystem. This is only required if the ``/`` filesystem is not using Btrfs. However, explicitly specifying the storage-driver has no harmful side effects.

   Edit the file /etc/docker/daemon.json (create it if it does not exist) and add the following contents:

   {
     "storage-driver": "btrfs"
   }
   

   Save and close the file.

5. Start Docker.

   $ sudo service docker start
   

6. Verify that Docker is installed correctly by running the hello-world image.

   $ sudo docker run hello-world
   

   This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Docker EE is installed and running. You need to use sudo to run Docker commands.

System requirements¶

To learn more about software requirements and supported storage drivers, check the compatibility matrix.

Uninstall old versions¶

If your version supports the aufs storage driver, you need some preparation before installing Docker.

$ sudo apt-get remove docker docker-engine docker-ce docker-ce-cli docker.io

It’s OK if apt-get reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are preserved. The Docker EE package is now called docker-ee.

$ sudo apt-get update

  $ sudo apt-get install \
     linux-image-extra-$(uname -r) \
     linux-image-extra-virtual
  

Install using the repository¶

Before you install Docker EE for the first time on a new host machine, you need to set up the Docker repository. Afterward, you can install and update Docker EE from the repository.

Install from a package¶

If you cannot use Docker’s repository to install Docker EE, you can download the .deb file for your release and install it manually. You need to download a new file each time you want to upgrade Docker EE.

1. Go to the Docker EE repository URL associated with your trial or subscription in your browser. Go to ubuntu/x86_64/stable-<VERSION> and download the .deb file for the Docker EE version and architecture you want to install.

2. Install Docker, changing the path below to the path where you downloaded the Docker EE package.

   $ sudo dpkg -i /path/to/package.deb
   

   The Docker daemon starts automatically.

3. Verify that Docker is installed correctly by running the hello-world image.

   $ sudo docker run hello-world
   

   This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

Docker EE is installed and running. The docker group is created but no users are added to it. You need to use sudo to run Docker commands.

Hardware and software requirements¶

You can install UCP on-premises or on a cloud provider. Common requirements:

• Docker Engine - Enterprise
• Linux kernel version 3.10 or higher. For debugging purposes, it is suggested to match the host OS kernel versions as close as possible.
• A static IP address for each node in the cluster
• User namespaces should not be configured on any node. This function is not currently supported by UCP.

Ports used¶

When installing UCP on a host, a series of ports need to be opened to incoming traffic. Each of these ports will expect incoming traffic from a set of hosts, indicated as the “Scope” of that port. The three scopes are: - External: Traffic arrives from outside the cluster through end-user interaction. - Internal: Traffic arrives from other hosts in the same cluster. - Self: Traffic arrives to that port only from processes on the same host.

Make sure the following ports are open for incoming traffic on the respective host types:

Disable CLOUD_NETCONFIG_MANAGE for SLES 15¶

For SUSE Linux Enterprise Server 15 (SLES 15) installations, you must disable CLOUD_NETCONFIG_MANAGE prior to installing UCP.

1. In the network interface configuration file, `/etc/sysconfig/network/ifcfg-eth0`, set
```
CLOUD_NETCONFIG_MANAGE="no"
```
2. Run `service network restart`.

Enable ESP traffic¶

For overlay networks with encryption to work, you need to ensure that IP protocol 50 (Encapsulating Security Payload) traffic is allowed.

Enable IP-in-IP traffic¶

The default networking plugin for UCP is Calico, which uses IP Protocol Number 4 for IP-in-IP encapsulation.

If you’re deploying to AWS or another cloud provider, enable IP-in-IP traffic for your cloud provider’s security group.

Enable connection tracking on the loopback interface for SLES¶

Calico’s Kubernetes controllers can’t reach the Kubernetes API server unless connection tracking is enabled on the loopback interface. SLES disables connection tracking by default.

On each node in the cluster:

sudo mkdir -p /etc/sysconfig/SuSEfirewall2.d/defaults
echo FW_LO_NOTRACK=no | sudo tee /etc/sysconfig/SuSEfirewall2.d/defaults/99-docker.cfg
sudo SuSEfirewall2 start

Timeout settings¶

Make sure the networks you’re using allow the UCP components enough time to communicate before they time out.

Time Synchronization¶

In distributed systems like UCP, time synchronization is critical to ensure proper operation. As a best practice to ensure consistency between the engines in a UCP cluster, all engines should regularly synchronize time with a Network Time Protocol (NTP) server. If a server’s clock is skewed, unexpected behavior may cause poor performance or even failures.

Compatibility and maintenance lifecycle¶

Docker Enterprise is a software subscription that includes three products:

• Docker Engine - Enterprise with enterprise-grade support
• Docker Trusted Registry
• Universal Control Plane

Version compatibility¶

UCP 3.1.8 requires minimum versions of the following Docker components:

• Docker Enterprise Engine 18.09.0-ee-1 or higher
• DTR 2.6 or higher

System requirements¶

Before installing UCP, make sure that all nodes (physical or virtual machines) that you’ll manage with UCP:

• Comply with the system requirements, and
• Are running the same version of Docker Engine.

Hostname strategy¶

UCP requires Docker Enterprise. Before installing Docker Enterprise on your cluster nodes, you should plan for a common hostname strategy.

Decide if you want to use short hostnames, like engine01, or Fully Qualified Domain Names (FQDN), like node01.company.example.com. Whichever you choose, confirm your naming strategy is consistent across the cluster, because Docker Engine and UCP use hostnames.

For example, if your cluster has three hosts, you can name them:

node1.company.example.com
node2.company.example.com
node3.company.example.com

Static IP addresses¶

UCP requires each node on the cluster to have a static IPv4 address. Before installing UCP, ensure your network and nodes are configured to support this.

Avoid IP range conflicts¶

The following table lists recommendations to avoid IP range conflicts.

{
   "default-address-pools": [
         {"base":"172.17.0.0/16","size":16}, <-- docker0
         {"base":"172.18.0.0/16","size":16}, <-- docker_gwbridge
         {"base":"172.19.0.0/16","size":16},
         {"base":"172.20.0.0/16","size":16},
         {"base":"172.21.0.0/16","size":16},
         {"base":"172.22.0.0/16","size":16},
         {"base":"172.23.0.0/16","size":16},
         {"base":"172.24.0.0/16","size":16},
         {"base":"172.25.0.0/16","size":16},
         {"base":"172.26.0.0/16","size":16},
         {"base":"172.27.0.0/16","size":16},
         {"base":"172.28.0.0/16","size":16},
         {"base":"172.29.0.0/16","size":16},
         {"base":"172.30.0.0/16","size":16},
         {"base":"192.168.0.0/16","size":20}
   ]
}

{
   "default-address-pools": [
         {"base":"172.17.0.0/16","size":16}, <-- Modify this value
         {"base":"172.18.0.0/16","size":16},
         {"base":"172.19.0.0/16","size":16},
         {"base":"172.20.0.0/16","size":16},
         {"base":"172.21.0.0/16","size":16},
         {"base":"172.22.0.0/16","size":16},
         {"base":"172.23.0.0/16","size":16},
         {"base":"172.24.0.0/16","size":16},
         {"base":"172.25.0.0/16","size":16},
         {"base":"172.26.0.0/16","size":16},
         {"base":"172.27.0.0/16","size":16},
         {"base":"172.28.0.0/16","size":16},
         {"base":"172.29.0.0/16","size":16},
         {"base":"172.30.0.0/16","size":16},
         {"base":"192.168.0.0/16","size":20}
   ]
}

{
  "fixed-cidr": "172.17.0.0/16",
}

{
  "bip": "172.17.0.0/16",
}