Top

incubator.api module

Python API for building docker images in better and more secure way.

"""
Python API for building docker images in better and more secure way.
"""

import logging

from .core import utils
from .core.build import Builder
from .core.caching import ImageCache
from .core.client import DockerClient
from .core.config import ImageConfig
from .core.constants import APP_NAME
from .core.context import BuildContext
from .core.output import ERROR_SUBTITLE
from .core.utilclasses import Volume

_logger = logging.getLogger(APP_NAME)


def build(path=None, fileobj=None, tag=None,
          custom_context=False, pull=False, rm=False,
          forcerm=False, dockerfile=None, buildargs=None,
          container_limits=None, volumes=None, layers=None,
          labels=None, config=None, context_file_limit=None,
          container_client=None, cache=None):
    """
    Build a container image from provided build context and Dockerfile.

    * path: (str) path to the directory containing *Dockerfile*
    * fileobj: a file object to use as *Dockerfile* (or a file-like
                object, e.g. `BytesIO`)
    * tag: (str) tag to add to the final image
    * custom_context: (bool) optional if using `fileobj`
    * pull: (bool) downloads any updates to the `FROM` image in *Dockerfile*
    * rm: (bool) remove intermediate containers
                The `docker build` command now defaults to `--rm=true`,
                but we have kept the old
                default of `False` to preserve backward compatibility.
    * forcerm: (bool) always remove intermediate containers,
                even after unsuccessful build
    * dockerfile: (str) path within the build context to the *Dockerfile*
    * buildargs:  (dict) dictionary of build arguments
    * container_limits: (dict) A dictionary of limits applied to each
                    container created by the build process.
                    Valid keys:
        - memory (int): set memory limit for build
        - memswap (int): total memory (memory + swap), -1 to disable swap
        - cpushares (int): CPU shares (relative weight)
        - cpusetcpus (str): CPUs in which to allow execution, e.g., `0-3`, `0,1`
    * labels: (dict) dictionary of labels to set on the image
    * volumes: (list) list of bind volumes (str or `Volume` instance)
    * layers: (list) list of layer splits
    * config: (dict or list of dicts) dictionary of addition configuration
    * context_file_limit: (int) maximum size of in memory config (0 is unlimited and default)
    * cache: object responsible for caching images
    * container_client: client representing basic container API

    * **return:** `ResultImage` instance
    """

    try:
        container_client = container_client or DockerClient()
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot launch container client:\n{}".format(ex)))
        raise ex

    cache = cache or ImageCache()

    try:
        config_object = ImageConfig.merge_configs(config)
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot merge config files:\n{}".format(ex)))
        raise ex

    try:
        config_object.update(buildargs=buildargs,
                             container_limits=container_limits,
                             context_file_limit=context_file_limit,
                             forcerm=forcerm,
                             labels=labels,
                             layers=layers,
                             pull=pull,
                             rm=rm,
                             tags=tag,
                             volumes=Volume.get_instances(volumes))
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot update config with arguments:\n{}".format(ex)))
        raise ex

    try:
        context_fileobj, dockerfile_fileobj = utils.mkbuildcontext(path=path,
                                                                   fileobj=fileobj,
                                                                   custom_context=custom_context,
                                                                   dockerfile=dockerfile,
                                                                   client=container_client,
                                                                   limit=config_object.context_file_limit)
        build_context = BuildContext(context=context_fileobj, limit=context_file_limit)

    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot make build context:\n{}".format(ex)))
        raise ex

    try:
        builder = Builder(context=build_context,
                          dockerfile=dockerfile_fileobj,
                          client=container_client,
                          config=config_object,
                          cache=cache)
        return builder.build()
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Build failed:\n{}".format(ex)))
        raise ex

Module variables

var APP_NAME

var ERROR_SUBTITLE

Functions

def build(

path=None, fileobj=None, tag=None, custom_context=False, pull=False, rm=False, forcerm=False, dockerfile=None, buildargs=None, container_limits=None, volumes=None, layers=None, labels=None, config=None, context_file_limit=None, container_client=None, cache=None)

Build a container image from provided build context and Dockerfile.

  • path: (str) path to the directory containing Dockerfile
  • fileobj: a file object to use as Dockerfile (or a file-like object, e.g. BytesIO)
  • tag: (str) tag to add to the final image
  • custom_context: (bool) optional if using fileobj
  • pull: (bool) downloads any updates to the FROM image in Dockerfile
  • rm: (bool) remove intermediate containers The docker build command now defaults to --rm=true, but we have kept the old default of False to preserve backward compatibility.
  • forcerm: (bool) always remove intermediate containers, even after unsuccessful build
  • dockerfile: (str) path within the build context to the Dockerfile
  • buildargs: (dict) dictionary of build arguments
  • container_limits: (dict) A dictionary of limits applied to each container created by the build process. Valid keys:
    • memory (int): set memory limit for build
    • memswap (int): total memory (memory + swap), -1 to disable swap
    • cpushares (int): CPU shares (relative weight)
    • cpusetcpus (str): CPUs in which to allow execution, e.g., 0-3, 0,1
  • labels: (dict) dictionary of labels to set on the image
  • volumes: (list) list of bind volumes (str or Volume instance)
  • layers: (list) list of layer splits
  • config: (dict or list of dicts) dictionary of addition configuration
  • context_file_limit: (int) maximum size of in memory config (0 is unlimited and default)
  • cache: object responsible for caching images
  • container_client: client representing basic container API

  • return: ResultImage instance

def build(path=None, fileobj=None, tag=None,
          custom_context=False, pull=False, rm=False,
          forcerm=False, dockerfile=None, buildargs=None,
          container_limits=None, volumes=None, layers=None,
          labels=None, config=None, context_file_limit=None,
          container_client=None, cache=None):
    """
    Build a container image from provided build context and Dockerfile.

    * path: (str) path to the directory containing *Dockerfile*
    * fileobj: a file object to use as *Dockerfile* (or a file-like
                object, e.g. `BytesIO`)
    * tag: (str) tag to add to the final image
    * custom_context: (bool) optional if using `fileobj`
    * pull: (bool) downloads any updates to the `FROM` image in *Dockerfile*
    * rm: (bool) remove intermediate containers
                The `docker build` command now defaults to `--rm=true`,
                but we have kept the old
                default of `False` to preserve backward compatibility.
    * forcerm: (bool) always remove intermediate containers,
                even after unsuccessful build
    * dockerfile: (str) path within the build context to the *Dockerfile*
    * buildargs:  (dict) dictionary of build arguments
    * container_limits: (dict) A dictionary of limits applied to each
                    container created by the build process.
                    Valid keys:
        - memory (int): set memory limit for build
        - memswap (int): total memory (memory + swap), -1 to disable swap
        - cpushares (int): CPU shares (relative weight)
        - cpusetcpus (str): CPUs in which to allow execution, e.g., `0-3`, `0,1`
    * labels: (dict) dictionary of labels to set on the image
    * volumes: (list) list of bind volumes (str or `Volume` instance)
    * layers: (list) list of layer splits
    * config: (dict or list of dicts) dictionary of addition configuration
    * context_file_limit: (int) maximum size of in memory config (0 is unlimited and default)
    * cache: object responsible for caching images
    * container_client: client representing basic container API

    * **return:** `ResultImage` instance
    """

    try:
        container_client = container_client or DockerClient()
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot launch container client:\n{}".format(ex)))
        raise ex

    cache = cache or ImageCache()

    try:
        config_object = ImageConfig.merge_configs(config)
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot merge config files:\n{}".format(ex)))
        raise ex

    try:
        config_object.update(buildargs=buildargs,
                             container_limits=container_limits,
                             context_file_limit=context_file_limit,
                             forcerm=forcerm,
                             labels=labels,
                             layers=layers,
                             pull=pull,
                             rm=rm,
                             tags=tag,
                             volumes=Volume.get_instances(volumes))
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot update config with arguments:\n{}".format(ex)))
        raise ex

    try:
        context_fileobj, dockerfile_fileobj = utils.mkbuildcontext(path=path,
                                                                   fileobj=fileobj,
                                                                   custom_context=custom_context,
                                                                   dockerfile=dockerfile,
                                                                   client=container_client,
                                                                   limit=config_object.context_file_limit)
        build_context = BuildContext(context=context_fileobj, limit=context_file_limit)

    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Cannot make build context:\n{}".format(ex)))
        raise ex

    try:
        builder = Builder(context=build_context,
                          dockerfile=dockerfile_fileobj,
                          client=container_client,
                          config=config_object,
                          cache=cache)
        return builder.build()
    except Exception as ex:
        _logger.warning(ERROR_SUBTITLE.format("Build failed:\n{}".format(ex)))
        raise ex