From 76120ce6388085c529d64e6bf6529dddb5681644 Mon Sep 17 00:00:00 2001 From: Matthew Heon Date: Mon, 30 Sep 2019 08:56:38 -0400 Subject: Move derivitive doc so it won't be treated as a manpage Anything with the .md suffix in docs/ gets compiled into a manpage, so let's get things that aren't manpages out of there. This isn't precisely a tutorial, but it seems like the next best place. Signed-off-by: Matthew Heon --- docs/tutorials/podman-derivative-api.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/tutorials/podman-derivative-api.md (limited to 'docs/tutorials') diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md new file mode 100644 index 000000000..0342bb740 --- /dev/null +++ b/docs/tutorials/podman-derivative-api.md @@ -0,0 +1,44 @@ +# How to use libpod for custom/derivative projects + +libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. + +Running as a subprocess +--- + +Advantages: + + - Many commands output JSON + - Works with languages other than Golang + - Easy to get started + +Disadvantages: + + - Error handling is harder + - May be slower + - Can't hook into or control low-level things like how images are pulled + +Vendoring into a Go project +--- + +Advantages: + + - Significant power and control + +Disadvantages: + + - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate) + - Binary size + - Potential skew between multiple libpod versions operating on the same storage can cause problems + +Varlink +--- + +Some code exists for this; splits the difference. Future uncertain. + +Making the choice +--- + +A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? +If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally +different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, +that may drive you towards vendoring. \ No newline at end of file -- cgit v1.2.3-54-g00ecf