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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL