summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorbaude <bbaude@redhat.com>2021-01-15 10:49:40 -0600
committerbaude <bbaude@redhat.com>2021-01-15 10:49:40 -0600
commitf59c29a6d7a58a0a324636e767570d8f6ab9624d (patch)
tree0188000d6598f2eebfae8d65d449be2be8d2c907
parent7d3a628c6ba79efa4b0daaff904b6c2b157dcfc5 (diff)
downloadpodman-f59c29a6d7a58a0a324636e767570d8f6ab9624d.tar.gz
podman-f59c29a6d7a58a0a324636e767570d8f6ab9624d.tar.bz2
podman-f59c29a6d7a58a0a324636e767570d8f6ab9624d.zip
[CI:DOCS]Add README.md for golang bindings
Add a brief description of the golang bindings and provide examples on how to use them Signed-off-by: baude <bbaude@redhat.com>
-rw-r--r--pkg/bindings/README.md156
1 files changed, 156 insertions, 0 deletions
diff --git a/pkg/bindings/README.md b/pkg/bindings/README.md
new file mode 100644
index 000000000..149deda5e
--- /dev/null
+++ b/pkg/bindings/README.md
@@ -0,0 +1,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/v2/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/v2/pkg/bindings"
+ "github.com/containers/podman/v2/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/v2/pkg/bindings"
+ "github.com/containers/podman/v2/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/v2/pkg/bindings"
+ "github.com/containers/podman/v2/pkg/bindings/containers"
+ "github.com/containers/podman/v2/pkg/bindings/images"
+ "github.com/containers/podman/v2/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.")
+}
+```