{"id":15103540,"url":"https://github.com/puppetlabs-toy-chest/puppetlabs-image_build","last_synced_at":"2025-09-27T02:31:33.914Z","repository":{"id":43609180,"uuid":"63430864","full_name":"puppetlabs-toy-chest/puppetlabs-image_build","owner":"puppetlabs-toy-chest","description":"Build Docker images from Puppet code","archived":true,"fork":false,"pushed_at":"2019-01-18T15:33:30.000Z","size":164,"stargazers_count":66,"open_issues_count":11,"forks_count":31,"subscribers_count":108,"default_branch":"master","last_synced_at":"2025-09-01T19:56:42.194Z","etag":null,"topics":["aci","docker","puppet","rocker"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puppetlabs-toy-chest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-15T15:10:08.000Z","updated_at":"2024-11-28T16:32:48.000Z","dependencies_parsed_at":"2022-07-12T18:19:13.239Z","dependency_job_id":null,"html_url":"https://github.com/puppetlabs-toy-chest/puppetlabs-image_build","commit_stats":null,"previous_names":["puppetlabs/puppetlabs-image_build"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/puppetlabs-toy-chest/puppetlabs-image_build","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-image_build","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-image_build/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-image_build/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-image_build/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puppetlabs-toy-chest","download_url":"https://codeload.github.com/puppetlabs-toy-chest/puppetlabs-image_build/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puppetlabs-toy-chest%2Fpuppetlabs-image_build/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277171507,"owners_count":25773232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-27T02:00:08.978Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aci","docker","puppet","rocker"],"created_at":"2024-09-25T19:40:20.997Z","updated_at":"2025-09-27T02:31:33.503Z","avatar_url":"https://github.com/puppetlabs-toy-chest.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# image_build\n\n[![Puppet\nForge](https://img.shields.io/puppetforge/v/puppetlabs/image_build.svg)](https://forge.puppetlabs.com/puppetlabs/image_build)\n[![Build\nStatus](https://secure.travis-ci.org/puppetlabs/puppetlabs-image_build.png)](https://travis-ci.org/puppetlabs/puppetlabs-image_build)\n[![Coverage\nStatus](https://coveralls.io/repos/github/puppetlabs/puppetlabs-image_build/badge.svg?branch=master)](https://coveralls.io/github/puppetlabs/puppetlabs-image_build?branch=master)\n\n[Module description]: #module-description\n[Setup]: #setup\n[Usage]: #usage\n[Reference]: #reference\n[A hello world example]: #a-hello-world-example---nginx\n[Involving hiera]: #involving-hiera---elasticsearch\n[Building multiple images from one manifest]: #building-multiple-images-from-one-manifest\n[Using a Puppet Master]: #using-a-puppet-master\n[Minimizing image size with Rocker]: #minimizing-image-size-with-rocker\n[Building ACI images]: #building-aci-images\n[Limitations]: #limitations\n[Maintainers]: #maintainers\n\n#### Table of Contents\n\n1. [Module description - What is the image_build module, and what does it\n   do?][Module description]\n2. [Setup - The basics of getting started with image_build][Setup]\n3. [Usage - How to build Docker containers with Puppet][Usage]\n    - [A hello world example][A hello world example]\n    - [Involving hiera][Involving hiera]\n    - [Building multiple images from one manifest][Building multiple images from one manifest]\n    - [Using a Puppet Master][using a Puppet Master]\n    - [Minimizing image size with Rocker][Minimizing image size with Rocker]\n    - [Building ACI images][Building ACI images]\n4. [Reference - Sample help output from the tool][Reference]\n5. [Limitations - OS compatibility, etc.][Limitations]\n6. [Maintainers - who maintains this project][Maintainers]\n\n\n## Module description\n\nThe basic purpose of `image_build` is to enable building various images,\nincluding Docker images, from Puppet code. There are two main cases\nwhere this can be useful:\n\n1. You have an existing Puppet codebase and you're moving some of your\n   services to using containers. By sharing the same code between\n   container and non-container based infrastructure you can cut down on\n   duplication of effort, and take advantage of work you've already\n   done.\n2. You're building a lot of images, but scaling Dockerfile means either\n   a complex hierachy of images or copy-and-pasting snippets between\n   many individual Dockerfiles. `image_build` allows for sharing common\n   functionality as Puppet modules, and Puppet itself provides a rich\n   domain-specific language for declarative composition of images.\n\n\n## Setup\n\n`puppetlabs/image_build` is a Puppet Module and is available on the Forge.\n\nThe following should work in most cases:\n\n```\npuppet module install puppetlabs/image_build\n```\n\nYou don't need any additional gems installed unless you are looking to\nwork on developing the module. All you need is a working Docker environment or\n`acbuild`, for which I'd recommend Docker for Mac or Docker for Windows\nor just installing Docker if you're on Linux. For acbuild you can use\nthe [rkt module](https://forge.puppet.com/puppetlabs/rkt).\n\n## Usage\n\nWith the module installed you should have access to two new puppet\ncommands; `puppet docker` and `puppet aci`. These have two subcommands,\none will trigger a build of an image, the other can be used to output\nthe intermediary dockerfile or shell script.\n\nThe examples directory contains a set of examples for experimenting with.\nSimply open up `examples/nginx` and run:\n\n    puppet docker build\n\nThe above is the simplest example of a build. Some settings are provided\nin the accompanying `metadata.yaml` file, while others are defaults\nspecific to the tool. You can change values in the metadata file (useful\nfor version control) or you can override those values on the command\nline.\n\n    puppet docker build --image-name puppet/sample --cmd nginx --expose 80\n\nSee the full help page for other arguments for specifying different\nbase images, setting a maintainer, using Rocker instead of Docker for the\nbuild and much more.\n\n    puppet docker build --help\n\nYou can also output the intermediary dockerfile using another\nsubcommand. This is useful for both debugging and if you want to do\nsomething not natively supported by the tool.\n\n    puppet docker dockerfile\n\n\n### A hello world example - Nginx\n\nLets see a simple hello world example. We'll create a Docker image\nrunning Nginx and serving a simple text file.\n\nFirst lets use a few Puppet modules from the Forge. We'll use the\nexisting [nginx module](https://forge.puppet.com/puppet/nginx) and\nwe'll specify it's dependencies. We're also using\n[dummy_service](https://forge.puppet.com/puppetlabs/dummy_service) to\nignore service resources in the Nginx module.\n\n```\n$ cat Puppetfile\nforge 'https://forgeapi.puppetlabs.com'\n\nmod 'puppet/nginx'\nmod 'puppetlabs/stdlib'\nmod 'puppetlabs/concat'\nmod 'puppetlabs/apt'\nmod 'puppetlabs/dummy_service'\n```\n\nThen lets write a simple manifest. Disabling nginx daemon mode isn't\nsupported by the module yet so we drop a file in place. Have a look at\n`manifests/init.pp`:\n\n```puppet\ninclude 'dummy_service'\n\nclass { 'nginx': }\n\nnginx::resource::vhost { 'default':\n  www_root =\u003e '/var/www/html',\n}\n\nfile { '/var/www/html/index.html':\n  ensure  =\u003e present,\n  content =\u003e 'Hello Puppet and Docker',\n}\n\nexec { 'Disable Nginx daemon mode':\n  path    =\u003e '/bin',\n  command =\u003e 'echo \"daemon off;\" \u003e\u003e /etc/nginx/nginx.conf',\n  unless  =\u003e 'grep \"daemon off\" /etc/nginx/nginx.conf',\n}\n```\n\nAnd finally lets store the metadata in a file rather than pass on the\ncommand line. Take a look at `metadata.yaml`:\n\n```yaml\ncmd: nginx\nexpose: 80\nimage_name: puppet/nginx\n```\n\nNow lets build a Docker image. Note that you'll need docker available on\nyour host to do so, along with the `image_build` module installed.\n\n```\npuppet docker build\n```\n\nAnd finally lets run our new image. We expose the webserver on port 8080\nto the local host.\n\n```\n$ docker run -d -p 8080:80 puppet/nginx\n83d5fbe370e84d424c71c1c038ad1f5892fec579d28b9905cd1e379f9b89e36d\n$ curl http://0.0.0.0:8080\nHello Puppet and Docker%\n```\n\n### Involving hiera - Elasticsearch\n\nThe Elasticsearch example is similar to the above, with a few additional\nfeatures demonstrated. In particular the use of Hiera to provide\nadditional context for the Puppet build. You can find this in the\n`examples/elasticsearch` directory.\n\n```\npuppet docker build manifests/init.pp --image-name puppet/es --expose 9200 --cmd /docker-entrypoint.sh\n```\n\n### A note on options with multiple arguments\n\nSeveral of the arguments to `image_build` can take a list of values.\nThis is done by passing in comma separated values. For instance, to\nspecify an `ENTRYPOINT` like so:\n\n```\nENTRYPOINT [\"nginx\", \"-g\", \"daemon off\"]\n```\n\nYou can pass the following on the commandline:\n\n```\n--entrypoint nginx,'-g','daemon off'\n```\n\n### Building multiple images from one manifest\n\nOne advantage of using Puppet for building Docker images is you are\nremoved from the need to have a single Dockerfile per image. Meaning a\nsingle repository of Puppet code can be used to describe multiple\nimages. This makes ensuring all images use (for example) the same\nrepositories or same hardening scripts much easier to enforce. Change\ncode in one place and rebuild multiple images.\n\nDescribing multiple images in Puppet is done using the existing `node`\nresource in your manifest. For instance:\n\n```puppet\nnode 'node1' {\n  webserver { 'hello node 1': }\n}\n\nnode 'node2' {\n  webserver { 'hello node 2': }\n}\n```\n\nYou can then select which image to build when running the build command,\nby explicitly passing the `image-name`.\n\n    puppet docker build --image-name puppet/node1\n\nThe match for the node resource in the Puppet code is done without the\nrepository name, in this case the `puppet/` before `node1`.\n\nNote that you may want different metadata for different images.\n`image_build` will attempt to detect additional metadata in the\n`metadata` folder, and will merge items from `metadata/metadata.yaml`\nwith node specific metadata, for instance from `metadata/node1.yaml`\n\nYou can see an example of this settup in the `examples/multi` directory.\n\n\n### Using a Puppet Master\n\nThe above examples all use local manifests copied to the image during\nbuild, but `image_build` also supports using a Puppet Master. You can\nprovide metadata via a local metadata file or directory, or by passing\ncommand line arguments to the build command as shown in the examples\nabove. The only change is passing `--master` like so.\n\n    puppet docker dockerfile --master puppet.example.com --image-name puppet/node1 --expose 80 --cmd nginx\n\nThe hostname passed to the Puppet Master will take the form\nnode1.{datetime}.dockerbuilder. This means you can match on that pattern\nin your manifests, for instance like so:\n\n```puppet\nnode /^node1/ {\n  webserver { 'hello node 1': }\n}\n```\n\nA worked example is provided in the `examples/master` folder. You can\neither upload this to an existing Puppet Master or Puppet Enterprise\ninstall, or run a new local master using Docker.\n\nFirst install the dependent modules into the local environment:\n\n    r10k puppetfile install --moduledir code/environments/production/modules\n\nCreate an `autosign.conf` file with the following:\n\n```\n*.dockerbuilder.*\n```\n\nThen, from the `examples/master` folder, use Docker to run an instance\nof Puppet Server:\n\n    docker run --name puppet -P --hostname puppet -v $(pwd)/code:/etc/puppetlabs/code -v $(pwd)/autosign.conf:/etc/puppetlabs/puppet/autosign.conf puppet/puppetserver-standalone\n\nDetermine the port on which the Puppet Server is exposed locally:\n\n    docker port puppet\n\nYou'll also need the IP address of your local machine. Replace the {ip}\nand {port} in the following with your own values.\n\n    puppet docker dockerfile --master {ip}:{port} --image-name puppet/node1 --expose 80 --cmd nginx\n\nThis should use the code on the Puppet Master to build the image.\n\n\n### Minimizing image size with Rocker\n\n`image_build` supports using the\n[Rocker](https://github.com/grammarly/rocker) build tool in place of the\nstandard Docker build command. The Rocker output provides a little more\ndetail about the build process, but also allows for mounting of folders\nat build time which minimizes the size of the resulting image.\n\n    puppet docker build --rocker\n\nNote that when using Rocker the Puppet tools are not left in the final\nimage, reducing it's file size.\n\n\n### Building ACI images\n\nAs well as Docker support, `image_build` also experimentally supports building\n[ACI](https://github.com/appc/spec/blob/master/spec/aci.md) compatible\nimages for use with Rkt or other supported runtimes. This works in the\nsame manner as above. The following command should generate a shell\nscript which, when run, generates an ACI:\n\n    puppet aci script\n\nAnd if you simply want to build the ACI directly you can just run:\n\n    puppet aci build\n\n\n## Reference\n\n```\n$ puppet docker --help\nUSAGE: puppet docker \u003caction\u003e [--from STRING]\n[--maintainer STRING]\n[--os STRING]\n[--os-version STRING]\n[--puppet-agent-version STRING]\n[--r10k-version STRING]\n[--module-path PATH]\n[--expose STRING]\n[--cmd STRING]\n[--entrypoint STRING]\n[--labels KEY=VALUE]\n[--rocker]\n[--[no-]inventory]\n[--hiera-config STRING]\n[--hiera-data STRING]\n[--image-user STRING]\n[--puppetfile STRING]\n[--image-name STRING]\n[--config-file STRING]\n[--config-directory STRING]\n[--master STRING]\n\nBuild Docker images and Dockerfiles using Puppet code\n\nOPTIONS:\n  --render-as FORMAT             - The rendering format to use.\n  --verbose                      - Whether to log verbosely.\n  --debug                        - Whether to log debug information.\n  --cmd STRING                   - The default command to be executed by the\n                                   resulting image\n  --config-directory STRING      - A folder where metadata can be loaded from\n  --config-file STRING           - A configuration file with all the metadata\n  --entrypoint STRING            - The default entrypoint for the resulting\n                                   image\n  --expose STRING                - A list of ports to be exposed by the\n                                   resulting image\n  --from STRING                  - The base docker image to use for the\n                                   resulting image\n  --hiera-config STRING          - Hiera config file to use\n  --hiera-data STRING            - Hieradata directory to use\n  --image-name STRING            - The name of the resulting image\n  --image-user STRING            - Specify a user to be used to run the\n                                   container process\n  --[no-]inventory               - Enable or disable the generation of an\n                                   inventory file at /inventory.json\n  --labels KEY=VALUE             - A set of labels to be applied to the\n                                   resulting image\n  --maintainer STRING            - Name and email address for the maintainer of\n                                   the resulting image\n  --master STRING                - A Puppet Master to use for building images\n  --module-path PATH             - A path to a directory containing a set of\n                                   modules to be copied into the image\n  --network STRING               - The Docker network to pass along to the\n                                   docker build command\n  --os STRING                    - The operating system used by the image if not\n                                   autodetected\n  --os-version STRING            - The version of the operating system used by\n                                   the image if not autodetected\n  --puppet-agent-version STRING  - Version of the Puppet Agent package to\n                                   install\n  --puppet-debug                 - Pass the debug flag to the Puppet process\n                                   used to build the container image\n  --puppetfile STRING            - Enable use of Puppetfile to install\n                                   dependencies during build\n  --r10k-version STRING          - Version of R10k to use for installing modules\n                                   from Puppetfile\n  --rocker                       - Use Rocker as the build tool\n  --[no-]show-diff               - Enable or disable showing the diff when\n                                   running Puppet to build the image\n  --skip-puppet-install          - If the base image already contains Puppet we\n                                   can skip installing it\n  --volume STRING                - A list of volumes to be added to the\n                                   resulting image\n\nACTIONS:\n  build         Build a Docker image from Puppet code\n  dockerfile    Generate a Dockerfile which will run the specified Puppet code\n\nSee 'puppet man docker' or 'man puppet-docker' for full help.\n```\n\n## Limitations\n\nThe module currently does not support building Windows containers, or\nbuilding containers from a Windows machine. We'll be adding support for\nthese in the future.\n\nThe inventory functionality does not work correctly on Centos 6 based\nimages, so if you're using Centos 6 then you need to pass the\n`--no-inventory` flag.\n\n## Maintainers\n\nThis repository is maintained by: Gareth Rushgrove \u003cgareth@puppet.com\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-image_build","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-image_build","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuppetlabs-toy-chest%2Fpuppetlabs-image_build/lists"}