Skip to content

Commit ebf1661

Browse files
siegfriedwebersiegfriedweber
authored
doc: Add SDP upgrade instructions (#124)
1 parent 65e1c96 commit ebf1661

3 files changed

Lines changed: 170 additions & 0 deletions

File tree

‎docs/modules/opensearch/pages/index.adoc‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@ The Stackable operator for {opensearch}[OpenSearch{external-link-icon}^] deploys
1717
OpenSearch is a powerful search and analytics engine built on Apache Lucene.
1818
This operator helps you manage your OpenSearch instances on Kubernetes efficiently.
1919

20+
[IMPORTANT]
21+
====
22+
If you intend to upgrade an existing OpenSearchCluster from a previous SDP version, please refer to the xref:usage-guide/upgrade.adoc[SDP upgrade notes] for detailed guidance.
23+
====
24+
2025
== Getting started
2126

2227
Get started using OpenSearch with the Stackable operator by following the xref:getting_started/index.adoc[].

‎docs/modules/opensearch/pages/usage-guide/upgrade.adoc‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
= SDP upgrade notes
2+
:description: Instructions for upgrading the SDP versions.
3+
4+
== Upgrade from SDP 25.11 to 26.3
5+
6+
When upgrading the OpenSearch operator from SDP 25.11 to 26.3, you may encounter several warnings and errors in the operator logs.
7+
These issues are not due to breaking changes in the Custom Resource Definition, but rather arise from incompatibilities in your `configOverrides` and `podOverrides` related to the current version.
8+
You might have configured the OpenSearch security plugin, TLS and other features with overrides which are now handled directly by the operator.
9+
10+
If `configOverrides` replace values that are already set by the operator, a corresponding warning will be issued:
11+
12+
[source]
13+
----
14+
WARN reconciling object{...}: stackable_opensearch_operator::controller::build::node_config:
15+
configOverrides: Configuration setting "plugins.security.ssl.http.pemcert_filepath" changed
16+
from "/stackable/opensearch/config/tls/server/tls.crt" to
17+
"/stackable/opensearch/config/tls/tls.crt".
18+
----
19+
20+
=== TLS
21+
22+
The operator now offers the option to configure TLS using SecretClasses:
23+
24+
[source,yaml]
25+
----
26+
spec:
27+
clusterConfig:
28+
tls:
29+
internalSecretClass: tls
30+
serverSecretClass: tls
31+
----
32+
33+
This means that the following `configOverrides` are now obsolete and must be removed:
34+
35+
[source,yaml]
36+
----
37+
configOverrides:
38+
opensearch.yml:
39+
plugins.security.ssl.http.enabled: ...
40+
plugins.security.ssl.http.pemcert_filepath: ...
41+
plugins.security.ssl.http.pemkey_filepath: ...
42+
plugins.security.ssl.http.pemtrustedcas_filepath: ...
43+
plugins.security.ssl.transport.enabled: ...
44+
plugins.security.ssl.transport.pemcert_filepath: ...
45+
plugins.security.ssl.transport.pemkey_filepath: ...
46+
plugins.security.ssl.transport.pemtrustedcas_filepath: ...
47+
----
48+
49+
Additionally, the following `podOverrides` for the TLS `volumes` and `volumeMounts` must be removed:
50+
51+
[source,yaml]
52+
----
53+
podOverrides:
54+
spec:
55+
containers:
56+
- name: opensearch
57+
volumeMounts:
58+
- mountPath: /stackable/opensearch/config/tls
59+
name: tls
60+
volumes:
61+
- name: tls
62+
ephemeral:
63+
volumeClaimTemplate:
64+
metadata:
65+
annotations:
66+
secrets.stackable.tech/class: tls
67+
secrets.stackable.tech/scope: ...
68+
spec:
69+
accessModes:
70+
- ReadWriteOnce
71+
resources:
72+
requests:
73+
storage: "1"
74+
storageClassName: secrets.stackable.tech
75+
----
76+
77+
Refer to the xref:usage-guide/security.adoc#_tls[TLS documentation] for further details.
78+
79+
=== Security plugin configuration
80+
81+
The configuration of the OpenSearch security plugin is now managed by the operator.
82+
83+
You may have defined the configuration files in a Secret or ConfigMap.
84+
These files were previously used to initialize the security index when you set `plugins.security.allow_default_init_securityindex` to `true`.
85+
Since these files are not utilized after the security index creation, you can safely remove the corresponding `configOverrides` and `podOverrides`, particularly to prevent mount path conflicts:
86+
87+
[source,yaml]
88+
----
89+
configOverrides:
90+
opensearch.yml:
91+
plugins.security.allow_default_init_securityindex: "true"
92+
podOverrides:
93+
spec:
94+
containers:
95+
- name: opensearch
96+
volumeMounts:
97+
- mountPath: /stackable/opensearch/config/opensearch-security
98+
name: security-config
99+
readOnly: true
100+
volumes:
101+
- name: security-config
102+
secret:
103+
defaultMode: 432
104+
secretName: opensearch-security-config
105+
----
106+
107+
Please have a look at the xref:usage-guide/security.adoc#_settings[documentation on security settings], if you want the operator to manage certain security configurations.
108+
109+
=== StatefulSet updates
110+
111+
The OpenSearch operator deploys a StatefulSet, in which Kubernetes restricts changes to certain fields.
112+
As a result, the following error may occur:
113+
114+
[source]
115+
----
116+
ERROR stackable_operator::logging::controller: Failed to reconcile object ...
117+
unable to patch resource "opensearch-nodes-default",
118+
ApiError: StatefulSet.apps "opensearch-nodes-default" is invalid:
119+
spec: Forbidden: updates to statefulset spec for fields other than 'replicas', ...
120+
----
121+
122+
To resolve this error, you need to delete the StatefulSets.
123+
You can do this using the following command:
124+
125+
[source,shell]
126+
----
127+
kubectl delete statefulsets.apps --cascade=orphan opensearch-nodes-default
128+
----
129+
130+
The operator will automatically recreate the StatefulSet.
131+
132+
=== Service discovery
133+
134+
The OpenSearch operator now deploys a discovery ConfigMap that is named after the OpenSearch cluster:
135+
136+
[source,yaml]
137+
----
138+
apiVersion: v1
139+
kind: ConfigMap
140+
metadata:
141+
name: opensearch
142+
data:
143+
OPENSEARCH_HOSTNAME: opensearch.default.svc.cluster.local
144+
OPENSEARCH_HOSTS: https://opensearch.default.svc.cluster.local:9200
145+
OPENSEARCH_PORT: "9200"
146+
OPENSEARCH_PROTOCOL: https
147+
----
148+
149+
Consider using this ConfigMap in your OpenSearch clients instead of hard-coding a Service or IP address.
150+
151+
For example, the Helm values for OpenSearch Dashboards can reference the discovery ConfigMap:
152+
153+
[source,yaml]
154+
----
155+
opensearchHosts: null # Use the discovery ConfigMap instead
156+
extraEnvs:
157+
- name: OPENSEARCH_HOSTS
158+
valueFrom:
159+
configMapKeyRef:
160+
name: opensearch
161+
key: OPENSEARCH_HOSTS
162+
----
163+
164+
Please consult the xref:reference/discovery.adoc[Discovery documentation] for instructions on how to select the role groups exposed by the discovery ConfigMap.

‎docs/modules/opensearch/partials/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
** xref:opensearch:usage-guide/scaling.adoc[]
1313
** xref:opensearch:usage-guide/keystore.adoc[]
1414
** xref:opensearch:usage-guide/security.adoc[]
15+
** xref:opensearch:usage-guide/upgrade.adoc[]
1516
** xref:opensearch:usage-guide/operations/index.adoc[]
1617
*** xref:opensearch:usage-guide/operations/cluster-operations.adoc[]
1718
*** xref:opensearch:usage-guide/operations/pod-placement.adoc[]

0 commit comments

Comments
 (0)