Skip to content

Commit

Permalink
docs(update): update TRG 4.02 - Base Image
Browse files Browse the repository at this point in the history
  • Loading branch information
@carslen
carslen committed Jan 18, 2024
1 parent 0ee8d43 commit f62591e
Show file tree
Hide file tree
Showing 2 changed files with 134 additions and 184 deletions.
156 changes: 0 additions & 156 deletions docs/release/trg-0/trg-4-02.md
View file

This file was deleted.

162 changes: 134 additions & 28 deletions docs/release/trg-4/trg-4-02.md
View file
Original file line number Diff line number Diff line change
@@ -1,50 +1,156 @@
---
title: TRG 4.02 - Base images
title: TRG 4.02 - Base Images
---

| Status | Created | Post-History |
|--------|-------------|---------------------------------------------------------------------------------|
| Active | 06-Dec-2023 | Add advantages of Dockerhub images
| Draft | 04-May-2023 | Remove notice in favor of dedicated TRG; Add mandatory base image for frontends |
| Update | 15-Jan-2024 | Add image tag usage, use base image as-is |
| Active | 06-Dec-2023 | Add advantages of Dockerhub images |
| Active | 04-May-2023 | Remove notice in favor of dedicated TRG; Add mandatory base image for frontends |
| Active | 25-Nov-2022 | Initial release |

## Why

As part of our legal due diligence, we need to provide the best information possible about our distributed (published) Docker images.
Similar to our 3rd-party dependency scans and the `DEPENDENCIES` file, Docker images also have to be scanned and the results published.
We want to help you to keep a high standard process, by defining guidelines, described in this TRG.
As part of our legal due diligence, we need to provide the best information possible about our distributed (published)
Docker images. Similar to our 3rd-party dependency scans and the `DEPENDENCIES` file, Docker images also have to be
scanned and the results published. We want to help you to keep a high standard process, by defining guidelines,
described in this TRG.

## Description

As Eclipse Tractus-X project, we don't have automated processes for publishing container scan results (yet). This is why we use information that is already gathered for us.
DockerHub is running container scans for all [official images](https://docs.docker.com/trusted-content/official-images/)
and is publishing the scans result in the [docker-library/repo-info repository](https://github.com/docker-library/repo-info).
As Eclipse Tractus-X project, we don't have automated processes for publishing container scan results (yet). This is why
we use information that is already gathered for us. DockerHub is running container scans for
all [official images](https://docs.docker.com/trusted-content/official-images/) and is publishing the scans result in
the [docker-library/repo-info repository](https://github.com/docker-library/repo-info).

Utilizing official images from DockerHub is advantageous due to its role as a trusted repository of curated and verified open source containers.
DockerHub provides a centralized platform where developers can access a wide range of pre built containers which adhere to established best practices and meet certain standards of quality, security, and reliability, giving developers confidence in the integrity of the containers they deploy. By incorporating prepared images, teams can foster consistency across environments, reduce the likelihood of vulnerabilities, and accelerate the overall software delivery pipeline rather than managing complex container configurations from scratch.
Utilizing official images from DockerHub is advantageous due to its role as a trusted repository of curated and verified
open source containers. DockerHub provides a centralized platform where developers can access a wide range of pre-built
containers which adhere to established best practices and meet certain standards of quality, security, and reliability,
giving developers confidence in the integrity of the containers they deploy. By incorporating prepared images, teams can
foster consistency across environments, reduce the likelihood of vulnerabilities, and accelerate the overall software
delivery pipeline rather than managing complex container configurations from scratch.

We are leveraging this information by restricting the base images we use for our published container images to a minimal set.
Aligning on specific base images also gives us the opportunity to provide you with templates for the legal notice,
like described in [TRG 4.06 - Notice for docker images](./trg-4-06.md)
We are leveraging this information by restricting the base images we use for our published container images to a minimal
set. Aligning on specific base images also gives us the opportunity to provide you with templates for the legal notice,
like described in [TRG 4.06 - Notice for docker images](./trg-4-06.md)

### Aligned Base Images

The following table lists container base images, that are already agreed on.

| Language / Runtime / OS | Container base image | Notes |
|---------------------------|----------------------------------------------------------------------------|----------------------------------------------------------|
| Java / Kotlin / JVM based | [Eclipse Temurin](https://hub.docker.com/_/eclipse-temurin) | prefer JRE over JDK and alpine tags for your JRE version |
| JS frontends | [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) | prefer :stable-alpine tag |
| .NET runtime | [.NET runtime](https://hub.docker.com/_/microsoft-dotnet-runtime) | prefer :alpine tag |
| ASP.NET runtime | [ASP.NET core runtime](https://hub.docker.com/_/microsoft-dotnet-aspnet) | prefer :alpine tag |
| Linux | [Alpine Linux](https://hub.docker.com/_/alpine) |
| Language / Runtime / OS | Container base image | Notes |
|---------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| Java / Kotlin / JVM based | [Eclipse Temurin](https://hub.docker.com/_/eclipse-temurin) | prefer JRE over JDK and alpine tags for your JRE version, e.g.:<br/>`21-jre`, `21-jre-alpine`, `20-jre`, `20-jre-alpine`, etc. |
| JS frontends | [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) | prefer `1.25`, `1.25-alpine` or `alpine` tag |
| .NET runtime | [.NET runtime](https://hub.docker.com/_/microsoft-dotnet-runtime) | prefer `8.0-alpine` tag |
| ASP.NET runtime | [ASP.NET core runtime](https://hub.docker.com/_/microsoft-dotnet-aspnet) | prefer `8.0-alpine` tag |
| Linux | [Alpine Linux](https://hub.docker.com/_/alpine) | prefer `3.16`, `3.17`, `3.18` or `3.19` tag |

If the language or runtime environment of your product is not listed above, feel free to [start a discussion](https://github.com/eclipse-tractusx/sig-infra/discussions)
and propose your preferred container images as base image.
If the language or runtime environment of your product is not listed above, feel free
to [start a discussion](https://github.com/eclipse-tractusx/sig-infra/discussions) and propose your preferred container
images as base image.

:::info
As stated in the description above, base image usage is particularly aligned for container images, that we distribute by publishing them on DockerHub.
In case you are using Docker images for build or testing purposes (for example pandoc or cypress, etc.) and you do not publish the images,
you can use other publicly available image, as long as the tools are open source license compliant.
As stated in the description above, base image usage is particularly aligned for container images, that we distribute by
publishing them on DockerHub. In case you are using Docker images for build or testing purposes (for example _pandoc_ or
_cypress_, etc.) and you do not publish the images, you can use other publicly available image, as long as the tools are
open source license compliant.

For automated TRG checks, you can skip base image checks on Dockerfiles by declaring it in the `.tractusx` metadata
files. Details can be found in
the [metadata file documentation](https://github.com/eclipse-tractusx/tractusx-quality-checks/blob/main/docs/metadata_file.md)
:::

### Use minor or major Image Tag

Do not use an image tag pointing to a patch version of the image. Instead, use an image tag containing either minor or
major version.

To keep application images compliant, up-to-date and secure it is mandatory to use image tags which allows to rebuild
the applications container image without touching the `Dockerfile` to pull an updated version of the base image (e.g. to
fix a potential problem inside the base image.

:::warning Do not use image tag with patch version

```Dockerfile
FROM alpine:3.18.5 as BUILDER

COPY . /app/build
WORKDIR /app/build
RUN build

FROM alpine:3.18.5

COPY --from=BUILDER /app/build /app
[...]
```

:::

:::tip Use image tag with minor or major version

```Dockerfile
FROM alpine:3 as BUILDER

COPY . /app/build
WORKDIR /app/build
RUN build

FROM alpine:3.18

COPY --from=BUILDER /app/build /app

[...]
```

For automated TRG checks, you can skip base image checks on Dockerfiles by declaring it in the `.tractusx` metadata files.
Details can be found in the [metadata file documentation](https://github.com/eclipse-tractusx/tractusx-quality-checks/blob/main/docs/metadata_file.md)
:::

The next time the applications container image is created, an updated base image will be used, if available.

### Use Base Image as-is

It is recommended to use the base image **as-is** and to not modify or update it.

Do not use package manager update mechanisms to update the runtime of the base image (e.g. to fix security
vulnerabilities). Updating or modifying the base image might pull in a new version of a library which is no longer under
the correct Intellectual Property and/or license.

Same applies for installing additional tools, libraries, commands, which modifies the base image. If possible, select a
base image for your application that contains all dependent tools.

:::warning Do not update or install additional packages

```Dockerfile
# Call for feedback: Does this example make sense at all or
# should it be removed?
FROM alpine:3.18.2

COPY some/binary /app/
RUN apk update && apk upgrade \ # fix CVE-2023-123
apk add someTool # install pkg "someTool"
```

:::

In the example a patch level image tag of alpine is used, which is not recommended, and an update/upgrade is done to get
the latest versions of all installed packages installed. Instead, use a minor image tag (e.g. `alpine:3.18`) as
recommended in [_Use minor or major Image Tag_](#use-minor-or-major-image-tag).

An exception from modifying the base image might be a build stage in the `Dockerfile`, as long as the resulting image
uses an unmodified base image, e.g.:

```Dockerfile
FROM alpine:3.18 as BUILDER

ENV DOWLOAD_URL "https://some-fqdn/tool.jar"

RUN apk update && apk add curl=8.5.0-r0 --no-cache
RUN curl -L --proto "=https" -sSf ${DOWLOAD_URL} \
--output /tmp/tool.jar

FROM eclipse-temurin:19-jre-alpine

COPY --from=otel /tmp/tool.jar .

[...]
```

0 comments on commit f62591e

Please sign in to comment.