diff --git a/Docs/Libs/Docker/03-Container-Lifecycle.md b/Docs/Libs/Docker/03-Container-Lifecycle.md index e69de29..d848c46 100644 --- a/Docs/Libs/Docker/03-Container-Lifecycle.md +++ b/Docs/Libs/Docker/03-Container-Lifecycle.md @@ -0,0 +1,284 @@ +# 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 + +```python +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 + +```python +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) + +```python +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) + +```python +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) + +```python +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 + +```python +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 + +```python +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 + +```python +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/](https://docker-py.readthedocs.io/)