DOCSEARCHbyAlgolia
Submit Docs

aiodocker Documentation

repository·main·Indexed 19 days ago

https://github.com/aio-libs/aiodocker

A simple AsyncIO-based wrapper for the Docker HTTP API built using aiohttp. It provides asynchronous bindings to manage Docker resources including containers, images, networks, volumes, services, secrets, and configs. The library includes the Docker class as the primary entrypoint, support for event streaming via Channel and ChannelSubscriber, and specialized sub-APIs for comprehensive Docker Engine interaction.

Tokens
28.6K
Snippets
117
Records
141
Agent score
67%

What's inside aiodocker

  1. Manage Host Key Verification

    main

    By default, aiodocker enforces strict host key verification. The remote host must be present in your ~/.ssh/known_hosts file.

    To add a host key:

    • Manually connect: ssh ubuntu@remote-host
    • Use keyscan: ssh-keyscan -H remote-host >> ~/.ssh/known_hosts

    To disable verification (Testing only): Use SSHConnector with strict_host_keys=False. Warning: This is vulnerable to man-in-the-middle attacks.

    from aiodocker.ssh import SSHConnector

# WARNING: Only for testing - vulnerable to man-in-the-middle attacks
connector = SSHConnector(
    "ssh://ubuntu@test-host:22",
    strict_host_keys=False
)
async with aiodocker.Docker(connector=connector) as docker:
    containers = await docker.containers.list()

  2. Bind-mount a host directory (Legacy method)

    main

    You can use the legacy HostConfig.Binds method by providing a list of strings in the format "<host>:<container>[:<opts>]".

    Options are comma-separated and can include:

    • ro (read-only)
    • rw (read-write)
    • z / Z (SELinux relabel)
    • Propagation modes: shared, rshared, slave, rslave, private, rprivate.
    config = {
    "Image": "alpine:latest",
    "Cmd": ["/bin/ls", "/data"],
    "HostConfig": {
        "Binds": ["/host/path:/data:ro,shared"],
    },
}

  3. Reuse SSHConnector for performance

    main

    To improve performance when interacting with the same remote host, create a single SSHConnector instance and reuse it across multiple aiodocker.Docker instances. Remember to call await connector.close() when finished.

    from aiodocker import Docker
from aiodocker.ssh import SSHConnector
import asyncio

async def main():
    # Create connector once
    connector = SSHConnector("ssh://ubuntu@host:22")

    # Reuse across multiple Docker instances
    async with aiodocker.Docker(connector=connector) as docker1:
        containers = await docker1.containers.list()

    async with aiodocker.Docker(connector=connector) as docker2:
        images = await docker2.images.list()

    # Clean up when done
    await connector.close()

asyncio.run(main())

  4. Connect to a remote Docker host over SSH

    main

    You can connect to a remote Docker host using the ssh:// URL scheme. aiodocker uses docker system dial-stdio to communicate, which automatically discovers the correct Docker socket on the remote host (supporting standard, rootless, and custom socket configurations).

    URL Format: ssh://[user[:password]@]host[:port]

    Examples:

    • ssh://ubuntu@host:22 (Specific port)
    • ssh://ubuntu@host (Default port 22)
    • ssh://dockeruser@production.example.com:2222 (Custom port)
    import asyncio
import aiodocker

async def main():
    # Connect to Docker over SSH
    async with aiodocker.Docker(url="ssh://user@remote-host:22") as docker:
        # Use Docker API normally
        version = await docker.version()
        print(f"Docker version: {version['Version']}")

        # List containers
        containers = await docker.containers.list()
        for container in containers:
            print(f"Container: {container['Names'][0]}")

if __name__ == "__main__":
    asyncio.run(main())

  5. Bind-mount a host directory (Recommended method)

    main

    The recommended way to perform bind mounts is using HostConfig.Mounts, which uses a list of structured mount specifications. This approach is more readable and less error-prone than the legacy string format. Propagation is defined as a named field within BindOptions.

    config = {
    "Image": "alpine:latest",
    "Cmd": ["/bin/ls", "/data"],
    "HostConfig": {
        "Mounts": [
            {
                "Type": "bind",
                "Source": "/host/path",
                "Target": "/data",
                "ReadOnly": True,
                "BindOptions": {"Propagation": "shared"},
            },
        ],
    },
}

  6. Use SSH configuration from ~/.ssh/config

    main

    If the paramiko library is available, aiodocker automatically reads SSH configuration from ~/.ssh/config. This allows you to use simplified host aliases in your connection URLs.

    # Automatically uses settings from ~/.ssh/config
# Example config entry: Host docker-prod ...
async with aiodocker.Docker(url="ssh://docker-prod") as docker:
    containers = await docker.containers.list()

  8. Authenticate via Password (Discouraged)

    main

    Passwords can be included directly in the URL. Warning: This is not recommended for security reasons as passwords may be stored in memory or appear in logs.

    # Warning: Password will be stored in memory and may appear in logs
async with aiodocker.Docker(url="ssh://ubuntu:password@host:22") as docker:
    containers = await docker.containers.list()

  9. Authenticate via SSH keys

    main

    SSH key authentication is the recommended method. You can either rely on automatic key discovery from your ~/.ssh/config or explicitly specify custom key files using the SSHConnector class.

    import aiodocker
from aiodocker.ssh import SSHConnector
import asyncio

async def main():
    # Option 1: Automatic key discovery from ~/.ssh/config
    async with aiodocker.Docker(url="ssh://ubuntu@host:22") as docker:
        containers = await docker.containers.list()

    # Option 2: Specify custom key file using SSHConnector
    connector = SSHConnector(
        "ssh://ubuntu@host:22",
        client_keys=["~/.ssh/docker_key"]
    )
    async with aiodocker.Docker(connector=connector) as docker:
        containers = await docker.containers.list()

asyncio.run(main())

  12. Stream container logs with DockerLog

    main

    The DockerLog class provides an asynchronous interface for streaming logs from a Docker container. It uses a Channel mechanism to allow multiple subscribers to receive log lines as they are produced.

    To use it, you typically call run() to start the log streaming process and use subscribe() to get a ChannelSubscriber that yields log messages.

    Key behaviors:

    • Streaming: run() uses follow=True by default to stream logs continuously.
    • Termination: When the log stream ends or an error occurs, a None sentinel is published to the channel to signal termination to all subscribers.
    • Concurrency: You can call subscribe() multiple times to have multiple independent subscribers listening to the same log stream.
    # Conceptual usage pattern
log_stream = container.logs()

# Create a subscriber
subscriber = log_stream.subscribe()

# Start the log streaming process in the background
task = asyncio.create_task(log_stream.run())

# Consume logs
async for line in subscriber:
    if line is None:
        break  # Stream ended
    print(f"Log: {line}")