@lakutata/containerd 0.0.0-stage → 3.0.0-beta.1

package/dist/cjs/containerd/Containerd.d.ts

@@ -0,0 +1,442 @@
+import { Component } from '@lakutata/core';
+import { type ContainerdEvent } from '../client/ContainerdClient.js';
+import { type CNINetwork } from '../client/Networks.js';
+import { type Message } from '@lakutata/grpc';
+import type { RegistryCredentials, RegistryOptions } from '../client/Registry.js';
+import { ContainerdImage } from './lib/ContainerdImage.js';
+import { ContainerdContainer } from './lib/ContainerdContainer.js';
+import { ContainerdPruneOptions } from './options/ContainerdPruneOptions.js';
+import { VolumeCreateOptions } from './options/volume/VolumeCreateOptions.js';
+import type { ContainerdVolumeInfo } from './types/ContainerdVolumeInfo.js';
+import type { ContainerdPruneResult } from './types/ContainerdPruneResult.js';
+import { VolumeStore, type Volume } from '../client/Volumes.js';
+import { ImagePullOptions } from './options/image/ImagePullOptions.js';
+import { ImageImportOptions } from './options/image/ImageImportOptions.js';
+import { ImageExportOptions } from './options/image/ImageExportOptions.js';
+import { ContainerCreateOptions } from './options/container/ContainerCreateOptions.js';
+import { NetworkCreateOptions } from './options/network/NetworkCreateOptions.js';
+import { ImageBuildOptions } from './options/image/ImageBuildOptions.js';
+import type { ContainerdNetworkInfo } from './types/ContainerdNetworkInfo.js';
+/**
+ * The containerd component: manages the images, containers, CNI networks and volumes of one containerd namespace by
+ * talking to containerd's gRPC socket directly, without a Docker daemon and without nerdctl. Use it on the Linux machines
+ * running containerd alone (embedded devices, servers without Docker); the application needs access to the socket (root,
+ * or a member of the group owning it). Register it in the `components` of an application (`{class: Containerd, ...}`)
+ * and get it with `getObject()` or `@Inject`; it is a singleton.
+ *
+ * Its API follows the Docker component's (`pullImage`, `createContainer`, `container.exec()`…). The containers it creates
+ * are nerdctl's: they carry nerdctl's labels (`nerdctl/name`…), so `nerdctl ps` lists them; containerd's shim writes
+ * their output to a log file and containerd's restart monitor applies their restart policy, also while the application
+ * is not running. The component pulls, pushes, imports and exports the images itself; it sends the builds to BuildKit
+ * (a local or remote `buildkitd`).
+ *
+ * The component connects when it is created: it fails with {@link ContainerdConnectionException} when containerd does
+ * not answer on `socketPath` (or `buildkitTLS` is given with a unix socket), and it creates its namespace when the
+ * namespace does not exist. BuildKit is only reached by
+ * the builds. When the component is destroyed, it ends its event streams, aborts its pulls, pushes and builds in
+ * progress, and closes its connections.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {Containerd, type ContainerdContainer, type ContainerdExecResult, type ContainerdImage} from 'lakutata/com/containerd'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'device.app',
+ *         name: 'Device',
+ *         components: {
+ *             containerd: {
+ *                 class: Containerd,
+ *                 socketPath: '/run/containerd/containerd.sock',
+ *                 namespace: 'default',
+ *                 registryAuths: {'registry.example.com': {username: 'deploy', password: 'secret'}}
+ *             }
+ *         },
+ *         bootstrap: ['containerd']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const containerd: Containerd = await app.getObject('containerd')
+ *         //Pulled for the machine's platform, unpacked into the snapshotter
+ *         const image: ContainerdImage = await containerd.pullImage({image: 'alpine:3.20'})
+ *         const container: ContainerdContainer = await containerd.createContainer({
+ *             image: image.name,
+ *             name: 'worker',
+ *             cmd: ['sleep', 'infinity'],
+ *             //Restarted by containerd, even when the application is not running
+ *             restartPolicy: 'always'
+ *         })
+ *         await container.start()
+ *         const result: ContainerdExecResult = await container.exec({cmd: 'cat /etc/os-release'})
+ *         console.log(result.exitCode, result.stdout)
+ *     })
+ * ```
+ */
+export declare class Containerd extends Component {
+    #private;
+    /**
+     * The path of containerd's gRPC socket.
+     * @default '/run/containerd/containerd.sock'
+     */
+    protected readonly socketPath: string;
+    /**
+     * The containerd namespace holding the component's images and containers: `default` is nerdctl's, `k8s.io` the one
+     * of Kubernetes. Letters, digits, `_`, `.` and `-`, starting with a letter or a digit; created when the component
+     * starts if it does not exist. The volumes are kept apart by namespace too.
+     * @default 'default'
+     */
+    protected readonly namespace: string;
+    /**
+     * The containerd snapshotter unpacking the images and holding the containers' root file systems: `overlayfs`, or
+     * `native` where overlayfs is not available.
+     * @default 'overlayfs'
+     */
+    protected readonly snapshotter: string;
+    /**
+     * The containerd runtime running the containers.
+     * @default 'io.containerd.runc.v2'
+     */
+    protected readonly runtime: string;
+    /**
+     * How runc manages the containers' cgroups: `cgroupfs`, or `systemd` when containerd's configuration sets
+     * `SystemdCgroup = true` for runc. It must match the machine's setup, or the containers fail to start.
+     * @default 'cgroupfs'
+     */
+    protected readonly cgroupManager: 'cgroupfs' | 'systemd';
+    /**
+     * The directory holding the component's files: each container's state (its log file, `hosts`, `resolv.conf`,
+     * `hostname` and the settings it was created with) under `containers/<namespace>/<id>`, the named volumes under
+     * `volumes/<namespace>`, and the temporary files of the builds and imports under `tmp`.
+     * @default '/var/lib/lakutata/containerd'
+     */
+    protected readonly dataRoot: string;
+    /**
+     * The size, in bytes, beyond which a container's log file is rotated when the component starts the container: the
+     * file is copied to `<log>.1` (replacing the previous copy) and emptied. Only checked at the starts made by the
+     * component, not at the restarts made by containerd's restart monitor. `0` never rotates.
+     * @default 0
+     */
+    protected readonly logMaxSize: number;
+    /**
+     * The directory of the CNI network configurations (`nerdctl-<name>.conflist`), shared with nerdctl.
+     * @default '/etc/cni/net.d'
+     */
+    protected readonly cniConfigPath: string;
+    /**
+     * The directories searched for the CNI plugins (`bridge`, `portmap`…); the ones that exist are used. A container
+     * joining a CNI network fails to be created when none of them exists.
+     * @default ['/opt/cni/bin', '/usr/lib/cni', '/usr/libexec/cni']
+     */
+    protected readonly cniPath: string[];
+    /**
+     * The address of the BuildKit daemon building the images: a unix socket (`unix:///run/buildkit/buildkitd.sock`, or
+     * an absolute path) or a remote daemon (`tcp://host:1234`). It is only reached by {@link Containerd.buildImage},
+     * {@link Containerd.buildkitVersion} and {@link Containerd.buildkitPlatforms}: the component starts without BuildKit.
+     * @default 'unix:///run/buildkit/buildkitd.sock'
+     */
+    protected readonly buildkitAddress: string;
+    /**
+     * Turns TLS on for a remote BuildKit (`tcp://`): `ca` verifies the daemon's certificate, `cert` and `key` are the
+     * client's certificate and key (PEM, as strings or buffers), `servername` is the name checked in the daemon's
+     * certificate (the address's host by default). Given with a unix socket address, it makes the component fail when it
+     * is created, with {@link ContainerdConnectionException}.
+     * @default none (plain TCP)
+     */
+    protected readonly buildkitTLS?: {
+        ca?: string | Buffer;
+        cert?: string | Buffer;
+        key?: string | Buffer;
+        servername?: string;
+    };
+    /**
+     * The registry credentials, by registry host (`docker.io`, `registry.example.com:5000`): a `username` and a
+     * `password`, or an `identityToken`. They are used by the pulls, the pushes and the base images of the builds; the
+     * `auth` option of a call replaces the credentials of its image's registry.
+     * @default none (anonymous access)
+     */
+    protected readonly registryAuths?: Record<string, RegistryCredentials>;
+    /**
+     * The registries reached over plain HTTP instead of HTTPS, by host (`localhost:5000`).
+     * @default none
+     */
+    protected readonly insecureRegistries?: string[];
+    /**
+     * Connect to containerd and create the namespace when it does not exist.
+     * @throws {ContainerdConnectionException} containerd does not answer on `socketPath` (not running, no access to the
+     * socket), or `buildkitTLS` is given with a unix socket `buildkitAddress`.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * End the event streams, abort the pulls, pushes and builds in progress, and close the connections to containerd and
+     * BuildKit. The containers keep running.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Build the registry options of a pull, a push or a build: the configured credentials (`auth` replacing the ones of
+     * the reference's registry), the insecure registries, and the component's abort signal.
+     * @param reference The image reference whose registry gets `auth` (`registry.example.com/team/app:1.0`).
+     * @param auth The credentials of the reference's registry; ignored without `reference`.
+     * @returns The registry options.
+     * @protected
+     */
+    protected registryOptions(reference?: string, auth?: RegistryCredentials): RegistryOptions;
+    /** Containerd Common Operations **/
+    /**
+     * Get the version of containerd.
+     * @returns Its version (`1.7.36`, `v2.4.1`) and its git revision.
+     * @throws {GRPCError} containerd no longer answers (from `@lakutata/grpc`).
+     */
+    version(): Promise<{
+        version: string;
+        revision: string;
+    }>;
+    /**
+     * List the platforms this machine runs containers of: its own, and the ones of the emulators registered in
+     * `binfmt_misc` (QEMU, Rosetta), as detected when the component was created or by
+     * {@link Containerd.detectPlatforms}. An image is described for the first of its platforms in this list.
+     * @returns A copy of the list, formatted `os/architecture[/variant]` (`linux/arm64/v8`, `linux/amd64`).
+     */
+    supportedPlatforms(): string[];
+    /**
+     * Detect again the platforms this machine runs, after emulators were registered or removed in `binfmt_misc`.
+     * @returns The platforms detected, as {@link Containerd.supportedPlatforms} returns them from now on.
+     */
+    detectPlatforms(): string[];
+    /**
+     * Stream containerd's events in the component's namespace (`/tasks/exit`, `/containers/create`, `/images/delete`…)
+     * as they happen. The stream ends without an error when `signal` aborts or when the component is destroyed. The
+     * fields of the task, container, image and snapshot events are decoded; the other events have an empty `event`.
+     * @param signal Ends the stream when aborted; without it, the stream lasts as long as the component.
+     * @returns The events, in their order.
+     * @throws {GRPCError} The connection to containerd fails or is lost (from `@lakutata/grpc`).
+     */
+    events(signal?: AbortSignal): AsyncGenerator<ContainerdEvent>;
+    /** Containerd Image Operations **/
+    /**
+     * List the images of the namespace, each one described as {@link Containerd.getImage} does. The images whose content
+     * is not complete (a pull in progress, content collected) or that have none of their platforms' content are left
+     * out.
+     * @returns The images.
+     */
+    listImages(): Promise<ContainerdImage[]>;
+    /**
+     * Get an image present in containerd; it is not pulled. The image is described for the first platform it has among
+     * {@link Containerd.supportedPlatforms}, or for the first platform it has.
+     * @param name Its name or a reference, normalized as Docker does (`alpine` is `docker.io/library/alpine:latest`).
+     * @returns The image.
+     * @throws {ContainerdImageNotFoundException} No image has this name.
+     * @throws {ContainerdPlatformException} The content of none of its platforms is present.
+     */
+    getImage(name: string): Promise<ContainerdImage>;
+    /**
+     * Pull an image from its registry: the manifests of the platforms asked, their configurations and layers, then
+     * unpack the ones the machine runs ({@link Containerd.supportedPlatforms}) into the snapshotter so that containers
+     * can run them; the other platforms are only stored. The image is named by its normalized reference
+     * (`docker.io/library/alpine:3.20`); an image of the same name is replaced. The pull is aborted when the component
+     * is destroyed.
+     * @param options The reference, the platforms (the machine's by default, `'all'` for every one), the registry
+     * credentials (`auth`, else the `registryAuths` of its registry), `unpack` and the progress callback.
+     * @returns The image pulled.
+     * @throws {ContainerdPlatformException} The image has no manifest for one of the platforms asked.
+     * @throws {ContainerdImagePullException} The registry cannot be reached, refuses the credentials, or does not have
+     * the reference; the transfer fails or is aborted; the unpacking fails (the image is stored).
+     */
+    pullImage(options: ImagePullOptions): Promise<ContainerdImage>;
+    /**
+     * Get the version of the BuildKit daemon at `buildkitAddress`.
+     * @returns Its package (`github.com/moby/buildkit`), version and revision.
+     * @throws {ContainerdImageBuildException} BuildKit cannot be reached.
+     */
+    buildkitVersion(): Promise<{
+        package: string;
+        version: string;
+        revision: string;
+    }>;
+    /**
+     * List the platforms the BuildKit daemon builds for: the ones of its workers, including the emulators of its own
+     * machine.
+     * @returns The platforms, formatted `os/architecture[/variant]`.
+     * @throws {ContainerdImageBuildException} BuildKit cannot be reached.
+     */
+    buildkitPlatforms(): Promise<string[]>;
+    /**
+     * Build an image with BuildKit (the local or remote daemon at `buildkitAddress`), as `docker buildx build` does: the
+     * build context (without the files its `.dockerignore` excludes) and the Dockerfile are sent over a BuildKit session,
+     * then the image built is imported into containerd, named by `repoTag`, and pushed when `push` is set. The base
+     * images are pulled by BuildKit with the component's registry credentials (or `auth`). The build is aborted when the
+     * component is destroyed.
+     * @param options The context directory, the Dockerfile, the name, the platforms (the machine's by default), the build
+     * arguments, labels and target, `nocache`, `pull`, `push`, the credentials and the output callback.
+     * @returns The image built.
+     * @throws {ContainerdImageBuildException} BuildKit cannot be reached, the build fails, or its import fails.
+     * @throws {ContainerdImagePushException} With `push`, the push fails; the image is built and imported.
+     */
+    buildImage(options: ImageBuildOptions): Promise<ContainerdImage>;
+    /**
+     * Import the images of an archive: an OCI image layout (`nerdctl save`, `docker save` of Docker 25+, the archives of
+     * {@link Containerd.exportImages}) or an older `docker save` archive. The images are named as the archive names
+     * them (or by `name`, for an archive of one image), replace the images of the same names, and the platforms the
+     * machine runs ({@link Containerd.supportedPlatforms}) are unpacked unless `unpack: false`. The images of an OCI
+     * layout without a name annotation are not imported unless `name` is given.
+     * @param options The archive (a file path or a readable stream), the name to give, and `unpack`.
+     * @returns The images imported.
+     * @throws {ContainerdImageImportException} The archive cannot be read or is not an image archive; `name` is given
+     * with an archive of several images (nothing is imported); the unpacking fails (the images are stored and named).
+     */
+    importImage(options: ImageImportOptions): Promise<ContainerdImage[]>;
+    /**
+     * Export images into one archive: an OCI image layout with the `manifest.json` of `docker load`, loaded by
+     * `docker load`, `nerdctl load` and {@link Containerd.importImage}. The archive has the platforms each image has in
+     * containerd.
+     * @param names The names or references of the images (one at least).
+     * @param options The destination: a file path (created or replaced) or a writable stream.
+     * @throws {ContainerdImageNotFoundException} One of the images does not exist.
+     * @throws {ContainerdImageExportException} The archive cannot be written.
+     */
+    exportImages(names: string[], options: ImageExportOptions): Promise<void>;
+    /** Containerd Network Operations **/
+    /**
+     * Describe a CNI network.
+     * @param network The network, as read from its configuration file.
+     * @returns Its information.
+     * @protected
+     */
+    protected networkInfo(network: CNINetwork): ContainerdNetworkInfo;
+    /**
+     * List the networks: `host` and `none`, then the CNI networks of `cniConfigPath`, among them nerdctl's default
+     * `bridge` once it exists (it is created when a container or {@link Containerd.getNetwork} first asks for it).
+     * @returns The networks.
+     */
+    listNetworks(): Promise<ContainerdNetworkInfo[]>;
+    /**
+     * Get a network. Asking for `bridge` creates nerdctl's default network when it does not exist.
+     * @param nameOrId Its name, its identifier, or a prefix of its identifier (3 characters at least).
+     * @returns The network.
+     * @throws {ContainerdNetworkNotFoundException} No network matches.
+     */
+    getNetwork(nameOrId: string): Promise<ContainerdNetworkInfo>;
+    /**
+     * Create a CNI network as `nerdctl network create` does: its configuration `nerdctl-<name>.conflist` written in
+     * `cniConfigPath`, so nerdctl sees it. Its bridge and firewall rules are set up when the first container joins it.
+     * @param options Its name, driver (`bridge`, `macvlan`, `ipvlan`), IPv4 subnet (a free one of `10.4.0.0/16` by
+     * default), gateway and range, IPv6 subnet, parent interface, `internal`, MTU and labels.
+     * @returns The network created.
+     * @throws {ContainerdNetworkConflictException} The name is taken (`host`, `none` and `bridge` included), or the subnet
+     * overlaps another network's.
+     */
+    createNetwork(options: NetworkCreateOptions): Promise<ContainerdNetworkInfo>;
+    /**
+     * Remove a CNI network created by nerdctl or by the component, as `nerdctl network rm` does: its configuration, its
+     * bridge and the leases of its addresses.
+     * @param nameOrId Its name, its identifier, or a prefix of its identifier.
+     * @throws {ContainerdNetworkNotFoundException} No network matches (`host` and `none` included).
+     * @throws {ContainerdNetworkConflictException} A container of the namespace uses it, it is the default `bridge`, or
+     * it was not created by nerdctl (its configuration is left to remove by hand).
+     */
+    removeNetwork(nameOrId: string): Promise<void>;
+    /** Containerd Container Operations **/
+    /**
+     * List the containers of the namespace, running or not, the ones created by nerdctl included.
+     * @param labels Only the containers having all these labels with these values (`{app: 'web'}`); all of them by
+     * default.
+     * @returns The containers.
+     */
+    listContainers(labels?: Record<string, string>): Promise<ContainerdContainer[]>;
+    /**
+     * Get a container.
+     * @param idOrName Its identifier, its name, or a prefix of its identifier (3 hexadecimal characters at least).
+     * @returns The container, its information read from containerd.
+     * @throws {ContainerdContainerNotFoundException} No container matches.
+     * @throws {Error} The prefix matches several containers.
+     */
+    getContainer(idOrName: string): Promise<ContainerdContainer>;
+    /**
+     * Create a container of an image present in containerd (it is not pulled): its snapshot, its OCI specification and
+     * its state directory (log file, `hosts`, `resolv.conf`, `hostname`). The container is not started. It joins the
+     * default CNI network `bridge` by default (created when first used, the CNI plugins needed), as with Docker; `network:
+     * 'host'` gives it the host's network. Its `ports` are published on its first CNI network. Its system calls are filtered by containerd's default seccomp profile, unless it is privileged or
+     * `seccompProfile` says otherwise. The settings are kept so that {@link ContainerdContainer.update} can create it
+     * again.
+     * @param options The image and the container's settings (name, command, environment, user, mounts, devices,
+     * networks, ports, resources, restart policy…).
+     * @returns The container created.
+     * @throws {ContainerdImageNotFoundException} The image does not exist.
+     * @throws {ContainerdPlatformException} The image has no manifest for the platform asked (the machine's by default).
+     * @throws {ContainerdContainerNameConflictException} Another container has the name.
+     * @throws {ContainerdNetworkNotFoundException} One of the CNI networks does not exist.
+     * @throws {Error} The settings cannot be applied: ports without a CNI network, no command, no CNI plugin installed, a
+     * device or a seccomp profile file that cannot be read.
+     */
+    createContainer(options: ContainerCreateOptions): Promise<ContainerdContainer>;
+    /**
+     * Replace a container by a new one created with other settings, as {@link ContainerdContainer.update} does: the old
+     * container is renamed, the new one created with `options`, then the old one removed by force, and the new one
+     * started when the old one was running or paused. When the creation fails, the old container gets its name back
+     * and keeps running.
+     * @param record The containerd record of the container to replace.
+     * @param options The complete settings of the new container.
+     * @returns The new container.
+     * @throws {ContainerdContainerNotFoundException} The container no longer exists.
+     * @throws {ContainerdImageNotFoundException} From the creation, as {@link Containerd.createContainer} throws.
+     */
+    recreateContainer(record: Message, options: ContainerCreateOptions): Promise<ContainerdContainer>;
+    /** Containerd Volume Operations **/
+    /**
+     * Describe a named volume.
+     * @param volume The volume, as read from its directory.
+     * @returns Its information.
+     * @protected
+     */
+    protected volumeInfo(volume: Volume): ContainerdVolumeInfo;
+    /**
+     * The store of the namespace's named volumes, under `<dataRoot>/volumes/<namespace>`.
+     * @protected
+     */
+    protected get volumes(): VolumeStore;
+    /**
+     * List the containers mounting a volume, running or not.
+     * @param name The volume's name.
+     * @returns The names of the containers.
+     * @protected
+     */
+    protected volumeUsers(name: string): Promise<string[]>;
+    /**
+     * List the named volumes of the namespace, sorted by name.
+     * @returns The volumes.
+     */
+    listVolumes(): Promise<ContainerdVolumeInfo[]>;
+    /**
+     * Get a named volume.
+     * @param name The volume's name.
+     * @returns The volume: its host directory (`mountpoint`), labels and creation time.
+     * @throws {ContainerdVolumeNotFoundException} The volume does not exist, or the name is not a valid one.
+     */
+    getVolume(name: string): Promise<ContainerdVolumeInfo>;
+    /**
+     * Create a named volume: a directory under `dataRoot` that containers mount by name. As Docker does, a volume that
+     * exists is returned unchanged (its labels are not updated). A container mounting a missing volume creates it too.
+     * @param options The name (letters, digits, `_`, `.` and `-`) and the labels.
+     * @returns The volume.
+     */
+    createVolume(options: VolumeCreateOptions): Promise<ContainerdVolumeInfo>;
+    /**
+     * Remove a named volume and its data.
+     * @param name The volume's name.
+     * @throws {ContainerdVolumeNotFoundException} The volume does not exist.
+     * @throws {ContainerdVolumeInUseException} A container of the namespace mounts it, even a stopped one.
+     */
+    removeVolume(name: string): Promise<void>;
+    /** Containerd Common Operations **/
+    /**
+     * Remove the unused resources of the namespace, in this order: the containers that are not running (created or
+     * exited), the images no container uses (the dangling ones, without a tag, or all of them with `allImages`), the CNI
+     * networks no container uses (except the default `bridge` and the ones nerdctl did not create), and the volumes no
+     * container mounts. A container, image, network or volume that fails to be removed is skipped (left out of the
+     * result).
+     * @param options What to remove: `containers` and `images` by default, `allImages`, `networks` and `volumes` when
+     * set.
+     * @returns The names (identifiers of the containers) of what was removed.
+     */
+    prune(options?: ContainerdPruneOptions): Promise<ContainerdPruneResult>;
+}