From Fedora Project Wiki

< Changes

Revision as of 19:05, 7 September 2016 by Bowlofeggs (talk | contribs) (→‎Mirror List: Document changes to mirror list)


Fedora Scale-Out Docker Registry

Summary

This is a proposal for a change to the Fedora Infrastructure and Fedora Release Engineering tooling to provide a scalable Docker Registry solution for Fedora that is integrated with the Fedora Docker Layered Image Build Service.

Owner

  • Name: Adam Miller and Randy Barlow
  • Email: maxamillion@fedoraproject.org and bowlofeggs@fedoraproject.org
  • Release notes owner:

Current status

Detailed Description

   +--+--------+               +------------------------+
   |  koji     +^--------------+ fedpkg container build +
   +--+---+----+               +------------------------+
      |   ^
      ^   |
   +--+---+----+
   |           |          +----------------------+
   |   OSBS    |          | docker/distribution  |
   |           +---------^+ registry             |
   +-----------+          |                      |
                          | (candidate builds)   |
                          +---------------+-------
                                          |
                                          |
                                          |
                                          |
                                          |
                                          |
                                          |
                               +----------v----------+
                               |                     |
                               | Small Python script |
                               |                     |
                               +----------+----------+
                                          |
                                          |
                                          |
                                          |
                                          |
                                          |
                                          |
+----------------+              +---------v----------+
|                |              | Mirror Manager     |
|  Mirror list   |              | master mirror      |
|                |              +-----------------+--+
+----+----+------+                                |
     ^    |                                       |
     |    |                                       |
     |    |                                       |
     |    |                                       ^
     |    |                             +---------+-------------------+
     |    |                             |                             |
     |    |   +------------------------^+ "Mirror Network"            |
     |    |   |                         | (All our ^olunteer mirrors) |
     |    |   |   +---------------------+                             |
     |    |   |   |                     +-----------------------------+
     |    |   |   |
     |    |   |   |
     |    |   |   |
     |    |   |   |
     |    |   |   |
     |    ^   |   ^
  +--+----+---+---+-+
  | Users           |
  | (docker pull)   |
  +-----------------+

Background

The Fedora project wishes to begin distributing new types of content than it has in the past. One of the types that has been identified as a goal is the Docker image. Adam Miller has already done the work that will allow packagers to build Docker images, but we still need a way to distribute those builds to Fedora's users. Adam Miller's implementation helpfully drops the builds we want into a Docker registry.

registry: a collection of docker image repositories

repository: named after an image and is a collection of multiple tags of an that image

tag: an arbitrary string assigned to a specific docker image (identified by the image's sha256 checksum) NOTE: The "latest" tag is special and is assumed if no tag is provided. This is true also for a 'docker pull' operation and an image tagged "latest" will be the default image pulled by users.

Proposal

In summary, the proposal is to work with @runcom[5][6] to write a patch for the docker client that will give it the capability to use the Docker Manifest schema 2 urls feature[7] during docker pull operations. We would also need to add support for Docker images to mirror list and mirror manager. Additionally, we will need a small tool to pull the content to be mirrored out of a docker registry and write them to disk in a format that can be mirrored, as well as some Ansible code to run the tool when there is new content to be mirrored.

  • MirrorManager is what Fedora uses to manage the public mirror network and distribute content.
  • Docker Distribution is the defacto standard open source implementation of the Docker Registry V2 API spec. It provides many features but the ability to have it's back-end storage be provided by a "mirror network" much like the one Fedora has at it's disposal is not one of them. The reason we need this in place is because the mechanism by which you could push a docker image directly to Pulp in Docker Registry v1 no longer exists in v2 so we must instead perform a "sync" operation between the two. (This is a common problem for all known "third party" v2 registry implementations).

Workflow

  • OSBS will perform Builds, as these builds complete they will be pushed to the docker-distribution (v2) registry, these will be considered "candidate images". These will be stored in candidate repositories on the docker-distribution registry.
  • Testing will occur using the "candidate images" (details of how we want to handle that are outside the scope of this proposal).
  • A "candidate image" will be marked stable once it's criteria have been satisfied to do so. (This is vague because this is a topic of ongoing discussion and work to decide what criteria an image will need to abide by before being considered "stable" and promoted as such)
  • Once stable, the images will be pushed into stable repositories in the docker-distribution registry.
  • The new Python tool will split that content and sync the image layers along with their metadata to Mirror Manager master mirror. It will also sync the repo metadata to somewhere Mirror List can pick it up.
  • Mirror Manager will distribute to the mirrors the image layers.
  • The docker clients will request Manifests from Mirror List. Mirror list will return schema 2 Manifests that contain lists of URLs to the mirrors where the client can retrieve the blobs.

Mirror List

Users will be pointing their docker clients at Mirror List when they docker pull Fedora's Docker images. In order for this to work, we will need to make two changes to Mirror List so that it can respond to the docker client properly. The first change is that Mirror List will need to respond with a special header and a body of "{}" when the docker client sends a GET request for /v2/. The second change is that it will need to return a Docker Manifest schema 2 document containing a list of mirrors that have the requested blobs when the client makes additional requests, so that the clients can be retrieve the blobs from a list of mirrors near their locations, similar to how it does with the dnf client today.

The docker client typically connects to port 5000. We could run a second instance of Mirror List on port 5000 if we wanted to isolate it from the current instance. We can also have the docker client pull from 443 as dnf does if we want to keep the deployment simpler.

Mirror Manager

docker

New Tool

Signing

Optional Mirror Registries

General Notes

A couple of things to note about maintenance and uptime considerations:

The Intermediate docker-distribution registry is needed for builds in koji+OSBS.

Much of the current design was discussed on the infrastructure mailing list[1].

All new components in this design should be able to be locked down, similar to the "Fedora internal" components like koji (builders, etc) and bodhi (signing, etc).

Benefit to Fedora

This will allow for Fedora to provide packages, software, and other content in the form of a Docker Image as an officially released artifact from the Fedora Project that is released and hosted much in the same way RPMs are today. These images can then be included in the distribution in various ways. This could potentially be used by the Modularization effort or by any other part of the Fedora.next initiative that may arise.

Scope

Proposal owners

Proposal owners shall have to:

  • Implement the proposed Design of a Scaled-Out Docker Registry
    • Build the new Python Tool to pull blobs out of the registry
    • Deploy Docker-Distribution Registry
    • Integrate with MirrorManager for content distribution
  • Document the system

Task matrix

This is a RACI matrix for tasks required to implement the RelEng Automation Workflow Engine. Work is tracked in Taiga: http://taiga.cloud.fedoraproject.org/project/acarter-fedora-docker-atomic-tooling/wiki/home


Is this current?

It is, as of 2016-09-07

Definitions

Here, we're using what Wikipedia calls "RACI (alternative scheme)":


Responsible
The person responsible for the performance of the task. There should be exactly one person with this assignment for each task.
Assists
Those who assist completion of the task.
Consulted
Those whose opinions are sought; and with whom there is two-way communication.
Informed
Those who are kept up-to-date on progress; and with whom there is one-way communication.

Task Table

Note.png
This an early cut. Please feel free to add new tasks as appropriate — just let one of the coordinators know.
Task Subtask Responsible Assists Consulted Informed Current Status
Implement the proposed design of a Scaled-Out Docker Registry Adam Miller 0%
Deploy solution, including ansible playbooks added for Fedora Infrastructure Ansible repo Adam Miller 0%
Deploy docker-distribution registry Adam Miller 0%
Integrate with MirrorManager for content distribution Adam Miller 0%
Document the system Adam Miller 0%

Glossary of Nicknames

Various Task Notes

Functional Requirements

The following features are functional requirements

  • Users must be able to perform a
    docker pull registry.fedoraproject.org/fedora
    and have the actual image layer data come from a local mirror via mirrormanager.

Other developers

  • (anything here)?

Upgrade/compatibility impact

N/A (not a System Wide Change)

How To Test

Once the service is deployed, users can perform the following on their systems to test.

$ dnf -y install docker
$ systemctl start docker
$ docker pull registry.fedoraproject.org/fedora

N/A (not a System Wide Change)

User Experience

N/A (not a System Wide Change)

Dependencies

N/A (not a System Wide Change)

Contingency Plan

  • Contingency mechanism: (What to do? Who will do it?) N/A (not a System Wide Change)
  • Contingency deadline: N/A (not a System Wide Change)
  • Blocks release? No (not a System Wide Change)
  • Blocks product? N/A

Documentation

FIXME

Release Notes