Skip to content
Switch branches/tags

Latest commit

* Create a k8schain directly from pull secrets

The k8schain package creates a new keychain by resolving Kubernets
secrets from service accounts and other image pull secrets specified by
name. The k8s client gets the full secret content for these named

Sometimes it's desirable to pull the content of a secret from a cache,
or to watch a resource for changes in a controller. In this situation
it would be helpful to create a k8schain directly from resolved secrets,
without making calls to the k8s api server.

This change refactors the existing k8schain.New() method to separate the
resolution of secrets from the creation of the keychain. This is only a
refactoring of existing behavior to shortcut the k8s api lookups. There
is no change in existing behavior for the keychain.


    k8schain.NewFromPullSecrets(context.Context, []corev1.Secret) (authn.Keychain, error)

Signed-off-by: Scott Andrews <>

* gofmt

Signed-off-by: Scott Andrews <>

Git stats


Failed to load latest commit information.


GitHub Actions Build Status GoDoc Code Coverage


This is a golang library for working with container registries. It's largely based on the Python library of the same name.

The following diagram shows the main types that this library handles. OCI image representation


The overarching design philosophy of this library is to define interfaces that present an immutable view of resources (e.g. Image, Layer, ImageIndex), which can be backed by a variety of medium (e.g. registry, tarball, daemon, ...).

To complement these immutable views, we support functional mutations that produce new immutable views of the resulting resource (e.g. mutate). The end goal is to provide a set of versatile primives that can compose to do extraordinarily powerful things efficiently and easily.

Both the resource views and mutations may be lazy, eager, memoizing, etc, and most are optimized for common paths based on the tooling we have seen in the wild (e.g. writing new images from disk to the registry as a compressed tarball).


Over time, we will add new functionality under experimental environment variables listed here.

Env Var Value(s) What is does
GGCR_EXPERIMENT_ESTARGZ "1" When enabled this experiment will direct tarball.LayerFromOpener to emit estargz compatible layers, which enable them to be lazily loaded by an appropriately configured containerd.












The simplest use for these libraries is to read from one source and write to another.

For example,

  • crane pull is remote.Image -> tarball.Write,
  • crane push is tarball.Image -> remote.Write,
  • crane cp is remote.Image -> remote.Write.

However, often you actually want to change something about an image. This is the purpose of the mutate package, which exposes some commonly useful things to change about an image.


If you're trying to use this library with a different source or sink than it already supports, it can be somewhat cumbersome. The Image and Layer interfaces are pretty wide, with a lot of redundant information. This is somewhat by design, because we want to expose this information as efficiently as possible where we can, but again it is a pain to implement yourself.

The purpose of the partial package is to make implementing a v1.Image much easier, by filling in all the derived accessors for you if you implement a minimal subset of v1.Image.


You might think our abstractions are bad and you just want to authenticate and send requests to a registry.

This is the purpose of the transport and authn packages.


This repo hosts some tools built on top of the library.


crane is a tool for interacting with remote images and registries.


gcrane is a GCR-specific variant of crane that has richer output for the ls subcommand and some basic garbage collection support.


k8schain implements the authentication semantics use by kubelets in a way that is easily consumable by this library.

k8schain is not a standalone tool, but it's linked here for visibility.

Emeritus: ko

This tool was originally developed in this repo but has since been moved to its own repo.