Container · XB Field Notes

Network namespaces isolate networking; their names do not own every process

Sat, 19 Feb 2028 00:00:00 +0000

A Linux network namespace separates networking resources such as interfaces, routes, neighbor tables, socket ports, and packet-filter rules. It shares the kernel with other namespaces; it is not a separate operating system. A process normally inherits its parent’s network namespace, and tools can execute a process in another one. The resulting isolation covers networking resources, not every aspect of process identity or filesystem access.

When it breaks

Running ip netns exec does not automatically provide the full isolation of a container. PID namespaces, user namespaces, and hostname isolation are separate mechanisms. An application may see different routes while still sharing ordinary files and a hostname with its parent environment. Treating one network namespace as a complete sandbox can therefore assign it guarantees that were never configured.

A new namespace also does not automatically receive useful external connectivity. Interfaces need deliberate placement and configuration, and local loopback may need to be brought up. Moving an interface changes which namespace manages it; the old context will no longer list that device as its own. A configuration command executed from the wrong namespace can report a missing interface even though the intended device still exists elsewhere.

Namespace names have their own lifecycle. ip netns conventionally exposes handles beneath /run/netns, commonly also reachable through /var/run/netns. Deleting a name removes that handle, but a process or another reference can keep the namespace alive. Cleanup that equates disappearance from the named list with termination of every service can leave networking resources and a running process behind.

Check it quickly

Save this as check-network-namespace.py and run python3 check-network-namespace.py with Docker. The pinned environment uses Python 3.11.16 and iproute2 6.1.0. NET_ADMIN and SYS_ADMIN permit nested namespace operations inside a disposable container. A temporary proc mount supports namespace-local network settings; no host interface is moved and no host port is published:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,uuid
recipe='FROM python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84\nRUN apt-get update && apt-get install -y --no-install-recommends iproute2=6.1.0-3 iputils-ping=3:20221126-1+deb12u1 nftables=1.0.6-2+deb12u2 tcpdump=4.99.3-1 traceroute=1:2.1.2-1 procps=2:4.0.2-3 && rm -rf /var/lib/apt/lists/*\nCMD ["python3"]\n'
program=r"""
from contextlib import ExitStack,contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import json,os,select,signal,subprocess,time

def run(*args,check=True,input=None,timeout=8):
 result=subprocess.run(args,input=input,capture_output=True,text=True,timeout=timeout)
 if check:assert result.returncode==0,(args,result.returncode,result.stdout,result.stderr)
 return result
def ns(name,*args,**kwargs):return run('ip','netns','exec',name,*args,**kwargs)
def ip(name,*args,**kwargs):return ns(name,'ip',*args,**kwargs)
def stop(process):
 if process.poll() is None:
 process.terminate()
 try:process.wait(timeout=2)
 except subprocess.TimeoutExpired:process.kill();process.wait(timeout=2)
def line(process,timeout=3):
 assert select.select([process.stdout],[],[],timeout)[0],'child response deadline exceeded'
 value=process.stdout.readline();assert value,'child exited without a response'
 return value
def spawn(stack,command):
 process=subprocess.Popen(command,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,text=True)
 stack.callback(stop,process);return process
@contextmanager
def lab(names):
 with TemporaryDirectory(prefix='net-path-') as directory,ExitStack() as stack:
 root=Path(directory);proc=root/'proc';proc.mkdir();run('mount','-t','proc','proc',str(proc))
 stack.callback(run,'umount',str(proc))
 for name in names:
 run('ip','netns','add',name);stack.callback(run,'ip','netns','delete',name,check=False)
 ip(name,'link','set','lo','up')
 def setting(name,key,value):
 assert name in names
 path=proc/'sys'/key.replace('.','/')
 return ns(name,'python3','-c',f'from pathlib import Path; p=Path({str(path)!r}); p.write_text({str(value)!r}); print(p.read_text().strip())').stdout.strip()
 yield root,stack,setting
def wire(left,left_if,right,right_if,left_addresses,right_addresses):
 run('ip','link','add',left_if,'type','veth','peer','name',right_if)
 for name,interface,addresses in [(left,left_if,left_addresses),(right,right_if,right_addresses)]:
 run('ip','link','set',interface,'netns',name)
 for address in addresses:ip(name,'address','add',address,'dev',interface,*(['nodad'] if ':' in address else []))
 ip(name,'link','set',interface,'up')
def nft(name,script):return ns(name,'nft','-f','-',input=script)
def counters(name):
 data=json.loads(ns(name,'nft','-j','list','ruleset').stdout);found={}
 for entry in data['nftables']:
 rule=entry.get('rule',{})
 if 'comment' in rule:
 for expression in rule['expr']:
 if 'counter' in expression:found[rule['comment']]=expression['counter']['packets']
 return found

def server(stack,name,address,port=18080,label='server'):
 code=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import json,socket,sys
address,port,label=sys.argv[1],int(sys.argv[2]),sys.argv[3]
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=json.dumps({'server':label,'peer':self.client_address,'path':self.path}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
 def log_message(self,*args):pass
class Server(ThreadingHTTPServer):
 address_family=socket.AF_INET6 if ':' in address else socket.AF_INET
 def server_bind(self):
 if self.address_family==socket.AF_INET6:self.socket.setsockopt(socket.IPPROTO_IPV6,socket.IPV6_V6ONLY,1)
 super().server_bind()
service=Server((address,port),Handler);print('ready',flush=True);service.serve_forever()
'''
 process=spawn(stack,['ip','netns','exec',name,'python3','-u','-c',code,address,str(port),label])
 assert line(process).strip()=='ready';return process
def request(name,address,port=18080):
 code=r'''
import http.client,json,sys
client=http.client.HTTPConnection(sys.argv[1],int(sys.argv[2]),timeout=.7)
try:
 client.request('GET','/lab-visible-message');response=client.getresponse();body=json.loads(response.read())
 assert response.status==200;print(json.dumps({'ok':True,'status':response.status,'body':body}))
except OSError as error:print(json.dumps({'ok':False,'type':type(error).__name__,'errno':error.errno}))
finally:client.close()
'''
 return json.loads(ns(name,'python3','-c',code,address,str(port)).stdout)

with lab(['blue','green']) as (root,stack,setting):
 probe='import json,os,socket;print(json.dumps({"net":os.readlink("/proc/self/ns/net"),"pid":os.readlink("/proc/self/ns/pid"),"hostname":socket.gethostname()}))'
 parent=json.loads(run('python3','-c',probe).stdout)
 views={name:json.loads(ns(name,'python3','-c',probe).stdout) for name in ['blue','green']}
 assert len({parent['net'],views['blue']['net'],views['green']['net']})==3
 assert all(v['pid']==parent['pid'] and v['hostname']==parent['hostname'] for v in views.values())
 for name in ['blue','green']:
 ip(name,'link','add','dummy0','type','dummy');ip(name,'addr','add','192.0.2.10/24','dev','dummy0');ip(name,'link','set','dummy0','up')
 ip('blue','route','add','203.0.113.0/24','dev','dummy0')
 assert json.loads(ip('blue','-j','route','show','203.0.113.0/24').stdout)
 assert not json.loads(ip('green','-j','route','show','203.0.113.0/24').stdout)
 setting('blue','net.ipv4.ip_forward',0);setting('green','net.ipv4.ip_forward',1)
 forwarding={name:ns(name,'sysctl','-n','net.ipv4.ip_forward').stdout.strip() for name in ['blue','green']};assert forwarding=={'blue':'0','green':'1'}
 marker=root/'shared.txt';marker.write_text('shared filesystem')
 assert ns('blue','cat',str(marker)).stdout==ns('green','cat',str(marker)).stdout=='shared filesystem'
 daemon=server(stack,'blue','192.0.2.10',label='blue')
 named=request('blue','192.0.2.10');assert named['ok'] and named['body']['server']=='blue'
 run('ip','netns','delete','blue');assert not Path('/run/netns/blue').exists()
 assert daemon.poll() is None and os.readlink(f'/proc/{daemon.pid}/ns/net')==views['blue']['net']
 by_pid=run('nsenter','-t',str(daemon.pid),'-n','python3','-c',
 'import http.client,json; c=http.client.HTTPConnection("192.0.2.10",18080,timeout=1);c.request("GET","/");r=c.getresponse();print(json.dumps({"status":r.status,"body":json.loads(r.read())}));c.close()')
 surviving=json.loads(by_pid.stdout);assert surviving['status']==200 and surviving['body']['server']=='blue'
 print(json.dumps({'parent':parent,'namespace_views':views,'blue_only_route':True,'forwarding':forwarding,
 'same_file_visible':True,'before_name_deleted':named,'name_deleted_process_alive':True,'after_name_deleted':surviving}))
"""
name='xbcatm-netpath-'+uuid.uuid4().hex[:10]
def docker(*args,**kwargs):return subprocess.run(['docker',*args],capture_output=True,text=True,timeout=300,**kwargs)
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'Dockerfile').write_text(recipe)
 build=docker('build','-t',name,str(root));assert build.returncode==0,build.stderr
 result=docker('run','--rm','-i','--name',name,'--network','none','--cap-add','NET_ADMIN','--cap-add','SYS_ADMIN',
 '--memory','256m','--pids-limit','128',name,'python3','-',input=program)
 assert result.returncode==0,result.stderr
 print(json.dumps(json.loads(result.stdout),sort_keys=True))
finally:
 docker('rm','-f',name);docker('image','rm',name)

The parent, blue, and green report three different network namespace identifiers. Their PID namespace identifiers and hostnames remain equal. A marker file created by the parent is also readable in both children. Those positive observations establish the intended scope: networking has changed, while these particular process and filesystem properties remain shared in the fixture.

Each child creates its own dummy0 with address 192.0.2.10/24. The identical names and addresses coexist because they belong to different networking contexts. Only blue receives a route for 203.0.113.0/24. Querying green’s routes confirms that it has no corresponding entry. The example verifies separate effective tables rather than merely printing the two namespace names.

The program explicitly sets IPv4 forwarding to zero in blue and one in green, then reads the values back through each namespace. This is a setting-isolation check, not a packet-forwarding demonstration. The local dummy interfaces have no physical peer. Configured addresses and routes can be inspected without implying that either namespace can reach an external service.

A real HTTP server starts in blue on 192.0.2.10. A normal named-namespace request receives status 200 and identity blue. The script then deletes the blue name and confirms its handle is absent, while the server process and its network namespace identifier remain. The process has not been killed by removing the naming reference.

Using that known server PID, nsenter executes another client in the surviving network namespace. It again receives status 200 and identity blue. This establishes continued application operation after name deletion, not just the presence of a proc entry. The fixture finally stops its own process and removes remaining named resources through its cleanup stack and container lifetime.

Keep naming, process ownership, and connectivity separate

Record both a service’s process ownership and the networking context used for management. Namespace identifiers help compare currently live contexts; do not turn an ephemeral identifier into a permanent inventory identity. If a name disappears unexpectedly, inspect the relevant owned process before concluding that its networking state has vanished or creating a replacement with assumed empty state.

For ordinary configuration files, ip netns exec can create a mount namespace and bind namespace-specific files into their conventional locations. This supports arrangements such as per-namespace resolver configuration; it does not establish a private copy of every filesystem object. Document those additional choices when reproducing a client’s environment so that DNS settings and route isolation are not confused.

Build connectivity through explicit virtual links, routes, forwarding, and filtering as required. A network namespace supplies a boundary for those resources, while their configuration determines communication. During teardown, stop the processes and release references owned by the service before expecting the namespace to disappear completely. Name deletion is one management operation within that lifecycle, not a universal process-termination command.

Sources

Linux network_namespaces(7), network resources isolated by a namespace, checked 2026-09-12.
Linux ip-netns(8), named handles, execution and deletion while processes remain, checked 2026-09-12.
Linux ip-link(8), interface creation and namespace placement, checked 2026-09-12.

ENTRYPOINT and CMD define defaults that operators can override

Sun, 03 Oct 2027 00:00:00 +0000

An image’s ENTRYPOINT and CMD contribute to the command used when a container is created. With an exec-form ENTRYPOINT, CMD commonly supplies default arguments appended to that entrypoint. Without an entrypoint, CMD can supply the executable and its arguments. These are startup defaults, not an enforcement boundary: an authorized operator can replace the entrypoint or arguments when creating a container.

When it breaks

Trailing arguments in docker run image ... replace CMD; they are not automatically added after CMD’s existing defaults. The exec-form entrypoint remains unless explicitly overridden. A user expecting to append one flag can accidentally discard required defaults, so command-line tools should document which values are optional, which must be repeated, and how their own argument parser treats overrides.

Exec form uses a JSON array and does not implicitly run a shell. A string such as $DEMO reaches the program literally instead of receiving shell variable expansion. Pipes, redirects, and wildcards likewise need an actual interpreter if that is the intended behavior. Shell form changes argument and process semantics, so switching forms is more than a cosmetic syntax choice.

A startup wrapper can also hide the service behind a shell that never forwards the container’s stop signal. Docker normally signals the main container process, waits for the configured timeout, then forces termination if necessary. A service’s correct SIGTERM handler is ineffective if the signal is delivered only to another process that does not pass it on.

Check it quickly

Run this script with host Python and access to a Docker builder after obtaining the pinned base. It was executed with Docker 29.3.1 and Linux arm64 Python 3.11.16. The fixture creates isolated temporary containers with networking disabled, waits for each service’s readiness output, tests stopping, and removes its containers and image tag:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,time,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(name):return json.loads(docker('inspect',name).stdout)[0]

name='xbcatm-entrypoint-'+uuid.uuid4().hex[:10];tag=name+':probe';containers=[name+'-exec',name+'-child']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory)
 (root/'args.py').write_text('import json,sys\nprint(json.dumps(sys.argv[1:]))\n')
 (root/'service.py').write_text('import json,os,signal\ndef stop(signum,frame):\n print("stopped",flush=True)\n raise SystemExit(0)\nsignal.signal(signal.SIGTERM,stop)\nprint(json.dumps({"pid":os.getpid()}),flush=True)\nwhile True:signal.pause()\n')
 (root/'exec.sh').write_text('#!/bin/sh\nexec python /service.py "$@"\n')
 (root/'child.sh').write_text('#!/bin/sh\npython /service.py "$@" &\nwait $!\n')
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY args.py service.py exec.sh child.sh /\nRUN chmod +x /exec.sh /child.sh\nENV DEMO=expanded\nENTRYPOINT ["python", "/args.py"]\nCMD ["default", "$DEMO"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert json.loads(docker('run','--rm','--network','none',tag).stdout)==['default','$DEMO']
 assert json.loads(docker('run','--rm','--network','none',tag,'changed').stdout)==['changed']
 assert docker('run','--rm','--network','none','--entrypoint','python',tag,'-c','print("override")').stdout.strip()=='override'
 assert docker('run','--rm','--network','none','--entrypoint','/bin/sh',tag,'-c','printf "%s" "$DEMO"').stdout=='expanded'
 print('CMD supplies literal default arguments; trailing arguments replace it; --entrypoint replaces the executable')
 for container,wrapper in zip(containers,['/exec.sh','/child.sh']):
 docker('run','-d','--name',container,'--network','none','--entrypoint',wrapper,tag)
 deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 logs=docker('logs',container).stdout
 if logs.strip():break
 time.sleep(.05)
 else:raise AssertionError('service did not become ready')
 pid=json.loads(logs.splitlines()[0])['pid']
 assert (pid==1)==(wrapper=='/exec.sh')
 docker('stop','--time','1',container)
 state=inspect(container)['State'];logs=docker('logs',container).stdout
 if wrapper=='/exec.sh':assert state['ExitCode']==0 and 'stopped' in logs
 else:assert state['ExitCode']==137 and 'stopped' not in logs
 print('exec makes the handler PID 1 and stops cleanly; the non-forwarding shell wrapper leaves its child unnotified until forced termination')
finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',tag,check=False)

The first image command prints its received argument list. With no override it receives default and the literal $DEMO, even though the image defines DEMO as expanded. Supplying changed after the image name replaces both default arguments, and the program receives exactly one argument. These assertions inspect the final argument vector rather than guessing from Dockerfile syntax.

Using --entrypoint python and explicit Python arguments runs an entirely different command that prints override. Using /bin/sh -c explicitly expands $DEMO and prints expanded. Together, these cases show both that ENTRYPOINT is overridable and that expansion belongs to the invoked shell, not to a hidden expansion step in exec-form command construction.

The second part compares two wrapper scripts launching the same service. The exec wrapper replaces itself with Python, which reports PID 1 inside the container. Its installed SIGTERM handler prints stopped and exits with status zero when Docker stops the container. The fixture verifies the message and the recorded exit status.

The other wrapper starts Python as a child and waits, without forwarding signals. The service reports a PID other than one. Stopping that container with a one-second timeout produces exit status 137 in the recorded environment, and the service never prints stopped. The forced termination is observed directly; no conclusion is inferred merely from the presence of a shell script.

PID 1 has special signal and child-reaping responsibilities in a Linux PID namespace. An exec wrapper makes the service the signal recipient, but it does not automatically implement application cleanup, drain in-flight work, or reap arbitrary descendants. The service still needs appropriate behavior, or a deliberately chosen init/supervision arrangement when its process model requires one.

Treat startup and shutdown as one interface

Use valid JSON arrays with double-quoted strings for exec-form instructions. Keep the executable and stable arguments clear, and document how callers replace defaults. If initialization requires a shell wrapper, finish with an appropriate exec when the wrapper’s job is to hand control to one foreground service. Quote forwarded arguments so their boundaries remain intact.

Test the actual deployed launch path, including any orchestration overrides. A correct image entrypoint can be replaced by a configuration that introduces another shell, and an overridden command may omit necessary initialization. Inspect the resulting process tree and exercise termination with representative active work.

Choose the stop signal and grace period according to the service’s contract. Record readiness, successful cleanup, and exit status separately. A container that eventually disappears after SIGKILL has stopped, but that observation alone does not prove requests completed or buffered state was safely handled.

Sources

Dockerfile ENTRYPOINT and CMD, exec and shell forms, argument combination, and entrypoint overrides, checked 2026-09-12.
Docker container stop, stop signals, timeout, and forced termination, checked 2026-09-12.
pid_namespaces(7), namespace-init signal behavior and termination of namespace members, checked 2026-09-12.

Deleting a file in a later image layer does not erase its bytes

Mon, 16 Aug 2027 00:00:00 +0000

Container image layers describe filesystem changes applied in order. A layer can add or replace a file, or record that an earlier path should disappear from the merged filesystem. That final view is what a normal container process sees, but it is not the complete history of bytes distributed with the image. Inspecting only the running container can therefore miss data retained in earlier layers.

When it breaks

Copying a credential into an image and deleting it in a later RUN does not remove the credential from the earlier immutable layer. Anyone who can obtain the relevant layer may recover the original bytes. The same mechanism explains why deleting a large build archive in a later instruction can leave the image’s distributed content unnecessarily large even though the final path is absent.

Layer changes are filesystem changesets, not necessarily compact binary differences. Replacing a large file can place its replacement content in another layer. Deletion uses a whiteout marker to suppress an earlier path when layers are applied. OCI also defines opaque-directory behavior for hiding lower directory contents, so implementing layer application as ordinary repeated tar extraction is insufficient.

Not every Dockerfile instruction creates a filesystem layer. ENV, LABEL, and CMD change image configuration and can add history entries marked empty_layer. Counting Dockerfile lines or history records therefore does not reliably count root filesystem layers. Configuration changes still matter to execution and artifact identity even when they add no application file bytes.

Check it quickly

Use Python with access to a Docker builder and the pinned base digest. The recorded run used Docker 29.3.1 with its containerd image store and a Linux arm64 Python 3.11.16 base. The marker is deliberately public. The script builds and saves one temporary image, inspects archive members without extracting them into the host filesystem, and removes its own tag:

from pathlib import Path
from tempfile import TemporaryDirectory
import json,subprocess,tarfile,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(["docker",*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def inspect(image):return json.loads(docker("image","inspect",image).stdout)[0]

name='xbcatm-whiteout-'+uuid.uuid4().hex[:10];tag=name+':probe';marker=b'PUBLIC_DEMONSTRATION_BYTES\n'
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'original.txt').write_bytes(marker)
 (root/'Dockerfile').write_text(f'FROM {BASE}\nCOPY original.txt /demo/original.txt\nRUN rm /demo/original.txt\nENV EXAMPLE_MODE=demo\nLABEL example.purpose="public fixture"\nCMD ["python", "-c", "from pathlib import Path;assert not Path(\'/demo/original.txt\').exists();print(\'absent\')"]\n')
 docker('build','--network','none','-t',tag,str(root))
 assert docker('run','--rm','--network','none',tag).stdout.strip()=='absent'
 archive=root/'image.tar';docker('image','save','-o',str(archive),tag)
 with tarfile.open(archive) as outer:
 manifests=json.load(outer.extractfile('manifest.json'));assert len(manifests)==1
 manifest=manifests[0];config=json.load(outer.extractfile(manifest['Config']))
 assert len(manifest['Layers'])==len(config['rootfs']['diff_ids'])
 assert len(manifest['Layers'])==len(inspect(BASE)['RootFS']['Layers'])+2
 found_data=False;found_whiteout=False
 for layer in manifest['Layers'][-2:]:
 with tarfile.open(fileobj=outer.extractfile(layer),mode='r:*') as contents:
 for entry in contents:
 path=entry.name.removeprefix('./')
 if path=='demo/original.txt':found_data=contents.extractfile(entry).read()==marker
 if path=='demo/.wh.original.txt':found_whiteout=True
 assert found_data and found_whiteout
 assert all(item.get('empty_layer') for item in config['history'][-3:])
 print('the final container hides the removed file, but the older layer still contains the exact public marker')
 print('the deletion layer contains a whiteout; ENV, LABEL and CMD add metadata history without filesystem layers')
finally:docker('image','rm',tag,check=False)

The Dockerfile copies original.txt into /demo, then removes it in a later RUN. The configured container command asserts the path is absent and prints absent. That confirms the merged runtime view. It does not establish that the bytes are absent from the image archive, so the next part examines the saved representation separately.

The archive’s manifest.json identifies its configuration and ordered layer files. The script reads the configuration’s rootfs.diff_ids and checks that the number of filesystem layers matches the manifest. It then inspects the final two layer archives, which correspond to the COPY addition and the subsequent deletion in this particular build.

The addition layer still contains the exact PUBLIC_DEMONSTRATION_BYTES marker. The deletion layer contains demo/.wh.original.txt. That whiteout instructs layer application to hide the lower file; it does not edit the original layer in place. Both facts are asserted directly, so an absent file in the container cannot be mistaken for evidence of secure erasure.

The final three configuration-history entries describe ENV, LABEL, and CMD and are marked as having no filesystem layer. The image has two additional filesystem layers above its base, not five. This is a concrete counterexample to the claim that each Dockerfile instruction necessarily appends another filesystem diff.

Archive representation and runtime storage are different interfaces. The experiment inspects the image-save format produced by the recorded Docker version and OCI changeset semantics. It does not assume that a snapshotter must store its internal deletion markers as the same visible .wh. filenames, nor does it measure how a particular host allocates physical blocks.

Exclude unnecessary bytes before they enter an image

Use an appropriate build context and ignore rules to keep unrelated files out of COPY inputs. Pass build credentials through the builder’s secret mechanism, and ensure commands do not write those credentials into retained outputs. If a real credential entered a published layer, rotate it and handle retained copies; a later deletion layer is not remediation.

Create and remove disposable package indexes or temporary archives within the same build operation when they are needed only during that operation. A separate final stage can copy the required runtime artifacts without inheriting the builder’s filesystem layers. Still inspect exported caches and copied outputs, because earlier build material can remain in the builder or escape through another export.

Judge the result by the actual final artifact and its intended runtime dependencies. Fewer layers alone does not guarantee smaller downloads, faster starts, or safer content. The useful question is which bytes are distributed, which paths become visible, and whether every retained file has a justified role.

Sources

OCI filesystem layer changesets 1.1.1, file additions, modifications, removals, and whiteout application, checked 2026-09-12.
OCI image configuration 1.1.1, rootfs DiffIDs and history entries without filesystem layers, checked 2026-09-12.
Dockerfile reference, COPY, RUN, ENV, LABEL, and CMD behavior, checked 2026-09-12.