From af00094558e0d16b56a7d4896a3c7ac250678498 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Wed, 25 Sep 2019 17:26:56 +0000 Subject: docs/podman-derivative-api.md: New file https://github.com/debarshiray/toolbox/ was planning to vendor libpod which I disagreed with. Let's document the advantages/disadvantages as they exist today. Signed-off-by: Colin Walters --- docs/podman-derivative-api.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/podman-derivative-api.md (limited to 'docs/podman-derivative-api.md') diff --git a/docs/podman-derivative-api.md b/docs/podman-derivative-api.md new file mode 100644 index 000000000..0342bb740 --- /dev/null +++ b/docs/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