OpenSearch Kubernetes Operator Documentation

The operator provides the following capabilities for managing OpenSearch environments:

• Cluster Management: Deploy and manage clusters with multiple node pools and configure all node roles (e.g., cluster_manager, data, ingest, coordinating).
• Scaling & Upgrades: Scale cluster resources manually per node pool, perform rolling version upgrades with quorum-safe restarts, and perform online volume expansion for disk scaling.
• Dashboards: Deploy and configure OpenSearch Dashboards.
• Security & Plugins: Manage certificates with TLS hot reloading and install plugins during the bootstrap phase.
• Organization: Support for multi-namespace management across organizational boundaries.

The Data Integrity Testing Framework is a set of reusable components designed to verify that OpenSearch data remains intact during various cluster operations. It is composed of three main pillars:

1. TestDataManager: Manages the lifecycle of test data, including importing documents into indices and validating that they remain intact after operations.
2. ClusterOperations: Executes and monitors cluster-level changes such as scaling node pools, upgrading versions, or adding/removing node pools.
3. Test Scenarios: Pre-built suites that combine the above components to test specific workflows like upgrades or scaling.

This framework is primarily used within the functionaltests directory to ensure the operator maintains cluster stability.

All RBAC-related custom resources (OpensearchUser, OpensearchRole, and OpensearchUserRoleBinding) must include a reference to an OpenSearchCluster resource. This reference tells the operator which specific OpenSearch cluster to reconcile the settings against.

Safety Mechanism: To prevent orphaned objects or unexpected behavior, the OpenSearch cluster reference is stored in the resource's status field during the first reconciliation. If the cluster reference in the spec is changed on a subsequent operation, the reconciler will raise an error and refuse to proceed.

The operator detects configuration changes to trigger restarts using the following mechanisms:

• Config Files: The operator calculates a SHA1 hash of the file content and adds it as an annotation to the pods. A change in the hash signals a change in configuration.
• Environment Variables: Changes to the environment variable definitions trigger a restart.

Restart Behavior by Node Type:

• Non-data nodes: The Kubernetes StatefulSet controller handles the restart of these pods.
• Data nodes: The operator's rolling restart reconciler detects pending changes and performs a graceful rolling restart to ensure cluster stability.

Index State Management (ISM) policies allow you to define a state machine for your indices. A policy consists of:

• States: Each state has a name and a list of actions to execute upon entering that state.
• Transitions: Defines how to move between states. Each transition includes conditions and the stateName of the target state. If no transitions exist, the policy is considered complete and stops managing the index.

The ClusterSpec object defines the desired state of an OpenSearchCluster. It is a top-level configuration object that aggregates several specialized configuration blocks:

• general: General cluster configuration.
• confMgmt: Configuration for additional services (e.g., auto-scaling).
• bootstrap: Configuration for the initial cluster setup.
• dashboards: Configuration for OpenSearch Dashboards.
• security: Security settings.
• nodePools: An array of NodePool objects defining different types of nodes.
• initHelper: Configuration for initialization helpers.

type ClusterSpec struct {
	General     GeneralConfig
	ConfMgmt    ConfMgmt
	Bootstrap    BootstrapConfig
	Dashboards   DashboardsConfig
	Security     Security
	NodePools    []NodePool
	InitHelper   InitHelperConfig
}

To prevent unsupported cluster states, the upgrade reconciler enforces the following validation rules before starting any upgrade:

• No Downgrades: The target version must not be lower than the current version.
• Major Version Limit: The target version cannot be more than one major version ahead of the current version.
• Initialization Requirement: The cluster must be fully initialized before an upgrade can begin.

If these conditions are not met, the reconciler emits an error event and aborts the upgrade.

The operator follows the standard Kubernetes operator model using Custom Resources (CR) and Custom Resource Definitions (CRD).

Core Abstractions

• OpenSearchCluster: The primary resource used to specify an OpenSearch cluster deployment.
• OpensearchRole, OpensearchUser, and OpensearchUserRoleBinding: Resources for managing users and roles declaratively.

Reconciliation Lifecycle

1. Controller: Each CRD has a corresponding controller that watches the Kubernetes API for changes to its specific custom objects.
2. Reconcile Loop: When a change is detected (or via regular requeueing), the controller triggers a Reconcile method.
3. Orchestration: The main Reconcile method acts as an orchestrator, delegating specific tasks to various reconcilers (e.g., one reconciler manages Dashboards, another manages securityconfig).