Introduction
Docker Registry is a stateless, scalable server-side application that stores and lets you distribute Docker images. With version 2 of the registry (Registry v2), significant enhancements were introduced over its predecessor (Registry v1). Among these improvements are security features and a streamlined API. This tutorial aims to guide you through retrieving a list of images stored in your Docker Registry v2 instance, highlighting how to navigate its enhanced catalog API effectively.
Understanding Docker Registry v2
Before diving into commands and code snippets, it’s essential to comprehend the structure and capabilities of Docker Registry v2:
-
Security: Registry v2 is designed with security as a priority. It supports HTTPS by default and requires authentication for certain operations.
-
API Structure: The API is RESTful, with endpoints that are intuitive if you’re familiar with HTTP methods like GET, POST, PUT, DELETE.
-
Pagination: To handle large datasets efficiently, Registry v2 implements pagination in its responses.
Listing Images from Docker Registry v2
Unlike the previous version, where a simple GET request to /v1/search? would list images, Registry v2 introduces a new endpoint for accessing this information: _catalog. This section will walk you through using this API effectively.
Accessing the Catalog Endpoint
To retrieve a list of repositories (effectively, a list of image names), you can make a GET request to /v2/_catalog.
Basic Command:
curl -X GET https://myregistry:5000/v2/_catalog
Expected Response:
{
"repositories": ["redis", "ubuntu"]
}
Handling Authentication
If your registry requires authentication, you need to include credentials in your request:
curl -X GET -u <user>:<pass> https://myregistry:5000/v2/_catalog
This command prompts for a username and password or uses the provided ones.
Managing Pagination
By default, Registry v2 limits responses to 100 entries. To retrieve more, you can adjust this with the ?n= query parameter:
curl https://myregistry:5000/v2/_catalog?n=1000
If you encounter a response that indicates more data is available (via the Link header), follow it to fetch additional pages in a loop until all data is retrieved.
Listing Tags for Each Repository
After obtaining repository names, you can list tags associated with each image by using:
curl -X GET https://myregistry:5000/v2/<repository>/tags/list
Example for ‘ubuntu’ repository:
curl -X GET https://myregistry:5000/v2/ubuntu/tags/list
Response:
{
"name": "ubuntu",
"tags": ["14.04", "18.04"]
}
Using Self-Signed Certificates
For secure HTTPS connections, especially in environments using self-signed certificates, ensure your requests include the certificate:
curl --cacert /path/to/domain.crt https://myregistry:5000/v2/_catalog
Ensure that the domain in your URL matches the one specified in your certificate.
Conclusion
Docker Registry v2 enhances security and offers a more robust API for managing Docker images. By understanding how to navigate its catalog endpoint, authenticate requests, handle pagination, and manage secure connections, you can effectively utilize this tool for image distribution in development and production environments. This tutorial should empower you to adapt your workflows to leverage these capabilities fully.