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: default

Instance

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-path

persistentVolumeClaim 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-issuer

Client 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 a kubernetes.io/basic-auth Secret with username, password, host and port in 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 (key password by 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.users is deleted from OpenSearch. Users created directly through the OpenSearch API and not listed in spec.users are left untouched.
  • An existing user added to spec.users is taken under management, and their role and password are set to the declared values.
  • ReadWrite users may manage API-created users through _plugins/_security/api/internalusers, assigning only the predefined roles via backend_roles. They cannot change roles, role mappings, or security settings.
  • _plugins/_security/api/account provides account information. Password self-service applies to API-created users not declared in spec.users. Manage declared users’ passwords through their selected password source.
  • Names admin, observability and names starting with d8- 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 admin account; declare users now. New instances, and instances that had TLS enabled before the upgrade, require authentication from the start. Existing admin credentials remain valid during the transition period; application users should be declared in spec.users. Enabling TLS on a migrated instance does not disable its anonymous access.

Every instance with an empty spec.users raises the ManagedOpensearchInstanceWithoutUsers alert (severity 7) after 15 minutes. The release that removes the admin account 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: the icu_analyzer, the icu_tokenizer with dictionary-based segmentation for CJK and Thai, the icu_normalizer and icu_folding filters, the icu_collation_keyword field type for locale-aware sorting, and the icu_transform filter for transliteration.
  • opensearch-custom-codecs — Zstandard compression of stored index fields through the zstd and zstd_no_dict codecs.

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: Enabled

Status

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 associated OpensearchClass.
  • 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: ScaledToLastValidConfiguration

A 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: ScaledToLastValidConfiguration

Usage Examples

Basic Usage (HTTP)

  1. Create a namespace:

    kubectl create ns opensearch-ns
  2. Create an Opensearch resource with an application user. The operator will generate the user’s credentials in the app-creds Secret specified by storeCredsToSecret:

    kubectl apply -f opensearch.yaml -n opensearch-ns
    apiVersion: 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"
  3. Wait until all conditions become True:

    kubectl get opensearch my-opensearch -n opensearch-ns -o wide -w
  4. Check that the generated credentials Secret exists. It contains the application user’s username and password:

    kubectl get secret app-creds -n opensearch-ns
  5. 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:9200

    In 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)

  1. Create a namespace:

    kubectl create ns opensearch-tls
  2. Create an Opensearch resource with TLS and an application user. The operator will generate the user’s credentials in the app-creds Secret in this namespace:

    kubectl apply -f opensearch-tls.yaml -n opensearch-tls
    apiVersion: 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
  3. Wait until all conditions become True:

    kubectl get opensearch my-opensearch -n opensearch-tls -o wide -w
  4. Forward the HTTPS port:

    kubectl port-forward -n opensearch-tls svc/d8ms-osch-my-opensearch 9200:9200

    In 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'