Cloud API Overview > @adpt/cloud > docker > ImageRef

docker.ImageRef interface

An immutable reference to a container image, including all information known about the image.

Signature:

export interface ImageRef extends Readonly<ImageRefData> 

Remarks

This type is the base type for an image reference and is allowed to contain partial or incomplete information about a container image. It can include both information about how to access the image and also information about the image itself.

Many of the properties of docker.ImageRef are related to the container image reference string used by Docker and other container-based systems. A container image reference string is a structured string containing multiple components. The most basic components are illustrated below, using the example image reference string "my.registry:5000/a/repo/path:sometag@sha256:899a03e9816e5283edba63d".

NOTE: The length of the digest has been shortened for formatting purposes.

"my.registry:5000/a/repo/path:sometag@sha256:899a03e9816e5283edba63d"
|     domain     |   path    |  tag  |         digest               |

To aid in correct formatting, docker.ImageRef and related types and classes also provide helper properties that combine these basic components into combinations that are often useful, such as name, which is the domain and path combined with a /.

Many tools, such as the Docker UI, also accept a shortened form of a string reference, called the familiar form. An example of a familiar reference is ubuntu. In this form, only the path component is required. When components of the reference are left out, default values are assumed. The default domain is docker.io and the default tag is latest. Additionally, if the domain is docker.io and there are no / characters in the path, library/ is prepended to the path. So ubuntu is the familiar form for the complete reference docker.io/library/ubuntu:latest.

An docker.ImageRef is designed to hold as much information about an image as may be available and therefore some properties that are not known will be undefined.

See also docker.MutableImageRef, which can be used to parse reference strings and construct or modify image references.

Properties

Property	Type	Description
familiar	string	The complete string reference for this image in familiar form, which leaves out certain fields from the reference when they are set to default values.
name	string	The image name, which is comprised of the optional domain and the (non-optional) path. Will be undefined if there is no path.
nameTag	string	The image name (including any registry) and image tag. Returns undefined if either path or tag are not set. If nameTag is set to a string that does not contain a tag (i.e. does not include a ":"), the default tag of latest will be set. To set nameTag without defaulting to latest, call the class method setNameTag with the parameter useDefaultTag set to false.
pathTag	string	The image path (not including any registry) and image tag. Returns undefined if either path or tag are not set.
ref	string	The best (most specific and complete) string reference for this image, given the information available in this docker.ImageRef.
registry	string	An alias for domain.
registryDigest	string	The remote digest reference in domain/path@digest form.
registryRef	string	The best remote reference available for this image in either domain/path@digest format or domain/path:tag format.
registryTag	string	The remote tag reference in domain/path:tag form.
type	ImageRefType	The type of an image reference indicates how the image can be accessed, either through a Docker host (daemon) or directly to a container registry.