Skip to content

prune998/docker-registry-client

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

56 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Docker Registry Client

An API client for the V2 Docker Registry API, for Go applications.

Imports

import (
    "github.com/heroku/docker-registry-client/registry"
    "github.com/docker/distribution/digest"
    "github.com/docker/distribution/manifest"
    "github.com/docker/libtrust"
)

Creating A Client

url      := "https://registry-1.docker.io/"
username := "" // anonymous
password := "" // anonymous
hub, err := registry.New(url, username, password)

Creating a registry will also ping it to verify that it supports the registry API, which may fail. Failures return non-nil err values.

Authentication supports both HTTP Basic authentication and OAuth2 token negotiation.

Listing Repositories

repositories, err := hub.Repositories()

The repositories will be returned as a slice of strings.

Listing Tags

Each Docker repository has a set of tags -- named images that can be downloaded.

tags, err := hub.Tags("heroku/cedar")

The tags will be returned as a slice of strings.

Deleting Tags

To delete a tag

tags, err := hub.Tags("heroku/cedar")
err = hub.DeleteTags("heroku/cedar", tags[0])

Downloading Manifests

Each tag has a corresponding manifest, which lists the layers and image configuration for that tag.

manifest, err := hub.Manifest("heroku/cedar", "14")

Schema V2

manifest, err := hub.ManifestV2("heroku/cedar", "14")

The returned manifest will be a manifest.SignedManifest pointer. For details, see the github.com/docker/distribution/manifest library.

Retrieving Manifest Digest

A manifest is identified by a digest.

digest, err := hub.ManifestDigest("heroku/cedar", "14")

The returned digest will be a digest.Digest. See github.com/docker/distribution/digest.

Retrieving "Image" Digest

An Image is identified by a digest. You can't search an image Digest if it have no tags, so use this instead :

digests, err := hub.Images("heroku/cedar")

The returned variable is a hash of string ([]string) representing all the digests.

To convert them to digest digest.Digest, use imageDigest, err := digest.Parse(imageDigestStr). See github.com/docker/distribution/digest.

Deleting Manifest

To delete a manifest

digest, err := hub.ManifestDigest("heroku/cedar", "14")
err = hub.DeleteManifest("heroku/cedar", digest)

Please notice that, as specified by the Registry v2 API, this call doesn't actually remove the fs layers used by the image.

Downloading Layers

Each manifest contains a list of layers, filesystem images that Docker will compose to create containers.

// or obtain the digest from an existing manifest's FSLayer list
digest := digest.NewDigestFromHex(
    "sha256",
    "a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
)
reader, err := hub.DownloadLayer("heroku/cedar", digest)
)
if reader != nil {
    defer reader.Close()
}
if err != nil {
    return err
}

Uploading Layers

This library can also publish new layers:

digest := digest.NewDigestFromHex(
    "sha256",
    "a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4",
)
exists, err := hub.HasLayer("example/repo", digest)
)
if err != nil {
    // …
}
if !exists {
    stream := …;
    hub.UploadLayer("example/repo", digest, stream)
}

Uploading Manifests

First, create a signed manifest:

manifest := &manifest.Manifest{
    Versioned: manifest.Versioned{
        SchemaVersion: 1,
    },
    Tag: "latest",
    // …
}

key, err := libtrust.GenerateECP256PrivateKey()
if err != nil {
    // …
}

signedManifest := manifest.Sign(manifest, key)
if err != nil {
    // …
}

Production applications should probably reuse keys, rather than generating ephemeral keys. See the libtrust documentation for details.

Then, upload the signed manifest:

err := hub.PutManifest("example/repo", "latest", signedManifest)
if err != nil {
    // …
}

This will also create or update tags, as necessary.

About

A Go API client for the v2 Docker Registry API

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Go 95.5%
  • Makefile 3.1%
  • Shell 1.4%