docs.md

public API

oci_image_config

load("@rules_oci//oci:defs.bzl", "oci_image_config")

oci_image_config(name, arch, image, os)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
arch	Used to extract config from image if image is an index	String	optional	""
image	-	Label	required
os	Used to extract config from image if image is an index	String	optional	""

oci_image_index

load("@rules_oci//oci:defs.bzl", "oci_image_index")

oci_image_index(name, annotations, manifests)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
annotations	-	Dictionary: String -> String	optional	{}
manifests	-	List of labels	optional	[]

oci_image_layout

load("@rules_oci//oci:defs.bzl", "oci_image_layout")

oci_image_layout(name, manifest)

Writes an OCI Image Index and related blobs to an OCI Image Format directory. See https://github.com/opencontainers/image-spec/blob/main/image-layout.md for the specification of the OCI Image Format directory.

All blobs must be provided in the manifest's OCILayout provider, in the files attribute. If blobs are missing, creation of the OCI Image Layout will fail.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
manifest	An OCILayout index to be written to the OCI Image Format directory.	Label	optional	None

oci_push

load("@rules_oci//oci:defs.bzl", "oci_push")

oci_push(name, headers, manifest, registry, repository, stamp, tag, x_meta_headers)

Pushes a manifest or a list of manifests to an OCI registry.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
headers	(optional) A list of key/values to to be sent to the registry as headers.	Dictionary: String -> String	optional	{}
manifest	A manifest to push to a registry. If an OCILayout index, then push all artifacts with a 'org.opencontainers.image.ref.name' annotation.	Label	optional	None
registry	A registry host to push to, if not present consult the toolchain.	String	optional	""
repository	A repository to push to, if not present consult the toolchain.	String	optional	""
stamp	Whether to encode build information into the output. Possible values: - stamp = 1: Always stamp the build information into the output, even in --nostamp builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result. - stamp = 0: Never stamp, instead replace build information by constant values. This gives good build result caching. - stamp = -1: Embedding of build information is controlled by the --[no]stamp flag. Stamped targets are not rebuilt unless their dependencies change.	Integer	optional	-1
tag	(optional) A tag to include in the target reference. This will not be included on child images. Subject to $(location) and "Make variable" substitution. Stamping You can use values produced by the workspace status command in your tag. To do this write a script that prints key-value pairs separated by spaces, e.g. #!/usr/bin/env bash echo "STABLE_KEY1 VALUE1" echo "STABLE_KEY2 VALUE2" You can reference these keys in tag using curly braces, oci_push( name = "push", tag = "v1.0-{STABLE_KEY1}", )	String	optional	""
x_meta_headers	(optional) A list of key/values to to be sent to the registry as headers with an X-Meta- prefix.	Dictionary: String -> String	optional	{}

generate_config_file_action

load("@rules_oci//oci:defs.bzl", "generate_config_file_action")

generate_config_file_action(ctx, config_file, image, os, arch)

Generates a run action with that extracts an image's config file.

In order to use this action, the calling rule must register @com_github_datadog_rules_oci//oci:toolchain and the image must provide the OCIDescriptor and OCILayout (this should not be an issue when using the oci_image rule).

PARAMETERS

Name	Description	Default Value
ctx	The current rules context	none
config_file	The file to write the config to	none
image	The image to extract the config from.	none
os	The os to extract the config for	none
arch	The arch to extract the config for	none

RETURNS

The config file named after the rule, os, and arch

oci_image

load("@rules_oci//oci:defs.bzl", "oci_image")

oci_image(name, base, annotations, arch, cmd, entrypoint, env, labels, layers, os, tars, kwargs)

oci_image

Creates a new image manifest and config by appending the layers to an existing image manifest and config defined by base. If base is an image index, then os and arch will be used to extract the image manifest.

PARAMETERS

Name	Description	Default Value
name	The name of the rule.	none
base	A base image, as defined by oci_pull or oci_image.	none
annotations	OCI Annotations to add to the manifest.	None
arch	Used to extract a manifest from base if base is an index.	None
cmd	Default arguments to the entrypoint of the container. If an Entrypoint value is not specified, then the first entry of the Cmd array will be interpreted as the executable to run	None
entrypoint	A list of arguments to use as the command to execute when the container starts; these will be inserted into the generated OCI image config	None
env	Entries are in the format of VARNAME=VARVALUE. These values act as defaults and are merged with any specified when creating a container.	None
labels	Labels that will be applied to the image configuration, as defined in the OCI config. These behave the same way as docker LABEL. In particular, labels from the base image are inherited. An empty value for a label will cause that label to be deleted. For backwards compatibility, if this is not set, then the value of annotations will be used instead.	None
layers	A list of layers defined by oci_image_layer.	None
os	Used to extract a manifest from base if base is an index.	None
tars	A list of tars to add as layers.	None
kwargs	Additional keyword arguments, e.g. tags or visibility	none

oci_image_layer

load("@rules_oci//oci:defs.bzl", "oci_image_layer")

oci_image_layer(name, directory, files, file_map, mode_map, owner_map, symlinks, compression_method,
                kwargs)

Creates a tarball and an OCI descriptor for it

PARAMETERS

Name	Description	Default Value
name	A unique name for this rule	none
directory	Directory in the tarball to place the files	None
files	List of files to include under directory	None
file_map	Dictionary of file -> file location in tarball	None
mode_map	Dictionary of file location in tarball -> mode int (e.g. 0o755)	None
owner_map	Dictionary of file location in tarball -> owner:group string (e.g. '501:501')	None
symlinks	Dictionary of symlink -> target entries to place in the tarball	None
compression_method	A string, currently supports "gzip" and "zstd", defaults to "gzip"	"gzip"
kwargs	Additional arguments to pass to the rule, e.g. tags or visibility	none

oci_pull

load("@rules_oci//oci:defs.bzl", "oci_pull")

oci_pull(name, debug, digest, registry, repo_mapping, repository, shallow)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this repository.	Name	required
debug	Enable ocitool debug output	Boolean	optional	False
digest	-	String	required
registry	-	String	required
repo_mapping	In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target). This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).	Dictionary: String -> String	optional
repository	-	String	required
shallow	-	Boolean	optional	True

ENVIRONMENT VARIABLES

This repository rule depends on the following environment variables:

• OCI_CACHE_DIR