Copyright	(c) 2021 Red Hat
License	Apache-2.0
Maintainer	Tristan de Cacqueray <tdecacqu@redhat.com>
Safe Haskell	None
Language	Haskell2010

Podman

Contents

Client
Server
Container
Exec
Pod
Image
Network
Volume
Secret
client API version
re-exports

Description

See Podman.Tutorial to learn how to use this library.

Here is the recommended way to import this library:

{-# LANGUAGE OverloadedStrings #-}

import Podman

This module re-exports the rest of the library.

Podman.Types provides data types generated from the swagger definitions.

Podman.Internal provides utility function to further decode API response. Internal is exposed for testing purpose and it shouldn't be used.

Notes

Some notes on the API. And on Podman generally. (Particularly on ttys, and attaching and detaching from them, since that's quite fiddly.)

When creating a container, _specGeneratorstdin is equivalent to "podman container create -i ...". However, it doesn't automatically allocate a tty. You need _specGeneratorterminal for that (the equivalent of passing "-t" to "podman container create").
If attaching to a container, a tty needs to be allocated if you want to detach again using the "detach keys". See container attach man page for details of "container attach", and this "wontfix" issue which says detaching from a non-tty container is not supported.
The Podman API notes on "containers/{ctr_name}/attach" are not very complete. It looks like the Docker Engine API docs have additional information (see https://docs.docker.com/engine/api/v1.41/#operation/ContainerAttach). Namely:
- When attaching to a container, the HTTP connection is "hijacked" so as to transport stdin, stdout, and stderr on the same socket.
- The response from the daemon for an attach request is:
```
 HTTP/1.1 200 OK
 Content-Type: application/vnd.docker.raw-stream

 [STREAM]
 
```
  After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.
- The client will (should?) send Upgrade: tcp and Connection: Upgrade headers in its request.
- If that happens server will (should?) respond with HTTP/1.1 101 UPGRADED, and Connection: Upgrade and Upgrade: tcp headers.
- Those "upgrade" headers are supposed to be a hint to any HTTP proxies about what's going on; but I suspect a fair few proxies just won't be able to cope with the socket being hijacked in this way.
- See the Docker API documentation for more info (e.g. on the stream format).

Synopsis

data PodmanClient
withClient :: MonadIO m => Text -> (PodmanClient -> m a) -> m a
type Result a = Either Error a
getVersion :: MonadIO m => PodmanClient -> m (Result Version)
newtype ContainerName = ContainerName Text
containerExists :: MonadIO m => PodmanClient -> ContainerName -> m (Result Bool)
containerInspect :: MonadIO m => PodmanClient -> ContainerName -> Bool -> m (Result InspectContainerResponse)
containerList :: MonadIO m => PodmanClient -> ContainerListQuery -> m (Result [ListContainer])
containerCreate :: MonadIO m => PodmanClient -> SpecGenerator -> m (Result ContainerCreateResponse)
data WaitCondition
- = Configured
- | Created
- | Running
- | Stopped
- | Paused
- | Exited
- | Removing
- | Stopping
containerWait :: MonadIO m => PodmanClient -> ContainerName -> WaitCondition -> m (Either Error Int)
mkSpecGenerator :: Text -> SpecGenerator
containerStart :: MonadIO m => PodmanClient -> ContainerName -> Maybe Text -> m (Maybe Error)
containerDelete :: MonadIO m => PodmanClient -> ContainerName -> Maybe Bool -> Maybe Bool -> m (Maybe Error)
containerKill :: MonadIO m => PodmanClient -> ContainerName -> Maybe Text -> m (Maybe Error)
containerMount :: MonadIO m => PodmanClient -> ContainerName -> m (Either Error FilePath)
containerPause :: MonadIO m => PodmanClient -> ContainerName -> m (Maybe Error)
containerUnpause :: MonadIO m => PodmanClient -> ContainerName -> m (Maybe Error)
containerRename :: MonadIO m => PodmanClient -> ContainerName -> ContainerName -> m (Maybe Error)
containerRestart :: MonadIO m => PodmanClient -> ContainerName -> Maybe Word -> m (Maybe Error)
containerSendFiles :: MonadIO m => PodmanClient -> ContainerName -> [Entry] -> Text -> Maybe Bool -> m (Maybe Error)
containerGetFiles :: MonadIO m => PodmanClient -> ContainerName -> Text -> m (Result (Entries FormatError))
containerAttach :: MonadIO m => PodmanClient -> ContainerName -> AttachQuery -> (ContainerConnection -> IO a) -> m (Result a)
containerChanges :: MonadIO m => PodmanClient -> ContainerName -> m (Result [ContainerChange])
containerInitialize :: MonadIO m => PodmanClient -> ContainerName -> m (Maybe Error)
containerExport :: MonadIO m => PodmanClient -> ContainerName -> m (Result (Entries FormatError))
containerLogs :: MonadIO m => PodmanClient -> ContainerName -> LogStream -> LogsQuery -> (ContainerOutput -> IO ()) -> m (Maybe Error)
data LogStream
- = LogStdout
- | LogStderr
- | LogBoth
data ContainerConnection = ContainerConnection {
- containerRecv :: IO ContainerOutput
- containerSend :: ByteString -> IO ()
}
data ContainerOutput
- = EOF
- | Stdout ByteString
- | Stderr ByteString
newtype ExecId = ExecId Text
execCreate :: MonadIO m => PodmanClient -> ContainerName -> ExecConfig -> m (Result ExecId)
execInspect :: MonadIO m => PodmanClient -> ExecId -> m (Result ExecInspectResponse)
execStart :: MonadIO m => PodmanClient -> ExecId -> m (Result [ContainerOutput])
generateKubeYAML :: MonadIO m => PodmanClient -> [ContainerName] -> Bool -> m (Result Text)
generateSystemd :: MonadIO m => PodmanClient -> ContainerName -> GenerateSystemdQuery -> m (Result (Map Text Text))
newtype ImageName = ImageName Text
imageExists :: MonadIO m => PodmanClient -> ImageName -> m (Result Bool)
imageList :: MonadIO m => PodmanClient -> ImageListQuery -> m (Result [ImageSummary])
imageTree :: MonadIO m => PodmanClient -> ImageName -> Maybe Bool -> m (Result ImageTreeResponse)
imagePull :: MonadIO m => PodmanClient -> ImagePullQuery -> m (Result [ImageName])
imagePullRaw :: MonadIO m => PodmanClient -> ImagePullQuery -> m (Result ImagesPullResponse)
newtype NetworkName = NetworkName Text
networkExists :: MonadIO m => PodmanClient -> NetworkName -> m (Maybe Error)
networkList :: MonadIO m => PodmanClient -> Maybe Text -> m (Result [NetworkListReport])
newtype VolumeName = VolumeName Text
volumeExists :: MonadIO m => PodmanClient -> VolumeName -> m (Maybe Error)
volumeList :: MonadIO m => PodmanClient -> Maybe Text -> m (Result [Volume])
newtype SecretName = SecretName Text
secretList :: MonadIO m => PodmanClient -> m (Result [SecretInfoReport])
secretCreate :: MonadIO m => PodmanClient -> SecretName -> ByteString -> m (Result SecretCreateResponse)
secretInspect :: MonadIO m => PodmanClient -> SecretName -> m (Result SecretInfoReport)
pattern API_VERSION :: (Eq a, IsString a) => a
module Podman.Types
data Text

Client

data PodmanClient Source #

Use withClient to create the PodmanClient

withClient Source #

Arguments

:: MonadIO m
=> Text	The api url, can be `"http+unix://var/run/podman.sock"` or `"https://localhost:9000"`
-> (PodmanClient -> m a)	The callback
-> m a	withClient performs the IO

type Result a = Either Error a Source #

Action result

Server

getVersion :: MonadIO m => PodmanClient -> m (Result Version) Source #

Returns the Component Version information

Container

newtype ContainerName Source #

Constructors

ContainerName Text

Instances

Eq ContainerName Source #
Instance details Defined in Podman.Api Methods (==) :: ContainerName -> ContainerName -> Bool # (/=) :: ContainerName -> ContainerName -> Bool #
Show ContainerName Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> ContainerName -> ShowS # show :: ContainerName -> String # showList :: [ContainerName] -> ShowS #

containerExists Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Result Bool)

Quick way to determine if a container exists by name or ID

containerInspect Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Bool	Get filesystem usage
-> m (Result InspectContainerResponse)

Return low-level information about a container.

containerList Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerListQuery	The list query, uses `defaultContainerListQuery`
-> m (Result [ListContainer])

Returns a list of containers

containerCreate :: MonadIO m => PodmanClient -> SpecGenerator -> m (Result ContainerCreateResponse) Source #

Create a container

data WaitCondition Source #

Constructors

Configured
Created
Running
Stopped
Paused
Exited
Removing
Stopping

Instances

Eq WaitCondition Source #
Instance details Defined in Podman.Api Methods (==) :: WaitCondition -> WaitCondition -> Bool # (/=) :: WaitCondition -> WaitCondition -> Bool #
Show WaitCondition Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> WaitCondition -> ShowS # show :: WaitCondition -> String # showList :: [WaitCondition] -> ShowS #

containerWait :: MonadIO m => PodmanClient -> ContainerName -> WaitCondition -> m (Either Error Int) Source #

Wait on a container to met a given condition

mkSpecGenerator Source #

Arguments

:: Text	image
-> SpecGenerator

Creates a SpecGenerator by setting all the optional attributes to Nothing

containerStart Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Maybe Text	Override the key sequence for detaching a container.
-> m (Maybe Error)

Start a container

containerDelete Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Maybe Bool	Force delete
-> Maybe Bool	Delete volumes
-> m (Maybe Error)

Delete container

containerKill Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Maybe Text	Signal to be sent to container, (default TERM)
-> m (Maybe Error)

Send a signal to a container, defaults to killing the container

containerMount Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Either Error FilePath)

Mount a container to the filesystem

containerPause Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Maybe Error)

Use the cgroups freezer to suspend all processes in a container.

containerUnpause Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Maybe Error)

Unpause Container

containerRename Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> ContainerName	New name for the container
-> m (Maybe Error)

Change the name of an existing container.

containerRestart Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Maybe Word	Timeout before sending kill signal to container
-> m (Maybe Error)

Restart a container

containerSendFiles Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> [Entry]	List of tar entries
-> Text	Path to a directory in the container to extract
-> Maybe Bool	Pause the container while copying (defaults to true)
-> m (Maybe Error)

Copy a tar archive of files into a container

containerGetFiles Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> Text	Path to a directory in the container to extract
-> m (Result (Entries FormatError))

Get a tar archive of files from a container

containerAttach Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> AttachQuery	The attach query, use `defaultAttachQuery`
-> (ContainerConnection -> IO a)	The callback
-> m (Result a)

Hijacks the connection to forward the container's standard streams to the client.

containerChanges Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Result [ContainerChange])

Report on changes to container's filesystem; adds, deletes or modifications.

containerInitialize Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Maybe Error)

Performs all tasks necessary for initializing the container but does not start the container.

containerExport Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> m (Result (Entries FormatError))

Export the contents of a container as a tarball.

containerLogs Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> LogStream	The log to stream
-> LogsQuery	The logs query, use `defaultLogsQuery`
-> (ContainerOutput -> IO ())	The callback
-> m (Maybe Error)

data LogStream Source #

Get stdout and stderr logs from a container.

Constructors

LogStdout
LogStderr
LogBoth

Instances

Eq LogStream Source #
Instance details Defined in Podman.Api Methods (==) :: LogStream -> LogStream -> Bool # (/=) :: LogStream -> LogStream -> Bool #
Show LogStream Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> LogStream -> ShowS # show :: LogStream -> String # showList :: [LogStream] -> ShowS #

data ContainerConnection Source #

A connection attached to a container. Note that full-duplex communication may require async threads because the http-client doesn't seems to expose aio (e.g. Connection doesn't have a fd, only a recv call)

Constructors

ContainerConnection
Fields containerRecv :: IO ContainerOutput containerSend :: ByteString -> IO ()

data ContainerOutput Source #

A container output

Constructors

EOF
Stdout ByteString
Stderr ByteString

Instances

Eq ContainerOutput Source #
Instance details Defined in Podman.Api Methods (==) :: ContainerOutput -> ContainerOutput -> Bool # (/=) :: ContainerOutput -> ContainerOutput -> Bool #
Show ContainerOutput Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> ContainerOutput -> ShowS # show :: ContainerOutput -> String # showList :: [ContainerOutput] -> ShowS #

Exec

newtype ExecId Source #

Constructors

ExecId Text

Instances

Eq ExecId Source #
Instance details Defined in Podman.Api Methods (==) :: ExecId -> ExecId -> Bool # (/=) :: ExecId -> ExecId -> Bool #
Show ExecId Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> ExecId -> ShowS # show :: ExecId -> String # showList :: [ExecId] -> ShowS #

execCreate Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	The container name
-> ExecConfig	The exec config
-> m (Result ExecId)

Create an exec instance

execInspect Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ExecId	Exec instance ID
-> m (Result ExecInspectResponse)

Inspect an exec instance

execStart Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ExecId	Exec instance ID
-> m (Result [ContainerOutput])

Start an exec instance

Pod

generateKubeYAML Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> [ContainerName]	List of name or ID of the container or pod.
-> Bool	Generate YAML for a Kubernetes service object.
-> m (Result Text)

Generate a Kubernetes YAML file.

generateSystemd Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ContainerName	Name or ID of the container or pod.
-> GenerateSystemdQuery	Systemd configuration.
-> m (Result (Map Text Text))

Generate Systemd Units based on a pod or container.

Image

newtype ImageName Source #

Constructors

ImageName Text

Instances

Eq ImageName Source #
Instance details Defined in Podman.Api Methods (==) :: ImageName -> ImageName -> Bool # (/=) :: ImageName -> ImageName -> Bool #
Show ImageName Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> ImageName -> ShowS # show :: ImageName -> String # showList :: [ImageName] -> ShowS #

imageExists Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ImageName	The image name
-> m (Result Bool)

Check if image exists in local store.

imageList Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ImageListQuery	The list query, use `defaultImageListQuery`
-> m (Result [ImageSummary])

Returns a list of images on the server.

imageTree Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ImageName	The image name
-> Maybe Bool	Show all child images and layers of the specified image
-> m (Result ImageTreeResponse)

Retrieve the image tree for the provided image name or ID

imagePull Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ImagePullQuery	The pull query, use `mkImagePullQuery`
-> m (Result [ImageName])

Pull one or more images from a container registry.

imagePullRaw Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> ImagePullQuery	The pull query, use `mkImagePullQuery`
-> m (Result ImagesPullResponse)

Pull one or more images from a container registry with the full results.

Network

newtype NetworkName Source #

Constructors

NetworkName Text

Instances

Eq NetworkName Source #
Instance details Defined in Podman.Api Methods (==) :: NetworkName -> NetworkName -> Bool # (/=) :: NetworkName -> NetworkName -> Bool #
Show NetworkName Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> NetworkName -> ShowS # show :: NetworkName -> String # showList :: [NetworkName] -> ShowS #

networkExists Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> NetworkName	The network name
-> m (Maybe Error)	Returns Nothing when the network exists

Check if network exists in local store.

networkList Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> Maybe Text	JSON encoded value of the filters (a map[string][]string) to process on the network list.
-> m (Result [NetworkListReport])

Returns a list of networks on the server.

Volume

newtype VolumeName Source #

Constructors

VolumeName Text

Instances

Eq VolumeName Source #
Instance details Defined in Podman.Api Methods (==) :: VolumeName -> VolumeName -> Bool # (/=) :: VolumeName -> VolumeName -> Bool #
Show VolumeName Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> VolumeName -> ShowS # show :: VolumeName -> String # showList :: [VolumeName] -> ShowS #

volumeExists Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> VolumeName	The volume name
-> m (Maybe Error)	Returns Nothing when the volume exists

Check if volume exists in local store.

volumeList Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> Maybe Text	JSON encoded value of the filters (a map[string][]string) to process on the volume list.
-> m (Result [Volume])

Returns a list of volumes on the server.

Secret

newtype SecretName Source #

Constructors

SecretName Text

Instances

Eq SecretName Source #
Instance details Defined in Podman.Api Methods (==) :: SecretName -> SecretName -> Bool # (/=) :: SecretName -> SecretName -> Bool #
Show SecretName Source #
Instance details Defined in Podman.Api Methods showsPrec :: Int -> SecretName -> ShowS # show :: SecretName -> String # showList :: [SecretName] -> ShowS #

secretList Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> m (Result [SecretInfoReport])

Returns a list of secrets

secretCreate Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> SecretName	The secret name
-> ByteString	The secret data
-> m (Result SecretCreateResponse)

secretInspect Source #

Arguments

:: MonadIO m
=> PodmanClient	The client instance
-> SecretName	The secret name
-> m (Result SecretInfoReport)

Inspect a secret.

client API version

pattern API_VERSION :: (Eq a, IsString a) => a Source #

module Podman.Types

re-exports

data Text #

A space efficient, packed, unboxed Unicode text type.

Instances

Hashable Text
Instance details Defined in Data.Hashable.Class Methods hashWithSalt :: Int -> Text -> Int # hash :: Text -> Int #
ToJSON Text
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSON :: Text -> Value # toEncoding :: Text -> Encoding # toJSONList :: [Text] -> Value # toEncodingList :: [Text] -> Encoding #
KeyValue Object	Constructs a singleton `HashMap`. For calling functions that demand an `Object` for constructing objects. To be used in conjunction with `mconcat`. Prefer to use `object` where possible.
Instance details Defined in Data.Aeson.Types.ToJSON Methods (.=) :: ToJSON v => Text -> v -> Object #
KeyValue Pair
Instance details Defined in Data.Aeson.Types.ToJSON Methods (.=) :: ToJSON v => Text -> v -> Pair #
ToJSONKey Text
Instance details Defined in Data.Aeson.Types.ToJSON Methods toJSONKey :: ToJSONKeyFunction Text # toJSONKeyList :: ToJSONKeyFunction [Text] #
FromJSON Text
Instance details Defined in Data.Aeson.Types.FromJSON Methods parseJSON :: Value -> Parser Text # parseJSONList :: Value -> Parser [Text] #
FromJSONKey Text
Instance details Defined in Data.Aeson.Types.FromJSON Methods fromJSONKey :: FromJSONKeyFunction Text # fromJSONKeyList :: FromJSONKeyFunction [Text] #
Chunk Text
Instance details Defined in Data.Attoparsec.Internal.Types Associated Types type ChunkElem Text :: Type # Methods nullChunk :: Text -> Bool # pappendChunk :: State Text -> Text -> State Text # atBufferEnd :: Text -> State Text -> Pos # bufferElemAt :: Text -> Pos -> State Text -> Maybe (ChunkElem Text, Int) # chunkElemToChar :: Text -> ChunkElem Text -> Char #
FoldCase Text
Instance details Defined in Data.CaseInsensitive.Internal Methods foldCase :: Text -> Text # foldCaseList :: [Text] -> [Text]
FromPairs Value (DList Pair)
Instance details Defined in Data.Aeson.Types.ToJSON Methods fromPairs :: DList Pair -> Value
v ~ Value => KeyValuePair v (DList Pair)
Instance details Defined in Data.Aeson.Types.ToJSON Methods pair :: String -> v -> DList Pair
type State Text
Instance details Defined in Data.Attoparsec.Internal.Types type State Text = Buffer
type ChunkElem Text
Instance details Defined in Data.Attoparsec.Internal.Types type ChunkElem Text = Char
type Item Text
Instance details Defined in Data.Text type Item Text = Char