aboutsummaryrefslogtreecommitdiff
path: root/pkg/bindings/README.md
blob: 6fd7d7831ed50e0a2b14721778ab669160393a39 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# 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.")
}
```