Link Search Menu Expand Document Documentation Menu
Documentation

OpenSearch Kubernetes Operator

The OpenSearch Kubernetes Operator is an open-source Kubernetes operator that helps automate the deployment and provisioning of OpenSearch and OpenSearch Dashboards in a containerized environment. The operator can manage multiple OpenSearch clusters that can be scaled up and down depending on your needs.

Installing the operator

The operator Helm chart installs a validation webhook whose certificate is issued by cert-manager, so cert-manager must be installed in your Kubernetes cluster before you install the operator. If cert-manager is not installed, the operator installation fails. For other options, see Webhooks.

To install the operator using Helm, follow these steps:

  1. Install cert-manager. First, add the cert-manager Helm repository:

    helm repo add jetstack https://charts.jetstack.io

    Then install cert-manager and its custom resource definitions:

    helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --set crds.enabled=true

  2. Add the operator Helm repository:

    helm repo add opensearch-operator https://opensearch-project.github.io/opensearch-k8s-operator/

  3. Update your local Helm chart information. If you added the repository previously, this step ensures that Helm installs the latest operator version:

    helm repo update

  4. Install the operator:

    helm install opensearch-operator opensearch-operator/opensearch-operator

Quickstart

After you have successfully installed the operator, you can deploy your first OpenSearch cluster by creating a custom OpenSearchCluster object in Kubernetes.

The following steps show you how to deploy a minimal cluster and are only intended for demonstration purposes. To learn how to configure and manage your cluster for production environments, see Configuration and management.

Follow these steps to deploy the cluster, verify that it is running, access it, and clean up resources when finished:

  1. Create a cluster.yaml file containing the following content:

     apiVersion: opensearch.org/v1
 kind: OpenSearchCluster
 metadata:
   name: my-first-cluster
   namespace: default
 spec:
   security:
     tls:
       transport:
         generate: true
       http:
         generate: true
   general:
     serviceName: my-first-cluster
     version: "3"
   dashboards:
     enable: true
     version: "3"
     replicas: 1
     resources:
       requests:
         memory: "512Mi"
         cpu: "200m"
       limits:
         memory: "512Mi"
         cpu: "200m"
   nodePools:
     - component: nodes
       replicas: 3
       diskSize: "5Gi"
       nodeSelector:
       resources:
         requests:
           memory: "2Gi"
           cpu: "500m"
         limits:
           memory: "2Gi"
           cpu: "500m"
       roles:
         - "cluster_manager"
         - "data"

    The version values must be quoted strings. The security.tls section is required: if you omit it, the OpenSearch pods never become ready. The security.tls section enables the Security plugin, and generate: true instructs the operator to generate self-signed TLS certificates. The operator also creates the my-first-cluster-admin-password and my-first-cluster-dashboards-password secrets containing randomly generated passwords. For more information, see TLS and User and role management.

  2. Create the cluster by running the following command:

     kubectl apply -f cluster.yaml

  3. (Optional) Monitor the cluster status by running the following command:

     watch -n 2 kubectl get pods

    The operator creates several pods:

    • A bootstrap pod (my-first-cluster-bootstrap-0) that helps with initial cluster manager discovery.
    • Three pods for the OpenSearch cluster (my-first-cluster-nodes-0, my-first-cluster-nodes-1, and my-first-cluster-nodes-2), named after the nodes node pool.
    • A pod for the OpenSearch Dashboards instance (my-first-cluster-dashboards-<id>).
    • A job pod (my-first-cluster-securityconfig-update-<id>) that applies the security configuration and then shows the Completed status.

    The cluster is ready when the three OpenSearch pods and the OpenSearch Dashboards pod show 1/1 in the READY column, which takes about 3 minutes. The operator then removes the bootstrap pod. You can now connect to your cluster using port forwarding.

  4. Retrieve the generated password for the admin user from the my-first-cluster-admin-password secret:

     kubectl get secret my-first-cluster-admin-password -o jsonpath='{.data.password}' | base64 -d; echo

  5. Access OpenSearch Dashboards or use the OpenSearch REST API:

    • To access OpenSearch Dashboards, start port forwarding by running the following command:

        kubectl port-forward svc/my-first-cluster-dashboards 5601

      Then go to http://localhost:5601 in your browser and log in as the admin user using the password that you retrieved in the previous step.

    • To use the OpenSearch REST API, start port forwarding by running the following command:

        kubectl port-forward svc/my-first-cluster 9200

      Then open a second terminal and run the following command, replacing <admin-password> with the password that you retrieved in the previous step:

        curl -k -u 'admin:<admin-password>' "https://localhost:9200/_cat/nodes?v"

      The response lists the three deployed nodes.

  6. To delete your cluster, run the following command:

     kubectl delete -f cluster.yaml

    This removes Kubernetes resources created by the operator but does not delete the persistent volumes. For a complete cleanup, delete the PVCs:

     kubectl delete pvc -l opensearch.org/opensearch-cluster=my-first-cluster

Single-node clusters are not supported. Your cluster must have at least 3 nodes with the master or cluster_manager role configured.

Configuration and management

After deploying your cluster, you can configure and manage it using the following guides:

Operator releases

Note the following about operator releases:

  • For a compatibility matrix of the operator and OpenSearch releases, see Compatibility.
  • The OpenSearch Operator User Guide in the repository corresponds to the current development state of the code. To view the documentation for a specific released version, switch to the version tag in the GitHub menu.
  • Feature requests are tracked as GitHub issues. If you would like a feature implemented and find a corresponding issue, note that an issue closed as completed means that the feature has been implemented in the development version. It may still take time before the feature is included in an official release. If you’re unsure, review the project’s release list on GitHub to see whether the feature appears in the release notes.

Next steps

Related documentation

350 characters left

Have a question? .

Want to contribute? or .