# Using AL2023 in containers
<a name="container"></a>

**Note**  
 For more information about how to use AL2023 to host containerized workloads on Amazon ECS, see [AL2023 for Amazon ECS container hosts](ecs.md). 

 There are several ways that AL2023 can be used inside containers depending on the use case. The [AL2023 Base Container Image](base-container.md) is most similar to an Amazon Linux 2 container image and the AL2023 minimal AMI. 

 For advanced users, we offer a minimal container image, introduced in the AL2023.2 release, along with documentation that describes how to build [bare-bones containers](barebones-containers.md). 

 AL2023 can also be used to host containerized workloads, either of AL2023 based container images, or containers based on other Linux distributions. You can use [AL2023 for Amazon ECS container hosts](ecs.md), or use the provided container runtime packages directly. The `docker`, `containerd`, and `nerdctl` packages are available to be installed and used on AL2023. 

**Topics**
+ [Using the AL2023 base container image](base-container.md)
+ [AL2023 Minimal container image](minimal-container.md)
+ [Building bare-bones AL2023 container images](barebones-containers.md)
+ [Comparing packages installed on Amazon Linux 2023 Container Images](al2023-container-image-types.md)
+ [Comparing packages installed on Amazon Linux 2023 Minimal AMI and Container Images](al2023-container-ami.md)

# Using the AL2023 base container image
<a name="base-container"></a>

The AL2023 container image is built from the same software components that are included in the AL2023 AMI. It's available for use in any environment as a base image for Docker workloads. If you're using the Amazon Linux AMI for applications in [Amazon Elastic Compute Cloud](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/) (Amazon EC2), you can containerize your applications with the Amazon Linux container image.

Use the Amazon Linux container image in your local development environment and then push your application to AWS using [Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/userguide/) (Amazon ECS). For more information, see [Using Amazon ECR images with Amazon ECS](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html) in the *Amazon Elastic Container Registry User Guide*.

The Amazon Linux container image is available on Amazon ECR Public. You can provide feedback for AL2023 through your designated AWS representative or by filing an issue in the [amazon-linux-2023 repo](https://github.com/amazonlinux/amazon-linux-2023/issues) on GitHub.

****To pull the Amazon Linux container image from Amazon ECR Public****

1. Authenticate your Docker client to the Amazon Linux Public registry. Authentication tokens are valid for 12 hours. For more information, see [Private registry authentication](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html) in the *Amazon Elastic Container Registry User Guide*.
**Note**  
The **get-login-password** command is supported using the latest version of AWS CLI version 2. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) in the *AWS Command Line Interface User Guide*.

   ```
   $ aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
   ```

   The output is as follows.

   ```
   Login succeeded
   ```

1. Pull the Amazon Linux container image by running the **docker pull** command. To view the Amazon Linux container image on the Amazon ECR Public Gallery, see [Amazon ECR Public Gallery - amazonlinux](https://gallery.ecr.aws/amazonlinux/amazonlinux).
**Note**  
When you pull the AL2023 Docker container image, you can use the tags in one of the following formats:  
To get the latest version of the AL2023 container image, use the `:2023` tag.
To get a specific version of AL2023, you can use the following format:  
`:2023.[0-7 release quarter].[release date].[build number]`
The following examples use the tag `:2023` and pull the most recent available container image of AL2023.

   ```
   $ docker pull public.ecr.aws/amazonlinux/amazonlinux:2023
   ```

1. (Optional) Run the container locally.

   ```
   $ docker run -it --security-opt seccomp=unconfined public.ecr.aws/amazonlinux/amazonlinux:2023 /bin/bash
   ```

**To pull the AL2023 container image from Docker Hub**

1. Pull the AL2023 container image using the **docker pull** command.

   ```
   $ docker pull amazonlinux:2023
   ```

1. (Optional) Run the container locally.

   ```
   $ docker run -it amazonlinux:2023 /bin/bash
   ```
**Note**  
The container image of AL2023 uses only the `dnf` package manager to install software packages. This means that there's no `amazon-linux-extras` or equivalent command to use for additional software.

# AL2023 Minimal container image
<a name="minimal-container"></a>

**Note**  
 The standard AL2023 container images are suitable for most use cases, and adapting to the minimal container image is likely to be more work than adapting to the AL2023 base container image. 

 The AL2023 minimal container image, introduced in AL2023.2, differs from the base container image because it contains only the bare minimum packages needed to install other packages. The minimal container image is designed to be a minimal set of packages, not a convenient set of packages . 

 The AL2023 minimal container image is built from software components already available in AL2023. The key difference in the minimal container image is using `microdnf` to provide the `dnf` package manager rather than the fully featured Python based `dnf`. This enables the minimal container image to be smaller with the trade-off of not having the full feature set of the `dnf` package manager which is included in the AL2023 AMIs and base container image. 

 The AL2023 minimal container image forms the base of the `provided.al2023` AWS Lambda runtime environment. 

 For a detailed list of packages included in the minimal container image, see [Comparing packages installed on Amazon Linux 2023 Container Images](al2023-container-image-types.md). 

## Minimal Container image size
<a name="container-minimal-size"></a>

 Because the AL2023 minimal container image contains fewer packages than the AL2023 base container image, it is also significantly smaller. The following table compares the container image options of current and past releases of Amazon Linux. 

**Note**  
 Image Size is as-shown on [ Amazon Linux on Amazon ECR Public Gallery](https://gallery.ecr.aws/amazonlinux/amazonlinux). 


| Image | Version | Image Size | Note | 
| --- | --- | --- | --- | 
| Amazon Linux 1 (AL1) | 2018.03.0.20230918.0 | 62.3MB | x86-64 only | 
| Amazon Linux 2 | 2.0.20230926.0 | 64.2MB | aarch64 is 1.6MB larger than x86-64 | 
| Amazon Linux 2023 base container image | 2023.2.20231002.0 | 52.4MB |  | 
| Amazon Linux 2023 minimal container image | 2023.2.20231002.0-minimal | 35.2MB |  | 

## Using the AL2023 Minimal Container image
<a name="using-container-minimal"></a>

 The AL2023 minimal container image is available on ECR and the `2023-minimal` tag will always point to the latest AL2023 based minimal container image, while the `minimal` tag may be updated to a newer version of Amazon Linux than AL2023. 

 You can pull these tags using `docker` with the following example: 

```
$ docker pull public.ecr.aws/amazonlinux/amazonlinux:minimal
```

```
$ docker pull public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
```

The following example shows a `Dockerfile` that takes the minimal container image and installs GCC on top of it :

```
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
RUN dnf install -y gcc && dnf clean all
```

# Building bare-bones AL2023 container images
<a name="barebones-containers"></a>

The AL2023 container image is built from the same software components that are included in the AL2023 AMI. It includes a software that enables the base container layer to behave similarly to running on an Amazon EC2 instance, such as the package manager `dnf`. This section explains how you can construct a container from scratch that includes only the bare minimum dependencies needed for an application.

**Note**  
The standard AL2023 container images are suitable for most use cases. Using the standard container image makes it easy to build on top of your image. A bare-bones container image makes it more difficult to build on top of your image.

**To create a container with bare minimum dependencies for an application**

1. Determine your runtime dependencies. This will vary based on your application.

1. Construct a `Dockerfile` / `Containerfile` that builds `FROM scratch`. The following example of a `Dockerfile` can be used to build a container that contains only the `bash` shell and its dependencies.

   ```
   FROM public.ecr.aws/amazonlinux/amazonlinux:2023 as build
   RUN mkdir /sysroot
   RUN dnf --releasever=$(rpm -q system-release --qf '%{VERSION}') \
     --installroot /sysroot \
     -y \
     --setopt=install_weak_deps=False \
     install bash
   
   FROM scratch
   COPY --from=build /sysroot /
   WORKDIR /
   ENTRYPOINT ["/bin/bash"]
   ```

   1. This `Dockerfile` works by:

     1.  Starting a AL2023 container named `build`. This container will be used to bootstrap the barebones container, this container is not deployed itself, but generates the container to be deployed. 

     1.  Creating the `/sysroot` directory. This directory will be where the `build` container will install the dependencies needed for the barebones container. In a subsequent step, the `/sysroot` path will be packaged up to be the root directory of our barebones image. 

         Using the `--installroot` option to `dnf` in this manner is how we create the other AL2023 images. It's a feature of `dnf` that allows installers and image creation tooling to work. 

     1.  Invoking `dnf` to install packages into `/sysroot`. 

         The `rpm -q system-release --qf '%{VERSION}'` command queries (`-q`) the `system-release` package, setting the query format (`--qf`) to print out the version of the package being queried (the `%{VERSION}` variable is the `rpm` variable for the version of the `RPM`). 

         By setting the `--releasever` argument of `dnf` to the version of `system-release` in the `build` container, this `Dockerfile` can be used to rebuild the barebones container whenever an updated container base image of Amazon Linux is released. 

         It is possible to set the `--releasever` to any Amazon Linux 2023 version, such as 2023.11.20260413. Doing this would mean that the `build` container would run as the latest AL2023 version, but build the barebones container from 2023.11.20260413 regardless of what was the current AL2023 release. 

         The `--setopt=install_weak_deps=False` configuration option tells `dnf` to only install dependencies that are *required* rather than recommended or suggested. 

     1. Copying the installed system into the root of a blank (`FROM scratch`) container.

     1. Setting the `ENTRYPOINT` to be the desired binary, in this case `/bin/bash`.

1. Create an empty directory and add the content of the example in Step 2 to a file named `Dockerfile`.

   ```
   $ mkdir al2023-barebones-bash-example
   	$ cd al2023-barebones-bash-example
   	$ cat > Dockerfile <<EOF
   FROM public.ecr.aws/amazonlinux/amazonlinux:2023 as build
   RUN mkdir /sysroot
   RUN dnf --releasever=$(rpm -q system-release --qf '%{VERSION}') \
     --installroot /sysroot \
     -y \
     --setopt=install_weak_deps=False \
     install bash && dnf --installroot /sysroot clean all
   
   FROM scratch
   COPY --from=build /sysroot /
   WORKDIR /
   ENTRYPOINT ["/bin/bash"]
   EOF
   ```

1. Build the container by running the following command.

   ```
   $ docker build -t al2023-barebones-bash-example
   ```

1. Run the container using the following command to see how minimal a `bash`-only container is.

   ```
   $ docker run -it --rm al2023-barebones-bash-example
   bash-5.2# rpm
   bash: rpm: command not found
   bash-5.2# du -sh /usr/
   bash: du: command not found
   bash-5.2# ls
   bash: ls: command not found
   bash-5.2# echo /bin/*
   /bin/alias /bin/bash /bin/bashbug /bin/bashbug-64 /bin/bg /bin/catchsegv /bin/cd /bin/command /bin/fc /bin/fg /bin/gencat /bin/getconf /bin/getent /bin/getopts /bin/hash /bin/iconv /bin/jobs /bin/ld.so /bin/ldd /bin/locale /bin/localedef /bin/pldd /bin/read /bin/sh /bin/sotruss /bin/sprof /bin/type /bin/tzselect /bin/ulimit /bin/umask /bin/unalias /bin/wait /bin/zdump
   ```

For a more practical example, the following procedure builds a container for a C application that displays `Hello World!`.

1. Create an empty directory and add the C source code and `Dockerfile`.

   ```
   $ mkdir al2023-barebones-c-hello-world-example
   $ cd al2023-barebones-c-hello-world-example
   $ cat > hello-world.c <<EOF
   #include <stdio.h>
   int main(void)
   {
     printf("Hello World!\n");
     return 0;
   }
   EOF
   
   $ cat > Dockerfile <<EOF
   FROM public.ecr.aws/amazonlinux/amazonlinux:2023 as build
   COPY hello-world.c /
   RUN dnf -y install gcc
   RUN gcc -o hello-world hello-world.c
   RUN mkdir /sysroot
   RUN mv hello-world /sysroot/
   RUN dnf --releasever=$(rpm -q system-release --qf '%{VERSION}') \
     --installroot /sysroot \
     -y \
     --setopt=install_weak_deps=False \
     install glibc && dnf --installroot /sysroot clean all
   
   FROM scratch
   COPY --from=build /sysroot /
   WORKDIR /
   ENTRYPOINT ["/hello-world"]
   EOF
   ```

1. Build the container using the following command.

   ```
   $ docker build -t al2023-barebones-c-hello-world-example .
   ```

1. Run the container using the following command.

   ```
   $ docker run -it --rm al2023-barebones-c-hello-world-example
   Hello World!
   ```

# Comparing packages installed on Amazon Linux 2023 Container Images
<a name="al2023-container-image-types"></a>

A comparison of the RPMs present on the AL2023 base container image compared with the RPMs present on the AL2023 minimal container image.

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/linux/al2023/ug/al2023-container-image-types.html)

# Comparing packages installed on Amazon Linux 2023 Minimal AMI and Container Images
<a name="al2023-container-ami"></a>

A comparison of the RPMs present on the AL2023 Minimial AMI to the RPMs present on the AL2023 base and minimal container images.

[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/linux/al2023/ug/al2023-container-ami.html)