podman

Documentation

Overview

Package podman implements the Podman engineclient.EngineClient.

Podman's Painful Go Bindings

The Podman Go bindings are ... “creative”: they don't define API services on a Podman “client” but instead use an API endpoint-less(!) client and then pass this client around as a special value attached to a context(!).

To crank up the pain level further, this context must be the context returned by github.com/containers/podman/pkg/bindings.NewConnection (sic!). Yes, you've read that right; the function to create a connection actually returns a context.Context. This engine client works around the problem using the wye context mix-in operation.

To add insult to injury, the v3 implementation of Podman completely ignores any cancellation on its “connection context” or any of its derived contexts. Instead, the Podman v3 client always uses its own context.Background-derived context. At least v4 fixed this mistake, but as long as, for instance, Debian and Ubuntu LTS still provide only v3 Podmen, we are stuck with a v3 client (a v3 client can talk to a v4 daemon, but a v4 client can't talk to a v3 daemon).

So Podman really alienates – pun intended – all its API users until the end of the universe, especially when they need to integrate Podman as yet another container engine, because so much production code out there gets a context passed in and passes that (or a derived context) on.

🤦‍♂️

Wait, there's more … Podman's system.Event causes left-over go routines that might or might not get reused, depending on your particular code. In any case they trip up the Gomega go routine leak detector. This engine client implementation works around this issue by forcing the HTTP client used by a Podman connection to close all idle connections.

Podman Incompatibility

Podman v3 and v4 aren't correctly implementing the container “died” event as they forget to include all labels of the freshly-deceased container, differing to Docker's “died” event. Luckily, whalewatcher's watcher internal event processing already handles such a situation as part of nerdctl on plain containerd.

Build Notes

Refer to Podman Getting Started: Building from Scratch for the long list of packages to install for your particular build system.

Index

• Constants
• type NewOption
  • func WithPID(pid int) NewOption
  • func WithRucksackPacker(packer engineclient.RucksackPacker) NewOption
• type PodmanWatcher
  • func NewPodmanWatcher(podman context.Context, opts ...NewOption) *PodmanWatcher
  • func (pw *PodmanWatcher) API() string
  • func (pw *PodmanWatcher) Client() interface{}
  • func (pw *PodmanWatcher) Close()
  • func (pw *PodmanWatcher) ID(svcctx context.Context) string
  • func (pw *PodmanWatcher) Inspect(svcctx context.Context, nameorid string) (*whalewatcher.Container, error)
  • func (pw *PodmanWatcher) LifecycleEvents(svcctx context.Context) (<-chan engineclient.ContainerEvent, <-chan error)
  • func (pw *PodmanWatcher) List(svcctx context.Context) ([]*whalewatcher.Container, error)
  • func (pw *PodmanWatcher) PID() int
  • func (pw *PodmanWatcher) Try(svcctx context.Context) error
  • func (pw *PodmanWatcher) Type() string
  • func (pw *PodmanWatcher) Version(svcctx context.Context) string

Constants

const (
	PodmanAnnotation = "io.github.thediveo/podman/"

	PodLabelName   = PodmanAnnotation + "podname" // name of pod if applicable
	PodIDName      = PodmanAnnotation + "podid"   // ID of pod if applicable
	InfraLabelName = PodmanAnnotation + "infra"   // present only if container is an infra container
)

Podman-specific "annotation" labels.

const Type = "podman.io"

Type specifies this container engine's type identifier.

Types

type NewOption

type NewOption func(*PodmanWatcher)

NewOption represents options to NewPodmanWatcher when creating new watchers keeping eyes on Podman daemons.

func WithPID

func WithPID(pid int) NewOption

WithPID sets the engine's PID when known.

func WithRucksackPacker

func WithRucksackPacker(packer engineclient.RucksackPacker) NewOption

WithRucksackPacker sets the Rucksack packer that adds application-specific container information based on the inspected container data. The specified Rucksack packer gets passed the inspection data in form of a Docker client types.ContainerJSON.

type PodmanWatcher

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

PodmanWatcher is a Podman EngineClient for interfacing the generic whale watching with podman daemons. There, I've said the bad word: "daemon". Never say "daemon" in the podman world. The podman creators even implemented a process dead (line) just to justify not having to call it "daemon" because it doesn't run constantly in the background. Unless someone watches a podman.

func NewPodmanWatcher

func NewPodmanWatcher(podman context.Context, opts ...NewOption) *PodmanWatcher

NewPodmanWatcher returns a new PodmanWatcher using the specified podman connection; typically, you would want to use this lower-level constructor only in unit tests and instead use sealwatcher.New instead in most use cases.

func (*PodmanWatcher) API

func (pw *PodmanWatcher) API() string

API returns the container engine API path.

func (*PodmanWatcher) Client

func (pw *PodmanWatcher) Client() interface{}

Client returns the underlying engine client (engine-specific); in case of Podman this is a context.Context (sic(k)!) that in turns contains a client.

func (*PodmanWatcher) Close

func (pw *PodmanWatcher) Close()

Close cleans up and release any engine client resources, if necessary.

func (*PodmanWatcher) ID

func (pw *PodmanWatcher) ID(svcctx context.Context) string

ID returns the (more or less) unique engine identifier; the exact format is engine-specific. In case of Podman there is no genuine engine ID due to Podman's architecture. So we simply use the API endpoint path as the ID.

func (*PodmanWatcher) Inspect

func (pw *PodmanWatcher) Inspect(svcctx context.Context, nameorid string) (*whalewatcher.Container, error)

Inspect (only) those container details of interest to us, given the name or ID of a container.

func (*PodmanWatcher) LifecycleEvents

func (pw *PodmanWatcher) LifecycleEvents(svcctx context.Context) (<-chan engineclient.ContainerEvent, <-chan error)

LifecycleEvents streams container engine events, limited just to those events in the lifecycle of containers getting born (=alive, as opposed to, say, "conceived") and die.

func (*PodmanWatcher) List

func (pw *PodmanWatcher) List(svcctx context.Context) ([]*whalewatcher.Container, error)

List all the currently alive and kicking containers, but do not list any containers without any processes.

func (*PodmanWatcher) PID

func (pw *PodmanWatcher) PID() int

PID returns the container engine PID, when known.

func (*PodmanWatcher) Try

func (pw *PodmanWatcher) Try(svcctx context.Context) error

Try queries the version of the Podman service and caches the result.

func (*PodmanWatcher) Type

func (pw *PodmanWatcher) Type() string

Type returns the type identifier for this container engine.

func (*PodmanWatcher) Version

func (pw *PodmanWatcher) Version(svcctx context.Context) string

Version information about this Podman engine.