Chapter 12. Using the container-tools API

The new REST based Podman 2.0 API replaces the old remote API for Podman that used the varlink library. The new API works in both a rootful and a rootless environment.

The Podman v2.0 RESTful API consists of the Libpod API providing support for Podman, and Docker-compatible API.

With this new REST API, you can call Podman from platforms such as cURL, Postman, Google’s Advanced REST client, and many others.

12.1. Enabling the Podman API using systemd in root mode

This procedure shows how to do the following:

  1. Use systemd to activate the Podman API socket.
  2. Use a Podman client to perform basic commands.

Prerequisities

  • The podman-remote package is installed.

    # yum install podman-remote

Procedure

  1. Configure the systemd unit file for Podman socket:

    # cat /usr/lib/systemd/system/podman.socket
    
    [Unit]
    Description=Podman API Socket
    Documentation=man:podman-api(1)
    
    [Socket]
    ListenStream=%t/podman/podman.sock
    SocketMode=0660
    
    [Install]
    WantedBy=sockets.target
  2. Reload the systemd manager configuration:

    # systemctl daemon-reload
  3. Start the service immediately:

    # systemctl enable --now podman.socket
  4. To enable the link to var/lib/docker.sock using the docker-podman package:

    # yum install podman-docker

Verification steps

  • Display system information of Podman:

    # podman-remote info
  • Verify the link:

    # ls -al /var/run/docker.sock
    lrwxrwxrwx. 1 root root 23 Nov  4 10:19 /var/run/docker.sock -> /run/podman/podman.sock

Additional resources

12.2. Enabling the Podman API using systemd in rootless mode

This procedure shows how to use systemd to activate the Podman API socket and podman API service.

Prerequisities

  • The podman-remote package is installed.

    # yum install podman-remote

Procedure

  1. Create a rootless socket for Podman:

    $ vim .config/systemd/user/podman.socket
    
    [Unit]
    Description=Podman API Socket
    Documentation=man:podman-api(1)
    
    [Socket]
    ListenStream=/home/username/podman.sock
    SocketMode=0660
    
    [Install]
    WantedBy=sockets.target
  2. Create a rootless service for Podman:

    $ vim .config/systemd/user/podman.service
    [Unit]
    Description=Podman API Service
    Requires=podman.socket
    After=podman.socket
    Documentation=man:podman-api(1)
    StartLimitIntervalSec=0
    
    [Service]
    Type=oneshot
    Environment=REGISTRIES_CONFIG_PATH=/etc/containers/registries.conf
    ExecStart=/usr/bin/podman system service unix:///home/username/podman.sock
    TimeoutStopSec=30
    KillMode=process
    
    [Install]
    WantedBy=multi-user.target
    Also=podman.socket
    • The After line in the [Unit] sections defines the dependency on the podman.socket unit file. The podman.socket unit started up before the configured podman.service.
  3. Reload the systemd manager configuration:

    $ systemctl --user daemon-reload
  4. Enable and start the service immediately:

    $ systemctl --user enable --now podman.socket
  5. To enable programs using Docker to interact with the rootless Podman socket:

    $ export DOCKER_HOST=unix:///var/run/<username>/podman.sock

Verification steps

  • Display system information of Podman:

    $ podman-remote info

Additional resources

12.3. Running the Podman API manually

This procedure describes how to run the Podman API. This is useful for debugging API calls, especially when using the Docker compatibility layer.

Prerequisities

  • The podman-remote package is installed.

    # yum install podman-remote

Procedure

  1. Run the service for the REST API:

    # podman system service -t 0 --log-level=debug
    • The value of 0 means no timeout. The default endpoint for a rootful service is unix:/run/podman/podman.sock.
    • The --log-level <level> option sets the logging level. The standard logging levels are debug, info, warn, error, fatal, and panic.
  2. In another terminal, display system information of Podman. The podman-remote command, unlike the regular podman command, communicates through the Podman socket:

    # podman-remote info
  3. To troubleshoot the Podman API and display request and responses, use the curl comman. To get the information about the Podman installation on the Linux server in JSON format:

    # curl -s --unix-socket /run/podman/podman.sock http://d/v1.0.0/libpod/info | jq
        {
      "host": {
        "arch": "amd64",
        "buildahVersion": "1.15.0",
        "cgroupVersion": "v1",
        "conmon": {
          "package": "conmon-2.0.18-1.module+el8.3.0+7084+c16098dd.x86_64",
          "path": "/usr/bin/conmon",
          "version": "conmon version 2.0.18, commit: 7fd3f71a218f8d3a7202e464252aeb1e942d17eb"
        },
        …
      "version": {
        "APIVersion": 1,
        "Version": "2.0.0",
        "GoVersion": "go1.14.2",
        "GitCommit": "",
        "BuiltTime": "Thu Jan  1 01:00:00 1970",
        "Built": 0,
        "OsArch": "linux/amd64"
      }
    }

    A jq utility is a command-line JSON processor.

  4. Pull the registry.access.redhat.com/ubi8/ubi container image:

    # curl -XPOST --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/images/create?fromImage=registry.access.redhat.com%2Fubi8%2Fubi'
    *   Trying /run/podman/podman.sock...
    * Connected to d (/run/podman/podman.sock) port 80 (#0)
    > POST /v1.0.0/images/create?fromImage=registry.access.redhat.com%2Fubi8%2Fubi HTTP/1.1
    > Host: d
    > User-Agent: curl/7.61.1
    > Accept: /
    >
    < HTTP/1.1 200 OK
    < Content-Type: application/json
    < Date: Tue, 20 Oct 2020 13:58:37 GMT
    < Content-Length: 231
    <
    {"status":"pulling image () from registry.access.redhat.com/ubi8/ubi:latest, registry.redhat.io/ubi8/ubi:latest","error":"","progress":"","progressDetail":{},"id":"ecbc6f53bba0d1923ca9e92b3f747da8353a070fccbae93625bd8b47dbee772e"}
    * Connection #0 to host d left intact
  5. Display the pulled image:

    # curl --unix-socket /run/podman/podman.sock -v 'http://d/v1.0.0/libpod/images/json' | jq
    *   Trying /run/podman/podman.sock...
      % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
      0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* Connected to d (/run/podman/podman.sock) port 80 (0) > GET /v1.0.0/libpod/images/json HTTP/1.1 > Host: d > User-Agent: curl/7.61.1 > Accept: / > < HTTP/1.1 200 OK < Content-Type: application/json < Date: Tue, 20 Oct 2020 13:59:55 GMT < Transfer-Encoding: chunked < { [12498 bytes data] 100 12485 0 12485 0 0 2032k 0 --:--:-- --:--:-- --:--:-- 2438k * Connection #0 to host d left intact [ { "Id": "ecbc6f53bba0d1923ca9e92b3f747da8353a070fccbae93625bd8b47dbee772e", "RepoTags": [ "registry.access.redhat.com/ubi8/ubi:latest", "registry.redhat.io/ubi8/ubi:latest" ], "Created": "2020-09-01T19:44:12.470032Z", "Size": 210838671, "Labels": { "architecture": "x86_64", "build-date": "2020-09-01T19:43:46.041620", "com.redhat.build-host": "cpt-1008.osbs.prod.upshift.rdu2.redhat.com", ... "maintainer": "Red Hat, Inc.", "name": "ubi8", ... "summary": "Provides the latest release of Red Hat Universal Base Image 8.", "url": "https://access.redhat.com/containers//registry.access.redhat.com/ubi8/images/8.2-347",
          ...
        },
        "Names": [
          "registry.access.redhat.com/ubi8/ubi:latest",
          "registry.redhat.io/ubi8/ubi:latest"
        ],
        ...
        ]
      }
    ]

Additional resources