Merge pull request #19769 from dvdksn/glossary-base-image

glossary: update base image terminology

.github/vale/config/vocabularies/Docker/accept.txt

@@ -29,6 +29,7 @@ DSOS
 DVP
 Datadog
 Ddosify
+Debootstrap
 Dev Environments?
 Django
 Docker

content/build/building/base-images.md

@@ -1,5 +1,5 @@
 ---
-title: Create a base image
+title: Base images
 description: Learn about base images and how they're created
 keywords: images, base image, examples
 aliases:
@@ -9,32 +9,97 @@ aliases:
 - /develop/develop-images/baseimages/
 ---
 
-Most Dockerfiles start from a parent image. If you need to completely control
-the contents of your image, you might need to create a base image instead.
-Here's the difference:
+All Dockerfiles start from a base image.
+A base is the image that your image extends.
+It refers to the contents of the `FROM` instruction in the Dockerfile.
 
-- A [parent image](../../glossary.md#parent-image) is the image that your
-  image is based on. It refers to the contents of the `FROM` directive in the
-  Dockerfile. Each subsequent declaration in the Dockerfile modifies this parent
-  image. Most Dockerfiles start from a parent image, rather than a base image.
-  However, the terms are sometimes used interchangeably.
+```dockerfile
+FROM debian
+```
 
-- A [base image](../../glossary.md#base-image) has `FROM scratch` in its Dockerfile.
+For most cases, you don't need to create your own base image. Docker Hub
+contains a vast library of Docker images that are suitable for use as a base
+image in your build. [Docker Official Images](../../trusted-content/official-images/_index.md)
+are specifically designed as a set of hardened, battle-tested images that
+supports a wide variety of platforms, languages, and frameworks. There are also
+[Docker Verified Publisher](https://hub.docker.com/search?q=&image_filter=store)
+images, created by trusted publishing partners, verified by Docker.
 
-This topic shows you several ways to create a base image. The specific process
-will depend heavily on the Linux distribution you want to package. We have some
-examples below, and you are encouraged to submit pull requests to contribute new
-ones.
+## Create a base image
+
+If you need to completely control the contents of your image, you can create
+your own base image from a Linux distribution of your choosing, or use the
+special `FROM scratch` base:
+
+```dockerfile
+FROM scratch
+```
+
+The `scratch` image is typically used to create minimal images containing only
+just what an application needs. See [Create a minimal base image using scratch](#create-a-minimal-base-image-using-scratch).
+
+To create a distribution base image, you can use a root filesystem, packaged as
+a `tar` file, and import it to Docker with `docker import`. The process for
+creating your own base image depends on the Linux distribution you want to
+package. See [Create a full image using tar](#create-a-full-image-using-tar).
+
+## Create a minimal base image using scratch
+
+The reserved, minimal `scratch` image serves as a starting point for
+building containers. Using the `scratch` image signals to the build process
+that you want the next command in the `Dockerfile` to be the first filesystem
+layer in your image.
+
+While `scratch` appears in Docker's [repository on Docker Hub](https://hub.docker.com/_/scratch),
+you can't pull it, run it, or tag any image with the name `scratch`.
+Instead, you can refer to it in your `Dockerfile`.
+For example, to create a minimal container using `scratch`:
+
+```dockerfile
+# syntax=docker/dockerfile:1
+FROM scratch
+ADD hello /
+CMD ["/hello"]
+```
+
+Assuming an executable binary named `hello` exists at the root of the [build context](../../build/building/context.md).
+You can build this Docker image using the following `docker build` command:
+
+```console
+$ docker build --tag hello .
+```
+
+To run your new image, use the `docker run` command:
+
+```console
+$ docker run --rm hello
+```
+
+This example image can only successfully execute as long as the `hello` binary
+doesn't have any runtime dependencies. Computer programs tend to depend on
+certain other programs or resources to exist in the runtime environment. For
+example:
+
+- Programming language runtimes
+- Dynamically linked C libraries
+- CA certificates
+
+When building a base image, or any image, this is an important aspect to
+consider. And this is why creating a base image using `FROM scratch` can be
+difficult, for anything other than small, simple programs. On the other hand,
+it's also important to include only the things you need in your image, to
+reduce the image size and attack surface.
 
 ## Create a full image using tar
 
 In general, start with a working machine that is running
-the distribution you'd like to package as a parent image, though that is
+the distribution you'd like to package as a base image, though that is
 not required for some tools like Debian's [Debootstrap](https://wiki.debian.org/Debootstrap),
 which you can also use to build Ubuntu images.
 
-It can be as simple as this to create an Ubuntu parent image:
+For example, to create an Ubuntu base image:
 
+```dockerfile
 $ sudo debootstrap focal focal > /dev/null
 $ sudo tar -C focal -c . | docker import - focal
 
@@ -46,69 +111,15 @@ It can be as simple as this to create an Ubuntu parent image:
 DISTRIB_RELEASE=20.04
 DISTRIB_CODENAME=focal
 DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
-
-There are more example scripts for creating parent images in
-[the Docker GitHub repository](https://github.com/docker/docker/blob/master/contrib).
-
-## Create a simple parent image using scratch
-
-You can use Docker's reserved, minimal image, `scratch`, as a starting point for
-building containers. Using the `scratch` "image" signals to the build process
-that you want the next command in the `Dockerfile` to be the first filesystem
-layer in your image.
-
-While `scratch` appears in Docker's repository on the hub, you can't pull it,
-run it, or tag any image with the name `scratch`. Instead, you can refer to it
-in your `Dockerfile`. For example, to create a minimal container using
-`scratch`:
-
-```dockerfile
-# syntax=docker/dockerfile:1
-FROM scratch
-ADD hello /
-CMD ["/hello"]
 ```
 
-Assuming you built the `hello` executable example by using the source code at
-[https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world),
-and you compiled it with the `-static` flag, you can build this Docker
-image using this `docker build` command:
-
-```console
-$ docker build --tag hello .
-```
-
-Don't forget the `.` character at the end, which sets the [build context](../../build/building/context.md)
-to the current directory.
-
-> **Note**
-> 
-> Because Docker Desktop for Mac and Docker Desktop for Windows use a Linux VM,
-> you need a Linux binary, rather than a Mac or Windows binary.
-> You can use a Docker container to build it:
->
-> ```console
-> $ docker run --rm -it -v $PWD:/build ubuntu:20.04
->
-> container# apt-get update && apt-get install build-essential
-> container# cd /build
-> container# gcc -o hello -static hello.c
-> ```
-
-To run your new image, use the `docker run` command:
-
-```console
-$ docker run --rm hello
-```
-
-This example creates the hello-world image used in the tutorials.
-If you want to test it out, you can clone [the image repo](https://github.com/docker-library/hello-world).
+There are more example scripts for creating base images in
+[the Moby GitHub repository](https://github.com/moby/moby/blob/master/contrib).
 
 ## More resources
 
-There are lots of resources available to help you write your `Dockerfile`.
+For more information about building images and writing Dockerfiles, see:
 
-* There's a [complete guide to all the instructions](../../reference/dockerfile.md) available for use in a `Dockerfile` in the reference section.
-* To help you write a clear, readable, maintainable `Dockerfile`, we've also
-  written a [Dockerfile best practices guide](../../build/building/best-practices.md).
-* If your goal is to create a new Docker Official Image, read [Docker Official Images](../../trusted-content/official-images/_index.md).
+* [Dockerfile reference](../../reference/dockerfile.md)
+* [Dockerfile best practices](../../build/building/best-practices.md)
+* [Docker Official Images](../../trusted-content/official-images/_index.md)

content/build/cache/invalidation.md

@@ -12,7 +12,7 @@ checks whether it can reuse the instruction from the build cache.
 
 The basic rules of build cache invalidation are as follows:
 
-- Starting with a parent image that's already in the cache, the next
+- Starting with a base image that's already in the cache, the next
   instruction is compared against all child images derived from that base
   image to see if one of them was built using the exact same instruction. If
   not, the cache is invalidated.

content/engine/faq.md

@@ -56,7 +56,7 @@ offers a high-level tool with several powerful functionalities:
  uploads and downloads, similar to `git pull`, so new versions of a container
  can be transferred by only sending diffs.
 
- - *Component re-use.* Any container can be used as a [*parent image*](../glossary.md#parent-image) to
+ - *Component re-use.* Any container can be used as a [base image](../glossary.md#base-image) to
 create more specialized components. This can be done manually or as part of an
 automated build. For example you can prepare the ideal Python environment, and
 use it as a base for 10 different applications. Your ideal PostgreSQL setup can

content/guides/docker-concepts/building-images/multi-stage-builds.md

@@ -325,7 +325,7 @@ Now that you have the project, you’re ready to create the `Dockerfile`.
 
 * [Multi-stage builds](/build/building/multi-stage/)
 * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
-* [Creating a base image](/build/building/base-images/)
+* [Base images](/build/building/base-images/)
 * [Spring Boot Docker](https://spring.io/guides/topicals/spring-boot-docker)
 
 

content/guides/docker-concepts/building-images/writing-a-dockerfile.md

@@ -142,7 +142,7 @@ To learn more about writing a Dockerfile, visit the following resources:
 
 * [Dockerfile reference](/reference/dockerfile/)
 * [Dockerfile best practices](/develop/develop-images/dockerfile_best-practices/)
-* [Create your own base image](/build/building/base-images/)
+* [Base images](/build/building/base-images/)
 * [Getting started with Docker Init](/reference/cli/docker/init/)
 
 ## Next steps

content/language/golang/build-images.md

@@ -113,7 +113,7 @@ has all necessary tools and libraries to compile and run a Go application.
 
 > **Note**
 >
-> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md).
+> If you are curious about creating your own base images, you can check out the following section of this guide: [creating base images](../../build/building/base-images.md#create-a-base-image).
 > Note, however, that this isn't necessary to continue with your task at hand.
 
 Now that you have defined the base image for your upcoming container image, you

data/glossary.yaml

@@ -4,8 +4,6 @@
 arm64: |
   ARM64 is the 64-bit extension of the ARM CPU architecture. arm64 architecture
   is used in Apple silicon machines.
-base image: |
-  A base image has no parent image specified in its Dockerfile. It is created using a Dockerfile with the `FROM scratch` directive.
 btrfs: |
   btrfs (B-tree file system) is a Linux [filesystem](#filesystem) that Docker
   supports as a storage backend. It is a [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write) filesystem.
@@ -197,11 +195,11 @@ overlay storage driver: |
   OverlayFS is a [filesystem](#filesystem) service for Linux which implements a
   [union mount](https://en.wikipedia.org/wiki/Union_mount) for other file systems.
   It is supported by the Docker daemon as a storage driver.
-parent image: |
-  An image's parent image is the image designated in the `FROM` directive
-  in the image's Dockerfile. All subsequent commands are based on this parent
-  image. A Dockerfile with the `FROM scratch` directive uses no parent image, and creates
-  a base image.
+base image: |
+  A base image is an image you designate in a `FROM` directive in a Dockerfile.
+  It defines the starting point for your build.
+  Dockerfile instructions create additional layers on top of the base image.
+  A Dockerfile with the `FROM scratch` directive uses an empty base image.
 persistent storage: |
   Persistent storage or volume storage provides a way for a user to add a
   persistent layer to the running container's file system. This persistent layer

data/toc.yaml

@@ -1892,7 +1892,7 @@ Manuals:
         - path: /build/building/opentelemetry/
           title: OpenTelemetry support
         - path: /build/building/base-images/
-          title: Create your own base image
+          title: Base images
     - sectiontitle: Builders
       section:
         - path: /build/builders/