README
¶
image is a set of Go libraries aimed at working in various way with
containers' images and container image registries.
The containers/image library allows application to pull and push images from container image registries, like the docker.io and quay.io registries. It also implements "simple image signing".
The containers/image library also allows you to inspect a repository on a
container registry without pulling down the image. This means it fetches the
repository's manifest and it is able to show you a docker inspect-like json
output about a whole repository or a tag. This library, in contrast to docker inspect, helps you gather useful information about a repository or a tag
without requiring you to run docker pull.
The containers/image library also allows you to translate from one image format to another, for example docker container images to OCI images. It also allows you to copy container images between various registries, possibly converting them as necessary, and to sign and verify images.
Command-line usage
The containers/image project is only a library with no user interface;
you can either incorporate it into your Go programs, or use the skopeo tool:
The skopeo tool uses the
containers/image library and takes advantage of many of its features,
e.g. skopeo copy exposes the containers/image/copy.Image functionality.
Dependencies
This library ships as a Go module.
Building
If you want to see what the library can do, or an example of how it is called, consider starting with the skopeo tool instead.
To integrate this library into your project, include it as a Go module,
put it into $GOPATH or use your preferred vendoring tool to include a copy
in your project. Ensure that the dependencies documented in go.mod
are also available (using those exact versions or different versions of
your choosing).
This library also depends on some C libraries. Either install them:
Fedora$ dnf install gpgme-devel libassuan-devel
macOS$ brew install gpgme
or use the build tags described below to avoid the dependencies (e.g. using go build -tags …)
Supported build tags
containers_image_docker_daemon_stub: Don’t import thedocker-daemon:transport ingithub.com/containers/image/transports/alltransports, to decrease the amount of required dependencies. Use a stub which reports that the transport is not supported instead.containers_image_openpgp: Use a Golang-only OpenPGP implementation for signature verification instead of the default cgo/gpgme-based implementation; the primary downside is that creating new signatures with the Golang-only implementation is not supported.containers_image_storage_stub: Don’t import thecontainers-storage:transport ingithub.com/containers/image/transports/alltransports, to decrease the amount of required dependencies. Use a stub which reports that the transport is not supported instead.
Contributing
Information about contributing to this project.
When developing this library, please use make (or make … BUILDTAGS=…) to take advantage of the tests and validation.
License
Apache License 2.0
SPDX-License-Identifier: Apache-2.0
Contact
- Mailing list: containers-dev
- IRC: #container-projects on freenode.net
Documentation
¶
Overview ¶
The package image provides libraries and commands to interact with container images.
package main
import (
"context"
"fmt"
"github.com/containers/image/v5/docker"
)
func main() {
ref, err := docker.ParseReference("//fedora")
if err != nil {
panic(err)
}
ctx := context.Background()
img, err := ref.NewImage(ctx, nil)
if err != nil {
panic(err)
}
defer img.Close()
b, _, err := img.Manifest(ctx)
if err != nil {
panic(err)
}
fmt.Printf("%s", string(b))
}
## Notes on running in rootless mode
If your application needs to access a containers/storage store in rootless mode, then the following additional steps have to be performed at start-up of your application:
package main
import (
"github.com/containers/storage/pkg/reexec"
"github.com/syndtr/gocapability/capability"
"github.com/containers/storage/pkg/unshare"
)
var neededCapabilities = []capability.Cap{
capability.CAP_CHOWN,
capability.CAP_DAC_OVERRIDE,
capability.CAP_FOWNER,
capability.CAP_FSETID,
capability.CAP_MKNOD,
capability.CAP_SETFCAP,
}
func main() {
reexec.Init()
capabilities, err := capability.NewPid(0)
if err != nil {
panic(err)
}
for _, cap := range neededCapabilities {
if !capabilities.Get(capability.EFFECTIVE, cap) {
// We miss a capability we need, create a user namespaces
unshare.MaybeReexecUsingUserNamespace(true)
}
}
// rest of your code follows here
}
TODO(runcom)
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
reference
Package reference provides a general type to represent any way of referencing images within the registry.
|
Package reference provides a general type to represent any way of referencing images within the registry. |
|
tarfile
Package tarfile is an internal implementation detail of some transports.
|
Package tarfile is an internal implementation detail of some transports. |
|
Package image consolidates knowledge about various container image formats (as opposed to image storage mechanisms, which are handled by types.ImageSource) and exposes all of them using an unified interface.
|
Package image consolidates knowledge about various container image formats (as opposed to image storage mechanisms, which are handled by types.ImageSource) and exposes all of them using an unified interface. |
|
internal
|
|
|
image
Package image consolidates knowledge about various container image formats (as opposed to image storage mechanisms, which are handled by types.ImageSource) and exposes all of them using an unified interface.
|
Package image consolidates knowledge about various container image formats (as opposed to image storage mechanisms, which are handled by types.ImageSource) and exposes all of them using an unified interface. |
|
imagedestination/stubs
Package stubs contains trivial stubs for parts of private.ImageDestination.
|
Package stubs contains trivial stubs for parts of private.ImageDestination. |
|
imagesource/stubs
Package stubs contains trivial stubs for parts of private.ImageSource.
|
Package stubs contains trivial stubs for parts of private.ImageSource. |
|
testing/explicitfilepath-tmpdir
Package tmpdir is a TESTING-ONLY utility.
|
Package tmpdir is a TESTING-ONLY utility. |
|
pkg
|
|
|
blobinfocache/boltdb
Package boltdb implements a BlobInfoCache backed by BoltDB.
|
Package boltdb implements a BlobInfoCache backed by BoltDB. |
|
blobinfocache/internal/prioritize
Package prioritize provides utilities for filtering and prioritizing locations in types.BlobInfoCache.CandidateLocations.
|
Package prioritize provides utilities for filtering and prioritizing locations in types.BlobInfoCache.CandidateLocations. |
|
blobinfocache/internal/test
Package test provides generic BlobInfoCache test helpers.
|
Package test provides generic BlobInfoCache test helpers. |
|
blobinfocache/memory
Package memory implements an in-memory BlobInfoCache.
|
Package memory implements an in-memory BlobInfoCache. |
|
blobinfocache/none
Package none implements a dummy BlobInfoCache which records no data.
|
Package none implements a dummy BlobInfoCache which records no data. |
|
blobinfocache/sqlite
Package boltdb implements a BlobInfoCache backed by SQLite.
|
Package boltdb implements a BlobInfoCache backed by SQLite. |
|
Package tarball provides a way to generate images using one or more layer tarballs and an optional template configuration.
|
Package tarball provides a way to generate images using one or more layer tarballs and an optional template configuration. |