The ONBUILD instruction is a tool used when creating images that will become the parameter to the FROM instructions in another Dockerfile. The ONBUILD instruction just adds metadata to your image, specifically a trigger that is stored in the image and not otherwise used. However, that metadata trigger does get used when your image is supplied as the parameter in the FROM command of another Dockerfile. Here is the ONBUILD instruction syntax:

# ONBUILD instruction syntax
ONBUILD [INSTRUCTION]

The ONBUILD instruction is kind of like a Docker time machine used to send instructions into the future. (You might laugh if you knew how many times I just typed Doctor time machine!) Let's demonstrate the use of the ONBUILD instruction with a simple example. First, we will build an image named my-base using the following Dockerfile:

# my-base Dockerfile
FROM alpine
LABEL maintainer="Earl Waud <[email protected]>"
ONBUILD LABEL version="1.0"
ONBUILD LABEL support-email="[email protected]" support-phone="(123) 456-7890"
CMD ["sh"]

Next, let's build an image named my-app that is built FROM the my-base image, like so:

# my-app Dockerfile
FROM my-base:1.0
CMD ["sh"]

Inspecting the resulting my-app image shows us that the LABEL commands provided in the ONBUILD instructions were sent forward in time, arriving at the my-app image:

If you did a similar inspect of the my-base image, you would find that it does not contain the version and support labels. Note also that the ONBUILD instruction is a one-time-use time machine. If you were to build a new image using the my-app in the FROM instruction, the new image would not get the labels that were provided in the ONBUILD instructions of the my-base image.