Package com.google.cloud.tools.jib.api

Class JibContainerBuilder

  • public class JibContainerBuilder
extends java.lang.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 Detail

      • addLayer

        public JibContainerBuilder addLayer​(java.util.List<java.nio.file.Path> files,
                                    com.google.cloud.tools.jib.api.buildplan.AbsoluteUnixPath pathInContainer)
                             throws java.io.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:

        • fileFoo
        • fileBar
        • 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/fileFoo
        • /path/in/container/fileBar
        • /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:
        java.io.IOException - if an exception occurred when recursively listing any directories

      • addLayer

        public JibContainerBuilder addLayer​(java.util.List<java.nio.file.Path> files,
                                    java.lang.String pathInContainer)
                             throws java.io.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:
        java.io.IOException - if an exception occurred when recursively listing any directories
        java.lang.IllegalArgumentException - if pathInContainer is not an absolute Unix-style path
        See Also:
        addLayer(List, AbsoluteUnixPath)

      • addFileEntriesLayer

        public JibContainerBuilder addFileEntriesLayer​(com.google.cloud.tools.jib.api.buildplan.FileEntriesLayer layer)
        Adds a layer (defined by a FileEntriesLayer).
        Parameters:
        layer - the FileEntriesLayer
        Returns:
        this

      • setFileEntriesLayers

        public JibContainerBuilder setFileEntriesLayers​(java.util.List<com.google.cloud.tools.jib.api.buildplan.FileEntriesLayer> layers)
        Sets the layers (defined by a list of FileEntriesLayers). This replaces any previously-added layers.
        Parameters:
        layers - the list of FileEntriesLayers
        Returns:
        this

      • setFileEntriesLayers

        public JibContainerBuilder setFileEntriesLayers​(com.google.cloud.tools.jib.api.buildplan.FileEntriesLayer... layers)
        Sets the layers. This replaces any previously-added layers.
        Parameters:
        layers - the FileEntriesLayers
        Returns:
        this

      • setEntrypoint

        public JibContainerBuilder setEntrypoint​(java.lang.String... entrypoint)
        Sets the container entrypoint.
        Parameters:
        entrypoint - the entrypoint command
        Returns:
        this
        See Also:
        setEntrypoint(List)

      • setProgramArguments

        public JibContainerBuilder setProgramArguments​(@Nullable
                                               java.util.List<java.lang.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​(java.lang.String... programArguments)
        Sets the container entrypoint program arguments.
        Parameters:
        programArguments - program arguments tokens
        Returns:
        this
        See Also:
        setProgramArguments(List)

      • setEnvironment

        public JibContainerBuilder setEnvironment​(java.util.Map<java.lang.String,​java.lang.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

      • setVolumes

        public JibContainerBuilder setVolumes​(java.util.Set<com.google.cloud.tools.jib.api.buildplan.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​(com.google.cloud.tools.jib.api.buildplan.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​(com.google.cloud.tools.jib.api.buildplan.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​(java.util.Set<com.google.cloud.tools.jib.api.buildplan.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​(com.google.cloud.tools.jib.api.buildplan.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​(com.google.cloud.tools.jib.api.buildplan.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​(java.util.Map<java.lang.String,​java.lang.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​(java.lang.String key,
                                    java.lang.String value)
        Sets a label for the container.
        Parameters:
        key - the label key
        value - the label value
        Returns:
        this

      • setFormat

        public JibContainerBuilder setFormat​(com.google.cloud.tools.jib.api.buildplan.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​(java.time.Instant creationTime)
        Sets the container image creation time. The default is Instant.EPOCH.
        Parameters:
        creationTime - the container image creation time
        Returns:
        this

      • setPlatforms

        public JibContainerBuilder setPlatforms​(java.util.Set<com.google.cloud.tools.jib.api.buildplan.Platform> platforms)
        Sets a desired platform (properties including OS and architecture) list. If the base image reference is a Docker manifest list or an OCI image index, an image builder may select the base images matching the given platforms. If the base image reference is an image manifest, an image builder may ignore the given platforms and use the platform of the base image or may decide to raise on error.

        Note that a new container builder starts with "amd64/linux" as the default platform.

        Parameters:
        platforms - list of platforms to select base images in case of a manifest list
        Returns:
        this

      • addPlatform

        public JibContainerBuilder addPlatform​(java.lang.String architecture,
                                       java.lang.String os)
        Adds a desired image platform (OS and architecture pair). If the base image reference is a Docker manifest list or an OCI image index, an image builder may select the base image matching the given platform. If the base image reference is an image manifest, an image builder may ignore the given platform and use the platform of the base image or may decide to raise on error.

        Note that a new new container builder starts with "amd64/linux" as the default platform. If you want to reset the default platform instead of adding a new one, use setPlatforms(Set).

        Parameters:
        architecture - architecture (for example, amd64) to select a base image in case of a manifest list
        os - OS (for example, linux) to select a base image in case of a manifest list
        Returns:
        this

      • setUser

        public JibContainerBuilder setUser​(@Nullable
                                   java.lang.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
        • :group
        • :gid
        • user:group
        • uid:gid
        • uid:group
        • user:gid
        Parameters:
        user - the user to run the container as
        Returns:
        this

      • setWorkingDirectory

        public JibContainerBuilder setWorkingDirectory​(@Nullable
                                               com.google.cloud.tools.jib.api.buildplan.AbsoluteUnixPath workingDirectory)
        Sets the working directory in the container.
        Parameters:
        workingDirectory - the working directory
        Returns:
        this

      • containerize

        public JibContainer containerize​(Containerizer containerizer)
                          throws java.lang.InterruptedException,
                                 RegistryException,
                                 java.io.IOException,
                                 CacheDirectoryCreationException,
                                 java.util.concurrent.ExecutionException
        Builds the container.
        Parameters:
        containerizer - the Containerizer that configures how to containerize
        Returns:
        the built container
        Throws:
        java.io.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
        java.net.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
        java.util.concurrent.ExecutionException - if some other exception occurred during execution
        java.lang.InterruptedException - if the execution was interrupted

      • describeContainer

        @Deprecated
public JibContainerDescription describeContainer()
        Deprecated.
        use toContainerBuildPlan().
        Describes the container contents and configuration without actually physically building a container.
        Returns:
        a description of the container being built

      • toContainerBuildPlan

        public com.google.cloud.tools.jib.api.buildplan.ContainerBuildPlan toContainerBuildPlan()
        Internal method. API end users should not use it.

        Converts to ContainerBuildPlan. Note that not all values that this class holds can be described by a build plan, such as CredentialRetrievers for RegistryImage, DockerClient for DockerDaemonImage, and output path for TarImage.

        Returns:
        ContainerBuildPlan