Kubernetes环境OpenSearch部署与应用

概述

本文用于整理基于Kubernetes环境的OpenSearch部署与应用，实现Elasticsearch OSS兼容的文档索引检索服务，作为后续演练项目的前置环境准备。

随着各相关组件版本的更新，笔者将在验证通过后对本文进行补充和更新，请参考更新记录。

本次演练环境为Kubernetes集群环境，环境配置可参考笔者另一篇笔记《Kubernetes集群部署笔记》。

本次演练使用Traefik作为Ingress Controller实现，环境配置可参考笔者另一篇笔记《Kubernetes环境Traefik部署与应用》。

组件版本

• OpenSearch v3.1.0

• OpenSearch Helm Charts v3.1.0

• OpenSearch Dashboards v3.1.0

• OpenSearch Dashboards Helm Charts v3.1.0

• Filebeat OSS v7.12.1

配置过程

准备工作

• 调整节点系统参数

  在Kubernetes集群所有工作节点上执行如下操作。

  # https://opensearch.org/docs/2.19/install-and-configure/install-opensearch/index/#important-settings
  cat <<EOF | sudo tee /etc/sysctl.d/99-vm-max_map_count.conf > /dev/null
  vm.max_map_count = 524288
  EOF
  
  sudo sysctl --system

• 添加Helm仓库

  添加用于安装OpenSearch和OpenSearch Dashboards的Helm仓库。

  helm repo add opensearch https://opensearch-project.github.io/helm-charts/
  helm repo update opensearch

• 创建命名空间

  本次演练中将OpenSearch安装至data-opensearch命名空间，可根据需要替换。

  kubectl create namespace data-opensearch

• 创建TLS证书Secret

  从已准备好的证书key文件和crt文件创建Secret。

  kubectl create secret tls local-choral-io-tls -n data-opensearch \
    --key=local.choral.io.key --cert=local.choral.io.crt

安装OpenSearch

• 创建预置用户

  创建internal_users.yml，包含下列预置用户信息：

  • admin : Xa6lr8j4ZYmh9Bq6xSYlk9MN
  • kibanaserver : sNZrllLnoBZgmaZn4b5pInnT
  • logstash : LhKrXnx5w2FT1qsPx4GiPDsL

  注：文档中hash字段的值为密码通过Bcrypt算法生成的哈希值。

  # https://opensearch.org/docs/2.19/security/configuration/yaml/#internal_usersyml
  _meta:
    type: "internalusers"
    config_version: 2
  
  admin:
    hash: "$2a$12$z6ook.e3UpLIXKcNR6MLT.pwz4XCYKXE4FrNQW9ofT5SjnFQKMJ2W" # Xa6lr8j4ZYmh9Bq6xSYlk9MN
    reserved: true
    backend_roles:
      - "admin"
  
  kibanaserver:
    hash: "$2a$12$cVhs1VYUhv7DC4YvRMdAk.GKS.YluXB3wmSZ4DmfhP4wJAmftirEu" # sNZrllLnoBZgmaZn4b5pInnT
    reserved: true
  
  logstash:
    hash: "$2a$12$y4/DbsUDpajUVQWOpO1Vl.iBaCq6rCsmdCwu8pP3JC.AECViempEe" # LhKrXnx5w2FT1qsPx4GiPDsL
    reserved: false
    backend_roles:
      - "logstash"

  创建包含上述文件的Secret对象。

  kubectl create secret --namespace data-opensearch generic opensearch-security-secrets \
    --from-file=internal_users.yml=internal_users.yml

• 创建helm-opensearch.yaml

  首先，创建OpenSearch的安装配置文件。

  image:
    repository: quay.io/choral-k8s/opensearch
  extraEnvs:
    - name: plugins.security.ssl.http.enabled
      value: "false" # HTTP服务禁用SSL
  persistence:
    image: quay.io/choral-k8s/busybox # 替换busybox镜像地址
    storageClass: "local-path" # 指定存储类，可根据需要替换
  securityConfig:
    path: /usr/share/opensearch/config/opensearch-security # 指定Security插件的配置目录
    internalUsersSecret: opensearch-security-secrets # 包含预置用户配置文件的Secret名称
  ingress:
    enabled: true # 启用Ingress
    ingressClassName: traefik # 指定IngressClass，可根据需要替换
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure # 仅限HTTPS访问
    hosts:
      - opensearch.local.choral.io # 服务对外访问主机名
    tls:
      - secretName: local-choral-io-tls # 提供TLS证书的Secret名称

• 安装OpenSearch

  helm pull opensearch/opensearch --version v3.1.0
  helm upgrade --install opensearch --namespace data-opensearch \
    --values helm-opensearch.yaml \
    opensearch-3.1.0.tgz

• 查看集群信息

  使用admin用户的用户名和密码做HTTP Basic认证，访问OpenSearch服务，获取服务基本信息，验证服务是否可用。

  curl -XGET https://opensearch.local.choral.io -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN'

  上面的命令会输出类似下面的内容。

  {
    "name": "opensearch-cluster-master-0",
    "cluster_name": "opensearch-cluster",
    "cluster_uuid": "bfalHqPIR5GJTSgZkZJAyA",
    "version": {
      "distribution": "opensearch",
      "number": "3.1.0",
      "build_type": "tar",
      "build_hash": "8ff7c6ee924a49f0f59f80a6e1c73073c8904214",
      "build_date": "2025-06-21T08:05:43.345081313Z",
      "build_snapshot": false,
      "lucene_version": "10.2.1",
      "minimum_wire_compatibility_version": "2.19.0",
      "minimum_index_compatibility_version": "2.0.0"
    },
    "tagline": "The OpenSearch Project: https://opensearch.org/"
  }

设置兼容模式（可选）

注意：自OpenSearch 3.x已经不再支持兼容模式，本节内容仅适用于OpenSearch 2.x版本。

为了与Filebeat OSS、Logstash OSS等组件兼容，需要设置OpenSearch为兼容模式。兼容模式下，OpenSearch服务会将版本报告为7.10.x。有关兼容模式的详细信息和兼容性矩阵，可访问OpenSearch文档中的这个页面了解更多。

• 查看当前设置

  使用admin用户的用户名和密码做HTTP Basic认证，访问OpenSearch服务，查看OpenSearch集群当前设置。

  curl -XGET https://opensearch.local.choral.io/_cluster/settings -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN'
  # {"persistent":{},"transient":{}}

• 设置兼容模式

  通过调用OpenSearch REST API添加兼容模式（compatibility.override_main_response_version）配置。

  curl -XPUT https://opensearch.local.choral.io/_cluster/settings -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN' \
    -H 'Content-Type: application/json' \
    -d '{"persistent":{"compatibility":{"override_main_response_version":true}}}'
  # {"acknowledged":true,"persistent":{"compatibility":{"override_main_response_version":"true"}},"transient":{}}

• 检查设置生效

  再次查看OpenSearch集群的设置，检查兼容模式（compatibility.override_main_response_version）是否已经启用。

  curl -XGET https://opensearch.local.choral.io/_cluster/settings -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN'
  # {"persistent":{"compatibility":{"override_main_response_version":"true"},"plugins":{"index_state_management":{"template_migration":{"control":"-1"}}}},"transient":{}}

  再次查看集群基本信息。

  curl -XGET https://opensearch.local.choral.io -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN'

  上面的命令会输出类似下面的内容。

  {
    "name": "opensearch-cluster-master-0",
    "cluster_name": "opensearch-cluster",
    "cluster_uuid": "bfalHqPIR5GJTSgZkZJAyA",
    "version": {
      "number": "7.10.2",
      "build_type": "tar",
      "build_hash": "e0ba5eebfa3f060fc76e4e2b5b61193a19470d4f",
      "build_date": "2025-04-29T20:06:33.471315233Z",
      "build_snapshot": false,
      "lucene_version": "9.12.1",
      "minimum_wire_compatibility_version": "7.10.0",
      "minimum_index_compatibility_version": "7.0.0"
    },
    "tagline": "The OpenSearch Project: https://opensearch.org/"
  }

  通过对比可以发现，version.distribution已经被移除，version.number由2.19.2变为7.10.2，说明兼容模式生效。

安装OpenSearch Dashboards

本次演练中将OpenSearch Dashboards安装至data-opensearch命名空间，可根据需要替换。

• 创建OpenSearch认证凭据

  创建包含kibanaserver用户认证信息的Secret对象。

  # cookie=                            会创建名为`COOKIE_PASS`的环境变量，查遍了文档和源码也没找到这个变量是干嘛用的，但Secret中没有这个Key会报错，暂时先这样😥
  # username=kibanaserver              `kibanaserver`用户的用户名
  # password=sNZrllLnoBZgmaZn4b5pInnT  `kibanaserver`用户的密码
  kubectl create secret --namespace data-opensearch generic opensearch-dashboards-credentials \
    --from-literal=cookie= \
    --from-literal=username=kibanaserver \
    --from-literal=password=sNZrllLnoBZgmaZn4b5pInnT

• 创建helm-opensearch-dashboards.yaml

  image:
    repository: quay.io/choral-k8s/opensearch-dashboards
  extraEnvs:
    - name: SERVER_BASEPATH
      value: "/_dashboards" # 设置OpenSearch Dashboards服务的访问路径
    - name: SERVER_REWRITEBASEPATH
      value: "true"
  opensearchHosts: "http://opensearch-cluster-master:9200" # 设置OpenSearch服务的地址
  opensearchAccount:
    secret: opensearch-dashboards-credentials # 包含`kibanaserver`用户认证信息的`Secret`名称
  ingress:
    enabled: true # 启用Ingress
    ingressClassName: traefik # 指定IngressClass，可根据需要替换
    annotations:
      traefik.ingress.kubernetes.io/router.entrypoints: websecure # 仅限HTTPS访问
    hosts:
      - host: opensearch.local.choral.io # 服务对外访问主机名
        paths:
          - path: /_dashboards # 服务对外访问路径前缀
            backend: {} # 空对象，没什么用，查看了charts的源码，不这样会报错😥
    tls:
      - secretName: local-choral-io-tls # 提供TLS证书的Secret名称

• 安装OpenSearch Dashboards

  helm pull opensearch/opensearch-dashboards --version v3.1.0
  helm upgrade --install opensearch-dashboards --namespace data-opensearch \
    --values helm-opensearch-dashboards.yaml \
    opensearch-dashboards-3.1.0.tgz
  # ...
  # NOTES:
  # 1. Get the application URL by running these commands:
  #   https://opensearch.local.choral.io/_dashboards

  使用浏览器打开上述命令输出中的链接，访问OpenSearch Dashboards界面。

采集Kubernetes集群日志

注意：自OpenSearch 3.x已经不再支持兼容模式，本节内容仅适用于OpenSearch 2.x版本。

作为OpenSearch文档存储和检索的应用案例，笔者将部署以DeamonSet模式运行的Filebeat组件来采集Kubernetes集群产生的日志文档，并保存至OpenSearch中。

使用Filebeat OSS连接到OpenSearch，需要配置兼容模式，可参考设置兼容模式一节。

• 创建包含OpenSearch认证凭据的Secret对象

  kubectl create secret -n kube-system generic opensearch-logstash-credentials \
    --from-literal=username=logstash --from-literal=password=LhKrXnx5w2FT1qsPx4GiPDsL

• 创建helm-filebeat.yaml

  image: docker.elastic.co/beats/filebeat-oss # 指定镜像仓库，使用开源版本
  extraEnvs:
    - name: ELASTICSEARCH_USERNAME # 设置环境变量，从指定的Secret中引用用户名
      valueFrom:
        secretKeyRef:
          key: username
          name: opensearch-logstash-credentials
    - name: ELASTICSEARCH_PASSWORD # 设置环境变量，从指定的Secret中引用密码
      valueFrom:
        secretKeyRef:
          key: password
          name: opensearch-logstash-credentials
  tolerations:
    - effect: NoSchedule # 允许在control-plane节点中运行
      key: node-role.kubernetes.io/control-plane
      operator: Equal
  filebeatConfig:
    filebeat.yml: | # 配置文件`filebeat.yml`
      filebeat.autodiscover: # 启用自动发现
        providers:
          - type: kubernetes
            node: ${NODE_NAME}
            hints.enabled: true # 启用Hints
            hints.default_config: # Hints默认配置
              type: container # 类型：容器
              paths:
                - /var/log/containers/*${data.kubernetes.container.id}.log # 日志位置
      processors: # 添加处理程序
        - add_cloud_metadata: # 添加云服务信息
        - add_host_metadata: # 添加主机信息
      output.elasticsearch: # 输出至Elasticsearch服务（这里实际上是OpenSearch服务）
        host: "${NODE_NAME}"
        hosts: ["opensearch-cluster-master.data-opensearch:9200"] # 指定Elasticsearch服务主机
        protocol: http # 连接协议
        username: "${ELASTICSEARCH_USERNAME}" # Elasticsearch服务的用户名
        password: "${ELASTICSEARCH_PASSWORD}" # Elasticsearch服务的密码
        max_bytes: 10485760 # 最大传输字节数
        index: "filebeat-%{[agent.version]}-%{[kubernetes.namespace]:default}-%{+YYYY.MM.dd}" # 修改索引名称，日志文档按命名空间保存
        ilm.enabled: false # 禁用ILM（OpenSearch不支持）
      setup.ilm.enabled: false # 禁用ILM（OpenSearch不支持）
      setup.template.enabled: true # 启用索引模板
      setup.template.overwrite: true # 覆盖当前索引模板
      setup.template.name: "filebeat-%{[agent.version]}" # 索引模板名称
      setup.template.pattern: "filebeat-%{[agent.version]}-*" # 索引模板匹配规则
      setup.template.settings: # 索引模板设置
        index.number_of_shards: 1 # 设置分片数量
        index.number_of_replicas: 0 # 设置副本数量

• 添加Helm仓库

  添加用于安装Filebeat的Helm仓库。

  helm repo add elastic https://helm.elastic.co/
  helm repo update elastic

• 安装Filebeat

  helm pull elastic/filebeat --version 7.12.1
  helm upgrade --install filebeat --namespace kube-system \
    --values helm-filebeat.yaml \
    filebeat-7.12.1.tgz

• 验证日志索引成功

  curl -s -XGET https://opensearch.local.choral.io/_cat/indices?v -u 'admin:Xa6lr8j4ZYmh9Bq6xSYlk9MN'

  health status index                                      uuid                   pri rep docs.count docs.deleted store.size pri.store.size
  green  open   filebeat-7.12.1-kube-system-2022.09.05     s_Fh8F2BQcalMtJP3goSHQ   1   0        472            0    357.7kb        357.7kb
  green  open   filebeat-7.12.1-metallb-system-2022.09.05  jfIi7dMsRe-zTrRM119auQ   1   0        391            0    275.8kb        275.8kb
  green  open   filebeat-7.12.1-apps-choral-2022.09.06     7aWKDzwVTuCVjsGnMjDSAA   1   0        496            0    328.1kb        328.1kb
  ...

参考资料

• https://opensearch.org/docs/3.1/

• https://github.com/opensearch-project/helm-charts/tree/main/charts/opensearch

• https://github.com/opensearch-project/helm-charts/tree/main/charts/opensearch-dashboards

• https://github.com/opensearch-project/OpenSearch/issues/18228#issuecomment-2859241708

• https://github.com/opensearch-project/OpenSearch-Dashboards/blob/3.1/src/dev/build/tasks/os_packages/docker_generator/resources/bin/opensearch-dashboards-docker

• https://github.com/elastic/helm-charts/tree/main/filebeat