python-doc/Docs/Libs/Docker/03-Containers.md

Docker SDK for Python – Working with Containers

This document explains how to manage Docker containers using the Docker SDK for Python. Containers are the runtime unit of Docker, so this section focuses on lifecycle management: listing, creating, running, starting, stopping, restarting, pausing, and inspecting logs.

The goal is to understand how container state changes, how the Python SDK maps to Docker CLI behavior, and how these operations are typically used in real DevOps automation.

---

1. Creating the Docker Client

import docker
import time

client = docker.DockerClient(base_url='unix://var/run/docker.sock')
ping_docker = client.ping()

Explanation

• Establishes a connection to the Docker daemon via the Unix socket.
• ping() is used as a sanity check before executing container operations.

In production-grade scripts, this check prevents:

• Silent failures
• Partial execution when Docker is down

---

2. Listing Running Containers

def get_containers_list():
    containers = client.containers.list()

    for c in containers:
        print(c.id, c.name, c.status)

Explanation

• containers.list() returns only running containers by default.
• Each returned object represents a live container instance.

Common attributes:

• id: unique container identifier
• name: human-readable container name
• status: runtime state (running)

This is equivalent to:

• docker ps

---

3. Listing All Containers (Including Stopped)

def get_all_containers_list():
    containers = client.containers.list(all=True)

    for c in containers:
        print(c.id, c.name, c.status)

Explanation

• all=True includes stopped, exited, and created containers.
• Useful for cleanup, auditing, and lifecycle reconciliation.

Equivalent CLI command:

• docker ps -a

---

4. Creating a Container (Without Starting It)

def create_container():
    container = client.containers.create(
        image="nginx:latest",
        name="my_nginx",
        ports={"80/tcp": 8080},
        detach=True
    )

Explanation

This creates a container in the created state.

Key parameters:

• image: base image for the container
• name: explicit container name
• ports: port mapping (container → host)
• detach=True: container runs in background when started

Important distinction:

• create() does not start the container
• This mirrors docker create

Use cases:

• Deferred startup
• Multi-step initialization

---

5. Running a Container (Create + Start)

def run_container():
    container = client.containers.run(
        "nginx:latest",
        name="nginx_run",
        ports={"80/tcp": 8081},
        detach=True
    )

Explanation

• run() is a convenience method.
• Internally performs create() followed by start().

Equivalent CLI command:

• docker run -d -p 8081:80 nginx:latest

This is the most common approach for:

• Short-lived workloads
• Simple services

---

6. Managing Container Lifecycle

def start_container():
    container = client.containers.get("my_nginx")

    container.start()
    time.sleep(1000)

    container.restart()
    time.sleep(1000)

    container.pause()
    container.unpause()
    time.sleep(1000)

    container.stop(timeout=10)

Explanation

This function demonstrates multiple lifecycle transitions.

containers.get(name)

• Retrieves an existing container by name or ID.
• Raises an exception if the container does not exist.

start()

• Transitions container from created or stopped → running.

restart()

• Stops and immediately starts the container.
• Often used after configuration changes.

pause() / unpause()

• Freezes container processes using cgroups.
• Network and filesystem state remain intact.

stop(timeout=10)

• Sends SIGTERM, then SIGKILL after timeout.
• Allows graceful shutdown.

The sleep() calls simulate:

• Long-running services
• Observing container behavior between states

---

7. Reading Container Logs

def log_container():
    container = client.containers.get("my_nginx")
    logs = container.logs(tail=20)
    print(logs.decode())

Explanation

• Retrieves logs from the container’s stdout/stderr.
• tail=20 limits output to the last 20 lines.

Important details:

• Logs are returned as bytes
• Decoding is required for readable output

Equivalent CLI command:

• docker logs --tail 20 my_nginx

This is critical for:

• Debugging runtime issues
• Health checks
• Observability tooling

---

8. Conditional Execution Based on Docker Availability

if ping_docker:
    get_containers_list()

Explanation

• Ensures container operations only run if Docker is reachable.
• Prevents unhandled API errors.

This pattern is common in:

• Entry-point scripts
• Health probes
• Automation jobs

---

9. Container States (Conceptual Model)

Understanding container states is essential:

• created: container exists but is not running
• running: container processes are active
• paused: execution is suspended
• exited: container stopped normally
• dead: container failed unexpectedly

Every method in this document transitions the container between these states.

---

10. Summary

In this section, you learned how to:

• List running and stopped containers
• Create containers separately from starting them
• Run containers in a single step
• Control container lifecycle states
• Read container logs
• Safely execute operations based on Docker availability

This container-level control is the foundation for:

• Service orchestration
• CI/CD job execution
• Debugging and recovery automation

---

References

Official Docker SDK for Python documentation:

• https://docker-py.readthedocs.io/