...
There are two points of integration with Synapse: (1) notification when a new repository is created, updated, etc., (2) request to authorize an operation on a repository. When a new Docker repository is created an object will be created in the repository services. This object will be related to an ACL which can be edited by the repository owner or other authorized Synapse users. When an authorization request comes in, the ACL is used to approve or deny the request.
There are three choices for representing repositories in Synapse: (1) as a variation of a file, (2) as a new kind of Entity, (3) as a new non-Entity object. The first two options have serious problems: If a repository is a kind of file then the semantics of a file as a document or stream of bytes breaks down. Clients need extra logic that says they cannot expect to do an 'HTTP GET' (for example) on such a file. Docker repositories cannot be entities because we cannot expose Create and Delete operations. The repository objects in Synapse must mirror those in the Docker registry. This means that objects can only be created and deleted as notifications about such events are received from the Docker registry.
Note: We can allow MULTIPLE Docker registries to delegate authorization to Synapse by ensuring Synapse includes the registry 'host' in the repository object.
...
Docker images are organized into repositories. A repository reference has five three parts: host, port, user and repository registry host (CNAME or IP address with optional port), repository path, and tag, e.g.
index.docker.io:5000/unameusername/reponame:v1
All fields are optional except 'reponame'. If the registry host and port are is omitted then the docker client assumes it is a reference to Dockerhub. Certain official images lack a user name (e.g. 'ubuntu')DockerHub. Each repository has a series of commits, identified by a digest (currently SHA256). Users may also define tags which name commits. These tags are mutable, they do not permanently reference a specific commit. When a repository reference omits a tag, the default tag "latest" is assumed.
...
Container: A running virtual machine, started from an image.
User Experience
docker build -t docker.synapse.org/syn1234567/myrepo .
docker login docker.synapse.org
username: mysynuser
password: xxxxxx
docker push docker.synapse.org/syn1234567/myrepo
Will now appear in Synapse under (Project or Folder) syn1234567. See https://app.moqups.com/bruce.hoff@sagebase.org/HY2x6MNWXo/view/page/a406bb9f1
Cannot be moved or renamed.
Once shared with other users, they can:
docker pull docker.synapse.org/syn1234567/myrepo
docker tag docker.synapse.org/syn1234567/myrepo docker.synapse.org/syn9876543/someotherrepo
docker push docker.synapse.org/syn9876543/someotherrepo
Now it will appear under syn9876543
Schemas:
Docker Repository Schema:
DockerRepository extends Entity
- name (registryhost/reponamerepopath)
metadataprovider EntityValidator validates format and that, for managed external/unmanaged repo's, the name starts with the parent entity id, that external repos' registryhosts don'registryhost doesn't violate the blacklist
- list of tag/digest pairs
digests must be unique
tags are optional but must be unique
for .
For managed repo's the list can't be edited by the user'repopath' must start with the Synapse ID of a container (folder or project)
- isManaged: says whether this repository is managed by Synapse or is a reference to an external registry.
We have a 'white list' of registry hosts for which we answer authorization requests and a 'reserved' list of registry hosts for which external repositories can't be created. (This allows us to reserve address spaces for the future. E.g. the white list could contain docker.synapse.org:443 and the reserved list *.synapse.org.)
DockerCommit:
Each Repository has a list of 'commits'. For external repo's the user must provide them. For managed repo's commits are added based on 'push' events received by the listener.
- tag e.g. "v1" Is optional and must be unique for a docker repository
- digest: e.g. "SHA256:a68df63..." Is required and must be unique for a docker repository
Will provide a service to retrieve a repo based on its hash.
Services:
Create, Update and Delete entity: not allowed for entities which are 'managed', i.e. their host field matches that of a managed repo.
...
| Description | URI | Method | Request Parameters | Request Body | Response Body | |||||
|---|---|---|---|---|---|---|---|---|---|---|
Authorization Request | /bearerToken | GET | service, scope | -- | BearerToken | |||||
| Post a registry event. This will create or delete repository objects in Synapse. | /registryEvent | POST | -- | Event | Add a commit to an external repository. (Also changes modifiedBy, modifiedOn for the entity.) | /entity/{id}/dockerCommit | POST | -- | DockerCommit | -- |
| Get the commits for a repository. | /entity/{id}/dockerCommit | GET | -- | -- | DockerCommitList | |||||
| Get Docker password for a Docker registry. (System will generate automatically.) | /dockerPassword | GET | registryHost | -- | Password | |||||
| Invalidate password for a Docker registry. | /dockerPassword | DELETE | registryHost | -- | -- |
org.sagebionetworks.repo.model.oauth.BearerToken: defined here: https://docs.docker.com/registry/spec/auth/jwt/
...
Details
Authorization Request
if the user making the request is the user specified in the repository reference or a member of the team made in a team reference, the access is approved;
If the repository is not represented in Synapse then deny the request, else answer the authorization question using the ACL associated with the project which is the prefix of requested repository. (Note: We can leverage existing Governance mechanisms by requiring 'download' access level in order to 'pull' a repository.)
...
Synapse will create, update and delete its representation of a Docker repository in response to received registry events.
Open questions:
- OK to have a Docker-Synapse password different from the user's Synapse password (or API key)? Answer: YES
- Is it OK for Docker Repo's to have Folders as parents or just Projects? Answer: JUST PROJECTS