The module lifecycle stage: Preview
The module has requirements for installation
Opensearch
Namespaced resource that describes the final configuration and serves as the source of truth for a specific deployed Opensearch service.
The resource name becomes part of the names of the Kubernetes objects the operator creates (d8ms-osch-<name>-...), so it must follow the Kubernetes Service naming rules (lowercase letters, digits and -, starting with a letter) and be at most 49 characters long. A name that does not fit is rejected when the resource is created.
OpensearchClass Name
The name of the class to which the resource will be linked.
Deploying the service is impossible without a created OpensearchClass.
spec:
opensearchClassName: defaultInstance
Section that describes the OpenSearch resources. Each instance additionally requires
a service overhead budget with requests of 100m CPU / 128Mi memory and limits
of 500m CPU / 256Mi memory.
Must pass validation according to the sizingPolicies of the corresponding class:
spec:
instance:
cpu:
cores: 2
coreFraction: "100%"
memory:
size: "4Gi"
persistentVolumeClaim:
size: "10Gi"
# storageClassName: local-pathpersistentVolumeClaim and its size are required; there is no default size.
Existing sizes are preserved; volumes can only be expanded.
TLS
Server-side TLS settings. When spec.tls is specified, mode is required and has no default:
CertManager— certificate is issued and managed by cert-manager.CustomCertificate— a user-provided TLS certificate from a Secret is used.
spec:
tls:
mode: CertManager
certManager:
clusterIssuerName: my-issuerClient certificates
spec.mTLS configures client certificate verification and requires spec.tls.
Only ConnectionOnly is supported: the client certificate is optional and does not
replace username/password authentication. ConnectionAndAuth is not yet supported.
Users and roles
spec.users lists the OpenSearch users managed through this resource.
Each user gets exactly one predefined role and a password from exactly one source:
hashedPassword— the user password hash in bcrypt format;storeCredsToSecret— the operator generates a password and publishes akubernetes.io/basic-authSecret withusername,password,hostandportin the instance namespace. The Secret cannot be edited by hand; delete it to get a new password;secretRef— an existing Secret in the same namespace holding the plaintext password (keypasswordby default).
Roles
| Role | Permissions | Purpose |
|---|---|---|
ReadOnly |
read and search any index | consumers of data |
ReadWrite |
read and write any index, create and manage indices and templates, manage users within these roles | applications |
Monitoring |
cluster and index statistics (_cluster/health, _nodes/stats, _stats), no documents |
metric collection |
Behavior
- If a referenced Secret or key is missing, the corresponding user is not created or updated until the credentials are available. An existing user keeps their last working password.
- A password change in the Secret is applied to the user; a user removed from
spec.usersis deleted from OpenSearch. Users created directly through the OpenSearch API and not listed inspec.usersare left untouched. - An existing user added to
spec.usersis taken under management, and their role and password are set to the declared values. ReadWriteusers may manage API-created users through_plugins/_security/api/internalusers, assigning only the predefined roles viabackend_roles. They cannot change roles, role mappings, or security settings._plugins/_security/api/accountprovides account information. Password self-service applies to API-created users not declared inspec.users. Manage declared users’ passwords through their selected password source.- Names
admin,observabilityand names starting withd8-are reserved.
Use the instance’s Kubernetes Service for application connections and authenticate with the application’s declared user.
Warning. Instances that ran without TLS before this release accepted requests without credentials. For the transition period such instances keep anonymous access on: requests without credentials get full access, as before. This will be disabled in a future release together with the
adminaccount; declare users now. New instances, and instances that had TLS enabled before the upgrade, require authentication from the start. Existingadmincredentials remain valid during the transition period; application users should be declared inspec.users. Enabling TLS on a migrated instance does not disable its anonymous access.Every instance with an empty
spec.usersraises theManagedOpensearchInstanceWithoutUsersalert (severity 7) after 15 minutes. The release that removes theadminaccount and anonymous access does not install while such an instance exists.
spec:
users:
- name: app
role: ReadWrite
storeCredsToSecret: app-creds
- name: reporting
role: ReadOnly
secretRef:
name: reporting-password
- name: exporter
role: Monitoring
hashedPassword: "$2y$12$2zLV96rRJu6Rqgsj7fjyyeJaHfs8vPnSF3vpQ/oRFtEf7hFl8BuTW"Monitoring
Built-in monitoring credentials are managed automatically; no monitoring user needs
to be added to spec.users. Declare application users separately.
Plugins
Every instance includes the following plugins, with versions matched to the OpenSearch release:
opensearch-security— authentication and authorization; always on (see “Users and roles”).analysis-icu— Unicode text analysis: theicu_analyzer, theicu_tokenizerwith dictionary-based segmentation for CJK and Thai, theicu_normalizerandicu_foldingfilters, theicu_collation_keywordfield type for locale-aware sorting, and theicu_transformfilter for transliteration.opensearch-custom-codecs— Zstandard compression of stored index fields through thezstdandzstd_no_dictcodecs.
The ICU analysis components are available in every index without additional installation. For example, an index whose text field folds accents and case and splits CJK text by words:
PUT /articles
{
"settings": {
"analysis": {
"analyzer": {
"folded": {
"tokenizer": "icu_tokenizer",
"filter": ["icu_folding"]
}
}
}
},
"mappings": {
"properties": {
"body": { "type": "text", "analyzer": "folded" }
}
}
}The installed plugins and their versions are listed by GET /_cat/plugins?v.
Index compression
The default index codec is unchanged. To opt into Zstandard compression, set index.codec
when creating an index or in an index template:
PUT /compressed-articles
{
"settings": {
"index.codec": "zstd",
"index.codec.compression_level": 3
}
}Use zstd_no_dict to disable dictionary compression. Both codecs support compression levels
from 1 to 6; higher levels favor smaller storage over compression speed.
Intel QAT acceleration and the qat_* codecs are not supported by the module.
Installing the plugin does not rewrite existing indexes. Once an index uses a custom codec, keep compatible codec support when upgrading, rolling back, or restoring snapshots to another cluster; an image without the plugin cannot read those segments.
Observability
Instance monitoring mode:
Enabled— full monitoring with alerts (default).Disabled— monitoring disabled.EnabledWithoutAlerts— monitoring without alerts.
spec:
observability: EnabledStatus
The service status is reflected in the Opensearch resource.
The Conditions structure shows the current state of the service.
Significant types:
ConfigurationValid— shows whether the configuration passed all validations of the associatedOpensearchClass.LastValidConfigurationApplied— shows whether the last valid configuration was successfully applied.ScaledToLastValidConfiguration— shows whether the number of running replicas matches the specified configuration.Available— shows whether the Opensearch instance is running and accepting connections.
conditions:
- lastTransitionTime: '2026-06-01T12:00:00Z'
observedGeneration: 1
status: 'True'
type: Available
- lastTransitionTime: '2026-06-01T11:58:00Z'
observedGeneration: 1
status: 'True'
type: ConfigurationValid
- lastTransitionTime: '2026-06-01T11:59:00Z'
observedGeneration: 1
status: 'True'
type: LastValidConfigurationApplied
- lastTransitionTime: '2026-06-01T12:00:00Z'
observedGeneration: 1
status: 'True'
type: ScaledToLastValidConfigurationA False status indicates a problem or incomplete state synchronization.
In such cases, reason and message with a description will be specified:
- lastTransitionTime: '2026-06-01T11:59:00Z'
message: Not all the instances are running, still waiting for 1 to become ready
observedGeneration: 1
reason: ScalingInProgress
status: 'False'
type: ScaledToLastValidConfigurationUsage Examples
Basic Usage (HTTP)
-
Create a namespace:
kubectl create ns opensearch-ns -
Create an
Opensearchresource with an application user. The operator will generate the user’s credentials in theapp-credsSecret specified bystoreCredsToSecret:kubectl apply -f opensearch.yaml -n opensearch-nsapiVersion: managed-services.deckhouse.io/v1alpha1 kind: Opensearch metadata: name: my-opensearch spec: opensearchClassName: default users: - name: app role: ReadWrite storeCredsToSecret: app-creds instance: cpu: cores: 2 coreFraction: "100%" memory: size: "4Gi" persistentVolumeClaim: size: "10Gi" -
Wait until all conditions become
True:kubectl get opensearch my-opensearch -n opensearch-ns -o wide -w -
Check that the generated credentials Secret exists. It contains the application user’s
usernameandpassword:kubectl get secret app-creds -n opensearch-ns -
Verify the service is available. Without
spec.tls, connections use HTTP without encryption, but authentication is still required:kubectl port-forward -n opensearch-ns svc/d8ms-osch-my-opensearch 9200:9200In another terminal, read the generated credentials and send an authenticated request:
OPENSEARCH_USER=$(kubectl get secret app-creds -n opensearch-ns -o jsonpath='{.data.username}' | base64 -d) OPENSEARCH_PASSWORD=$(kubectl get secret app-creds -n opensearch-ns -o jsonpath='{.data.password}' | base64 -d) curl -u "$OPENSEARCH_USER:$OPENSEARCH_PASSWORD" 'http://localhost:9200/_cluster/health?pretty'Expected result:
"status": "green"or"yellow"(single-node).
Deployment with TLS (cert-manager)
-
Create a namespace:
kubectl create ns opensearch-tls -
Create an
Opensearchresource with TLS and an application user. The operator will generate the user’s credentials in theapp-credsSecret in this namespace:kubectl apply -f opensearch-tls.yaml -n opensearch-tlsapiVersion: managed-services.deckhouse.io/v1alpha1 kind: Opensearch metadata: name: my-opensearch spec: opensearchClassName: default users: - name: app role: ReadWrite storeCredsToSecret: app-creds instance: cpu: cores: 2 coreFraction: "100%" memory: size: "4Gi" persistentVolumeClaim: size: "10Gi" tls: mode: CertManager certManager: clusterIssuerName: letsencrypt -
Wait until all conditions become
True:kubectl get opensearch my-opensearch -n opensearch-tls -o wide -w -
Forward the HTTPS port:
kubectl port-forward -n opensearch-tls svc/d8ms-osch-my-opensearch 9200:9200In another terminal, read the generated credentials and verify availability via HTTPS:
OPENSEARCH_USER=$(kubectl get secret app-creds -n opensearch-tls -o jsonpath='{.data.username}' | base64 -d) OPENSEARCH_PASSWORD=$(kubectl get secret app-creds -n opensearch-tls -o jsonpath='{.data.password}' | base64 -d) curl -k -u "$OPENSEARCH_USER:$OPENSEARCH_PASSWORD" 'https://localhost:9200/_cluster/health?pretty'