Roadmap: [Docker Hub] Official REST API

[pkennedyr]

Tell us about your request
Official REST API for Docker Hub

Which service(s) is this request for?
Docker Hub

Tell us about the problem you're trying to solve. What are you trying to do, and why is it hard?
Hub customers have cited a desire to have an officially supported REST API for programmatically performing common Hub operations relating to repositories, organizations, teams, users, search, etc.

Are you currently working around this issue?
N/A

Additional context
N/A

Attachments
N/A

[mgreau]

Hi @pkennedyr

Publishing the Docker images to the store via the Publisher Center is only doable manually today, as far as I know.

It would be great to be able to do this via this REST API.
Would it be part of this work?

Thanks

[pkennedyr]

Hi @mgreau,

Indeed, the Official REST API would also encompass core publisher activities. However, would you mind adding a separate Publisher API issue/request to ensure any publisher-specific use cases that you have in mind are addressed?

Thanks,
Ryan

[ingshtrom]

As part of this, it would be absolutely fantastic to also release a Terraform provider to support this. I'm not sure what % of Docker Hub users use Terraform, but I think it's likely that operators of teams using Docker Hub would really enjoy this.

[pkennedyr]

What class of APIs would the Hub community ideally like to see prioritized first (e.g. repositories, organizations, teams, users, search, etc.)?

[seemethere]

For our workflows it'd be incredibly useful to have team management (and to a greater extent organization management) implemented for Docker Hub.

It's currently a pain to add / remove users from our teams and to do any kind of auditing around who should / should not be part of our current docker hub organizations.

[manishtomar]

As part of this, it would be absolutely fantastic to also release a Terraform provider to support this. I'm not sure what % of Docker Hub users use Terraform, but I think it's likely that operators of teams using Docker Hub would really enjoy this.

@ingshtrom Just curious: what would the terraform provider help provision? Hub resources like repositories, teams, permissions? For what use case is reproducibility of these resources useful?

[ingshtrom]

@manishtomar

I would think it could provision whatever is available through the official API.

I think there are a few forms of reproducibility we could talk about. First, reproducing a whole set up from scratch--in this case, it isn't nice to be able to re-spin up your organization and repos from scratch as it should be safe to assume that Docker Hub can handle that data and won't lose it.

The second form of reproducibility is within the same environment across the same resources that change slowly over time. So for example, you have an organization that has 100 users with 200 repositories in it. As time goes on, users come and go, users change teams, applications evolve to include more parts, and older applications are deprecated. These are changes that pile up over time and having it in Terraform, presumably in a version control system, means you have an audit trail that can easily be looked at to see what has happened, how you did something in the past, etc.

It's really the same reason you would use Terraform (or any IAC, really) for anything. Another example I had heard of with using Terraform was with PagerDuty. This team spun up new teams/schedules/api integrations/etc that were configured in a similar way so it was known across the organization that no matter what team dealt with PagerDuty, you knew it was set up similarly.

Hopefully that helps?

[olegburov]

@manishtomar, regarding Alex's idea. Something like this: https://auth0.com/blog/use-terraform-to-manage-your-auth0-configuration/

Probably it worth to move it into a separate issue.

[nanoz]

Hi !

Thanks for prioritizing this on the roadmap 😊

As part of a new service bootstrap, all of our workflow to get from code to prod is automated, except for new Docker Hub images declaration, where we have to go on the interface and change the permissions set in order for developers to use the repository. So an image permissions setting accessible via an API endpoint could be great, along with users management.

A terraform provider at least to manage users, groups and to manage images lifecycle sure would be nice too !

[christian-korneck]

@pkennedyr

Tell us about the problem you're trying to solve.
What are you trying to do

I would like to update a repo's short and full descriptions (README).
(I maintain and use a small tool for that purpose).

and why is it hard?

currently the only way I'm aware of doing this for Docker Hub is using an undocumented API that doesn't support login via personal access tokens (only username/password, which only work when 2FA auth is disabled). I would wish for an officially supported REST API that allows to update the repo's description that works for all users, no matter if they have 2FA auth enabled or not.

[jfarraraains]

These ideas are great, but REST API is not complete for many without WebHooks. REST is on request responses. WebHooks are on event responses to outside targets. These should be able to be configured via REST also of course.

[yanjost]

As stated in docker/hub-feedback#2044 having access to the vulnerabilities list and details would be of great help. I am OK to give some feedback on this API part if you have a prototype in mind

[gesellix]

In addition to access the vulnarabilities list, we'd like to enable image scanning via API - or at least get a list with an indicator whether image scanning is enabled for a repository.

[zephinzer]

vulnerabilities list would be awesome so that we don't have to pull images from docker hub just to scan it with an internal tool- also, updating a repo's description via api would help with keeping docs in-sync between the code repository and the image repository