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.
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(List<Port> ports) Sets the ports to expose from the container.
JibContainerBuilder	setExposedPorts(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.

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

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

addLayer

public JibContainerBuilder addLayer(LayerConfiguration layerConfiguration)

Adds a layer (defined by a LayerConfiguration).

Parameters:

layerConfiguration - the LayerConfiguration

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:

for more details

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:

for more details

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:

for more details

setExposedPorts

public JibContainerBuilder setExposedPorts(List<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 list of 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:

for more details

addExposedPort

public JibContainerBuilder addExposedPort(Port port)

Adds a port to expose from the container.

Parameters:

port - the port to expose

Returns:

this

See Also:

for more details

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

containerize

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

Builds the container.

Parameters:

containerizer - the Containerizer that configures how to containerize

Returns:

the built container

Throws:

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

ExecutionException - if an exception occurred during execution

InterruptedException - if the execution was interrupted

IOException - if an I/O exception occurs