Dockerfile

Table of Contents

1. Description
2. Setup
3. Usage
   • Config
     • Multistage
     • Plain
4. Reference
5. Development
6. Contributors

Description

The Puppet dockerfile module manage content of dockerfile, exposing instructions as key/values while supporting multistage builds. All dockerfile instructions are supported:

• ADD
• ARG
• CMD
• COPY
• ENTRYPOINT
• ENV
• EXPOSE
• FROM
• HEALTHCHECK
• LABEL
• ONBUILD
• RUN
• SHELL
• STOPSIGNAL
• USER
• VOLUME
• WORKDIR

Setup

To install Dockerfile module use puppet module install command:

puppet module install levinine-dockerfile

Usage

Config

In order to provide configuration for dockerfile use the dockerfile::config defined type in the manifest file:

dockerfile::config { 'Dockerfile': 
  ensure => 'present',
  home   => '/var/lib/jenkins/Docker-Build',
  type   => 'multistage',
  conf   => {},
}

Config types

Multistage

Multistage config type Hiera example:

dockerfile::configs:
  Multistage:
    type: multistage
    home: /var/lib/jenkins/Docker-Build
    conf:
      Header:
        comment:
          - Starting comment 1
          - Starting comment 2
      Stage1:
        ensure: present
        comment: Build some docker image
        arg:
          BUILD_NUM: latest
          SOMEARG1: ''
          SOMEARG2: 5
        from:
          platform: linux/amd64
          image: centos:7.6.1810
          as: TEST
        env:
          NUM: $BUILD_NUM
          SOMEENV: test
        label:
          'com.levi9.cluster': cluster
          'com.levi9.role': role
        expose: 80/tcp
        copy:
          from: 0
          source:
            - /tmp with space
            - /test
          destination: /home
        add:
          chown: '0:0'
          source: /tmp
          destination: /home
        volume: test
        cmd:
          - /bin/sh
          - -c
          - top
        entrypoint:
          - /bin/sh
          - -c
          - top
        user: '0:0'
        run:
          - apt-get update
          - apt-get clean
        workdir: /tmp
        stopsignal: signal
        shell:
          - powershell
          - noprofile
        order: '10'
      Stage2:
        ensure: present
        from:
          image: centos:7.6.1810
        env:
          NUM: $BUILD_NUM
          SOMEENV: test
        label:
          'com.levi9.cluster': cluster
          'com.levi9.role': role
        expose: 80/tcp
        copy:
          from: 0
          chown: '0:0'
          source:
            - /tmp
            - /test
          destination: /home
        add:
          chown: '0:0'
          source: /tmp
          destination: /home
        volume: test
        cmd:
          - /bin/sh
          - -c
          - top
        entrypoint:
          - /bin/sh
          - -c
          - top
        user: '0:0'
        run:
          - apt-get update
          - apt-get clean
        workdir: /tmp
        stopsignal: signal
        shell:
          - powershell
          - noprofile
        healthcheck:
          interval: 30s
          timeout: 30s
          start-period: 0s
          retries: 3
          cmd: curl http://localhost
        order: '20'

Multiple COPY/RUN instructions Hiera example:

dockerfile::configs:
  Multistage:
    type: multistage
    home: /var/lib/jenkins/Docker-Build
    conf:
      Stage1:
        from:
          image: centos:7.6.1810
          as: TEST
      Copy1:
        comment: Copy some files
        copy:
          from: TEST
          source:
            - /tmp1
          destination: /home
      Run1:
        ensure: absent
        run:
          - apt-get update
          - apt-get clean
      Copy2:
        onbuild: true
        copy:
          source:
            - /tmp2
          destination: /home
      Stage2:
        comment: Expose some ports
        expose:
          - 80/tcp
          - 8080/tcp

Plain

Plain config type Hiera example:

dockerfile::configs:
  Plain:
    type: plain
    home: /var/lib/jenkins/Docker-Build2
    conf: |
      FROM ubuntu:18.04 as BUILD

      ARG BUILD_NUM="latest"
      ENV PUPPET_AGENT_VERSION="5.5.10" CERTNAME=$BUILD_NUM CODENAME="bionic"

      LABEL BUILD=intermediate

      RUN apt-get update && \
          apt-get install --no-install-recommends -y lsb-release wget ca-certificates && \
          wget https://apt.puppetlabs.com/puppet5-release-"$CODENAME".deb && \
          dpkg -i puppet5-release-"$CODENAME".deb && \
          rm puppet5-release-"$CODENAME".deb && \
          apt-get update && \
          apt-get install --no-install-recommends -y puppet-agent="$PUPPET_AGENT_VERSION"-1"$CODENAME" && \
          apt-get remove --purge -y wget && \
          apt-get autoremove -y && \
          apt-get clean && \
          mkdir -p /etc/puppetlabs/facter/facts.d/ && \
          rm -rf /var/lib/apt/lists/*

      RUN apt-get update && \
          /opt/puppetlabs/bin/puppet agent --verbose --onetime --no-daemonize --summarize && \
          apt-get autoremove -y && \
          apt-get clean && \
          rm -rf /var/lib/apt/lists/*

      FROM ubuntu:18.04

      COPY --from=BUILD /tmp/mydir/myfile .

Reference

See Reference.

Limitations

This module depends on Puppetlabs Concat module, it should be working on all operating systems supported by this module.

Development

Use Report Issues link to report any issues.

Contributors

• Mladen Pavlik
• Dragan Nastic
• Karolj Kocmaros
• Marko Stojanovic

Reference

Table of Contents

Classes

• dockerfile: Manage content of Dockerfiles.

Defined types

• dockerfile::config: A define that manages a Dockerfile configuration.
• dockerfile::config::multistage: Manage Dockerfile using concat resource. Supports multistages.
• dockerfile::config::plain: Heredoc passthrough from $conf variable to Dockerfile.
• dockerfile::config::stage: Single stage configuration for docker::config::multistage. Private defined type.

Functions

• order_dockerfile_stages: Increments order attribute in each stage by increment of 10 starting from '10' if not already defined. Stages are prefixed with prefix in ord

Classes

dockerfile

Manage content of Dockerfiles.

Parameters

The following parameters are available in the dockerfile class.

configs

Data type: Any

Configurations for Dockerfiles. Creates dockerfile::config resources.

Default value: {}

Defined types

dockerfile::config

A define that manages a Dockerfile configuration.

Parameters

The following parameters are available in the dockerfile::config defined type.

home

Data type: String

Directory in which Dockerfile is located.

dockerfile_name

Data type: String

The name of the managed dockerfile

Default value: 'Dockerfile'

conf

Data type: Variant[String, Hash]

Configuration for Dockerfile. Depends on type.

Default value: {}

type

Data type: String

Type of Dockerfile configuration.

Default value: 'multistage'

ensure

Data type: String

Manage existance of Dockerfile.

Default value: 'present'

owner

Data type: Optional[Variant[String, Integer]]

Specifies the owner of the destination file.

Default value: undef

group

Data type: Optional[Variant[String, Integer]]

Specifies a permissions group for the destination file.

Default value: undef

mode

Data type: Optional[Variant[String, Integer]]

Specifies the permissions mode of the destination file.

Default value: undef

dockerfile::config::multistage

Manage Dockerfile using concat resource. Supports multistages.

Parameters

The following parameters are available in the dockerfile::config::multistage defined type.

dockerfile

Data type: String

Full path to Dockerfile to manage.

conf

Data type: Hash

Configuration in key/value form. Keys are mapped to names of dockerfile::config::stage resources.

ensure

Data type: String

Manage existance of Dockerfile.

Default value: 'present'

owner

Data type: Optional[Variant[String, Integer]]

Specifies the owner of the destination file.

Default value: undef

group

Data type: Optional[Variant[String, Integer]]

Specifies a permissions group for the destination file.

Default value: undef

mode

Data type: Optional[Variant[String, Integer]]

Specifies the permissions mode of the destination file.

Default value: undef

dockerfile::config::plain

Heredoc passthrough from $conf variable to Dockerfile.

Parameters

The following parameters are available in the dockerfile::config::plain defined type.

dockerfile

Data type: String

Full path to Dockerfile to manage.

conf

Data type: String

Configuration in text form.

ensure

Data type: String

Manage existance of Dockerfile.

Default value: 'present'

owner

Data type: Optional[Variant[String, Integer]]

Specifies the owner of the destination file.

Default value: undef

group

Data type: Optional[Variant[String, Integer]]

Specifies a permissions group for the destination file.

Default value: undef

mode

Data type: Optional[Variant[String, Integer]]

Specifies the permissions mode of the destination file.

Default value: undef

dockerfile::config::stage

Single stage configuration for docker::config::multistage. Private defined type.

• See also https://docs.docker.com/engine/reference/builder/

Parameters

The following parameters are available in the dockerfile::config::stage defined type.

dockerfile

Data type: String

Target of concat::fragment.

ensure

Data type: String

Should stage exist in Dockerfile.

Default value: 'present'

comment

Data type: Variant[Array[String], String, Undef]

Use to add comment to stage.

Default value: undef

arg

Data type: Variant[Hash, Undef]

ARG instruction of Dockerfile.

Default value: undef

from

Data type: Variant[Hash, Undef]

FROM instruction of Dockerfile.

Default value: undef

copy

Data type: Variant[Hash, Undef]

COPY instruction of Dockerfile.

Default value: undef

add

Data type: Variant[Hash, Undef]

ADD instruction of Dockerfile.

Default value: undef

env

Data type: Variant[Hash, Undef]

ENV instruction of Dockerfile.

Default value: undef

expose

Data type: Variant[Array[Variant[String, Integer]], String, Integer, Undef]

EXPOSE instruction of Dockerfile.

Default value: undef

label

Data type: Variant[Hash, Undef]

LABEL instruction of Dockerfile.

Default value: undef

stopsignal

Data type: Variant[String, Undef]

STOPSIGNAL instruction of Dockerfile.

Default value: undef

user

Data type: Variant[String, Undef]

USER instruction of Dockerfile.

Default value: undef

volume

Data type: Variant[Array, String, Undef]

VOLUME instruction of Dockerfile.

Default value: undef

workdir

Data type: Variant[String, Undef]

WORKDIR instruction of Dockerfile.

Default value: undef

healthcheck

Data type: Variant[String, Hash, Undef]

HEALTHCHECK instruction of Dockerfile.

Default value: undef

cmd

Data type: Variant[Array, Undef]

CMD instruction of Dockerfile.

Default value: undef

entrypoint

Data type: Variant[Array, Undef]

ENTRYPOINT instruction of Dockerfile.

Default value: undef

shell

Data type: Variant[Array, Undef]

SHELL instruction of Dockerfile.

Default value: undef

run

Data type: Variant[Array, String, Undef]

RUN instruction of Dockerfile.

Default value: undef

onbuild

Data type: Boolean

All instructions in this stage will be prefixed with ONBUILD.

Default value: false

pre

Data type: Hash

Default value: {}

post

Data type: Hash

Default value: {}

order

Data type: Variant[String, Undef]

Default value: undef

Functions

order_dockerfile_stages

Type: Ruby 4.x API

Increments order attribute in each stage by increment of 10 starting from '10' if not already defined. Stages are prefixed with prefix in order to avoid duplicate declarations.

Examples

Calling the function

order_dockerfile_stages({
  Stage1 => {},
  Stage2 => {},
  Stage3 => {
    order => '15'
    }
  },
  'prefix-'
)
will return
{
  prefix-Stage1 => {
    order => '10'
  },
  prefix-Stage2 => {
    order => '20'
  },
  prefix-Stage3 => {
    order => '15'
  }
}

order_dockerfile_stages(Hash $hash, String $prefix)

Increments order attribute in each stage by increment of 10 starting from '10' if not already defined. Stages are prefixed with prefix in order to avoid duplicate declarations.

Returns: Hash Transformed hash with added order attributes and prefixed keys

Examples

Calling the function

order_dockerfile_stages({
  Stage1 => {},
  Stage2 => {},
  Stage3 => {
    order => '15'
    }
  },
  'prefix-'
)
will return
{
  prefix-Stage1 => {
    order => '10'
  },
  prefix-Stage2 => {
    order => '20'
  },
  prefix-Stage3 => {
    order => '15'
  }
}

hash

Data type: Hash

Multistage hash for ordering.

prefix

Data type: String

Prefix for hash keys.

Version 2.0.0

Implemented acceptance tests with litmus

Removed warnings when using empty function

Version 1.6.0

Added support for comments in stages

Version 1.5.1

Added support for platform flag in FROM instruction

Version 1.5.0

Added support for ONBUILD instruction

Version 1.4.1

EXPOSE parameter now accepts array

Version 1.4.0

Supported chown option in COPY instruction

Removed dependency on stdlib

Version 1.3.1

Make stages ensurable

Version 1.3.0

Manage permissions of Dockerfile

Version 1.2.1

Updated documentation

Version 1.2.0

Implemented persistent ordering for multistages

Version 1.1.0

Added creating of resources from init.pp

Version 1.0.0

Initial Version