Module gcip.addons.container.jobs.docker

This modules provide Jobs executing Docker CLI scripts

Those require Docker to be installed on the Gitlab runner.

Classes

class Build (*, repository: str, tag: Optional[str] = None, context: str = '.', jobName: dataclasses.InitVar[str] = 'docker', jobStage: dataclasses.InitVar[str] = 'build')

Runs docker build

Example:

from gcip.addons.container.job.docker import Build
build_job = Build(BuildOpts(repository="myrepo/myimage", tag="v0.1.0"))

This subclass of Job will configure following defaults for the superclass:

• name: docker
• stage: build

Args

repository : str

The Docker repository name ([<registry>/]<image>).

tag : Optional[str]

A Docker image tag applied to the image. Defaults to None which no tag is provided to the docker build command. Docker should then apply the default tag latest.

context : str

The Docker build context (the directory containing the Dockerfile). Defaults to the current directory ..

Expand source code

@dataclass(kw_only=True)
class Build(Job):
    """Runs [```docker build```](https://docs.docker.com/engine/reference/commandline/build/)

    Example:

    ```
    from gcip.addons.container.job.docker import Build
    build_job = Build(BuildOpts(repository="myrepo/myimage", tag="v0.1.0"))
    ```

    This subclass of `Job` will configure following defaults for the superclass:

    * name: docker
    * stage: build

    Args:
        repository (str): The Docker repository name ```([<registry>/]<image>)```.
        tag (Optional[str]): A Docker image tag applied to the image. Defaults to `None` which no tag is provided
            to the docker build command. Docker should then apply the default tag ```latest```.
        context (str): The Docker build context (the directory containing the Dockerfile). Defaults to
            the current directory `.`.
    """

    repository: str
    tag: Optional[str] = None
    context: str = "."
    jobName: InitVar[str] = "docker"
    jobStage: InitVar[str] = "build"

    def __post_init__(self, jobName: str, jobStage: str) -> None:
        super().__init__(script="", name=jobName, stage=jobStage)
        self.add_variables(DOCKER_DRIVER="overlay2", DOCKER_TLS_CERTDIR="")

    def render(self) -> Dict[str, Any]:
        fq_image_name = self.repository
        if self.tag:
            fq_image_name += f":{self.tag}"

        self._scripts = [f"docker build -t {fq_image_name} {self.context}"]
        return super().render()

Ancestors

• Job

Class variables

var context : str

var jobName : dataclasses.InitVar[str]

var jobStage : dataclasses.InitVar[str]

var repository : str

var tag : Optional[str]

Inherited members

• Job:
  • add_dependencies
  • add_needs
  • add_tags
  • add_variables
  • allow_failure
  • append_rules
  • append_scripts
  • artifacts
  • cache
  • dependencies
  • environment
  • image
  • name
  • needs
  • prepend_rules
  • prepend_scripts
  • render
  • resource_group
  • retry
  • rules
  • scripts
  • set_allow_failure
  • set_artifacts
  • set_cache
  • set_dependencies
  • set_environment
  • set_image
  • set_needs
  • set_resource_group
  • set_retry
  • set_tags
  • set_timeout
  • set_when
  • stage
  • tags
  • timeout
  • variables
  • when

class Push (*, container_image: str, registry: Optional[str] = None, tag: Optional[str] = None, user_env_var: Optional[str] = None, login_env_var: Optional[str] = None, jobName: dataclasses.InitVar[str] = 'docker', jobStage: dataclasses.InitVar[str] = 'deploy')

Runs docker push and optionally docker login before.

Example:

from gcip.addons.container.docker import Push
push_job = Push(PushOpts(
                registry="docker.pkg.github.com/dbsystel/gitlab-ci-python-library",
                image="gcip",
                tag="v0.1.0",
                user_env_var="DOCKER_USER",
                login_env_var="DOCKER_TOKEN"
            ))

The user_env_var and login_env_var should be created as protected and masked custom environment variable configured in the UI.

This subclass of Job will configure following defaults for the superclass:

• name: docker
• stage: deploy

Args

registry : Optional[str]

The Docker registry the image should be pushed to. Defaults to None which targets to the official Docker Registry at hub.docker.com.

image : str

The name of the Docker image to push to the registry.

tag : Optional[str]

The Docker image tag that should be pushed to the registry. Defaults to latest.

user_env_var : Optional[str]

If you have to login to the registry before the push, you have to provide the name of the environment variable, which contains the username value, here. DO NOT PROVIDE THE USERNAME VALUE ITSELF! This would be a security issue! Defaults to None which skips the docker login attempt.

login_env_var : Optional[str]

If you have to login to the registry before the push, you have to provide the name of the environment variable, which contains the password or token, here. DO NOT PROVIDE THE LOGIN VALUE ITSELF! This would be a security issue! Defaults to None which skips the docker login attempt.

Expand source code

@dataclass(kw_only=True)
class Push(Job):
    """Runs [```docker push```](https://docs.docker.com/engine/reference/commandline/push/)
    and optionally [```docker login```](https://docs.docker.com/engine/reference/commandline/login/) before.

    Example:

    ```python
    from gcip.addons.container.docker import Push
    push_job = Push(PushOpts(
                    registry="docker.pkg.github.com/dbsystel/gitlab-ci-python-library",
                    image="gcip",
                    tag="v0.1.0",
                    user_env_var="DOCKER_USER",
                    login_env_var="DOCKER_TOKEN"
                ))
    ```

    The `user_env_var` and `login_env_var` should be created as *protected* and *masked*
    [custom environment variable configured
    in the UI](https://git.tech.rz.db.de/help/ci/variables/README#create-a-custom-variable-in-the-ui).

    This subclass of `Job` will configure following defaults for the superclass:

    * name: docker
    * stage: deploy

    Args:
        registry (Optional[str]): The Docker registry the image should be pushed to.
            Defaults to `None` which targets to the official Docker Registry at hub.docker.com.
        image (str): The name of the Docker image to push to the `registry`.
        tag (Optional[str]): The Docker image tag that should be pushed to the `registry`. Defaults to ```latest```.
        user_env_var (Optional[str]): If you have to login to the registry before the push, you have to provide
            the name of the environment variable, which contains the username value, here.
            **DO NOT PROVIDE THE USERNAME VALUE ITSELF!** This would be a security issue!
            Defaults to `None` which skips the docker login attempt.
        login_env_var (Optional[str]): If you have to login to the registry before the push, you have to provide
            the name of the environment variable, which contains the password or token, here.
            **DO NOT PROVIDE THE LOGIN VALUE ITSELF!** This would be a security issue!
            Defaults to `None` which skips the docker login attempt.
    """

    container_image: str
    registry: Optional[str] = None
    tag: Optional[str] = None
    user_env_var: Optional[str] = None
    login_env_var: Optional[str] = None
    jobName: InitVar[str] = "docker"
    jobStage: InitVar[str] = "deploy"

    def __post_init__(self, jobName: str, jobStage: str) -> None:
        super().__init__(script="", name=jobName, stage=jobStage)

    def render(self) -> Dict[str, Any]:
        self._scripts = []
        if self.user_env_var and self.login_env_var:
            self._scripts.append(
                f'docker login -u "${self.user_env_var}" -p "${self.login_env_var}"'
            )

        fq_image_name = self.container_image
        if self.registry:
            fq_image_name = f"{self.registry}/{fq_image_name}"
        if self.tag:
            fq_image_name += f":{self.tag}"

        self._scripts.append(f"docker push {fq_image_name}")
        return super().render()

Ancestors

• Job

Class variables

var container_image : str

var jobName : dataclasses.InitVar[str]

var jobStage : dataclasses.InitVar[str]

var login_env_var : Optional[str]

var registry : Optional[str]

var tag : Optional[str]

var user_env_var : Optional[str]

Inherited members

• Job:
  • add_dependencies
  • add_needs
  • add_tags
  • add_variables
  • allow_failure
  • append_rules
  • append_scripts
  • artifacts
  • cache
  • dependencies
  • environment
  • image
  • name
  • needs
  • prepend_rules
  • prepend_scripts
  • render
  • resource_group
  • retry
  • rules
  • scripts
  • set_allow_failure
  • set_artifacts
  • set_cache
  • set_dependencies
  • set_environment
  • set_image
  • set_needs
  • set_resource_group
  • set_retry
  • set_tags
  • set_timeout
  • set_when
  • stage
  • tags
  • timeout
  • variables
  • when