Targeting specific stages in Docker - Deep Dive

Overview - Targeting specific stages

What is it?

Targeting specific stages in Docker means choosing which part of a multi-step build you want to use or export. Dockerfiles can have multiple stages to build parts of an image separately. By targeting a stage, you can create smaller images or reuse intermediate results without building everything again.

Why it matters

Without targeting specific stages, every Docker build would create one big image including all build steps, making images large and slow to build. Targeting stages helps save time, disk space, and bandwidth by focusing only on what you need. This makes development faster and deployment lighter.

Where it fits

Before learning this, you should understand basic Dockerfiles and how Docker images build. After this, you can learn about multi-stage builds in detail, image optimization, and advanced Docker caching strategies.

Mental Model

Core Idea

Targeting specific stages lets you pick exactly which step of a multi-step Docker build to use, saving time and space.

Think of it like...

It's like cooking a meal in steps and choosing to serve only the salad stage without making the full dinner every time.

Dockerfile Build Flow:

┌─────────────┐
│ Stage 1:    │
│ Build base  │
└─────┬───────┘
      │
┌─────▼───────┐
│ Stage 2:    │
│ Compile app │
└─────┬───────┘
      │
┌─────▼───────┐
│ Stage 3:    │
│ Final image │
└─────────────┘

You can target Stage 2 to get the compiled app without the final image.

Build-Up - 7 Steps

1

Foundation

Understanding Dockerfile stages

Concept: Dockerfiles can have multiple stages, each named or unnamed, to separate build steps.

A Dockerfile can have several FROM lines. Each FROM starts a new stage. For example: FROM alpine AS base RUN echo "Base stage" FROM base AS build RUN echo "Build stage" FROM build AS final RUN echo "Final stage" Each stage can build on the previous one.

Result

Docker builds three stages: base, build, and final, each with its own filesystem snapshot.

Understanding that Dockerfiles can have multiple stages is the foundation for targeting specific ones later.

2

Foundation

Basic Docker build command

Concept: The docker build command creates an image from the Dockerfile, usually using the last stage by default.

Running: docker build -t myimage . builds the Dockerfile in the current folder and tags the final image as 'myimage'. By default, it uses the last stage in the Dockerfile.

Result

An image named 'myimage' is created from the last stage.

Knowing the default behavior helps understand why targeting stages changes the output.

3

Intermediate

Targeting a specific stage with --target

🤔Before reading on: do you think docker build --target picks a stage by number or by name? Commit to your answer.

Concept: You can tell Docker to build only up to a named stage using the --target option.

If your Dockerfile has stages named 'base', 'build', and 'final', you can run: docker build --target build -t mybuild . This builds only up to the 'build' stage and tags the image 'mybuild'.

Result

Docker stops building after the 'build' stage and creates an image from it.

Knowing that --target uses stage names lets you control build output precisely and reuse intermediate results.

4

Intermediate

Using targeted stages for smaller images

🤔Before reading on: do you think targeting an earlier stage always makes the image smaller? Commit to your answer.

Concept: Targeting earlier stages can produce smaller images by excluding later build steps like installing extra tools.

For example, a final stage might copy build artifacts and remove build tools. Targeting the build stage keeps the tools but excludes final cleanup. This is useful for debugging or when you want a development image with tools included.

Result

You get an image with only the files and layers up to the targeted stage, which can be smaller or larger depending on the stage.

Understanding that targeted stages control image size helps optimize builds for different environments.

5

Intermediate

Reusing stages in multi-stage builds

Concept: Stages can be reused as base images for later stages, enabling complex build flows.

You can name a stage and then use it as the base for another stage: FROM node:18 AS builder RUN build commands FROM alpine AS runtime COPY --from=builder /app /app This copies files from the 'builder' stage into the 'runtime' stage.

Result

The final image contains only runtime files, not build tools.

Knowing how stages share data enables efficient, clean images by separating build and runtime environments.

6

Advanced

Targeting stages in CI/CD pipelines

🤔Before reading on: do you think targeting stages can speed up CI builds by skipping steps? Commit to your answer.

Concept: CI/CD systems can target specific stages to speed up builds or run tests on intermediate images.

For example, a pipeline might build only the 'test' stage to run unit tests without building the full final image: docker build --target test -t mytest . This saves time and resources during automated testing.

Result

Faster CI builds and more modular pipeline steps.

Understanding targeted stages in CI/CD helps optimize build times and resource use in real projects.

7

Expert

Caching and layer reuse with targeted stages

🤔Before reading on: do you think targeting a stage always invalidates cache for previous stages? Commit to your answer.

Concept: Docker caches layers per stage, so targeting a stage can reuse cached layers from earlier builds, speeding up incremental builds.

When you build with --target, Docker uses cache for all stages up to that target if nothing changed. This means you can build intermediate images quickly. However, changing a stage's instructions invalidates cache for that stage and later ones. Example: docker build --target build -t mybuild . If 'build' stage is unchanged, Docker reuses cached layers.

Result

Faster builds by reusing cached layers for targeted stages.

Knowing how caching interacts with targeted stages helps avoid unnecessary rebuilds and speeds up development.

Under the Hood

Docker builds images in layers. Each stage creates a set of layers representing filesystem changes. When targeting a stage, Docker stops building after that stage and packages its layers as the final image. Internally, Docker tracks each stage's layers separately, allowing reuse and selective export.

Why designed this way?

Multi-stage builds and targeting were designed to solve the problem of large, monolithic images that include unnecessary build tools. By separating build steps into stages and allowing targeting, Docker enables smaller, cleaner images and faster builds. Alternatives like separate Dockerfiles were less efficient and harder to maintain.

Build Process Flow:

┌─────────────┐
│ Stage 1     │
│ Layers A    │
└─────┬───────┘
      │
┌─────▼───────┐
│ Stage 2     │
│ Layers B    │
└─────┬───────┘
      │
┌─────▼───────┐
│ Stage 3     │
│ Layers C    │
└─────────────┘

Target --target Stage 2 → Image with Layers A + B
Target --target Stage 3 → Image with Layers A + B + C

Myth Busters - 4 Common Misconceptions

Quick: Does targeting a stage build only that stage or all stages up to it? Commit to your answer.

Common Belief: Targeting a stage builds only that stage's instructions.

Reality: Targeting a stage builds all stages up to and including the targeted stage, not just that stage alone.

Why it matters: Thinking it builds only the targeted stage can cause confusion when build steps from earlier stages are missing, leading to build failures.

Quick: Does targeting a stage always produce a smaller image? Commit to your answer.

Common Belief: Targeting an earlier stage always makes the image smaller.

Reality: Targeting an earlier stage can produce a larger image if that stage includes build tools or files removed in later stages.

Why it matters: Assuming smaller images can cause inefficient images with unnecessary files, wasting space and increasing attack surface.

Quick: Can you target a stage by its position number instead of name? Commit to your answer.

Common Belief: You can target a stage by its order number in the Dockerfile.

Reality: Docker requires targeting stages by their name, not by position number.

Why it matters: Trying to target by number leads to build errors and confusion.

Quick: Does targeting a stage disable Docker's layer caching? Commit to your answer.

Common Belief: Targeting a stage disables caching for all stages.

Reality: Docker still uses cache for all stages up to the target if nothing changed.

Why it matters: Misunderstanding caching behavior can lead to unnecessarily long build times.

Expert Zone

1

Targeting stages can affect image metadata like labels and environment variables if they are set in later stages, which might be missing in targeted images.

2

When using --target, the final image's entrypoint and command come from the targeted stage, which can cause runtime issues if not planned.

3

Docker's build cache is shared across stages, so changes in early stages can invalidate cache for all dependent stages, impacting build speed.

When NOT to use

Avoid targeting stages when you need the complete final image for production deployment. Instead, use full multi-stage builds without --target. For simple images without multi-stage builds, targeting is irrelevant.

Production Patterns

In production, multi-stage builds target the final stage to produce minimal images. During development or CI, intermediate stages are targeted to speed up builds or run tests. Some teams use targeted stages to create debug images with extra tools.

Connections

Continuous Integration (CI) Pipelines

Targeting stages builds on CI concepts by optimizing build steps for testing and deployment.

Understanding targeted stages helps design faster CI pipelines by building only necessary parts.

Software Build Systems

Targeting stages is similar to incremental builds in software compilation, where only changed parts are rebuilt.

Knowing incremental build principles clarifies why targeting stages speeds up Docker builds.

Cooking Recipes

Targeting stages parallels preparing parts of a recipe separately and serving only what is needed.

This connection shows how breaking complex tasks into stages improves efficiency and flexibility.

Common Pitfalls

#1 Trying to target a stage by its number instead of name.

Wrong approach:

docker build --target 2 -t myimage .

Correct approach:

docker build --target build -t myimage .

Root cause:

Misunderstanding that Docker requires stage names for targeting, not numeric positions.

#2 Assuming targeting an earlier stage always produces a smaller image.

Wrong approach:

docker build --target base -t smallimage . # expecting smallest image

Correct approach:

docker build --target final -t optimizedimage . # final stage removes build tools

Root cause:

Not realizing earlier stages may include build tools or files removed later, making images larger.

#3 Expecting only the targeted stage to build, ignoring previous stages.

Wrong approach:

docker build --target final -t finalimage .
# expecting only final stage commands to run

Correct approach:

docker build --target final -t finalimage .
# actually builds all stages up to final

Root cause:

Misunderstanding that Docker builds all stages up to the target, not just the target stage.

Key Takeaways

Targeting specific stages in Docker lets you build and export images from any step in a multi-stage Dockerfile.

Using --target with stage names controls which build steps run and which image is created, improving build speed and image size.

Docker builds all stages up to the targeted one, not just the targeted stage alone.

Targeting stages is essential for efficient CI/CD pipelines and creating optimized images for different environments.

Understanding caching and layer reuse with targeted stages helps avoid unnecessary rebuilds and speeds up development.