sealwatcher

README

Sealwatcher

sealwatcher adds Podman support to @thediveo/whalewatcher in order to track the list of containers (name, PID, project, pod) without constant polling and without the hassle of event "binge processing".

Please note: because building the Podman REST API client requires a considerable amount of C libraries as well as header files to be installed in the build system, sealwatcher isn't an integral part of the whalewatcher module so far. If at some future point the Podman project improves the situation so that Podman REST API clients can be built without the huge installation overhead, then sealwatcher might be finally integrated into whalewatcher.

Installation

First, install the non-Go stuff the Podman module insists of having available, even if it is totally unnecessary for a REST API client. The following is a massively stripped-down version of the Debian/Ubuntu package list from Podman's "Building from scratch" instructions:

sudo apt-get -y install build-essential pkg-config libbtrfs-dev libgpgme-dev

In order to use sealwatcher as a depency in your own Go modules, you first need to pin the cni module version in your go.mod...

replace github.com/containernetworking/cni => github.com/containernetworking/cni v0.8.1

...and only then you can go get the sealwatcher module.

go get github.com/thediveo/sealwatcher

Finally, when building your application using sealwatcher directly or indirectly, use these build tags:

-tags exclude_graphdriver_btrfs,exclude_graphdriver_devicemapper,libdm_no_deferred_remove

Supported Go Versions

sealwatcher supports versions of Go that are noted by the Go release policy, that is, N and N-1 major versions.

Miscellaneous

• to view the package documentation locally:
  • either: make pkgsite,
  • or, in VSCode (using the VSCode-integrated simple browser): “Tasks: Run Task” ⇢ “View Go module documentation”.
• make shows the available make targets.

Hacking It

This project comes with comprehensive unit tests, even covering goroutine and file descriptor leak checks:

• goroutine leak checking courtesy of Gomega's gleak package.

• file descriptor leak checking courtesy of the @thediveo/fdooze module.

Note: do not run parallel tests for multiple packages. make test ensures to run all package tests always sequentially, but in case you run go test yourself, please don't forget -p 1 when testing multiple packages in one, erm, go.

Copyright and License

Copyright 2022-23 Harald Albrecht, licensed under the Apache License, Version 2.0.

Documentation

Overview

Package sealwatcher provides a container watcher.Watcher for Podman engines.

Usage

import "github.com/thediveo/sealwatcher"
watcher := sealwatcher.NewWatcher("", nil) // with default backoff

The watcher constructor accepts options, with currently the only option being specifying a container engine's PID. The PID information then can be used downstream in tools like lxkns to translate container PIDs between different PID namespaces.

Notes

This package adds the following Podman-specific "annotation" labels to the discovered containers:

• io.github.thediveo/podman/podname (PodLabelName) – if present, the name of the corresponding pod the container belongs to.
• io.github.thediveo/podman/infra (InfraLabelName) – just the presence of this label marks a container as an “infrastructure” container, its value doesn't matter and must not be relied upon.

Index

• Constants
• func New(podmansock string, buggeroff backoff.BackOff, opts ...engineclient.NewOption) (watcher.Watcher, error)

Constants

const InfraLabelName = engineclient.InfraLabelName

InfraLabelName is the label key that is present on “infrastructure” containers only; the label value is irrelevant and must not be relied upon.

const PodLabelName = engineclient.PodLabelName

PodLabelName is the label key for the pod name in case a container belongs to a pod.

const Type = engineclient.Type

Type ID of the container engine handled by this watcher.

Functions

func New

func New(podmansock string, buggeroff backoff.BackOff, opts ...engineclient.NewOption) (watcher.Watcher, error)

New returns a watcher.Watcher for keeping track of the currently alive containers, optionally with the composer projects they're associated with.

When the podmansock parameter is left empty then Podman's usual client defaults apply, such as trying to pick it up from the environment or falling back to the local host's "unix:///run/podman/podman.sock".

If the backoff is nil then the backoff defaults to backoff.StopBackOff, that is, any failed operation will never be retried.

Finally, Podman engine client-specific options can be passed in.