docker

package
v0.0.0-...-3bfe646 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2023 License: Apache-2.0 Imports: 52 Imported by: 0

Documentation

Overview

docker package is responsible for pushing container data (layers) from the offline storage into the regisitry running on-site

This happens during installation or software upgrades.

Package reference provides a general type to represent any way of referencing images within the registry. Its main purpose is to abstract tags and digests (content-addressable hash).

The source code is based on https://github.com/docker/distribution/blob/master/reference/reference.go with irrelevant parts removed.

Grammar 

reference                       := name [ ":" tag ] [ "@" digest ]
name                            := [domain '/'] path-component ['/' path-component]*
domain                          := domain-component ['.' domain-component]* [':' port-number]
domain-component                := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
port-number                     := /[0-9]+/
path-component                  := alpha-numeric [separator alpha-numeric]*
alpha-numeric                   := /[a-z0-9]+/
separator                       := /[_.]|__|[-]*/

tag                             := /[\w][\w.-]{0,127}/

digest                          := digest-algorithm ":" digest-hex
digest-algorithm                := digest-algorithm-component [ digest-algorithm-separator digest-algorithm-component ]*
digest-algorithm-separator      := /[+.-_]/
digest-algorithm-component      := /[A-Za-z][A-Za-z0-9]*/
digest-hex                      := /[0-9a-fA-F]{32,}/ ; At least 128 bit digest value

identifier                      := /[a-f0-9]{64}/
short-identifier                := /[a-f0-9]{6,64}/

Copyright 2020 Gravitational, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

Constants

View Source 
const (
	// NameTotalLengthMax is the maximum total number of characters in a repository name.
	NameTotalLengthMax = 255
)

Variables

View Source 
var (
	// ErrReferenceInvalidFormat represents an error while trying to parse a string as a reference.
	ErrReferenceInvalidFormat = errors.New("invalid reference format")

	// ErrTagInvalidFormat represents an error while trying to parse a string as a tag.
	ErrTagInvalidFormat = errors.New("invalid tag format")

	// ErrDigestInvalidFormat represents an error while trying to parse a string as a tag.
	ErrDigestInvalidFormat = errors.New("invalid digest format")

	// ErrNameContainsUppercase is returned for invalid repository names that contain uppercase characters.
	ErrNameContainsUppercase = errors.New("repository name must be lowercase")

	// ErrNameEmpty is returned for empty, invalid repository names.
	ErrNameEmpty = errors.New("repository name must have at least one component")

	// ErrNameTooLong is returned when a repository name is longer than NameTotalLengthMax.
	ErrNameTooLong = fmt.Errorf("repository name must not be more than %v characters", NameTotalLengthMax)

	// ErrNameNotCanonical is returned when a name is not canonical.
	ErrNameNotCanonical = errors.New("repository name must be canonical")
)
View Source 
var (

	// DomainRegexp defines the structure of potential domain components
	// that may be part of image names. This is purposely a subset of what is
	// allowed by DNS to ensure backwards compatibility with Docker image
	// names.
	DomainRegexp = expression(
		domainComponentRegexp,
		optional(repeated(literal(`.`), domainComponentRegexp)),
		optional(literal(`:`), match(`[0-9]+`)))

	// TagRegexp matches valid tag names. From docker/docker:graph/tags.go.
	TagRegexp = match(`[\w][\w.-]{0,127}`)

	// DigestRegexp matches valid digests.
	DigestRegexp = match(`[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][[:xdigit:]]{32,}`)

	// NameRegexp is the format for the name component of references. The
	// regexp has capturing groups for the domain and name part omitting
	// the separating forward slash from either.
	NameRegexp = expression(
		optional(DomainRegexp, literal(`/`)),
		nameComponentRegexp,
		optional(repeated(literal(`/`), nameComponentRegexp)))

	// ReferenceRegexp is the full supported format of a reference. The regexp
	// is anchored and has capturing groups for name, tag, and digest
	// components.
	ReferenceRegexp = anchored(capture(NameRegexp),
		optional(literal(":"), capture(TagRegexp)),
		optional(literal("@"), capture(DigestRegexp)))

	// IdentifierRegexp is the format for string identifier used as a
	// content addressable identifier using sha256. These identifiers
	// are like digests without the algorithm, since sha256 is used.
	IdentifierRegexp = match(`([a-f0-9]{64})`)

	// ShortIdentifierRegexp is the format used to represent a prefix
	// of an identifier. A prefix may be used to match a sha256 identifier
	// within a list of trusted identifiers.
	ShortIdentifierRegexp = match(`([a-f0-9]{6,64})`)
)

Functions

func BasicConfiguration 

func BasicConfiguration(addr, rootdir string) *configuration.Configuration

BasicConfiguration creates a configuration object for running a local registry server on the specified address addr and using rootdir as a root directory for a filesystem driver

func CleanRegistry 

func CleanRegistry(ctx context.Context, registryDir string, requiredImages []string) error

CleanRegistry removes images not present in requiredImages from registry rooted at registryDir

func Domain 

func Domain(named Named) string

Domain returns the domain part of the Named reference

func GenerateTestDockerImage 

func GenerateTestDockerImage(client *dockerapi.Client, repoName, tag string, c *check.C) loc.DockerImage

GenerateTestDockerImage generates a test docker image in the specified repository and with the given tag

func GenerateTestDockerImages 

func GenerateTestDockerImages(client *dockerapi.Client, repoName string, size int, c *check.C) []loc.DockerImage

GenerateTestDockerImages generates the requested number of docker images in the specified repository

func IsManifestUnknown 

func IsManifestUnknown(err error) bool

IsManifestUnknown determines if the specified error is an `unknown manifest` error

func ListRepos 

func ListRepos(ctx context.Context, namespace registryclient.Registry) (repos []string, err error)

func Login 

func Login(name, username, password string) error

Login logs into a Docker registry.

func Logout 

func Logout(name string) error

Logout logs out of a Docker registry.

func NewClient 

func NewClient(endpoint string) (*dockerapi.Client, error)

NewClient creates a docker client using endpoint for connection

func NewClientFromEnv 

func NewClientFromEnv() (*dockerapi.Client, error)

NewClientFromEnv creates a docker client using environment

func NewClientWithTimeout 

func NewClientWithTimeout(endpoint string, timeout time.Duration) (*dockerapi.Client, error)

NewClientWithTimeout creates a docker client using endpoint for connection and a time limit for requests

func Path 

func Path(named Named) (name string)

Path returns the name without the domain part of the Named reference

func TranslateRuntimeImage 

func TranslateRuntimeImage(req TranslateImageRequest) error

TranslateRuntimeImage translates the specified docker image into a gravity package specified in req.

Types

type Canonical 

type Canonical interface {
	Named
	Digest() digest.Digest
}

Canonical reference is an object with a fully unique name including a name with domain and digest

type Digested 

type Digested interface {
	Reference
	Digest() digest.Digest
}

Digested is an object which has a digest in which it can be referenced by

type Image 

type Image struct {
	// Repository is the image name.
	Repository string `json:"repository" yaml:"repository"`
	// Tags is the image tags.
	Tags []string `json:"tags" yaml:"tags"`
}

Image represents a single Docker image.

type ImageService 

type ImageService interface {
	// Sync synchronizes the contents of dir with this private docker registry
	// Returns the list of images synced
	Sync(ctx context.Context, dir string, progress utils.Printer) ([]TagSpec, error)

	// Wrap translates the specified image name to point to the private registry.
	Wrap(image string) string

	// Unwrap translates the specified image name to point to the original repository
	// if it's prefixed with this registry address - functional inverse of Wrap
	Unwrap(image string) string

	// List fetches a list of all images from the registry
	List(context.Context) ([]Image, error)
}

ImageService defines an interface to a private docker registry

func NewClusterImageService 

func NewClusterImageService(registry string) (ImageService, error)

NewClusterImageService returns an in-cluster image service for the specified registry address.

func NewDefaultImageService 

func NewDefaultImageService() ImageService

NewDefaultImageService returns a new instance of the ImageService using defaults

func NewImageService 

func NewImageService(req RegistryConnectionRequest) (ImageService, error)

NewImageService creates an image service using the supplied address and certificate name to connect to the remote registry

func NewScanningImageService 

func NewScanningImageService(req RegistryConnectionRequest, conf ScanConfig) (ImageService, error)

NewScanningImageService creates an image service that rewrites image paths to a repository used for scanning those images.

type Interface 

type Interface interface {
	// InspectImage retrieves metadata for the specified image
	InspectImage(name string) (*dockerapi.Image, error)
	// TagImage tags the image specified with name
	TagImage(name string, opt dockerapi.TagImageOptions) error
	// PushImage pushes the image specified with opts using the specified
	// authentication configuration
	PushImage(opts dockerapi.PushImageOptions, auth dockerapi.AuthConfiguration) error
	// RemoveImage removes the specified image
	RemoveImage(image string) error
	// CreateContainer creates a container instance based on the given configuration
	CreateContainer(opts dockerapi.CreateContainerOptions) (*dockerapi.Container, error)
	// RemoveContainer removes the container given with opts
	RemoveContainer(opts dockerapi.RemoveContainerOptions) error
	// ExportContainer exports the contents of the running container given with opts
	// as a tarball
	ExportContainer(opts dockerapi.ExportContainerOptions) error
	// Version returns version information about the docker server.
	Version() (*dockerapi.Env, error)
}

Interface defines an interface to docker

func NewDefaultClient 

func NewDefaultClient() (Interface, error)

NewDefaultClient returns a new docker client using defaults

type Named 

type Named interface {
	Reference
	Name() string
}

Named is an object with a full name

type NamedTagged 

type NamedTagged interface {
	Named
	Tag() string
}

NamedTagged is an object including a name and tag.

type PullService 

type PullService interface {
	// Pull pulls the specified image
	Pull(image string) error
	// IsImagePresent checks if the specified image is available locally
	IsImagePresent(image string) (bool, error)
}

PullService defines an interface to pull images

type Puller 

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

Puller is a docker puller implementation. Implements the PullerService

func NewPuller 

func NewPuller(client Interface) *Puller

NewPuller returns an instance of Puller using the specified client and credentials

func (*Puller) IsImagePresent 

func (r *Puller) IsImagePresent(image string) (bool, error)

IsImagePresent determines if the specified image is available in docker

func (*Puller) Pull 

func (r *Puller) Pull(image string) error

Pull pulls an image using "docker pull" command that lets us take advantage of its cached credentials for multiple docker registries

type Reference 

type Reference interface {
	// String returns the full reference
	String() string
}

Reference is an opaque object reference identifier that may include modifiers such as a hostname, name, tag, and digest.

func Parse 

func Parse(s string) (Reference, error)

Parse parses s and returns a syntactically valid Reference. If an error was encountered it is returned, along with a nil Reference. NOTE: Parse will not handle short digests.

type Registry 

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

A Registry represents a complete instance of the registry.

func NewRegistry 

func NewRegistry(config *configuration.Configuration) (*Registry, error)

NewRegistry creates a new registry instance from the specified configuration.

func (*Registry) Addr 

func (r *Registry) Addr() string

Addr returns the address this registry listens on.

func (*Registry) Close 

func (r *Registry) Close() error

Close shuts down the registry.

func (*Registry) Start 

func (r *Registry) Start() error

Start starts the registry server and returns when the server has actually started listening.

type RegistryConnectionRequest 

type RegistryConnectionRequest struct {
	// RegistryAddress is either a host:port or a complete URL of a Docker registry
	RegistryAddress string
	// CertName allows to override directory where to look for certs
	// which normally equals to the registry address
	CertName string
	// CACertPath is the full path to the root certificate
	CACertPath string
	// ClientCertPath is the full path to the client certificate
	ClientCertPath string
	// ClientKeyPath is the full path to the client private key
	ClientKeyPath string
	// Username specifies optional registry username for basic auth
	Username string
	// Password specifies optional registry password for basic auth
	Password string
	// Prefix specifies optional registry prefix when pushing images
	Prefix string
	// Insecure indicates a plain http registry
	Insecure bool
}

RegistryConnectionRequest represents connection information for a Docker registry

func (*RegistryConnectionRequest) CheckAndSetDefaults 

func (r *RegistryConnectionRequest) CheckAndSetDefaults() error

CheckAndSetDefaults makes sure the request is valid and sets some defaults

func (*RegistryConnectionRequest) HasBasicAuth 

func (r *RegistryConnectionRequest) HasBasicAuth() bool

HasBasicAuth returns true if the request contains basic auth credentials.

func (RegistryConnectionRequest) String 

func (r RegistryConnectionRequest) String() string

String returns string representation for the request

func (*RegistryConnectionRequest) TLSClientConfig 

func (r *RegistryConnectionRequest) TLSClientConfig() (*tls.Config, error)

TLSClientConfig returns client TLS config for this request.

type RegistryInfo 

type RegistryInfo struct {
	// Address stores the address of the registry as host:port
	Address string
	// Protocol stores the Protocol (https or http)
	Protocol string
}

RegistryInfo contains information about connecting to a registry.

func (*RegistryInfo) GetURL 

func (i *RegistryInfo) GetURL() string

GetURL returns the url for current registry

type RemoteStore 

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

RemoteStore defines a remote distribution registry

func ConnectRegistry 

func ConnectRegistry(ctx context.Context, req RegistryConnectionRequest) (*RemoteStore, error)

ConnectRegistry connects to the registry with the specified address

func (*RemoteStore) Repositories 

func (s *RemoteStore) Repositories(ctx context.Context, entries []string, last string) (n int, err error)

Repositories lists the remote repositories

func (*RemoteStore) Repository 

func (s *RemoteStore) Repository(ctx context.Context, name string) (distribution.Repository, error)

Repository provides access to the repository named with name

type ScanConfig 

type ScanConfig struct {
	// Remote Repository is the docker repository to use to scan the images.
	// Example: gravitational/gravity-scan
	RemoteRepository string
	// TagPrefix is a string to prepend to each images tag, in order to help identify the source of the image.
	// Example: 7.0.0 for a release of gravity 7.0.0
	TagPrefix string
}

ScanConfig represents configuration used to push images to a docker repository configured for scanning those images for vulnerabilities or other problems

type Synchronizer 

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

Synchronizer contains the logic for pulling and exporting image layers

func NewSynchronizer 

func NewSynchronizer(log log.FieldLogger, dockerClient Interface, progressReporter utils.Progress) *Synchronizer

NewSynchronizer creates a new docker image synchronizer responsible for exporting docker images to a filesystem during build.

func (*Synchronizer) ImageExists 

func (h *Synchronizer) ImageExists(ctx context.Context, registryURL string, img loc.DockerImage) (bool, error)

ImageExists checks if the image exists in the registry

func (*Synchronizer) ImageTags 

func (h *Synchronizer) ImageTags(ctx context.Context, registryURL, repository string) ([]string, error)

ImageTags returns the list of tags for specified image from the registry

func (*Synchronizer) PullAndExportImages 

func (h *Synchronizer) PullAndExportImages(ctx context.Context, images []string, reg RegistryInfo, forcePull bool, parallel int) error

PullAndExportImages pulls and pushes the list of specified images into the registry

func (*Synchronizer) Push 

func (h *Synchronizer) Push(image, registryAddr string) error

Push pushes the specified image into the registry

type TagSpec 

type TagSpec struct {
	Name    string // same as 'repo' in dockerspeak, could be something like 'vendor.com/app'
	Version string // same as 'tag' in dockerspeak, usually '1.2.3' or 'latest'
}

TagSpec is a helper to deal with Docker 'registry tag' format like host:port/name:version

func TagFromString 

func TagFromString(s string) (t TagSpec)

TagFromString creates a new tag structure from string. It never fails, but you can use tag.IsValid() method later.

func (TagSpec) Equals 

func (t TagSpec) Equals(tag string) bool

func (TagSpec) IsValid 

func (t TagSpec) IsValid() bool

IsValid returns 'true' if it is a valid tag

func (TagSpec) String 

func (t TagSpec) String() string

String returns a long/full name of the tag

type Tagged 

type Tagged interface {
	Reference
	Tag() string
}

Tagged is an object which has a tag

type TestRegistry 

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

TestRegistry represents an instance of a docker registry for testing purposes

func NewTestRegistry 

func NewTestRegistry(dir string, s *Synchronizer, c *check.C) *TestRegistry

NewTestRegistry returns a new started docker registry

func (*TestRegistry) Close 

func (r *TestRegistry) Close() error

Close stops this registry instance and removes its resources

func (*TestRegistry) Push 

func (r *TestRegistry) Push(c *check.C, images ...loc.DockerImage)

Push pushes the specified images to the underlying registry

type TranslateImageRequest 

type TranslateImageRequest struct {
	// Image defines the docker image to translate.
	// The image must have been already pulled and available
	// locally
	Image string
	// Client is the docker client
	Client Interface
	// Package specifies the resulting telekube package
	Package loc.Locator
	// PackageService is the package service to create package in
	pack.PackageService
}

TranslateImageRequest describes a request to translate runtime docker image to telekube package

Source Files

View all Source files

Directories

Path Synopsis

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.