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,58 +9,51 @@ aliases:
 - /develop/develop-images/baseimages/
 ---
 
-Most Dockerfiles start from a parent image. If you need to completely control
+All Dockerfiles start from a base image.
-the contents of your image, you might need to create a base image instead.
+A base is the image that your image extends.
-Here's the difference:
+It refers to the contents of the `FROM` instruction in the Dockerfile.
 
-- A [parent image](../../glossary.md#parent-image) is the image that your
+```dockerfile
-  image is based on. It refers to the contents of the `FROM` directive in the
+FROM debian
-  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.
 
-- 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
+## Create a base image
-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 full image using tar
+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:
 
-In general, start with a working machine that is running
+```dockerfile
-the distribution you'd like to package as a parent image, though that is
+FROM scratch
-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:
+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).
 
-    $ sudo debootstrap focal focal > /dev/null
+To create a distribution base image, you can use a root filesystem, packaged as
-    $ sudo tar -C focal -c . | docker import - focal
+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).
 
-    sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3
+## Create a minimal base image using scratch
 
-    $ docker run focal cat /etc/lsb-release
+The reserved, minimal `scratch` image serves as a starting point for
-
+building containers. Using the `scratch` image signals to the build process
-    DISTRIB_ID=Ubuntu
-    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,
+While `scratch` appears in Docker's [repository on Docker Hub](https://hub.docker.com/_/scratch),
-run it, or tag any image with the name `scratch`. Instead, you can refer to it
+you can't pull it, run it, or tag any image with the name `scratch`.
-in your `Dockerfile`. For example, to create a minimal container using
+Instead, you can refer to it in your `Dockerfile`.
-`scratch`:
+For example, to create a minimal container using `scratch`:
 
 ```dockerfile
 # syntax=docker/dockerfile:1
@@ -69,46 +62,64 @@ ADD hello /
 CMD ["/hello"]
 ```
 
-Assuming you built the `hello` executable example by using the source code at
+Assuming an executable binary named `hello` exists at the root of the [build context](../../build/building/context.md).
-[https://github.com/docker-library/hello-world](https://github.com/docker-library/hello-world),
+You can build this Docker image using the following `docker build` command:
-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.
+This example image can only successfully execute as long as the `hello` binary
-If you want to test it out, you can clone [the image repo](https://github.com/docker-library/hello-world).
+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 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.
+
+For example, to create an Ubuntu base image:
+
+```dockerfile
+$ sudo debootstrap focal focal > /dev/null
+$ sudo tar -C focal -c . | docker import - focal
+
+sha256:81ec9a55a92a5618161f68ae691d092bf14d700129093158297b3d01593f4ee3
+
+$ docker run focal cat /etc/lsb-release
+
+DISTRIB_ID=Ubuntu
+DISTRIB_RELEASE=20.04
+DISTRIB_CODENAME=focal
+DISTRIB_DESCRIPTION="Ubuntu 20.04 LTS"
+```
+
+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.
+* [Dockerfile reference](../../reference/dockerfile.md)
-* To help you write a clear, readable, maintainable `Dockerfile`, we've also
+* [Dockerfile best practices](../../build/building/best-practices.md)
-  written a [Dockerfile best practices guide](../../build/building/best-practices.md).
+* [Docker Official Images](../../trusted-content/official-images/_index.md)
-* If your goal is to create a new Docker Official Image, read [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: |
+base image: |
-  An image's parent image is the image designated in the `FROM` directive
+  A base image is an image you designate in a `FROM` directive in a Dockerfile.
-  in the image's Dockerfile. All subsequent commands are based on this parent
+  It defines the starting point for your build.
-  image. A Dockerfile with the `FROM scratch` directive uses no parent image, and creates
+  Dockerfile instructions create additional layers on top of the base image.
-  a 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/