Docker Community Forums

Share and learn in the Docker community.

Upgrading Docker Hub Enterprise to Docker Trusted Registry


(Andy Rothfusz) #1

Migrating from DHE 1.0 to DTR 1.1

Docker Hub Enterprise (DHE) is now called Docker Trusted Registry (DTR).

Because of major changes in DTR 1.1, automatic upgrading has been disabled. You will need to perform a few steps to make your DHE 1.0 configuration settings and data compatible with DTR 1.1. You will first collect needed data from your existing 1.0 instance. You will then install DTR (which will over-write your existing data) and then modify settings and data for compatibility with the data you collected as described below.

Stop DHE

First, stop your instance of DHE with: sudo bash -c "$(sudo docker run dockerhubenterprise/manager stop)".

Stopping DHE will close the connection on any pushes and pulls that are currently running, but these can be restarted when the upgrade is complete.

Migrate Settings & Data

Most of your DHE configuration settings and data will be migrated automatically to DTR. However, since authentication settings have been expanded to allow for more flexibility for role-based access control features, you may need to manually migrate your auth data. In most cases, registry storage settings will not need to be manually updated. However, if you are using a separate storage device to store your Docker images, you will need to change the mount point.

Migrating Auth settings

If you haven’t set up any access control for DHE (that is, you chose the ‘None’ option from the “Authentication Method” drop-down on the Authentication Settings Admin page), you don’t need to take any further action. If you are using either the ‘Basic’ or ‘LDAP’ method, please read the corresponding section for migrating data for each auth method below.

Migrating Basic Auth settings

In DTR 1.1, the user auth database has been migrated from SQLite to a new PostgreSQL database running in a container along with all other DTR services. Because the database cannot be automatically migrated, you must manually all usernames and (re)set all passwords after you’ve installed DTR 1.1. You will need to retrieve the data from your current file, store it temporarily while you install DTR (which will over-write your existing data), and then add the data back in.

Note that because passwords are secured, they can’t be migrated and must be re-set.

The basic auth users database file can be found on the host at:

/var/local/dhe/databases/auth.db

To access the list of users, you will need to install sqlite3 on this host.

To list the users’ names, run the following command:

sqlite3 /var/local/dhe/databases/auth.db "SELECT username FROM users;"

Optionally, you can add ORDER BY username to display the list alphabeticially. This command will output all usernames, one per line. Save this list so that you can manually enter it into the new “Managed Auth” settings page in DTR 1.1.

If you need to see which users had admin privileges in your instance of DTR 1.0.0, view the white list at /usr/local/etc/dhe/garant.yml in the auth: sq: [...] name:admins section.

Migrating LDAP Auth settings

LDAP settings have also been changed to allow for the changes to user roles. Since DTR 1.1 changes how these settings are stored, they must be re-entered after upgrading to DTR 1.1. You will need to retrieve the data from your current file, store it temporarily while you install DTR (which will over-write your existing data), and then add the data back in.

Your LDAP auth settings for DHE 1.0 are stored in a configuration file at:

/usr/local/etc/dhe/garant.yml

This file will have an “auth” section in YAML syntax similar to this:

auth:
  ldap:
    groups:
    - access_sets:
        '*':
        - pull
        - push
      name: users
      search_filter: (|(uid=euler)(uid=newton)(uid=euclid)(uid=gauss))
      user_whitelist: []
    - access_sets:
        '*':
        - pull
        - push
      name: admins
      search_filter: ""
      user_whitelist:
      - euler
      - newton
    reader_dn: cn=read-only-admin,dc=example,dc=com
    reader_password: password
    server_url: ldap://ldap.forumsys.com
    start_tls: true
    user_base_dn: dc=example,dc=com
    user_login_attr_name: uid

From this data, you can retrieve settings such as server_url, start_tls, reader_dn, reader_password, user_base_dn, and user_login_attr_name. If you have configured a global user filter, it will be under auth.ldap.groups. This field contains a list of any “users” and “admins” filters you may have configured in the search_filter field.

Similarly, if you configured a whitelist of admin users, these values will be in a list in the
user_whitelist field for the “admins” group.

Take note of these values so you can reset them when you configure LDAP Authentication in DTR 1.1.

Note: If you were using a username whitelist for admin users, you will need to convert this into a filter in DTR 1.1. You can do this with a logical OR filter, e.g., “(|(uid=euler)(uid=newton))” in the above example.

Migrating registry storage settings

If you are using the local filesystem to store image data in DHE 1.0 and the data is stored on a separate device mounted at /var/local/dhe/image-storage, then you will need to update your fstab file to mount this device at the new location in DTR 1.1: /var/local/dtr/image-storage.

Install DTR and transfer data

Ensuring that your DHE instance is still stopped, perform an ordinary installation of DTR by following the installation instructions. Once installation is complete, enter the data you collected into the appropriate database at /var/local/dtr/databases or re-enter your LDAP settings on the Settings > Authentication page.