Skip to content

docs: Add stackableVersionPolicy to product image selection page #936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Techassi merged 2 commits into from
Sep 14, 2026
+41 −18
Merged

docs: Add stackableVersionPolicy to product image selection page #936

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c044053
docs: Add stackableVersionPolicy to product image selection page
Techassi Sep 10, 2026
ee90569
chore: Apply suggestions
Techassi Sep 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 33 additions & 12 deletions modules/concepts/pages/product-image-selection.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -79,39 +83,56 @@ 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 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`.

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.
As of 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]
----
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

Expand All @@ -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/<product>:<product-version>-stackable<stackable-version>`.
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.
Expand Down
14 changes: 8 additions & 6 deletions modules/contributor/pages/project-overview.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<documentation>> 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.
Expand Down Expand Up @@ -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
Expand All @@ -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`:
Expand All @@ -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]
----
Expand Down