Skip to content

Commit f62591e

Browse files
carslencarslen
committed
docs(update): update TRG 4.02 - Base Image
1 parent 0ee8d43 commit f62591e

File tree

2 files changed

+134
-184
lines changed

2 files changed

+134
-184
lines changed

‎docs/release/trg-0/trg-4-02.md

-156
This file was deleted.

‎docs/release/trg-4/trg-4-02.md

+134-28
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,156 @@
11
---
2-
title: TRG 4.02 - Base images
2+
title: TRG 4.02 - Base Images
33
---
44

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

1112
## Why
1213

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

1719
## Description
1820

19-
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.
20-
DockerHub is running container scans for all [official images](https://docs.docker.com/trusted-content/official-images/)
21-
and is publishing the scans result in the [docker-library/repo-info repository](https://github.com/docker-library/repo-info).
21+
As Eclipse Tractus-X project, we don't have automated processes for publishing container scan results (yet). This is why
22+
we use information that is already gathered for us. DockerHub is running container scans for
23+
all [official images](https://docs.docker.com/trusted-content/official-images/) and is publishing the scans result in
24+
the [docker-library/repo-info repository](https://github.com/docker-library/repo-info).
2225

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

26-
We are leveraging this information by restricting the base images we use for our published container images to a minimal set.
27-
Aligning on specific base images also gives us the opportunity to provide you with templates for the legal notice,
28-
like described in [TRG 4.06 - Notice for docker images](./trg-4-06.md)
33+
We are leveraging this information by restricting the base images we use for our published container images to a minimal
34+
set. Aligning on specific base images also gives us the opportunity to provide you with templates for the legal notice,
35+
like described in [TRG 4.06 - Notice for docker images](./trg-4-06.md)
36+
37+
### Aligned Base Images
2938

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

32-
| Language / Runtime / OS | Container base image | Notes |
33-
|---------------------------|----------------------------------------------------------------------------|----------------------------------------------------------|
34-
| Java / Kotlin / JVM based | [Eclipse Temurin](https://hub.docker.com/_/eclipse-temurin) | prefer JRE over JDK and alpine tags for your JRE version |
35-
| JS frontends | [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) | prefer :stable-alpine tag |
36-
| .NET runtime | [.NET runtime](https://hub.docker.com/_/microsoft-dotnet-runtime) | prefer :alpine tag |
37-
| ASP.NET runtime | [ASP.NET core runtime](https://hub.docker.com/_/microsoft-dotnet-aspnet) | prefer :alpine tag |
38-
| Linux | [Alpine Linux](https://hub.docker.com/_/alpine) |
41+
| Language / Runtime / OS | Container base image | Notes |
42+
|---------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
43+
| 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. |
44+
| JS frontends | [nginx-unprivileged](https://hub.docker.com/r/nginxinc/nginx-unprivileged) | prefer `1.25`, `1.25-alpine` or `alpine` tag |
45+
| .NET runtime | [.NET runtime](https://hub.docker.com/_/microsoft-dotnet-runtime) | prefer `8.0-alpine` tag |
46+
| ASP.NET runtime | [ASP.NET core runtime](https://hub.docker.com/_/microsoft-dotnet-aspnet) | prefer `8.0-alpine` tag |
47+
| Linux | [Alpine Linux](https://hub.docker.com/_/alpine) | prefer `3.16`, `3.17`, `3.18` or `3.19` tag |
3948

40-
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)
41-
and propose your preferred container images as base image.
49+
If the language or runtime environment of your product is not listed above, feel free
50+
to [start a discussion](https://github.com/eclipse-tractusx/sig-infra/discussions) and propose your preferred container
51+
images as base image.
4252

4353
:::info
44-
As stated in the description above, base image usage is particularly aligned for container images, that we distribute by publishing them on DockerHub.
45-
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,
46-
you can use other publicly available image, as long as the tools are open source license compliant.
54+
As stated in the description above, base image usage is particularly aligned for container images, that we distribute by
55+
publishing them on DockerHub. In case you are using Docker images for build or testing purposes (for example _pandoc_ or
56+
_cypress_, etc.) and you do not publish the images, you can use other publicly available image, as long as the tools are
57+
open source license compliant.
58+
59+
For automated TRG checks, you can skip base image checks on Dockerfiles by declaring it in the `.tractusx` metadata
60+
files. Details can be found in
61+
the [metadata file documentation](https://github.com/eclipse-tractusx/tractusx-quality-checks/blob/main/docs/metadata_file.md)
62+
:::
63+
64+
### Use minor or major Image Tag
65+
66+
Do not use an image tag pointing to a patch version of the image. Instead, use an image tag containing either minor or
67+
major version.
68+
69+
To keep application images compliant, up-to-date and secure it is mandatory to use image tags which allows to rebuild
70+
the applications container image without touching the `Dockerfile` to pull an updated version of the base image (e.g. to
71+
fix a potential problem inside the base image.
72+
73+
:::warning Do not use image tag with patch version
74+
75+
```Dockerfile
76+
FROM alpine:3.18.5 as BUILDER
77+
78+
COPY . /app/build
79+
WORKDIR /app/build
80+
RUN build
81+
82+
FROM alpine:3.18.5
83+
84+
COPY --from=BUILDER /app/build /app
85+
[...]
86+
```
87+
88+
:::
89+
90+
:::tip Use image tag with minor or major version
91+
92+
```Dockerfile
93+
FROM alpine:3 as BUILDER
94+
95+
COPY . /app/build
96+
WORKDIR /app/build
97+
RUN build
98+
99+
FROM alpine:3.18
100+
101+
COPY --from=BUILDER /app/build /app
102+
103+
[...]
104+
```
47105

48-
For automated TRG checks, you can skip base image checks on Dockerfiles by declaring it in the `.tractusx` metadata files.
49-
Details can be found in the [metadata file documentation](https://github.com/eclipse-tractusx/tractusx-quality-checks/blob/main/docs/metadata_file.md)
50106
:::
107+
108+
The next time the applications container image is created, an updated base image will be used, if available.
109+
110+
### Use Base Image as-is
111+
112+
It is recommended to use the base image **as-is** and to not modify or update it.
113+
114+
Do not use package manager update mechanisms to update the runtime of the base image (e.g. to fix security
115+
vulnerabilities). Updating or modifying the base image might pull in a new version of a library which is no longer under
116+
the correct Intellectual Property and/or license.
117+
118+
Same applies for installing additional tools, libraries, commands, which modifies the base image. If possible, select a
119+
base image for your application that contains all dependent tools.
120+
121+
:::warning Do not update or install additional packages
122+
123+
```Dockerfile
124+
# Call for feedback: Does this example make sense at all or
125+
# should it be removed?
126+
FROM alpine:3.18.2
127+
128+
COPY some/binary /app/
129+
RUN apk update && apk upgrade \ # fix CVE-2023-123
130+
apk add someTool # install pkg "someTool"
131+
```
132+
133+
:::
134+
135+
In the example a patch level image tag of alpine is used, which is not recommended, and an update/upgrade is done to get
136+
the latest versions of all installed packages installed. Instead, use a minor image tag (e.g. `alpine:3.18`) as
137+
recommended in [_Use minor or major Image Tag_](#use-minor-or-major-image-tag).
138+
139+
An exception from modifying the base image might be a build stage in the `Dockerfile`, as long as the resulting image
140+
uses an unmodified base image, e.g.:
141+
142+
```Dockerfile
143+
FROM alpine:3.18 as BUILDER
144+
145+
ENV DOWLOAD_URL "https://some-fqdn/tool.jar"
146+
147+
RUN apk update && apk add curl=8.5.0-r0 --no-cache
148+
RUN curl -L --proto "=https" -sSf ${DOWLOAD_URL} \
149+
--output /tmp/tool.jar
150+
151+
FROM eclipse-temurin:19-jre-alpine
152+
153+
COPY --from=otel /tmp/tool.jar .
154+
155+
[...]
156+
```

0 commit comments

Comments
 (0)