Skip to content

resource-usage.md

Latest commit

 

History

History
160 lines (119 loc) · 5.9 KB

resource-usage.md

File metadata and controls

160 lines (119 loc) · 5.9 KB
Raw

Resource usage

Configure CPU, memory, and disk resources for your containers and builds, monitor usage while they run, and reclaim disk space afterward.

Configure memory and CPUs for your containers

Since the containers created by container are lightweight virtual machines, consider the needs of your containerized application when you use container run. The --memory and --cpus options allow you to override the default memory and CPU limits for the virtual machine. The default values are 1 gigabyte of RAM and 4 CPUs. You can use abbreviations for memory units; for example, to run a container for image big with 8 CPUs and 32 GiBytes of memory, use:

container run --rm --cpus 8 --memory 32g big

See Resource limits (ulimits) for per-process resource limits like open-file and process-count limits.

Configure memory and CPUs for large builds

When you first run container build, container starts a builder, which is a utility container that builds images from your Dockerfiles. As with anything you run with container run, the builder runs in a lightweight virtual machine, so for resource-intensive builds, you may need to increase the memory and CPU limits for the builder VM.

By default, the builder VM receives 2 GiBytes of RAM and 2 CPUs. You can change these limits by starting the builder container before running container build:

container builder start --cpus 8 --memory 32g

If your builder is already running and you need to modify the limits, just stop, delete, and restart the builder:

container builder stop
container builder delete
container builder start --cpus 8 --memory 32g

Overcommit memory and CPUs across containers

You can run more containers than your host has physical CPUs or memory for — container does not reject a --cpus or --memory request that exceeds physical capacity, whether for a single container or in aggregate across several. For example, on an 8-CPU, 16 GB host you could run a builder VM with 4 CPUs/8 GB and three more containers with 4 CPUs/2 GB each: 16 CPUs and 14 GB requested against 8 CPUs and 16 GB physical.

This works because macOS schedules host and guest VM processes together against the same physical resources, the same way it schedules any set of contending processes. Throughput can't exceed what the physical CPUs provide, and CPU-bound containers slow down as more of them compete for time. For memory, once real demand exceeds physical RAM, macOS swaps out less-used pages — applications keep running, but performance degrades and becomes limited by disk I/O as swapping increases. Leaving some CPU and memory headroom for macOS and your other applications is a good practice.

Monitor container resource usage

The container stats command displays real-time resource usage statistics for your running containers, similar to the top command for processes. This is useful for:

  • Monitoring CPU and memory consumption
  • Tracking network and disk I/O
  • Identifying resource-intensive containers
  • Verifying container resource limits are appropriate

By default, container stats shows live statistics for all running containers in an interactive display:

% container stats
Container ID    Cpu %    Memory Usage           Net Rx/Tx              Block I/O               Pids
my-web-server   2.45%    45.23 MiB / 1.00 GiB   1.23 MiB / 856.00 KiB  4.50 MiB / 2.10 MiB     3
db              125.12%  512.50 MiB / 2.00 GiB  5.67 MiB / 3.21 MiB    125.00 MiB / 89.00 MiB  12

To monitor specific containers, provide their names or IDs:

% container stats my-web-server db

For a single snapshot (non-interactive), use the --no-stream flag:

% container stats --no-stream my-web-server
Container ID    Cpu %    Memory Usage          Net Rx/Tx              Block I/O              Pids
my-web-server   30.45%    45.23 MiB / 1.00 GiB  1.23 MiB / 856.00 KiB  4.50 MiB / 2.10 MiB    3

You can also output statistics in JSON format for scripting:

% container stats --format json --no-stream my-web-server | jq
[
  {
    "id": "my-web-server",
    "memoryUsageBytes": 47431680,
    "memoryLimitBytes": 1073741824,
    "cpuUsageUsec": 1234567,
    "networkRxBytes": 1289011,
    "networkTxBytes": 876544,
    "blockReadBytes": 4718592,
    "blockWriteBytes": 2202009,
    "numProcesses": 3
  }
]

Understanding the metrics:

  • Cpu %: Percentage of CPU usage. ~100% = one fully utilized core. A multi-core container can show > 100%.
  • Memory Usage: Current memory usage vs. the container's memory limit.
  • Net Rx/Tx: Network bytes received and transmitted.
  • Block I/O: Disk bytes read and written.
  • Pids: Number of processes running in the container.

Disk usage

Each container gets a macOS sparse disk image for its writable filesystem. Named volumes get their own sparse disk image too. As your containerized application writes data, these images grow; when a container process deletes a file, the freed blocks aren't automatically returned to the host filesystem, so image size doesn't shrink on its own.

Check overall usage with:

container system df
TYPE            TOTAL   ACTIVE   SIZE      RECLAIMABLE
Images          12      4        3.2GB     1.1GB (34%)
Containers      4       2        890MB     210MB (24%)
Local Volumes   6       3        4.5GB     2.1GB (47%)

Reclaim disk space

Remove stopped containers:

container prune

Remove images not referenced by any container (add --all to remove all untagged and unused images, not just dangling ones):

container image prune
container image prune --all

Remove volumes with no container references:

container volume prune

Reclaim space used by the builder VM's layer cache by replacing the builder:

container builder stop
container builder delete

See Mounts and volumes for bind mounts, named volumes, and tmpfs mounts.