k8schain

README

k8schain

This is an implementation of the authn.Keychain interface loosely based on the authentication semantics used by the Kubelet when performing the pull of a Pod's images.

This keychain supports passing a Kubernetes Service Account and some ImagePullSecrets which may represent registry credentials.

In addition to those, the keychain also includes cloud-specific credential helpers for Google Container Registry (and Artifact Registry), Azure Container Registry, and Amazon AWS Elasic Container Registry. This means that if the keychain is used from within Kubernetes services on those clouds (GKE, AKS, EKS), any available service credentials will be discovered and used.

In general this keychain should be used when the code is expected to run in a Kubernetes cluster, and especially when it will run in one of those clouds. To get a cloud-agnostic keychain, use pkg/authn/kubernetes instead.

To get only cloud-aware keychains, use google.Keychain, or pkg/authn.NewKeychainFromHelper with a cloud credential helper implementation -- see the implementation of k8schain.NewNoClient for more details.

Usage

Creating a keychain

A k8schain keychain can be built via one of:

// client is a kubernetes.Interface
kc, err := k8schain.New(ctx, client, k8schain.Options{})
...

// This method is suitable for use by controllers or other in-cluster processes.
kc, err := k8schain.NewInCluster(ctx, k8schain.Options{})
...

Using the keychain

The k8schain keychain can be used directly as an authn.Keychain, e.g.

auth, err := kc.Resolve(registry)
if err != nil {
	...
}

Or, with the remote.WithAuthFromKeychain option:

img, err := remote.Image(ref, remote.WithAuthFromKeychain(kc))
if err != nil {
	...
}

Documentation

Overview

Package k8schain exposes an implementation of the authn.Keychain interface based on the semantics the Kubelet follows when pulling the images for a Pod in Kubernetes.

Index

• func New(ctx context.Context, client kubernetes.Interface, opt Options) (authn.Keychain, error)
• func NewFromPullSecrets(ctx context.Context, pullSecrets []corev1.Secret) (authn.Keychain, error)
• func NewInCluster(ctx context.Context, opt Options) (authn.Keychain, error)
• func NewNoClient(ctx context.Context) (authn.Keychain, error)
• type Options

Functions

func New

func New(ctx context.Context, client kubernetes.Interface, opt Options) (authn.Keychain, error)

New returns a new authn.Keychain suitable for resolving image references as scoped by the provided Options. It speaks to Kubernetes through the provided client interface.

func NewFromPullSecrets

func NewFromPullSecrets(ctx context.Context, pullSecrets []corev1.Secret) (authn.Keychain, error)

NewFromPullSecrets returns a new authn.Keychain suitable for resolving image references as scoped by the pull secrets.

func NewInCluster

func NewInCluster(ctx context.Context, opt Options) (authn.Keychain, error)

NewInCluster returns a new authn.Keychain suitable for resolving image references as scoped by the provided Options, constructing a kubernetes.Interface based on in-cluster authentication.

func NewNoClient

func NewNoClient(ctx context.Context) (authn.Keychain, error)

NewNoClient returns a new authn.Keychain that supports the portions of the K8s keychain that don't read ImagePullSecrets. This limits it to roughly the Node-identity-based authentication schemes in Kubernetes pkg/credentialprovider. This version of the k8schain drops the requirement that we run as a K8s serviceaccount with access to all of the on-cluster secrets. This drop in fidelity also diminishes its value as a stand-in for Kubernetes authentication, but this actually targets a different use-case. What remains is an interesting sweet spot: this variant can serve as a credential provider for all of the major public clouds, but in library form (vs. an executable you exec).

Types

type Options

type Options = kauth.Options

Options holds configuration data for guiding credential resolution.