Class: ContainerdContainer
A container of the Containerd component's namespace, with the operations of a Docker container: start, stop, kill, pause, exec, terminals, logs, stats, live updates or updates by recreation, commit and file export. Get it from Containerd.getContainer, Containerd.listContainers or Containerd.createContainer; do not create it yourself. Each call returns a new object (transient).
Its properties are a snapshot taken when it was obtained: the operations changing the container (start(), stop(), kill(), pause(), wait(), update()…) take a new one when they end, and ContainerdContainer.syncContainerInfo takes one on demand. The state the container is in decides what works: exec(), createTTY() and stats() need it running, and remove() refuses a running container unless forced.
Example
import {Containerd, type ContainerdContainer, type ContainerdContainerStats} from 'lakutata/com/containerd'
declare const containerd: Containerd
const container: ContainerdContainer = await containerd.getContainer('worker')
if (!container.state.running) await container.start()
//The last 100 lines, without following the output
for await (const chunk of await container.logs({tail: 100, follow: false})) process.stdout.write(chunk)
const stats: ContainerdContainerStats = await container.stats()
console.log(stats.cpu.percent, stats.memory.usage)
//Live, without a restart
await container.update({memoryLimit: 256 * 1024 * 1024})
//Its stop signal, then SIGKILL after 5 seconds
await container.stop({timeout: 5})
await container.remove()Extends
Constructors
Constructor
new ContainerdContainer(
cradleProxy):ContainerdContainer
Called by the container only: an object is created through a container (see the class description), never with new.
Parameters
cradleProxy
Record<string | symbol, any>
The container's resolution proxy.
Returns
ContainerdContainer
Inherited from
Properties
constructor
constructor:
Function
The initial value of Object.prototype.constructor is the standard built-in Object constructor.
Inherited from
Provider.constructor
createdAt
createdAt:
Time
When the container was created.
hostname
hostname:
string
The container's hostname; empty for the containers created without nerdctl's labels.
id
id:
string
The container's identifier (64 hexadecimal characters). The name or identifier prefix the object was asked with is resolved to it; it changes when ContainerdContainer.update creates the container again.
imageName
imageName:
string
The name of the container's image (docker.io/library/alpine:3.20).
labels
labels:
Record<string,string>
The container's labels: the ones given at its creation, its image's, and nerdctl's (nerdctl/*).
name
name:
string
The container's name (nerdctl's nerdctl/name label); its identifier when it has none.
networkNames
networkNames:
string[]
The networks the container joins: ['host'], ['none'], or the names of its CNI networks.
networks
networks:
ContainerdContainerNetwork[]
The container's interfaces on its CNI networks (eth0, eth1…), with their addresses while it runs.
platform
platform:
string
The platform of the image the container runs (linux/arm64/v8); empty when unknown.
ports
ports:
ContainerdContainerPort[]
The container's ports published on the host, through its first CNI network.
restartPolicy
restartPolicy:
ContainerdRestartPolicy
The container's restart policy, applied by containerd's restart monitor; 'no' when it has none.
state
state:
ContainerdContainerState
The container's state when the snapshot was taken: its status, its process identifier, its last exit code, and when it started and finished.
volumes
volumes:
string[]
The names of the named volumes the container mounts.
Accessors
$id
Get Signature
get $id():
string|symbol
The name the object was registered under (its key in the module options), or a symbol of its class for an object registered by its class or built without registration.
Returns
string | symbol
Inherited from
$symbol
Get Signature
get $symbol():
symbol
A symbol unique to the instance (made from its $uuid), created on first read.
Returns
symbol
Inherited from
$uuid
Get Signature
get $uuid():
string
A random UUID identifying the instance.
Returns
string
Inherited from
className
Get Signature
get
staticclassName():string
The name of the class.
Returns
string
Inherited from
className
Get Signature
get className():
string
The name of the object's class.
Returns
string
Inherited from
Methods
[asyncDispose]()
[asyncDispose]():
Promise<void>
Dispose the object at the end of an await using block, as BaseObject.dispose.
Returns
Promise<void>
Resolves once the object is destroyed.
Inherited from
acceptsOption()
staticacceptsOption(name,value):boolean
Whether the class accepts an option which is not one of its @Configurable properties (an option it reads with getConfigurableRecords()): the modules check the options of the objects they declare and warn of the options the classes do not accept. Override it in the classes reading options without configurable properties.
Parameters
name
string
The option name.
value
unknown
The option value.
Returns
boolean
true when the option is accepted; false by default.
Inherited from
assign()
Call Signature
staticassign<T,U>(target,source):T&U
Copy the values of all of the enumerable own properties from one or more source objects to a target object. Returns the target object.
Type Parameters
T
T extends object
U
U
Parameters
target
T
The target object to copy to.
source
U
The source object from which to copy properties.
Returns
T & U
Inherited from
Call Signature
staticassign<T,U,V>(target,source1,source2):T&U&V
Copy the values of all of the enumerable own properties from one or more source objects to a target object. Returns the target object.
Type Parameters
T
T extends object
U
U
V
V
Parameters
target
T
The target object to copy to.
source1
U
The first source object from which to copy properties.
source2
V
The second source object from which to copy properties.
Returns
T & U & V
Inherited from
Call Signature
staticassign<T,U,V,W>(target,source1,source2,source3):T&U&V&W
Copy the values of all of the enumerable own properties from one or more source objects to a target object. Returns the target object.
Type Parameters
T
T extends object
U
U
V
V
W
W
Parameters
target
T
The target object to copy to.
source1
U
The first source object from which to copy properties.
source2
V
The second source object from which to copy properties.
source3
W
The third source object from which to copy properties.
Returns
T & U & V & W
Inherited from
Call Signature
staticassign(target, ...sources):any
Copy the values of all of the enumerable own properties from one or more source objects to a target object. Returns the target object.
Parameters
target
object
The target object to copy to.
sources
...any[]
One or more source objects from which to copy properties
Returns
any
Inherited from
commit()
commit(
options?):Promise<ContainerdImage>
Commit the container: save the changes of its root file system (not its mounts) as a new layer on its image, with configuration changes, as docker commit does. A running container is paused meanwhile by default.
Parameters
options?
The name of the new image (<registry>/<repository>:commit-<milliseconds> of the container's image by default), pauseBeforeCommitting (true by default), the configuration changes, comment and author.
Returns
Promise<ContainerdImage>
The new image.
Throws
The container's image was removed.
create()
Call Signature
staticcreate(o):any
Creates an object that has the specified prototype or that has null prototype.
Parameters
o
object | null
Object to use as a prototype. May be null.
Returns
any
Inherited from
Call Signature
staticcreate(o,properties):any
Creates an object that has the specified prototype, and that optionally contains specified properties.
Parameters
o
object | null
Object to use as a prototype. May be null
properties
PropertyDescriptorMap & ThisType<any>
JavaScript object that contains one or more property descriptors.
Returns
any
Inherited from
createTTY()
createTTY(
options?):Promise<ContainerdContainerTTY>
Open an interactive terminal in the running container: a process with a pseudo terminal (TERM=xterm), its input and output through FIFOs (mkfifo of the host). Close it with ContainerdContainerTTY.close when done.
Parameters
options?
The command (a string is run by /bin/sh -c as ContainerdContainer.exec runs it, an array as is; ['/bin/sh'] by default, so the image needs a shell), the initial console size, env, workingDir and user.
Returns
Promise<ContainerdContainerTTY>
The terminal, its process started.
Throws
The container is not running.
Throws
The host has no mkfifo; the user is not found in the container.
defineProperties()
staticdefineProperties<T>(o,properties):T
Adds one or more properties to an object, and/or modifies attributes of existing properties.
Type Parameters
T
T
Parameters
o
T
Object on which to add or modify the properties. This can be a native JavaScript object or a DOM object.
properties
PropertyDescriptorMap & ThisType<any>
JavaScript object that contains one or more descriptor objects. Each descriptor object describes a data property or an accessor property.
Returns
T
Inherited from
defineProperty()
staticdefineProperty<T>(o,p,attributes):T
Adds a property to an object, or modifies attributes of an existing property.
Type Parameters
T
T
Parameters
o
T
Object on which to add or modify the property. This can be a native JavaScript object (that is, a user-defined object or a built in object) or a DOM object.
p
PropertyKey
The property name.
attributes
PropertyDescriptor & ThisType<any>
Descriptor for the property. It can be for a data property or an accessor property.
Returns
T
Inherited from
dispose()
dispose():
Promise<void>
Destroy the object: its beforeDestroy(), the objects it created, then its destroy(). Calling it more than once destroys once. A disposed singleton or scoped object is dropped from its container, which creates a new one on the next request. Using a destroyed object (getObject(), buildObject()) throws an ObjectDestroyedException.
Returns
Promise<void>
Resolves once the object is destroyed.
Throws
The error of the object's own beforeDestroy() or destroy() (an AggregateError when several fail); the errors of the objects it created are reported through the application's logger instead.
Inherited from
entries()
Call Signature
staticentries<T>(o): [string,T][]
Returns an array of key/values of the enumerable own properties of an object
Type Parameters
T
T
Parameters
o
{[s: string]: T; } | ArrayLike<T>
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
[string, T][]
Inherited from
Call Signature
staticentries(o): [string,any][]
Returns an array of key/values of the enumerable own properties of an object
Parameters
o
{ }
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
[string, any][]
Inherited from
exec()
exec(
options):Promise<ContainerdExecResult>
Run a command in the running container and wait for it to exit, its outputs captured in memory. The process gets the container's environment (with env added), working directory and user unless given. Its standard output and error are kept apart through FIFOs (mkfifo of the host); without mkfifo, both are in stdout.
Parameters
options
The command (a string is run by /bin/sh -c, an array as is), env, workingDir, user (name, uid, name:group), stdin (written then closed) and timeout (milliseconds, then the process is killed with SIGKILL).
Returns
Promise<ContainerdExecResult>
The exit code and the outputs; a command killed by its timeout resolves with exit code 137.
Throws
The container is not running (stopped or paused).
Throws
stdin is given and the host has no mkfifo; the user is not found in the container.
exportDirectory()
exportDirectory(
options):Promise<void>
Copy a file or directory of the container out as a tar archive, as docker cp does: from the running process's file system (its mounts included), or from its root file system when it is not running (without its mounts). The symbolic links of the path are resolved inside the container; the devices, sockets and pipes are not archived.
Parameters
options
ContainerExportDirectoryOptions
The absolute path in the container, and the destination (a file path, created or replaced, or a writable stream).
Returns
Promise<void>
Throws
The path does not exist in the container.
Throws
The archive cannot be written.
freeze()
Call Signature
staticfreeze<T>(f):T
Prevents the modification of existing property attributes and values, and prevents the addition of new properties.
Type Parameters
T
T extends Function
Parameters
f
T
Object on which to lock the attributes.
Returns
T
Inherited from
Call Signature
staticfreeze<T,U>(o):Readonly<T>
Prevents the modification of existing property attributes and values, and prevents the addition of new properties.
Type Parameters
T
T extends object
U
U extends string | number | bigint | boolean | symbol
Parameters
o
T
Object on which to lock the attributes.
Returns
Readonly<T>
Inherited from
Call Signature
staticfreeze<T>(o):Readonly<T>
Prevents the modification of existing property attributes and values, and prevents the addition of new properties.
Type Parameters
T
T
Parameters
o
T
Object on which to lock the attributes.
Returns
Readonly<T>
Inherited from
fromEntries()
Call Signature
staticfromEntries<T>(entries):object
Returns an object created by key-value entries for properties and methods
Type Parameters
T
T = any
Parameters
entries
Iterable<readonly [PropertyKey, T]>
An iterable object that contains key-value entries for properties and methods.
Returns
object
Inherited from
Call Signature
staticfromEntries(entries):any
Returns an object created by key-value entries for properties and methods
Parameters
entries
Iterable<readonly any[]>
An iterable object that contains key-value entries for properties and methods.
Returns
any
Inherited from
getMethod()
getMethod(
name,throwExceptionIfNotFound?): (...args) =>any
Get a method bound to the object, to call it by name.
Parameters
name
string | symbol
The method name or symbol.
throwExceptionIfNotFound?
boolean
Throw when the method does not exist, instead of returning a function doing nothing; false by default.
Returns
The bound method, or a function doing nothing (returning undefined) when it does not exist.
(...args) => any
Throws
When the method does not exist and throwExceptionIfNotFound is true.
Inherited from
getOwnPropertyDescriptor()
staticgetOwnPropertyDescriptor(o,p):PropertyDescriptor|undefined
Gets the own property descriptor of the specified object. An own property descriptor is one that is defined directly on the object and is not inherited from the object's prototype.
Parameters
o
any
Object that contains the property.
p
PropertyKey
Name of the property.
Returns
PropertyDescriptor | undefined
Inherited from
Provider.getOwnPropertyDescriptor
getOwnPropertyDescriptors()
staticgetOwnPropertyDescriptors<T>(o): { [P in string | number | symbol]: TypedPropertyDescriptor<T[P]> } &object
Returns an object containing all own property descriptors of an object
Type Parameters
T
T
Parameters
o
T
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
{ [P in string | number | symbol]: TypedPropertyDescriptor<T[P]> } & object
Inherited from
Provider.getOwnPropertyDescriptors
getOwnPropertyNames()
staticgetOwnPropertyNames(o):string[]
Returns the names of the own properties of an object. The own properties of an object are those that are defined directly on that object, and are not inherited from the object's prototype. The properties of an object include both fields (objects) and functions.
Parameters
o
any
Object that contains the own properties.
Returns
string[]
Inherited from
getOwnPropertySymbols()
staticgetOwnPropertySymbols(o):symbol[]
Returns an array of all symbol properties found directly on object o.
Parameters
o
any
Object to retrieve the symbols from.
Returns
symbol[]
Inherited from
Provider.getOwnPropertySymbols
getProperty()
getProperty<
T>(propertyKey,defaultValue?):T
Read an own property of the object.
Type Parameters
T
T = any
Parameters
propertyKey
string
The property name.
defaultValue?
T
The value returned when the object has no own property of this name.
Returns
T
The property value, or the default value.
Inherited from
getPrototypeOf()
staticgetPrototypeOf(o):any
Returns the prototype of an object.
Parameters
o
any
The object that references the prototype.
Returns
any
Inherited from
hasMethod()
hasMethod(
name):boolean
Whether the object has a method of this name or symbol (a function of its class, not an own property).
Parameters
name
string | symbol
The method name or symbol.
Returns
boolean
true when the method exists.
Inherited from
hasOwn()
statichasOwn(o,v):boolean
Determines whether an object has a property with the specified name.
Parameters
o
object
An object.
v
PropertyKey
A property name.
Returns
boolean
Inherited from
hasOwnProperty()
hasOwnProperty(
v):boolean
Determines whether an object has a property with the specified name.
Parameters
v
PropertyKey
A property name.
Returns
boolean
Inherited from
hasProperty()
hasProperty(
propertyKey):boolean
Whether the object has an own property (not a method or accessor of its class) of this name or symbol.
Parameters
propertyKey
string | symbol
The property name or symbol.
Returns
boolean
true when the property exists.
Inherited from
image()
image():
Promise<ContainerdImage>
Get the container's image.
Returns
Promise<ContainerdImage>
The image.
Throws
The image was removed since the container was created.
is()
staticis(value1,value2):boolean
Returns true if the values are the same value, false otherwise.
Parameters
value1
any
The first value.
value2
any
The second value.
Returns
boolean
Inherited from
isExtensible()
staticisExtensible(o):boolean
Returns a value that indicates whether new properties can be added to an object.
Parameters
o
any
Object to test.
Returns
boolean
Inherited from
isFrozen()
staticisFrozen(o):boolean
Returns true if existing property attributes and values cannot be modified in an object, and new properties cannot be added to the object.
Parameters
o
any
Object to test.
Returns
boolean
Inherited from
isPrototypeOf()
isPrototypeOf(
v):boolean
Determines whether an object exists in another object's prototype chain.
Parameters
v
Object
Another object whose prototype chain is to be checked.
Returns
boolean
Inherited from
isSealed()
staticisSealed(o):boolean
Returns true if existing property attributes cannot be modified in an object and new properties cannot be added to the object.
Parameters
o
any
Object to test.
Returns
boolean
Inherited from
keys()
Call Signature
statickeys(o):string[]
Returns the names of the enumerable string properties and methods of an object.
Parameters
o
object
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
string[]
Inherited from
Call Signature
statickeys(o):string[]
Returns the names of the enumerable string properties and methods of an object.
Parameters
o
{ }
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
string[]
Inherited from
kill()
kill(
options?):Promise<void>
Send a signal to the container's main process, or to all its processes. SIGKILL also tells the restart monitor not to restart it; other signals do not.
Parameters
options?
The signal (SIGKILL by default; a name or a number) and all.
Returns
Promise<void>
Throws
The container is not running.
logs()
logs(
options?):Promise<Readable>
Read the container's logs: its standard output and error interleaved in one stream, without timestamps, from its log file (and the previous rotated file). By default the stream follows the new output while the container runs (or is being restarted by the restart monitor), and ends once it stopped or when the object is destroyed.
Parameters
options?
tail, the number of last lines to start with (all by default), and follow (true by default).
Returns
Promise<Readable>
A readable stream of buffers.
pause()
pause():
Promise<void>
Pause all the processes of the running container (cgroup freezer).
Returns
Promise<void>
Throws
The container is not running.
preventExtensions()
staticpreventExtensions<T>(o):T
Prevents the addition of new properties to an object.
Type Parameters
T
T
Parameters
o
T
Object to make non-extensible.
Returns
T
Inherited from
processes()
processes():
Promise<number[]>
List the processes of the running container.
Returns
Promise<number[]>
Their process identifiers on the host.
Throws
The container is not running.
propertyIsEnumerable()
propertyIsEnumerable(
v):boolean
Determines whether a specified property is enumerable.
Parameters
v
PropertyKey
A property name.
Returns
boolean
Inherited from
propertyNames()
propertyNames():
string[]
The names of the object's own properties (not its class's methods and accessors).
Returns
string[]
The names.
Inherited from
propertySymbols()
propertySymbols():
symbol[]
The symbols of the object's own properties.
Returns
symbol[]
The symbols.
Inherited from
remove()
remove(
options?):Promise<void>
Remove the container: its task, its CNI network interfaces, its record, its snapshot and its state directory (its logs included). The named volumes it mounts are kept. With force, a running or paused container is killed first.
Parameters
options?
force (false by default).
Returns
Promise<void>
Throws
The container is running and force is not set.
restart()
restart(
options?):Promise<void>
Restart the container: stop it as ContainerdContainer.stop does, then start it.
Parameters
options?
How it is stopped: the time to wait in seconds (10 by default) and the signal.
Returns
Promise<void>
Throws
The task cannot be started again.
seal()
staticseal<T>(o):T
Prevents the modification of attributes of existing properties, and prevents the addition of new properties.
Type Parameters
T
T
Parameters
o
T
Object on which to lock the attributes.
Returns
T
Inherited from
setProperty()
setProperty(
propertyKey,value):void
Set a property of the object; the value is not validated, even for a @Configurable property.
Parameters
propertyKey
string
The property name.
value
any
The value.
Returns
void
Inherited from
setPrototypeOf()
staticsetPrototypeOf(o,proto):any
Sets the prototype of a specified object o to object proto or null. Returns the object o.
Parameters
o
any
The object to change its prototype.
proto
object | null
The value of the new prototype or null.
Returns
any
Inherited from
start()
start():
Promise<void>
Start the container: a new task of its root file system, its output appended to its log file (rotated first beyond the component's logMaxSize), its CNI networks set up. Its restart policy applies from now on. A running container is left as it is.
Returns
Promise<void>
Throws
The container is paused: unpause it.
Throws
The task cannot be created or started (the command is not found, seccomp refuses it…).
stats()
stats(
interval?):Promise<ContainerdContainerStats>
Read the resources the running or paused container uses: its cgroup counters and its network interface counters, sampled twice to compute its CPU use over the interval.
Parameters
interval?
number
The time between the two samples, in milliseconds; 0 takes one sample and reports a CPU use of 0. 1000 by default.
Returns
Promise<ContainerdContainerStats>
The counters of the last sample, with the CPU use over the interval.
Throws
The container is not running.
stop()
stop(
options?):Promise<void>
Stop the container: send its stop signal (the one of options, else its stopSignal, else SIGTERM), wait for it to exit, then kill all its processes with SIGKILL when the timeout ends. Its exit code is kept, and the restart monitor no longer restarts it. A paused container is resumed first; a stopped one is left as it is.
Parameters
options?
The time to wait in seconds (10 by default) and the signal.
Returns
Promise<void>
syncContainerInfo()
syncContainerInfo():
Promise<void>
Read the container's information and state again from containerd into the object's properties.
Returns
Promise<void>
Throws
The container no longer exists.
toLocaleString()
toLocaleString():
string
Returns a date converted to a string using the current locale.
Returns
string
Inherited from
toString()
toString():
string
Returns a string representation of an object.
Returns
string
Inherited from
unpause()
unpause():
Promise<void>
Resume the processes of the paused container.
Returns
Promise<void>
Throws
The container is not running.
update()
update(
options):Promise<void>
Update the container's settings. When only resources and the restart policy change (memoryLimit, memorySwap, cpus, cpuShares, cpuSet, pidsLimit, OOMKillDisable, restartPolicy), they are applied live, without a restart, as docker update does: 0 ([] for cpuSet) removes a limit, from the running container too, and from the settings it is created again with (ContainerResourceOptions). Any other setting creates the container again with its creation settings and the changes: a new container with the same name (and a new identifier, which this object follows), started when the old one was running; the old one is removed. The recreation only works for the containers created by the component, whose settings it kept.
Parameters
options
Partial<ContainerCreateOptions>
The settings to change, as Containerd.createContainer takes them.
Returns
Promise<void>
Throws
A live update gives a memorySwap (positive) to a container without a memory limit, or leaves its memorySwap below its memoryLimit (from @lakutata/core).
Throws
The container must be created again but was not created by the component (nerdctl's, or created by another dataRoot).
Throws
From the recreation, as Containerd.createContainer throws.
valueOf()
valueOf():
Object
Returns the primitive value of the specified object.
Returns
Object
Inherited from
values()
Call Signature
staticvalues<T>(o):T[]
Returns an array of values of the enumerable own properties of an object
Type Parameters
T
T
Parameters
o
{[s: string]: T; } | ArrayLike<T>
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
T[]
Inherited from
Call Signature
staticvalues(o):any[]
Returns an array of values of the enumerable own properties of an object
Parameters
o
{ }
Object that contains the properties and methods. This can be an object that you created or an existing Document Object Model (DOM) object.
Returns
any[]
Inherited from
wait()
wait():
Promise<number>
Wait for the container's main process to exit, as docker wait does. A container that is not running resolves at once: with the exit code of its last run when it exited or was stopped by ContainerdContainer.stop, with 0 when it was never started (or when the component did not keep its exit code: a container created by nerdctl or by another dataRoot). The wait ends with an error when the object is destroyed.
Returns
Promise<number>
The exit code.
Throws
The wait was aborted (from @lakutata/grpc, its code is CANCELLED).