From c044053e249e78f56b9826554230cf87c2e0868e Mon Sep 17 00:00:00 2001 From: Techassi Date: Thu, 10 Sep 2026 11:02:38 +0200 Subject: [PATCH 1/2] docs: Add stackableVersionPolicy to product image selection page --- .../pages/product-image-selection.adoc | 45 ++++++++++++++----- .../contributor/pages/project-overview.adoc | 14 +++--- 2 files changed, 41 insertions(+), 18 deletions(-) diff --git a/modules/concepts/pages/product-image-selection.adoc b/modules/concepts/pages/product-image-selection.adoc index 392bc9791..f0649cec8 100644 --- a/modules/concepts/pages/product-image-selection.adoc +++ b/modules/concepts/pages/product-image-selection.adoc @@ -65,7 +65,11 @@ At the bottom of this page, in the <<_common_scenarios, common scenarios>> secti If your Kubernetes cluster has internet access, the easiest way is to use the publicly available images from the https://oci.stackable.tech/[Stackable Image Registry{external-link-icon}^]. -TIP: All our images are also mirrored to our https://quay.io/organization/stackable[Stackable Quay.io organization{external-link-icon}^]. +[TIP] +==== +All our images are also published to our https://quay.io/organization/stackable[Stackable Quay.io organization{external-link-icon}^]. +The layout of our artifacts is detailed on our xref:artifact-registries/index.adoc[artifact registries] page. +==== [source,yaml] ---- @@ -79,27 +83,45 @@ Consult the product operator documentation to find out about supported product v <.> The version of the Stackable Data Platform. Simply omit this to use the operator version. -NOTE: If the Kubernetes cluster does not have internet access, you can use a xref:_custom_docker_registry[] or xref:_custom_images[]. +NOTE: If the Kubernetes cluster does not have internet access, you can use a xref:_custom_registry[] or xref:_custom_images[]. You only need to specify the product version, but you _can_ also specify an explicit Stackable version. The product version can be found on the xref:operators:supported_versions.adoc[list of supported product versions] or on the product operator documentation page. +If you don't specify the Stackable version, the operator will use its own version, e.g. `25.7.0`. +When using a nightly operator or a `-pr` version, it will use the nightly `0.0.0-dev` image. As images should be updated from time to time (e.g., new base image, security updates), a Stackable version can be provided. An image with the Stackable version `25.7.0` is fixed and will never change. Security updates within a release line will result in patch version bumps in the Stackable version, for example, to `25.7.1`. -If you don't specify the Stackable version, the operator will use its own version, e.g., `25.7.0`. -When using a nightly operator or a `pr` version, it will use the nightly `0.0.0-dev` image. +By default, updating to the newest patch version is an explicit change of the `stackableVersion` field. +Since 26.11.0 however, it is possible to opt into automatic patch level updates. + +[source,yaml] +---- +spec: + image: + productVersion: 3.9.1 + stackableVersionPolicy: LatestPatch # Default: Exact <.> +---- +<.> This instructs the operator to choose the latest patch level version of the product image. + +[NOTE] +==== +A potential newer image is only pulled when Pods are rotated or their containers are restarted. +Pods are **not** rotated and containers are **not** restarted automatically when a new image is available. +This behaviour makes this a passive update mechanism, rather than an active one. +==== All the available images (with their product and Stackable versions) can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[Stackable OCI registry{external-link-icon}^]. -Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[Docker images section of the project overview]. +Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[container images section of the project overview]. -== Custom docker registry +== Custom registry -Custom Docker registries can be used to fetch the image from a local image registry rather than from the internet. +Custom registries can be used to fetch the image from a local image registry rather than from the internet. The prerequisite is that you mirror all the required images in the same way (with the same name and tag) as the images provided by Stackable. -Afterward, you can use the following snippet to configure your custom Docker repo: +Afterwards, you can use the following snippet to configure your custom repo: [source,yaml] ---- @@ -107,11 +129,10 @@ spec: image: productVersion: 3.3.1 stackableVersion: 25.7.0 # Optional - repo: my.corp/myteam/stackable <.> + repo: my.corp/myteam/stackable ---- -<.> We recommend not including a slash at the end while we plan on https://github.com/stackabletech/operator-rs/issues/1020[improving the situation{external-link-icon}^]. -This will change the image from the default Stackable repository `oci.stackable.tech/sdp/kafka:3.3.1-stackable23.7.0` to `my.corp/myteam/stackable/kafka:3.3.1-stackable23.7.0`. +This will change the image from the default Stackable repository `oci.stackable.tech/sdp/kafka:3.3.1-stackable25.7.0` to `my.corp/myteam/stackable/kafka:3.3.1-stackable25.7.0`. == [[customimages]] Custom images @@ -135,7 +156,7 @@ Using custom images has a few limitations that users should be aware of: * The images must have the same structures that Stackable operators expect. This should usually be ensured by specifying a Stackable image in the `FROM` clause of the Dockerfile (all the available images can be found in our https://oci.stackable.tech/api/v2.0/projects/sdp[Stackable OCI registry{external-link-icon}^] - the schema is typically: `oci.stackable.tech/sdp/:-stackable`. -Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[Docker images section of the project overview]). +Information on how to browse the registry can be found in the xref:contributor:project-overview.adoc#docker-images[container images section of the project overview]). * Images will need to be upgraded for every new Stackable release to follow structural changes that Stackable may have made to their images. When deriving images from official Stackable images, this will mean updating the version of the image in the `FROM` clause to the correct Stackable release. diff --git a/modules/contributor/pages/project-overview.adoc b/modules/contributor/pages/project-overview.adoc index bbb190ba1..c95c0977c 100644 --- a/modules/contributor/pages/project-overview.adoc +++ b/modules/contributor/pages/project-overview.adoc @@ -21,7 +21,7 @@ image::project-overview-operators.drawio.svg[] All the operators are written in https://www.rust-lang.org/[Rust{external-link-icon}^] and the source code is found in the `rust` directory. `tests` contains the integration tests which use https://kuttl.dev/[kuttl{external-link-icon}^] and our own test template https://github.com/stackabletech/beku.py[beku.py{external-link-icon}^]. Documentation is written in https://antora.org/[Antora{external-link-icon}^] and found in the `docs` directory, see also <> further down the page. -`deploy` and `docker` contain files used to package the operator into a Docker image and Helm chart. +`deploy` and `docker` contain files used to package the operator into a container image and Helm chart. Some files in these repositories are actually _templated_: The https://github.com/stackabletech/operator-templating[operator-templating{external-link-icon}^] repository contains a template for all operator repositories, where shared files are distributed from. @@ -80,7 +80,7 @@ There is no code in this repository. [[artifact-storage]] == Artifact storage -Where are binaries, Helm Charts and Docker images stored? +Where are binaries, Helm Charts and container images stored? [[product-artifacts]] === Product artifacts @@ -100,7 +100,7 @@ stackable stackable-charts ---- -`sdp` contains the product and operator Docker images. The Helm Charts for the operators are found under `sdp-charts`. Some artifacts like the +`sdp` contains the product and operator container images. The Helm Charts for the operators are found under `sdp-charts`. Some artifacts like the product binaries are stored in the https://repo.stackable.tech/#browse/browse[Nexus repo{external-link-icon}^] under `packages`. List the Helm Charts in `sdp-charts`: @@ -127,11 +127,13 @@ $ curl -X GET --header 'Accept: application/json' 'https://oci.stackable.tech/ap 24.3.0 ---- +// NOTE (@Techassi): The header was updated, but the anchor was kept the same to ensure links to this don't break. [[docker-images]] -=== Docker images +=== Container images -Docker images are stored in https://oci.stackable.tech[https://oci.stackable.tech{external-link-icon}^] as mentioned above. To list all the available repositories in a project, for example in -the `sdp` project, run this command: +Container images are stored in https://oci.stackable.tech[https://oci.stackable.tech{external-link-icon}^] as mentioned above. +They are additionally published to our https://quay.io/organization/stackable[Stackable Quay.io organization{external-link-icon}^]. +To list all the available repositories in a project, for example in the `sdp` project, run this command: [source,console] ---- From ee90569a162706af9ef2be7eaad5c2faba2044b0 Mon Sep 17 00:00:00 2001 From: Techassi Date: Mon, 14 Sep 2026 09:39:50 +0200 Subject: [PATCH 2/2] chore: Apply suggestions Co-authored-by: Andrew Kenworthy <1712947+adwk67@users.noreply.github.com> --- modules/concepts/pages/product-image-selection.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/concepts/pages/product-image-selection.adoc b/modules/concepts/pages/product-image-selection.adoc index f0649cec8..400f35317 100644 --- a/modules/concepts/pages/product-image-selection.adoc +++ b/modules/concepts/pages/product-image-selection.adoc @@ -88,14 +88,14 @@ NOTE: If the Kubernetes cluster does not have internet access, you can use a xre You only need to specify the product version, but you _can_ also specify an explicit Stackable version. The product version can be found on the xref:operators:supported_versions.adoc[list of supported product versions] or on the product operator documentation page. If you don't specify the Stackable version, the operator will use its own version, e.g. `25.7.0`. -When using a nightly operator or a `-pr` version, it will use the nightly `0.0.0-dev` image. +When using a nightly or a `-pr` version of the operator, it will use the nightly `0.0.0-dev` product image. As images should be updated from time to time (e.g., new base image, security updates), a Stackable version can be provided. An image with the Stackable version `25.7.0` is fixed and will never change. Security updates within a release line will result in patch version bumps in the Stackable version, for example, to `25.7.1`. By default, updating to the newest patch version is an explicit change of the `stackableVersion` field. -Since 26.11.0 however, it is possible to opt into automatic patch level updates. +As of 26.11.0, however, it is possible to opt into automatic patch level updates. [source,yaml] ----