bindings

README

Podman Golang bindings

The Podman Go bindings are a set of functions to allow developers to execute Podman operations from within their Go based application. The Go bindings connect to a Podman service which can run locally or on a remote machine. You can perform many operations including pulling and listing images, starting, stopping or inspecting containers. Currently, the Podman repository has bindings available for operations on images, containers, pods, networks and manifests among others.

Quick Start

The bindings require that the Podman system service is running for the specified user. This can be done with systemd using the systemctl command or manually by calling the service directly.

Starting the service with system

The command to start the Podman service differs slightly depending on the user that is running the service. For a rootful service, start the service like this:

# systemctl start podman.socket

For a non-privileged, aka rootless, user, start the service like this:

$ systemctl start --user podman.socket

Starting the service manually

It can be handy to run the system service manually. Doing so allows you to enable debug messaging.

$ podman --log-level=debug system service -t0

If you do not provide a specific path for the socket, a default is provided. The location of that socket for rootful connections is /run/podman/podman.sock and for rootless it is /run/USERID#/podman/podman.sock. For more information about the Podman system service, see man podman-system-service.

Creating a connection

The first step for using the bindings is to create a connection to the socket. As mentioned earlier, the destination of the socket depends on the user who owns it. In this case, a rootful connection is made.

import (
	"context"
	"fmt"
	"os"

	"github.com/containers/podman/v3/pkg/bindings"
)

func main() {
	conn, err := bindings.NewConnection(context.Background(), "unix://run/podman/podman.sock")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}

}

The conn variable returned from the bindings.NewConnection function can then be used in subsequent function calls to interact with containers.

Examples

The following examples build upon the connection example from above. They are all rootful connections as well.

Inspect a container

The following example obtains the inspect information for a container named foorbar and then prints the container's ID. Note the use of optional inspect options for size.

import (
	"context"
	"fmt"
	"os"

	"github.com/containers/podman/v3/pkg/bindings"
	"github.com/containers/podman/v3/pkg/bindings/containers"
)

func main() {
	conn, err := bindings.NewConnection(context.Background(), "unix://run/podman/podman.sock")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	inspectData, err := containers.Inspect(conn, "foobar", new(containers.InspectOptions).WithSize(true))
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	// Print the container ID
	fmt.Println(inspectData.ID)
}

Pull an image

The following example pulls the image quay.ioo/libpod/alpine_nginx to the local image store.

import (
	"context"
	"fmt"
	"os"

	"github.com/containers/podman/v3/pkg/bindings"
	"github.com/containers/podman/v3/pkg/bindings/images"
)

func main() {
	conn, err := bindings.NewConnection(context.Background(), "unix://run/podman/podman.sock")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	_, err = images.Pull(conn, "quay.io/libpod/alpine_nginx", nil)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

Pull an image, create a container, and start the container

The following example pulls the quay.io/libpod/alpine_nginx image and then creates a container named foobar from it. And finally, it starts the container.

import (
	"context"
	"fmt"
	"os"

	"github.com/containers/podman/v3/pkg/bindings"
	"github.com/containers/podman/v3/pkg/bindings/containers"
	"github.com/containers/podman/v3/pkg/bindings/images"
	"github.com/containers/podman/v3/pkg/specgen"
)

func main() {
	conn, err := bindings.NewConnection(context.Background(), "unix://run/podman/podman.sock")
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	_, err = images.Pull(conn, "quay.io/libpod/alpine_nginx", nil)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	s := specgen.NewSpecGenerator("quay.io/libpod/alpine_nginx", false)
	s.Name = "foobar"
	createResponse, err := containers.CreateWithSpec(conn, s, nil)
	if err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	fmt.Println("Container created.")
	if err := containers.Start(conn, createResponse.ID, nil); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
	fmt.Println("Container started.")
}

Documentation

Overview

Package bindings provides golang-based access to the Podman REST API. Users can then interact with API endpoints to manage containers, images, pods, etc.

This package exposes a series of methods that allow users to firstly create their connection with the API endpoints. Once the connection is established, users can then manage the Podman container runtime.

Index

• Variables
• func CheckResponseCode(inError error) (int, error)
• func FiltersToString(filters map[string][]string) (string, error)
• func JoinURL(elements ...string) string
• func NewConnection(ctx context.Context, uri string) (context.Context, error)
• func NewConnectionWithIdentity(ctx context.Context, uri string, identity string) (context.Context, error)
• type APIResponse
  • func (h *APIResponse) IsClientError() bool
  • func (h *APIResponse) IsInformational() bool
  • func (h *APIResponse) IsRedirection() bool
  • func (h *APIResponse) IsServerError() bool
  • func (h *APIResponse) IsSuccess() bool
  • func (h APIResponse) Process(unmarshalInto interface{}) error
• type Connection
  • func GetClient(ctx context.Context) (*Connection, error)
  • func (c *Connection) DoRequest(httpBody io.Reader, httpMethod, endpoint string, queryParams url.Values, ...) (*APIResponse, error)

Variables

var (
	PTrue = &pTrue

	PFalse = &pFalse

	// APIVersion - podman will fail to run if this value is wrong
	APIVersion = semver.MustParse("2.0.0")
)

var (
	BasePath = &url.URL{
		Scheme: "http",
		Host:   "d",
		Path:   "/v" + APIVersion.String() + "/libpod",
	}
)

var (
	ErrNotImplemented = errors.New("function not implemented")
)

Functions

func CheckResponseCode

func CheckResponseCode(inError error) (int, error)

func FiltersToString

func FiltersToString(filters map[string][]string) (string, error)

FiltersToString converts our typical filter format of a map[string][]string to a query/html safe string.

func JoinURL

func JoinURL(elements ...string) string

JoinURL elements with '/'

func NewConnection

func NewConnection(ctx context.Context, uri string) (context.Context, error)

func NewConnectionWithIdentity

func NewConnectionWithIdentity(ctx context.Context, uri string, identity string) (context.Context, error)

NewConnection takes a URI as a string and returns a context with the Connection embedded as a value. This context needs to be passed to each endpoint to work correctly.

A valid URI connection should be scheme:// For example tcp://localhost:<port> or unix:///run/podman/podman.sock or ssh://<user>@<host>[:port]/run/podman/podman.sock?secure=True

Types

type APIResponse

type APIResponse struct {
	*http.Response
	Request *http.Request
}

func (*APIResponse) IsClientError

func (h *APIResponse) IsClientError() bool

IsClientError returns true if the response code is 4xx

func (*APIResponse) IsInformational

func (h *APIResponse) IsInformational() bool

IsInformation returns true if the response code is 1xx

func (*APIResponse) IsRedirection

func (h *APIResponse) IsRedirection() bool

IsRedirection returns true if the response code is 3xx

func (*APIResponse) IsServerError

func (h *APIResponse) IsServerError() bool

IsServerError returns true if the response code is 5xx

func (*APIResponse) IsSuccess

func (h *APIResponse) IsSuccess() bool

IsSuccess returns true if the response code is 2xx

func (APIResponse) Process

func (h APIResponse) Process(unmarshalInto interface{}) error

type Connection

type Connection struct {
	URI    *url.URL
	Client *http.Client
}

func GetClient

func GetClient(ctx context.Context) (*Connection, error)

GetClient from context build by NewConnection()

func (*Connection) DoRequest

func (c *Connection) DoRequest(httpBody io.Reader, httpMethod, endpoint string, queryParams url.Values, header map[string]string, pathValues ...string) (*APIResponse, error)

DoRequest assembles the http request and returns the response