Skip to content

resource-usage.md

Latest commit

 

History

History
183 lines (137 loc) · 6.92 KB

resource-usage.md

File metadata and controls

183 lines (137 loc) · 6.92 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,
    "cpuUtilization": 0.0312
  }
]

Understanding the metrics:

  • Cpu %: Percentage of CPU usage. ~100% = one fully utilized core. A multi-core container can show > 100%.
  • cpuUtilization (JSON, YAML, TOML): The same measurement as a fraction of one core. 1.0 is one fully utilized core, 2.5 is two and a half. Format it as you need; Cpu % in the table is this value times 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.

Image snapshots and container root filesystems are excluded from backups when those directories are first created. Backup software that honors this exclusion, including Time Machine, skips them. Both are large sparse files that can be recreated by pulling the image or creating the container again. Named volume data under volumes/ stays included. An exclusion removed from an existing directory is left as it is.

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%)

A named volume's disk image can grow to 512 GiB by default. To set a smaller limit, give a size when you create the volume:

container volume create -s 10g myvolume

Reclaim disk space

Remove stopped containers:

container prune

Remove dangling images, the ones with no tag. Add --all to remove every image that no container references, tagged or not:

container image prune
container image prune --all

Remove volumes with no container references:

container volume prune

Return the blocks that a running container has freed by deleting files on its root filesystem and named volumes to the host, without stopping the container:

container clean mycontainer

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.