registry

package
v0.0.0-...-b642de1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2020 License: Apache-2.0 Imports: 8 Imported by: 8

Documentation

Overview

Package registry is an API wrapper for the Docker Registry v1 API and supports all of the documented operations, including: getting/putting images, retrieving repository tags, and executing searches.

Full documentation for the Docker Registry API can be found here:

https://docs.docker.com/reference/api/registry_api/

Usage

There are two different usage models for the registry client depending on whether you are trying to interact with a private Docker registry or the Docker Hub.

When using the client with a private Docker registry you can simply pass basic auth credentials to the functions you are invoking and the appropriate authentication headers will be passed along with the request: 

c := registry.NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")

auth := registry.BasicAuth{"user", "pass"}

err := c.Repository.SetTag("foo/bar", "abc123", "1.0", auth)

When using the client to interact with the Docker Hub there is an extra call that you need to make. You need to use your basic auth credentials to first retrieve a token and then you can use that token when interacting with the Registry API: 

c := registry.NewClient()

basicAuth := registry.BasicAuth{"user", "pass"}

tokenAuth, err := c.Hub.GetWriteToken("foo/bar", basicAuth)

err := c.Repository.SetTag("foo/bar", "abc123", "1.0", tokenAuth)

Depending on the API you're trying to use, you may need to first retreive either a read, write or delete token.

For more details about interacting with the Docker Hub, see the Docker Hub and Registry Spec:

https://docs.docker.com/reference/api/hub_registry_spec/

Note: If your Docker Hub repository has been setup as an Automated Build repositry you will not be able to make any changes to it (setting tags, etc...) via the Registry API. You can only make changes to an Automated Build repository through the Docker Hub UI.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Access 

type Access int

Access is an enum type representing the access type provided by a TokenAuth authenticator. 

const (
	None Access = iota
	Read
	Write
	Delete
)

Enum values for the Access type: None, Read, Write, Delete

type Authenticator 

type Authenticator interface {
	ApplyAuthentication(*http.Request)
}

Authenticator is the interface used to abstract various HTTP authentication methods.

ApplyAuthentication accepts an http.Request and will apply the appropriate authentication headers to the request.

type BasicAuth 

type BasicAuth struct {
	Username string
	Password string
}

BasicAuth is an Authenticator implementation which can be used for HTTP basic authentication.

func (BasicAuth) ApplyAuthentication 

func (a BasicAuth) ApplyAuthentication(r *http.Request)

Sets the Authorization header on the request to use HTTP Basic Authentication with the username and password provided.

type Client 

type Client struct {
	// BaseURL represents the base URL for the Registry API.
	// Defaults to "https://index.docker.io/v1/".
	BaseURL *url.URL

	// Hub gives access to the Docker Hub API for retrieving auth tokens.
	Hub *HubService

	// Image gives access to the /images part of the Registry API.
	Image *ImageService

	// Repository gives access to the /repositories part of the Registry API.
	Repository *RepositoryService

	// Search gives access to the /search part of the Registry API.
	Search *SearchService
	// contains filtered or unexported fields
}

Client manages communication with the Docker Registry API.

func NewClient 

func NewClient() *Client

NewClient returns a new Docker Registry API client.

type ContainerConfig 

type ContainerConfig struct {
	HostName        string              `json:"Hostname"`
	DomainName      string              `json:"Domainname"`
	User            string              `json:"User"`
	Memory          int64               `json:"Memory"`
	MemorySwap      int64               `json:"MemorySwap"`
	CPUShares       int64               `json:"CpuShares"`
	CPUSet          string              `json:"Cpuset"`
	AttachStdin     bool                `json:"AttachStdin"`
	AttachStdout    bool                `json:"AttachStdout"`
	AttachStderr    bool                `json:"AttachStderr"`
	PortSpecs       []string            `json:"PortSpecs"`
	ExposedPorts    map[string]struct{} `json:"ExposedPorts"`
	TTY             bool                `json:"Tty"`
	OpenStdin       bool                `json:"OpenStdin"`
	StdinOnce       bool                `json:"StdinOnce"`
	Env             []string            `json:"Env"`
	Cmd             []string            `json:"Cmd"`
	DNS             []string            `json:"Dns"`
	Image           string              `json:"Image"`
	Volumes         map[string]struct{} `json:"Volumes"`
	VolumesFrom     string              `json:"VolumesFrom"`
	WorkingDir      string              `json:"WorkingDir"`
	Entrypoint      []string            `json:"Entrypoint"`
	NetworkDisabled bool                `json:"NetworkDisabled"`
	SecurityOpts    []string            `json:"SecurityOpts"`
	OnBuild         []string            `json:"OnBuild"`
}

ContainerConfig is the list of configuration options used when creating a container.

type HubService 

type HubService struct {
	// contains filtered or unexported fields
}

HubService gives acess to the Docker Hub API used to retrieve authentication tokens.

func (*HubService) GetDeleteToken 

func (h *HubService) GetDeleteToken(repo string, auth Authenticator) (*TokenAuth, error)

Retrieves a write-only token from the Docker Hub for the specified repo. The auth argument should be the user's basic auth credentials.

func (*HubService) GetReadToken 

func (h *HubService) GetReadToken(repo string) (*TokenAuth, error)

Retrieves a read-only token from the Docker Hub for the specified repo.

func (*HubService) GetReadTokenWithAuth 

func (h *HubService) GetReadTokenWithAuth(repo string, auth Authenticator) (*TokenAuth, error)

Retrieves a read-only token from the Docker Hub for the specified private repo.

func (*HubService) GetWriteToken 

func (h *HubService) GetWriteToken(repo string, auth Authenticator) (*TokenAuth, error)

Retrieves a write-only token from the Docker Hub for the specified repo. The auth argument should be the user's basic auth credentials.

type ImageMetadata 

type ImageMetadata struct {
	ID              string           `json:"id"`
	Parent          string           `json:"parent"`
	Comment         string           `json:"Comment"`
	Created         time.Time        `json:"created"`
	Container       string           `json:"container"`
	ContainerConfig ContainerConfig  `json:"container_config"`
	DockerVersion   string           `json:"docker_version"`
	Author          string           `json:"author"`
	Config          *ContainerConfig `json:"config"`
	Architecture    string           `json:"architecture"`
	OS              string           `json:"os"`
	Size            int64            `json:"Size"`
}

ImageMetadata represents metadata about an image layer.

type ImageService 

type ImageService struct {
	// contains filtered or unexported fields
}

ImageService gives access to the /images portion of the Registry API.

func (*ImageService) AddLayer 

func (i *ImageService) AddLayer(imageID string, layer io.Reader, auth Authenticator) error

Upload the layer for a given image ID. Contents of the layer will be read from the provided io.Reader.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#put-image-layer

func (*ImageService) AddMetadata 

func (i *ImageService) AddMetadata(imageID string, metadata *ImageMetadata, auth Authenticator) error

Upload the layer metadata for a given image ID.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#put-image-layer_1

func (*ImageService) GetAncestry 

func (i *ImageService) GetAncestry(imageID string, auth Authenticator) ([]string, error)

Retrieve the ancestry for an image given an image ID.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#get-image-ancestry

Example (DockerHub) 
c := NewClient()
auth, err := c.Hub.GetReadToken("ubuntu")

images, err := c.Image.GetAncestry("ubuntu", auth)
if err != nil {
	panic(err)
}

for _, imageID := range images {
	fmt.Println(imageID)
}

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

images, err := c.Image.GetAncestry("ubuntu", auth)
if err != nil {
	panic(err)
}

for _, imageID := range images {
	fmt.Println(imageID)
}

Output:

func (*ImageService) GetLayer 

func (i *ImageService) GetLayer(imageID string, layer io.Writer, auth Authenticator) error

Retrieve the layer for a given image ID. Contents of the layer will be written to the provided io.Writer.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#get-image-layer

Example (DockerHub) 
c := NewClient()
auth, err := c.Hub.GetReadToken("ubuntu")

buffer := &bytes.Buffer{}
imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
err = c.Image.GetLayer(imageID, buffer, auth)
if err != nil {
	panic(err)
}

fmt.Println(buffer)

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

buffer := &bytes.Buffer{}
imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
err := c.Image.GetLayer(imageID, buffer, auth)
if err != nil {
	panic(err)
}

fmt.Println(buffer)

Output:

func (*ImageService) GetMetadata 

func (i *ImageService) GetMetadata(imageID string, auth Authenticator) (*ImageMetadata, error)

Retrieve the layer metadata for a given image ID.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#get-image-layer_1

Example (DockerHub) 
c := NewClient()
auth, err := c.Hub.GetReadToken("ubuntu")

imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
meta, err := c.Image.GetMetadata(imageID, auth)
if err != nil {
	panic(err)
}

fmt.Printf("%#v", meta)

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
meta, err := c.Image.GetMetadata(imageID, auth)
if err != nil {
	panic(err)
}

fmt.Printf("%#v", meta)

Output:

type NilAuth 

type NilAuth struct{}

NilAuth is an Authenticator implementation that can be used when no authentication is required.

func (NilAuth) ApplyAuthentication 

func (NilAuth) ApplyAuthentication(r *http.Request)

No-op implementation. Makes NO changes to the specified request.

type RegistryError 

type RegistryError struct {
	Code int
	// contains filtered or unexported fields
}

RegistryError encapsulates any errors which result from communicating with the Docker Registry API

func (RegistryError) Error 

func (e RegistryError) Error() string

type RepositoryService 

type RepositoryService struct {
	// contains filtered or unexported fields
}

ImageService gives access to the /repositories portion of the Registry API.

func (*RepositoryService) Delete 

func (r *RepositoryService) Delete(repo string, auth Authenticator) error

Deletes the specified repository.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#delete-a-repository

Example (DockerHub) 
c := NewClient()
basicAuth := BasicAuth{"user", "pass"}
tokenAuth, err := c.Hub.GetDeleteToken("foo/bar", basicAuth)

err = c.Repository.Delete("foo/bar", tokenAuth)
if err != nil {
	panic(err)
}

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

err := c.Repository.Delete("foo/bar", auth)
if err != nil {
	panic(err)
}

Output:

func (*RepositoryService) DeleteTag 

func (r *RepositoryService) DeleteTag(repo, tag string, auth Authenticator) error

Deletes a tag from the specified repository.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#delete-a-repository-tag

Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

err := c.Repository.DeleteTag("foo/bar", "1.0", auth)
if err != nil {
	panic(err)
}

Output:

func (*RepositoryService) GetImageID 

func (r *RepositoryService) GetImageID(repo, tag string, auth Authenticator) (string, error)

Retrieves the ID of the image identified by the given repository and tag.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#get-image-id-for-a-particular-tag

Example (DockerHub) 
c := NewClient()
auth, err := c.Hub.GetReadToken("ubuntu")

imageID, err := c.Repository.GetImageID("ubuntu", "latest", auth)
if err != nil {
	panic(err)
}

fmt.Println(imageID)

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

imageID, err := c.Repository.GetImageID("ubuntu", "latest", auth)
if err != nil {
	panic(err)
}

fmt.Println(imageID)

Output:

func (*RepositoryService) ListTags 

func (r *RepositoryService) ListTags(repo string, auth Authenticator) (TagMap, error)

Retrieves a list of tags for the specified repository.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#list-repository-tags

Example (DockerHub) 
c := NewClient()
auth, err := c.Hub.GetReadToken("ubuntu")

tags, err := c.Repository.ListTags("ubuntu", auth)
if err != nil {
	panic(err)
}

for tag, imageID := range tags {
	fmt.Printf("%s = %s", tag, imageID)
}

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

tags, err := c.Repository.ListTags("ubuntu", auth)
if err != nil {
	panic(err)
}

for tag, imageID := range tags {
	fmt.Printf("%s = %s", tag, imageID)
}

Output:

func (*RepositoryService) SetTag 

func (r *RepositoryService) SetTag(repo, imageID, tag string, auth Authenticator) error

Sets a tag for the the specified repository and image ID.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#set-a-tag-for-a-specified-image-id

Example (DockerHub) 
c := NewClient()
basicAuth := BasicAuth{"user", "pass"}
tokenAuth, err := c.Hub.GetWriteToken("foo/bar", basicAuth)

imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
err = c.Repository.SetTag("foo/bar", imageID, "1.0", tokenAuth)
if err != nil {
	panic(err)
}

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")
auth := BasicAuth{"user", "pass"}

imageID := "2427658c75a1e3d0af0e7272317a8abfaee4c15729b6840e3c2fca342fe47bf1"
err := c.Repository.SetTag("foo/bar", imageID, "1.0", auth)
if err != nil {
	panic(err)
}

Output:

type SearchResult 

type SearchResult struct {
	Name        string `json:"name"`
	IsAutomated bool   `json:"is_automated"`
	IsTrusted   bool   `json:"is_trusted"`
	IsOfficial  bool   `json:"is_official"`
	StarCount   int    `json:"star_count"`
	Description string `json:"description"`
}

SearchResult represents a single result returned from a search against the registry.

type SearchResults 

type SearchResults struct {
	NumPages   int            `json:"num_pages"`
	NumResults int            `json:"num_results"`
	Results    []SearchResult `json:"results"`
	PageSize   int            `json:"page_size"`
	Query      string         `json:"query"`
	Page       int            `json:"page,string"`
}

SearchResults represents the list of SearchResult structs returned from a search against the registry.

type SearchService 

type SearchService struct {
	// contains filtered or unexported fields
}

SearchService gives access to the /search portion of the Registry API

func (*SearchService) Query 

func (s *SearchService) Query(query string, page, num int) (*SearchResults, error)

Searches the registry for the given term. The page argument is the page number for the desired results. The num argument is the number of results to be returned per page.

Docker Registry API docs: https://docs.docker.com/reference/api/registry_api/#search

Example (DockerHub) 
c := NewClient()

results, err := c.Search.Query("mysql", 1, 25)
if err != nil {
	panic(err)
}

for _, result := range results.Results {
	fmt.Println(result.Name)
}

Output:
Example (PrivateRegistry) 
c := NewClient()
c.BaseURL, _ = url.Parse("http://my.registry:8080/v1/")

results, err := c.Search.Query("mysql", 1, 25)
if err != nil {
	panic(err)
}

for _, result := range results.Results {
	fmt.Println(result.Name)
}

Output:

type TagMap 

type TagMap map[string]string

TagMap represents a collection of image tags and their corresponding image IDs.

type TokenAuth 

type TokenAuth struct {
	Host   string
	Token  string
	Access Access
}

TokenAuth is an Authenticator implementation which implements the token authentication scheme used by the Docker Hub.

func (TokenAuth) ApplyAuthentication 

func (a TokenAuth) ApplyAuthentication(r *http.Request)

Sets the Authorization header on the request to use the provided token. Will also re-write the host value of the request URL to use the value provided in the TokenAuth.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.