Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

nix-oci

nix-oci is a flake-parts module designed to streamline the management of OCI (Open Container Initiative) repositories using the Nix package manager. By leveraging nix2container as its backend, nix-oci facilitates the declarative creation and handling of container images, ensuring reproducibility and efficiency in containerized environments.

Installation

See the readme.

Options

oci.enableDevShell

Whether to enable the flake development shell.

Type: boolean

Default: false

Declared by:

oci.enabled

Whether to enable Enable the OCI module…

Type: boolean

Default: false

Example: true

Declared by:

oci.credentialsLeak

Options for credential leak detection in container images.

Type: submodule

Default: { }

Declared by:

oci.credentialsLeak.configPath

Path where global credentials leak check configuration files will be stored.

Type: absolute path

Default: config.oci.rootPath + "/credentials-leak/"

Declared by:

oci.credentialsLeak.trivy

Configuration for detecting credentials leaks using Trivy.

Type: submodule

Default: { }

Declared by:

oci.credentialsLeak.trivy.enabled

Whether to enable credentials leak detection with Trivy.

Type: boolean

Default: false

Example: true

Declared by:

oci.cve

Configuration for Common Vulnerabilities and Exposures (CVE) scanning in container images.

Type: submodule

Default: { }

Declared by:

oci.cve.configPath

Path where CVE scanner configuration files will be stored.

Type: absolute path

Default: cfg.oci.rootPath

Declared by:

oci.cve.grype

Configuration for CVE scanning using Grype.

Type: submodule

Default: { }

Declared by:

oci.cve.grype.enabled

Whether to enable CVE scanning with Grype.

Type: boolean

Default: false

Example: true

Declared by:

oci.cve.grype.config

Configuration for Grype scanner settings.

Type: submodule

Default: { }

Declared by:

oci.cve.grype.config.enabled

Whether to enable Grype configuration file generation.

Type: boolean

Default: false

Example: true

Declared by:

oci.cve.grype.config.rootPath

Path where Grype configuration files will be stored.

Type: absolute path

Default: config.oci.cve.configPath + "/grype/"

Declared by:

oci.cve.trivy

Configuration for CVE scanning using Trivy.

Type: submodule

Default: { }

Declared by:

oci.cve.trivy.enabled

Whether to enable CVE scanning with Trivy.

Type: boolean

Default: false

Example: true

Declared by:

oci.cve.trivy.ignore

Configuration for CVE exclusions in Trivy scans.

Type: submodule

Default: { }

Declared by:

oci.cve.trivy.ignore.extra

Additional CVE identifiers to ignore globally in Trivy scans.

Type: list of string

Default: [ ]

Declared by:

oci.cve.trivy.ignore.fileEnabled

Whether to enable Trivy CVE ignore file generation.

Type: boolean

Default: false

Example: true

Declared by:

oci.cve.trivy.ignore.rootPath

Path where Trivy CVE ignore files will be stored.

Type: absolute path

Default: cfg.oci.cve.configPath

Declared by:

oci.devShellPackage

The package to use for the development shell.

Type: package

Declared by:

oci.fromImageManifestRootPath

The root path to store the pulled OCI image manifest JSON lockfiles.

Type: absolute path

Default: config.oci.rootPath + "/pulledManifestsLocks/"

Declared by:

oci.lib.filterEnabledOutputsSet

A function to filter outputs.

Type: unspecified value

Default: <function, args: {config, subConfig}>

Declared by:

oci.lib.mkAppCVEGrype

To build grype app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkAppCVETrivy

To build trivy app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function>

Declared by:

oci.lib.mkAppContainerStructureTest

A function to create a check that runs container-structure-test on a built image using podman.

Type: function that evaluates to a(n) (attribute set)

Default: <function>

Declared by:

oci.lib.mkAppCredentialsLeakTrivy

To build trivy app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkAppDgoss

Type: function that evaluates to a(n) (attribute set)

Default: <function>

Declared by:

oci.lib.mkAppSBOMSyft

To build syft app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkCheckDive

A function to create a check that runs dive on a built image

Type: function that evaluates to a(n) package

Default: <function, args: {oci, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkDebugOCI

A function to build debug container.

Type: function that evaluates to a(n) package

Default: <function>

Declared by:

oci.lib.mkDockerArchive

A function to transform nix2container build into docker archive

Type: function that evaluates to a(n) package

Default: <function, args: {oci, pkgs, skopeo}>

Declared by:

oci.lib.mkNixConfig

A function to build nix configuration file for containers

Type: unspecified value

Default: pkgs: pkgs.writeText "etc/nix/nix.conf" "..."

Declared by:

oci.lib.mkNixOCI

A function to build nix container

Type: function that evaluates to a(n) package

Default: <function>

Declared by:

oci.lib.mkNixOCILayer

A function to build nix container

Type: package

Default: <function>

Declared by:

oci.lib.mkNixOrSimpleOCI

A function to that build nix or simple container depending config.

Type: function that evaluates to a(n) package

Default: <function>

Declared by:

oci.lib.mkNixShadowSetup

A function to build passwd, shadow, group, and gshadow files for containers that run nested Nix

Type: unspecified value

Default: pkgs: [ (writeText "etc/passwd" "...") (writeText "etc/group" "...") ... ]

Declared by:

oci.lib.mkNonRootShadowSetup

A function to build passwd, shadow, group, and gshadow files for containers run as non-root user

Type: unspecified value

Default: { user, pkgs, uid ? 4000, gid ? uid }: [ (writeTextDir "etc/passwd" "...") ... ]

Declared by:

oci.lib.mkOCI

A function to build container

Type: function that evaluates to a(n) package

Default: <function, args: {config, containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkOCIEntrypoint

A function to get entrypoint of container

Type: function that evaluates to a(n) list of string

Default: <function, args: {package}>

Declared by:

oci.lib.mkOCIName

A function to get name of container

Type: function that evaluates to a(n) string

Default: <function, args: {fromImage, package}>

Declared by:

oci.lib.mkOCIPulledManifestLock

A function to build OCI manifest to pull

Type: function that evaluates to a(n) package

Default: <function, args: {config, containerId, perSystemConfig}>

Declared by:

oci.lib.mkOCIPulledManifestLockPath

A function to build OCI manifest to pull

Type: function that evaluates to a(n) absolute path

Default: <function, args: {config, containerId, perSystemConfig}>

Declared by:

oci.lib.mkOCIPulledManifestLockRelativePath

Generate local relive path to download OCI

Type: function that evaluates to a(n) string

Default: <function, args: {config, containerId, perSystemConfig, self}>

Declared by:

oci.lib.mkOCIPulledManifestLockRelativeRootPath

A function to get relative path lock manifest of to pull OCI

Type: function that evaluates to a(n) string

Default: <function>

Declared by:

oci.lib.mkOCIPulledManifestLockUpdateScript

A function to build script to update pulled OCI manifests locks

Type: function that evaluates to a(n) package

Default: <function, args: {config, perSystemConfig, pkgs, self}>

Declared by:

oci.lib.mkOCITag

A function to get tag of container

Type: function that evaluates to a(n) string

Default: <function, args: {fromImage, package}>

Declared by:

oci.lib.mkOCIUser

A function to get user of container

Type: function that evaluates to a(n) string

Default: <function, args: {isRoot, name}>

Declared by:

oci.lib.mkPodmanOCI

Function to build a container image with Podman and a non-root daemon.

Type: unspecified value

Default: <function, args: {dependencies?, nix2container, package, pkgs}>

Declared by:

oci.lib.mkPodmanOCIRunScript

Function to build a script into a podman container image

Type: function that evaluates to a(n) package

Default: <function, args: {dependencies?, nix2container, package, pkgs}>

Declared by:

oci.lib.mkPodmanPolicy

A function to build podman security policy configuration

Type: unspecified value

Default: pkgs: pkgs.writeTextDir "etc/containers/policy.json" "..."

Declared by:

oci.lib.mkPublishOCIScript

A function to build publishing script for CI that pushes container images to registry

Type: unspecified value

Default: { container, pkgs }: pkgs.writeScriptBin "publish-docker-image" "..."

Declared by:

oci.lib.mkRoot

A function to build container root filesystem with package, user setup, and dependencies

Type: function that evaluates to a(n) package

Default:

{ pkgs, tag, user, package ? null, dependencies ? [ ] }: pkgs.buildEnv { name = "root"; version = tag; paths = (optional (package != null) package) ++ shadowSetup ++ dependencies; pathsToLink = [ "/bin" "/lib" "/etc" ]; }

Declared by:

oci.lib.mkRootShadowSetup

A function to build passwd, shadow, group, and gshadow files for containers run as root user

Type: unspecified value

Default: { pkgs }: [ (writeTextDir "etc/passwd" "...") (writeTextDir "etc/shadow" "...") ... ]

Declared by:

oci.lib.mkScriptCVEGrype

To build grype app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkScriptCVETrivy

To build trivy app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {config, containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkScriptContainerStructureTest

A function to create a check that runs container-structure-test on a built image using podman.

Type: function that evaluates to a(n) package

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkScriptCredentialsLeakTrivy

To build trivy app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkScriptDgoss

A function to create a check that runs dgoss on a built image using podman.

Type: function that evaluates to a(n) package

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkScriptSBOMSyft

To build syft app to check for CVEs on OCI.

Type: function that evaluates to a(n) (attribute set)

Default: <function, args: {containerId, perSystemConfig, pkgs}>

Declared by:

oci.lib.mkSimpleOCI

A function to build simple container

Type: function that evaluates to a(n) package

Default: <function>

Declared by:

oci.lib.prefixOutputs

A prefix to add to the output file.

Type: unspecified value

Default: <function, args: {prefix, set}>

Declared by:

oci.registry

The OCI registry to use for pushing and pulling images.

Type: null or string

Default: null

Declared by:

oci.rootPath

The root path to store the Nix OCI resources.

Type: absolute path

Default: self + "/oci/"

Declared by:

oci.sbom

Configuration for Software Bill of Materials (SBOM) generation in container images.

Type: submodule

Default: { }

Declared by:

oci.sbom.path

Path where SBOM files will be stored.

Type: absolute path

Default: cfg.oci.rootPath

Declared by:

oci.sbom.syft

Configuration for SBOM generation using Syft.

Type: submodule

Default: { }

Declared by:

oci.sbom.syft.enabled

Whether to enable SBOM generation with Syft.

Type: boolean

Default: false

Declared by:

oci.sbom.syft.config

Configuration settings for Syft SBOM generation.

Type: submodule

Default: { }

Declared by:

oci.sbom.syft.config.enabled

Whether to enable Syft configuration file generation.

Type: boolean

Default: false

Declared by:

oci.sbom.syft.config.rootPath

Path where Syft configuration files will be stored.

Type: absolute path

Default: cfg.oci.sbom.path

Declared by:

oci.test

Global configuration for container testing tools.

Type: submodule

Default: { }

Declared by:

oci.test.containerStructureTest

Configuration for container-structure-test validation tool.

Type: submodule

Default: { }

Declared by:

oci.test.containerStructureTest.enabled

Whether to enable container-structure-test globally for all containers.

Type: boolean

Default: false

Declared by:

oci.test.dgoss

Configuration for dgoss (Docker + goss) testing framework.

Type: submodule

Default: { }

Declared by:

oci.test.dgoss.enabled

Whether to enable dgoss testing globally for all containers.

Type: boolean

Default: false

Declared by:

oci.test.dive

Configuration for Dive container image analysis tool.

Type: submodule

Default: { }

Declared by:

oci.test.dive.enabled

Whether to enable Dive analysis globally for all containers.

Type: boolean

Default: false

Declared by:

perSystem.oci.packages

Type: submodule

Default: { }

Declared by:

perSystem.oci.packages.containerStructureTest

The package to use for container-structure-test.

Type: package

Default: pkgs.container-structure-test

Example: pkgs.container-structure-test

Declared by:

perSystem.oci.packages.dgoss

The package to use for dgoss.

Type: package

Default: pkgs.dgoss

Example: pkgs.dgoss

Declared by:

perSystem.oci.packages.dive

The package to use for dive.

Type: package

Default: pkgs.dive

Example: pkgs.dive

Declared by:

perSystem.oci.packages.grype

The package to use for grype.

Type: package

Default: pkgs.grype

Example: pkgs.grype

Declared by:

perSystem.oci.packages.nix2container

The nix2container package.

Type: attribute set

Default: inputs.nix2container.packages.${system}.nix2container

Example: inputs.nix2container.packages.${system}.nix2container

Declared by:

perSystem.oci.packages.podman

The package to use for podman.

Type: package

Default: pkgs.podman

Example: pkgs.podman

Declared by:

perSystem.oci.packages.skaffold

The package to use for skaffold.

Type: package

Default: pkgs.skaffold

Example: pkgs.skaffold

Declared by:

perSystem.oci.packages.skopeo

The package to use for skopeo.

Type: package

Default: inputs.nix2container.packages.${system}.skopeo-nix2container

Example: inputs.nix2container.packages.${system}.skopeo-nix2container

Declared by:

perSystem.oci.packages.syft

The package to use for syft.

Type: package

Default: pkgs.syft

Example: pkgs.syft

Declared by:

perSystem.oci.packages.trivy

The package to use for trivy.

Type: package

Default: pkgs.trivy

Example: pkgs.trivy

Declared by:

perSystem.oci.containers

Definitions for all containers managed by this flake.

Type: attribute set of (submodule)

Default: { }

Example:

{ my-app = { package = pkgs.hello; dependencies = [ pkgs.bash ]; fromImage = { imageName = "library/alpine"; imageTag = "3.21.2"; }; isRoot = false; }; }

Declared by:

perSystem.oci.containers.<name>.package

The main package for the container

Type: null or package

Default: null

Example: pkgs.hello

Declared by:

perSystem.oci.containers.<name>.credentialsLeak

.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.credentialsLeak.trivy

The package to use for the cve check.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.credentialsLeak.trivy.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.cve

Whether to check for CVEs.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.cve.grype

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.cve.grype.enabled

Whether to run grype.

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.cve.grype.config

The path to the grype config.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.cve.grype.config.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.cve.grype.config.path

Type: absolute path

Default: config.oci.rootPath + name + "/cve/grype.yaml"

Declared by:

perSystem.oci.containers.<name>.cve.rootPath

Type: absolute path

Default: config.oci.rootPath + name + "/cve/"

Declared by:

perSystem.oci.containers.<name>.cve.trivy

The package to use for the cve check.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.cve.trivy.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.cve.trivy.ignore

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.cve.trivy.ignore.extra

Extra CVE to ignore.

Type: list of string

Default: [ ]

Declared by:

perSystem.oci.containers.<name>.cve.trivy.ignore.fileEnabled

Whether to enable .

Type: boolean

Default: false

Example: true

Declared by:

perSystem.oci.containers.<name>.cve.trivy.ignore.path

Type: null or absolute path

Default: config.oci.rootPath + name + "/cve/trivy.ignore"

Declared by:

perSystem.oci.containers.<name>.debug

Configuration for debug builds with additional debugging tools and packages.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.debug.enabled

Whether to enable debug build with additional debugging tools.

Type: boolean

Default: perSystemConfig.oci.debug.enabled

Declared by:

perSystem.oci.containers.<name>.debug.packages

List of additional packages to include in debug builds.

Type: list of package

Default: perSystemConfig.oci.debug.packages

Declared by:

perSystem.oci.containers.<name>.debug.entrypoint

Debug entrypoint wrapper configuration.

Type: submodule

Declared by:

perSystem.oci.containers.<name>.debug.entrypoint.enabled

Whether to enable debug entrypoint wrapper.

Type: boolean

Default: perSystemConfig.oci.debug.entrypoint.enabled

Declared by:

perSystem.oci.containers.<name>.debug.entrypoint.wrapper

Package containing the debug entrypoint wrapper.

Type: package

Default: perSystemConfig.oci.debug.entrypoint.wrapper

Declared by:

perSystem.oci.containers.<name>.dependencies

Additional dependencies packages to include in the container.

Type: list of package

Default: [ ]

Example: [ pkgs.bash pkgs.coreutils ]

Declared by:

perSystem.oci.containers.<name>.entrypoint

The entrypoint command and arguments for the container. Will be automatically generated from the package if not specified.

Type: list of string

Default: cfg.oci.lib.mkOCIEntrypoint { inherit package; }

Example:

[ "/bin/sh" "-c" "echo hello" ]

Declared by:

perSystem.oci.containers.<name>.fromImage

The base image to use as the foundation for this container. If null, will create a minimal scratch-based container.

Type: null or (submodule)

Default: null

Example:

{ arch = "amd64"; imageName = "library/alpine"; imageTag = "1.2.3"; os = "linux"; }

Declared by:

perSystem.oci.containers.<name>.fromImage.arch

The architecture of the image.

Type: one of “amd64”, “arm64”

Default:

if system == "x86_64-linux" then "amd64" else if system == "aarch64-linux" then "arm64" else throw "Unsupported system: ${system} as default arch, please set the arch option."

Example: "amd64"

Declared by:

perSystem.oci.containers.<name>.fromImage.imageName

The name of the base image.

Type: null or string

Default: null

Example: "library/alpine"

Declared by:

perSystem.oci.containers.<name>.fromImage.imageTag

The tag/version of the image.

Type: string

Example: "3.21.2"

Declared by:

perSystem.oci.containers.<name>.fromImage.os

The operating system for the image.

Type: value “linux” (singular enum)

Default: "linux"

Example: "linux"

Declared by:

perSystem.oci.containers.<name>.installNix

Whether to install nix in the container.

Type: boolean

Default: false

Example: true

Declared by:

perSystem.oci.containers.<name>.isRoot

Whether the container is a root container.

Type: boolean

Default: false

Example: true

Declared by:

perSystem.oci.containers.<name>.name

Name of the container. If null, the name will be automatically generated from the package or base image.

Type: null or string

Default: cfg.oci.lib.mkOCIName { inherit package fromImage; }

Example: "my-app"

Declared by:

perSystem.oci.containers.<name>.push

Whether to push the container to the OCI registry.

Type: boolean

Default: false

Example: true

Declared by:

perSystem.oci.containers.<name>.registry

Container registry prefix (e.g., “ghcr.io/my-org” or “my-registry.io/project”). If set, the full container name will be “registry/name”. If null or empty string, no registry prefix will be added.

Type: null or string

Default: null

Example: "ghcr.io/my-org"

Declared by:

perSystem.oci.containers.<name>.rootPath

The root path for the container.

Type: absolute path

Default: config.oci.rootPath + name + "/"

Declared by:

perSystem.oci.containers.<name>.sbom

.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.sbom.rootPath

The root path for the sbom.

Type: absolute path

Default: config.oci.rootPath + name + "/sbom/"

Declared by:

perSystem.oci.containers.<name>.sbom.syft

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.sbom.syft.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.sbom.syft.config

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.sbom.syft.config.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.containers.<name>.sbom.syft.config.path

Type: absolute path

Default: config.oci.rootPath + name + "/sbom/syft.yaml"

Declared by:

perSystem.oci.containers.<name>.tag

Tag of the container.

Type: null or string

Default: config.oci.lib.mkOCITag { inherit package fromImage; }

Example: "1.0.0"

Declared by:

perSystem.oci.containers.<name>.test

.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.test.containerStructureTest

Configuration for container-structure-test to validate container structure and metadata.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.test.containerStructureTest.enabled

Whether to enable container-structure-test for validating container structure and metadata.

Type: boolean

Default: cfg.oci.test.containerStructureTest.enabled

Declared by:

perSystem.oci.containers.<name>.test.containerStructureTest.configs

List of container-structure-test configuration files to run.

Type: list of absolute path

Default: [ (cfg.oci.rootPath + name + "/test/container-structure-test.yaml") ]

Declared by:

perSystem.oci.containers.<name>.test.dgoss

Configuration for dgoss (Docker + goss) testing framework.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.test.dgoss.enabled

Whether to enable dgoss testing for the container.

Type: boolean

Default: cfg.oci.test.dgoss.enabled

Declared by:

perSystem.oci.containers.<name>.test.dgoss.optionsPath

Path to the dgoss configuration file.

Type: absolute path

Default: config.oci.rootPath + name + "/test/dgoss.yaml"

Declared by:

perSystem.oci.containers.<name>.test.dive

Configuration for Dive analysis of container image layers and efficiency.

Type: submodule

Default: { }

Declared by:

perSystem.oci.containers.<name>.test.dive.enabled

Whether to enable Dive analysis for container image layers and efficiency.

Type: boolean

Default: cfg.oci.test.dive.enabled

Example: true

Declared by:

perSystem.oci.containers.<name>.test.rootPath

The root path for the test.

Type: absolute path

Default: config.oci.rootPath + name + "/test/"

Declared by:

perSystem.oci.containers.<name>.user

The user to run the container as. If null, will be automatically determined based on isRoot setting.

Type: null or string

Default: cfg.oci.lib.mkOCIUser { inherit name isRoot; }

Declared by:

perSystem.oci.debug

Add debug build in output.

Type: submodule

Default: { }

Declared by:

perSystem.oci.debug.enabled

Type: boolean

Default: false

Declared by:

perSystem.oci.debug.packages

Type: list of package

Default:

with pkgs; [ coreutils bash curl ]

Declared by:

perSystem.oci.debug.entrypoint

Debug entrypoint wrapper configuration.

Type: submodule

Declared by:

perSystem.oci.debug.entrypoint.enabled

Whether to enable debug entrypoint wrapper.

Type: boolean

Default: false

Declared by:

perSystem.oci.debug.entrypoint.wrapper

Default behavior run sleep infinity fallback if entrypoint fail.

Type: package

Default: pkgs.writeScriptBin "entrypoint" ./debug-entrypoint.sh

Declared by: