podman

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 20, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const PodmanAuthLockFileName = "podman-auth.lock"

PodmanAuthLockFileName is the name of the lock file used to serialize concurrent podman login operations that write to the shared auth.json file.

Variables

View Source 
var CommonRegistries = map[string]string{
	"dockerhub": "docker.io",
	"docker":    "docker.io",
	"ghcr":      "ghcr.io",
	"github":    "ghcr.io",
	"gcr":       "gcr.io",
	"google":    "gcr.io",
	"ecr":       "amazonaws.com",
	"aws":       "amazonaws.com",
	"acr":       "azurecr.io",
	"azure":     "azurecr.io",
	"quay":      "quay.io",
	"gitlab":    "registry.gitlab.com",
}

Functions

func BuildImageRef 

func BuildImageRef(registry, repository, tag string) string

func ParseImageRef 

func ParseImageRef(image string) (registry, repository, tag string)

ParseImageRef parses an image reference into registry, repository, and tag.

func PodmanAuthLockFile 

func PodmanAuthLockFile(user string) string

PodmanAuthLockFile returns the path to the podman auth lock file for the given user. Deprecated: Use state.LockFile(user, "podman-auth") instead.

func QualifyImage 

func QualifyImage(image string) string

QualifyImage ensures an image reference is fully qualified with a registry prefix so that Podman can pull it without unqualified-search registries. Short names like "postgres:18" become "docker.io/library/postgres:18", and "myuser/myimage:v1" becomes "docker.io/myuser/myimage:v1". Already-qualified references (containing a dot or colon in the first path component, e.g. "ghcr.io/org/img:tag") are returned unchanged.

func ResolveRegistry 

func ResolveRegistry(name string) string

func ValidateOptions 

func ValidateOptions(options []string) error

ValidateOptions checks that none of the extra options contain denied flags.

Types

type BuildConfig 

type BuildConfig struct {
	Context    string
	Dockerfile string
	Tag        string
	Tags       []string
	Args       map[string]string
	Target     string
	CacheFrom  []string
	CacheTo    string
	Platform   string
	NoCache    bool
	Pull       bool
	Squash     bool
	Secrets    []string
	SSH        []string
	Options    []string
}

BuildConfig holds configuration for building an image.

func (*BuildConfig) BuildCommand 

func (c *BuildConfig) BuildCommand() string

type Client 

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

Client executes Podman commands on remote hosts via SSH.

func NewClient 

func NewClient(sshClient *ssh.Client) *Client

func NewClientWithCommand 

func NewClientWithCommand(sshClient *ssh.Client, command string) *Client

NewClientWithCommand creates a Podman client with a custom command prefix. Example: "sudo -n podman" for rootful operations via passwordless sudo.

func (*Client) Execute 

func (c *Client) Execute(host string, args ...string) (*ssh.Result, error)

func (*Client) ExecuteAll 

func (c *Client) ExecuteAll(hosts []string, args ...string) []*ssh.Result

func (*Client) GetInfo 

func (c *Client) GetInfo(host string) (*Info, error)

func (*Client) RewriteCommand 

func (c *Client) RewriteCommand(cmd string) string

RewriteCommand rewrites shell commands generated with "podman" to use this client's configured command prefix (e.g. "sudo -n podman").

func (*Client) Version 

func (c *Client) Version(host string) (string, error)

type Container 

type Container struct {
	ID      string
	Name    string
	Image   string
	Status  string
	State   string
	Created time.Time
	Ports   []string
	Labels  map[string]string
}

type ContainerConfig 

type ContainerConfig struct {
	Name       string
	Image      string
	Command    []string
	Entrypoint string
	Env        map[string]string
	SecretEnv  []string // Secret env var names (resolved from secrets file)
	EnvFile    string   // Path to env file on remote host
	// EnvFileOptional controls whether a missing env file is tolerated.
	// When true, run command falls back to no env file if it's missing.
	EnvFileOptional bool
	Ports           []string // host:container or ip:host:container
	Volumes         []string // host:container or host:container:options
	Labels          map[string]string
	Network         string
	NetworkAliases  []string
	Networks        []string
	Memory          string // e.g., "512m"
	CPUs            string // e.g., "0.5"
	Restart         string // no, always, unless-stopped, on-failure[:max-retries]
	Detach          bool
	Remove          bool
	Pull            bool

	// Healthcheck
	HealthCmd         string
	HealthInterval    string
	HealthTimeout     string
	HealthRetries     int
	HealthStartPeriod string

	Options []string // Additional run options
}

ContainerConfig holds configuration for running a container.

func (*ContainerConfig) BuildRunCommand 

func (c *ContainerConfig) BuildRunCommand() string

type ContainerManager 

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

ContainerManager handles container lifecycle operations via Podman.

func NewContainerManager 

func NewContainerManager(client *Client) *ContainerManager

func (*ContainerManager) ConnectNetwork 

func (m *ContainerManager) ConnectNetwork(host, container, network string) error

func (*ContainerManager) CopyFrom 

func (m *ContainerManager) CopyFrom(host, container, src, dest string) error

func (*ContainerManager) CopyTo 

func (m *ContainerManager) CopyTo(host, container, src, dest string) error

func (*ContainerManager) DisconnectNetwork 

func (m *ContainerManager) DisconnectNetwork(host, container, network string) error

func (*ContainerManager) Exec 

func (m *ContainerManager) Exec(host string, config *ExecConfig) (*ssh.Result, error)

func (*ContainerManager) ExecInteractive 

func (m *ContainerManager) ExecInteractive(host string, config *ExecConfig, stdin io.Reader, stdout, stderr io.Writer) error

func (*ContainerManager) Exists 

func (m *ContainerManager) Exists(host, container string) (bool, error)

func (*ContainerManager) HasHealthcheck 

func (m *ContainerManager) HasHealthcheck(host, container string) (bool, error)

HasHealthcheck checks whether the container has a Podman HEALTHCHECK defined.

func (*ContainerManager) HostPort 

func (m *ContainerManager) HostPort(host, container string, containerPort int) (int, error)

HostPort resolves the published host port for containerPort/tcp.

func (*ContainerManager) Inspect 

func (m *ContainerManager) Inspect(host, container string) (string, error)

func (*ContainerManager) IsRunning 

func (m *ContainerManager) IsRunning(host, container string) (bool, error)

func (*ContainerManager) Kill 

func (m *ContainerManager) Kill(host, container, signal string) error

func (*ContainerManager) List 

func (m *ContainerManager) List(host string, all bool, filters map[string]string) ([]Container, error)

func (*ContainerManager) Logs 

func (m *ContainerManager) Logs(host string, config *LogsConfig) (*ssh.Result, error)

func (*ContainerManager) LogsStream 

func (m *ContainerManager) LogsStream(host string, config *LogsConfig, stdout, stderr io.Writer) error

func (*ContainerManager) Prune 

func (m *ContainerManager) Prune(host string) (int, error)

func (*ContainerManager) Remove 

func (m *ContainerManager) Remove(host, container string, force bool) error

func (*ContainerManager) Rename 

func (m *ContainerManager) Rename(host, oldName, newName string) error

func (*ContainerManager) Restart 

func (m *ContainerManager) Restart(host, container string, timeout int) error

func (*ContainerManager) Run 

func (m *ContainerManager) Run(host string, config *ContainerConfig) (string, error)

func (*ContainerManager) Start 

func (m *ContainerManager) Start(host, container string) error

func (*ContainerManager) Stats 

func (m *ContainerManager) Stats(host, container string) (string, error)

func (*ContainerManager) Stop 

func (m *ContainerManager) Stop(host, container string, timeout int) error

func (*ContainerManager) WaitHealthy 

func (m *ContainerManager) WaitHealthy(host, container string, timeout time.Duration) error

func (*ContainerManager) WaitRunning 

func (m *ContainerManager) WaitRunning(host, container string, stabilize time.Duration) error

WaitRunning waits for a brief stabilization period and then verifies the container is still running. This catches containers that crash immediately on start (e.g., bad config, missing env vars).

type ExecConfig 

type ExecConfig struct {
	Container   string
	Command     []string
	Interactive bool
	TTY         bool
	User        string
	WorkDir     string
	Env         map[string]string
	Detach      bool
}

ExecConfig holds configuration for executing a command in a container.

func (*ExecConfig) BuildExecCommand 

func (c *ExecConfig) BuildExecCommand() string

type Image 

type Image struct {
	ID         string
	Repository string
	Tag        string
	Size       string
	Created    time.Time
}

type ImageManager 

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

ImageManager handles image operations via Podman.

func NewImageManager 

func NewImageManager(client *Client) *ImageManager

func (*ImageManager) Build 

func (m *ImageManager) Build(host string, config *BuildConfig) error

func (*ImageManager) Exists 

func (m *ImageManager) Exists(host, image string) (bool, error)

func (*ImageManager) GetDigest 

func (m *ImageManager) GetDigest(host, image string) (string, error)

func (*ImageManager) List 

func (m *ImageManager) List(host string, filters map[string]string) ([]Image, error)

func (*ImageManager) Load 

func (m *ImageManager) Load(host, inputPath string) error

func (*ImageManager) ManifestBuild 

func (m *ImageManager) ManifestBuild(host string, config *ManifestBuildConfig) error

func (*ImageManager) Prune 

func (m *ImageManager) Prune(host string, all bool) error

func (*ImageManager) Pull 

func (m *ImageManager) Pull(host, image string) error

func (*ImageManager) PullAll 

func (m *ImageManager) PullAll(hosts []string, image string) map[string]error

func (*ImageManager) Push 

func (m *ImageManager) Push(host, image string) error

func (*ImageManager) Remove 

func (m *ImageManager) Remove(host, image string, force bool) error

func (*ImageManager) Save 

func (m *ImageManager) Save(host, image, outputPath string) error

func (*ImageManager) Tag 

func (m *ImageManager) Tag(host, source, target string) error

type Info 

type Info struct {
	ServerVersion     string
	ContainersTotal   int
	ContainersRunning int
	ContainersPaused  int
	ContainersStopped int
	Images            int
	Driver            string
	MemoryTotal       string
	CPUs              int
}

type LogsConfig 

type LogsConfig struct {
	Container  string
	Follow     bool
	Tail       string
	Timestamps bool
	Since      string
	Until      string
}

LogsConfig holds configuration for viewing container logs.

func (*LogsConfig) BuildLogsCommand 

func (c *LogsConfig) BuildLogsCommand() string

type ManifestBuildConfig 

type ManifestBuildConfig struct {
	BuildConfig
	Platforms []string // e.g., ["linux/amd64", "linux/arm64"]
	Push      bool
	CacheTo   string
	Output    string
}

ManifestBuildConfig holds configuration for multi-arch manifest builds.

func (*ManifestBuildConfig) ManifestBuildCommands 

func (c *ManifestBuildConfig) ManifestBuildCommands() []string

ManifestBuildCommands generates manifest create, per-platform builds, and optional manifest push commands.

type RegistryConfig 

type RegistryConfig struct {
	Server   string // e.g., docker.io, ghcr.io, gcr.io
	Username string
	Password string
	Email    string
}

RegistryConfig holds registry authentication configuration.

type RegistryManager 

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

RegistryManager handles container registry operations via Podman.

func NewRegistryManager 

func NewRegistryManager(client *Client) *RegistryManager

NewRegistryManager creates a new RegistryManager. The user parameter is the SSH user (e.g., "root" or "deploy") used to determine the correct state directory paths on remote hosts.

func NewRegistryManagerWithUser 

func NewRegistryManagerWithUser(client *Client, user string) *RegistryManager

NewRegistryManagerWithUser creates a new RegistryManager with a specific SSH user.

func (*RegistryManager) ECRLogin 

func (m *RegistryManager) ECRLogin(host, region, accountID string) error

ECRLogin handles AWS ECR login via the AWS CLI.

func (*RegistryManager) GCRLogin 

func (m *RegistryManager) GCRLogin(host, keyFile string) error

GCRLogin handles Google Container Registry login via a JSON key file.

func (*RegistryManager) GetAuthToken 

func (m *RegistryManager) GetAuthToken(config *RegistryConfig) string

func (*RegistryManager) IsLoggedIn 

func (m *RegistryManager) IsLoggedIn(host, server string) (bool, error)

func (*RegistryManager) Login 

func (m *RegistryManager) Login(host string, config *RegistryConfig) error

func (*RegistryManager) LoginAll 

func (m *RegistryManager) LoginAll(hosts []string, config *RegistryConfig) map[string]error

func (*RegistryManager) Logout 

func (m *RegistryManager) Logout(host, server string) error

func (*RegistryManager) LogoutAll 

func (m *RegistryManager) LogoutAll(hosts []string, server string) map[string]error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.