com.google.cloud.tools.jib.api

Class JibContainerBuilder

java.lang.Object

com.google.cloud.tools.jib.api.JibContainerBuilder

public class JibContainerBuilder
extends Object

Builds a container with Jib.

Example usage:

 Jib.from(baseImage)
    .addLayer(sourceFiles, extractionPath)
    .setEntrypoint("myprogram", "--flag", "subcommand")
    .setProgramArguments("hello", "world")
    .addEnvironmentVariable("HOME", "/app")
    .addExposedPort(Port.tcp(8080))
    .addLabel("containerizer", "jib")
    .containerize(...);
 

Method Summary

Modifier and Type	Method and Description
JibContainerBuilder	addEnvironmentVariable(String name, String value) Sets a variable in the container environment.
JibContainerBuilder	addExposedPort(Port port) Adds a port to expose from the container.
JibContainerBuilder	addLabel(String key, String value) Sets a label for the container.
JibContainerBuilder	addLayer(LayerConfiguration layerConfiguration) Adds a layer (defined by a LayerConfiguration).
JibContainerBuilder	addLayer(List<Path> files, AbsoluteUnixPath pathInContainer) Adds a new layer to the container with files as the source files and pathInContainer as the path to copy the source files to in the container file system.
JibContainerBuilder	addLayer(List<Path> files, String pathInContainer) Adds a new layer to the container with files as the source files and pathInContainer as the path to copy the source files to in the container file system.
JibContainerBuilder	addVolume(AbsoluteUnixPath volume) Adds a directory that may hold an externally mounted volume.
JibContainer	containerize(Containerizer containerizer) Builds the container.
JibContainerBuilder	setCreationTime(Instant creationTime) Sets the container image creation time.
JibContainerBuilder	setEntrypoint(List<String> entrypoint) Sets the container entrypoint.
JibContainerBuilder	setEntrypoint(String... entrypoint) Sets the container entrypoint.
JibContainerBuilder	setEnvironment(Map<String,String> environmentMap) Sets the container environment.
JibContainerBuilder	setExposedPorts(Port... ports) Sets the ports to expose from the container.
JibContainerBuilder	setExposedPorts(Set<Port> ports) Sets the ports to expose from the container.
JibContainerBuilder	setFormat(ImageFormat imageFormat) Sets the format to build the container image as.
JibContainerBuilder	setLabels(Map<String,String> labelMap) Sets the labels for the container.
JibContainerBuilder	setLayers(LayerConfiguration... layerConfigurations) Sets the layers.
JibContainerBuilder	setLayers(List<LayerConfiguration> layerConfigurations) Sets the layers (defined by a list of LayerConfigurations).
JibContainerBuilder	setProgramArguments(List<String> programArguments) Sets the container entrypoint program arguments.
JibContainerBuilder	setProgramArguments(String... programArguments) Sets the container entrypoint program arguments.
JibContainerBuilder	setUser(String user) Sets the user and group to run the container as.
JibContainerBuilder	setVolumes(AbsoluteUnixPath... volumes) Sets the directories that may hold externally mounted volumes.
JibContainerBuilder	setVolumes(Set<AbsoluteUnixPath> volumes) Sets the directories that may hold externally mounted volumes.
JibContainerBuilder	setWorkingDirectory(AbsoluteUnixPath workingDirectory) Sets the working directory in the container.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addLayer

public JibContainerBuilder addLayer(List<Path> files,
                                    AbsoluteUnixPath pathInContainer)
                             throws IOException

Adds a new layer to the container with files as the source files and pathInContainer as the path to copy the source files to in the container file system.

Source files that are directories will be recursively copied. For example, if the source files are:

• fileA
• fileB
• directory/

and the destination to copy to is /path/in/container, then the new layer will have the following entries for the container file system:

• /path/in/container/fileA
• /path/in/container/fileB
• /path/in/container/directory/
• /path/in/container/directory/... (all contents of directory/)

Parameters:

files - the source files to copy to a new layer in the container

pathInContainer - the path in the container file system corresponding to the sourceFile

Returns:

this

Throws:

IOException - if an exception occurred when recursively listing any directories

addLayer

public JibContainerBuilder addLayer(List<Path> files,
                                    String pathInContainer)
                             throws IOException

Adds a new layer to the container with files as the source files and pathInContainer as the path to copy the source files to in the container file system.

Parameters:

files - the source files to copy to a new layer in the container

pathInContainer - the path in the container file system corresponding to the sourceFile

Returns:

this

Throws:

IOException - if an exception occurred when recursively listing any directories

IllegalArgumentException - if pathInContainer is not an absolute Unix-style path

See Also:

addLayer(List, AbsoluteUnixPath)

addLayer

public JibContainerBuilder addLayer(LayerConfiguration layerConfiguration)

Adds a layer (defined by a LayerConfiguration).

Parameters:

layerConfiguration - the LayerConfiguration

Returns:

this

setLayers

public JibContainerBuilder setLayers(List<LayerConfiguration> layerConfigurations)

Sets the layers (defined by a list of LayerConfigurations). This replaces any previously-added layers.

Parameters:

layerConfigurations - the list of LayerConfigurations

Returns:

this

setLayers

public JibContainerBuilder setLayers(LayerConfiguration... layerConfigurations)

Sets the layers. This replaces any previously-added layers.

Parameters:

layerConfigurations - the LayerConfigurations

Returns:

this

setEntrypoint

public JibContainerBuilder setEntrypoint(@Nullable
                                         List<String> entrypoint)

Sets the container entrypoint. This is the beginning of the command that is run when the container starts. setProgramArguments(java.util.List<java.lang.String>) sets additional tokens.

This is similar to ENTRYPOINT in Dockerfiles or command in the Kubernetes Container spec.

Parameters:

entrypoint - a list of the entrypoint command

Returns:

this

setEntrypoint

public JibContainerBuilder setEntrypoint(String... entrypoint)

Sets the container entrypoint.

Parameters:

entrypoint - the entrypoint command

Returns:

this

See Also:

setEntrypoint(List)

setProgramArguments

public JibContainerBuilder setProgramArguments(@Nullable
                                               List<String> programArguments)

Sets the container entrypoint program arguments. These are additional tokens added to the end of the entrypoint command.

This is similar to CMD in Dockerfiles or args in the Kubernetes Container spec.

For example, if the entrypoint was myprogram --flag subcommand and program arguments were hello world, then the command that run when the container starts is myprogram --flag subcommand hello world.

Parameters:

programArguments - a list of program argument tokens

Returns:

this

setProgramArguments

public JibContainerBuilder setProgramArguments(String... programArguments)

Sets the container entrypoint program arguments.

Parameters:

programArguments - program arguments tokens

Returns:

this

See Also:

setProgramArguments(List)

setEnvironment

public JibContainerBuilder setEnvironment(Map<String,String> environmentMap)

Sets the container environment. These environment variables are available to the program launched by the container entrypoint command. This replaces any previously-set environment variables.

This is similar to ENV in Dockerfiles or env in the Kubernetes Container spec.

Parameters:

environmentMap - a map of environment variable names to values

Returns:

this

addEnvironmentVariable

public JibContainerBuilder addEnvironmentVariable(String name,
                                                  String value)

Sets a variable in the container environment.

Parameters:

name - the environment variable name

value - the environment variable value

Returns:

this

See Also:

setEnvironment(java.util.Map<java.lang.String, java.lang.String>)

setVolumes

public JibContainerBuilder setVolumes(Set<AbsoluteUnixPath> volumes)

Sets the directories that may hold externally mounted volumes.

This is similar to VOLUME in Dockerfiles.

Parameters:

volumes - the directory paths on the container filesystem to set as volumes

Returns:

this

setVolumes

public JibContainerBuilder setVolumes(AbsoluteUnixPath... volumes)

Sets the directories that may hold externally mounted volumes.

Parameters:

volumes - the directory paths on the container filesystem to set as volumes

Returns:

this

See Also:

setVolumes(Set)

addVolume

public JibContainerBuilder addVolume(AbsoluteUnixPath volume)

Adds a directory that may hold an externally mounted volume.

Parameters:

volume - a directory path on the container filesystem to represent a volume

Returns:

this

See Also:

setVolumes(Set)

setExposedPorts

public JibContainerBuilder setExposedPorts(Set<Port> ports)

Sets the ports to expose from the container. Ports exposed will allow ingress traffic. This replaces any previously-set exposed ports.

Use Port.tcp(int) to expose a port for TCP traffic and Port.udp(int) to expose a port for UDP traffic.

This is similar to EXPOSE in Dockerfiles or ports in the Kubernetes Container spec.

Parameters:

ports - the ports to expose

Returns:

this

setExposedPorts

public JibContainerBuilder setExposedPorts(Port... ports)

Sets the ports to expose from the container. This replaces any previously-set exposed ports.

Parameters:

ports - the ports to expose

Returns:

this

See Also:

setExposedPorts(Set)

addExposedPort

public JibContainerBuilder addExposedPort(Port port)

Adds a port to expose from the container.

Parameters:

port - the port to expose

Returns:

this

See Also:

setExposedPorts(Set)

setLabels

public JibContainerBuilder setLabels(Map<String,String> labelMap)

Sets the labels for the container. This replaces any previously-set labels.

This is similar to LABEL in Dockerfiles.

Parameters:

labelMap - a map of label keys to values

Returns:

this

addLabel

public JibContainerBuilder addLabel(String key,
                                    String value)

Sets a label for the container.

Parameters:

key - the label key

value - the label value

Returns:

this

setFormat

public JibContainerBuilder setFormat(ImageFormat imageFormat)

Sets the format to build the container image as. Use ImageFormat.Docker for Docker V2.2 or ImageFormat.OCI for OCI.

Parameters:

imageFormat - the ImageFormat

Returns:

this

setCreationTime

public JibContainerBuilder setCreationTime(Instant creationTime)

Sets the container image creation time. The default is Instant.EPOCH.

Parameters:

creationTime - the container image creation time

Returns:

this

setUser

public JibContainerBuilder setUser(@Nullable
                                   String user)

Sets the user and group to run the container as. user can be a username or UID along with an optional groupname or GID.

The following are valid formats for user

• user
• uid
• user:group
• uid:gid
• uid:group
• user:gid

Parameters:

user - the user to run the container as

Returns:

this

setWorkingDirectory

public JibContainerBuilder setWorkingDirectory(@Nullable
                                               AbsoluteUnixPath workingDirectory)

Sets the working directory in the container.

Parameters:

workingDirectory - the working directory

Returns:

this

containerize

public JibContainer containerize(Containerizer containerizer)
                          throws InterruptedException,
                                 RegistryException,
                                 IOException,
                                 CacheDirectoryCreationException,
                                 ExecutionException

Builds the container.

Parameters:

containerizer - the Containerizer that configures how to containerize

Returns:

the built container

Throws:

IOException - if an I/O exception occurs

CacheDirectoryCreationException - if a directory to be used for the cache could not be created

org.apache.http.conn.HttpHostConnectException - if jib failed to connect to a registry

RegistryUnauthorizedException - if a registry request is unauthorized and needs authentication

RegistryAuthenticationFailedException - if registry authentication failed

UnknownHostException - if the registry does not exist

InsecureRegistryException - if a server could not be verified due to an insecure connection

RegistryException - if some other error occurred while interacting with a registry

ExecutionException - if some other exception occurred during execution

InterruptedException - if the execution was interrupted