Deploy StarRocks with Operator

このトピックでは、StarRocks Operator を使用して Kubernetes クラスター上で StarRocks クラスターのデプロイと管理を自動化する方法を紹介します。

注記

StarRocks k8s operator はレベル 2 オペレーターとして設計されています。レベル 2 オペレーターの機能について詳しくは、https://sdk.operatorframework.io/docs/overview/operator-capabilities/ を参照してください。

How it works

Before you begin

Create Kubernetes cluster

クラウド管理の Kubernetes サービス、例えば Amazon Elastic Kubernetes Service (EKS) や Google Kubernetes Engine (GKE) クラスター、または自己管理の Kubernetes クラスターを使用できます。

• Amazon EKS クラスターを作成する

  1. 以下のコマンドラインツールが環境にインストールされていることを確認します:
     1. AWS コマンドラインツール AWS CLI をインストールして設定します。
     2. EKS クラスターコマンドラインツール eksctl をインストールします。
     3. Kubernetes クラスターコマンドラインツール kubectl をインストールします。
  2. 次のいずれかの方法で EKS クラスターを作成します:
     1. eksctl を使用して EKS クラスターを迅速に作成する。
     2. AWS コンソールと AWS CLI を使用して EKS クラスターを手動で作成する。

• GKE クラスターを作成する

  GKE クラスターを作成する前に、すべての前提条件を完了してください。その後、Create a GKE cluster の指示に従って GKE クラスターを作成します。

• 自己管理の Kubernetes クラスターを作成する

  Bootstrapping clusters with kubeadm の指示に従って自己管理の Kubernetes クラスターを作成します。Minikube と Docker Desktop を使用して、最小限の手順でシングルノードのプライベート Kubernetes クラスターを作成できます。

Deploy StarRocks Operator

1. カスタムリソース StarRocksCluster を追加します。

   kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/starrocks.com_starrocksclusters.yaml

2. StarRocks Operator をデプロイします。デフォルトの設定ファイルまたはカスタム設定ファイルを使用して StarRocks Operator をデプロイできます。

   1. デフォルトの設定ファイルを使用して StarRocks Operator をデプロイします。

      kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml

      StarRocks Operator は starrocks ネームスペースにデプロイされ、すべてのネームスペース下のすべての StarRocks クラスターを管理します。

   2. カスタム設定ファイルを使用して StarRocks Operator をデプロイします。

      • StarRocks Operator をデプロイするために使用される設定ファイル operator.yaml をダウンロードします。

        curl -O https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/deploy/operator.yaml

      • 設定ファイル operator.yaml をニーズに合わせて修正します。

      • StarRocks Operator をデプロイします。

        kubectl apply -f operator.yaml

3. StarRocks Operator の実行状態を確認します。ポッドが Running 状態で、ポッド内のすべてのコンテナが READY であれば、StarRocks Operator は期待通りに動作しています。

   $ kubectl -n starrocks get pods
   NAME                                  READY   STATUS    RESTARTS   AGE
   starrocks-controller-65bb8679-jkbtg   1/1     Running   0          5m6s

NOTE

StarRocks Operator が配置されているネームスペースをカスタマイズする場合は、starrocks をカスタマイズしたネームスペースの名前に置き換える必要があります。

Deploy StarRocks Cluster

StarRocks が提供する サンプル設定ファイル を直接使用して、StarRocks クラスター（カスタムリソース StarRocks Cluster を使用してインスタンス化されたオブジェクト）をデプロイできます。例えば、starrocks-fe-and-be.yaml を使用して、3 つの FE ノードと 3 つの BE ノードを含む StarRocks クラスターをデプロイできます。

kubectl apply -f https://raw.githubusercontent.com/StarRocks/starrocks-kubernetes-operator/main/examples/starrocks/starrocks-fe-and-be.yaml

以下の表は、starrocks-fe-and-be.yaml ファイルのいくつかの重要なフィールドを説明しています。

Field	Description
Kind	オブジェクトのリソースタイプ。値は StarRocksCluster でなければなりません。
Metadata	メタデータ。以下のサブフィールドがネストされています: name: オブジェクトの名前。各オブジェクト名は同じリソースタイプのオブジェクトを一意に識別します。 namespace: オブジェクトが属するネームスペース。
Spec	オブジェクトの期待される状態。有効な値は starRocksFeSpec、starRocksBeSpec、および starRocksCnSpec です。

修正された設定ファイルを使用して StarRocks クラスターをデプロイすることもできます。サポートされているフィールドと詳細な説明については、api.md を参照してください。

StarRocks クラスターのデプロイには時間がかかります。この期間中、kubectl -n starrocks get pods コマンドを使用して StarRocks クラスターの起動状態を確認できます。すべてのポッドが Running 状態で、ポッド内のすべてのコンテナが READY であれば、StarRocks クラスターは期待通りに動作しています。

NOTE

StarRocks クラスターが配置されているネームスペースをカスタマイズする場合は、starrocks をカスタマイズしたネームスペースの名前に置き換える必要があります。

$ kubectl -n starrocks get pods
NAME                                  READY   STATUS    RESTARTS   AGE
starrocks-controller-65bb8679-jkbtg   1/1     Running   0          22h
starrockscluster-sample-be-0          1/1     Running   0          23h
starrockscluster-sample-be-1          1/1     Running   0          23h
starrockscluster-sample-be-2          1/1     Running   0          22h
starrockscluster-sample-fe-0          1/1     Running   0          21h
starrockscluster-sample-fe-1          1/1     Running   0          21h
starrockscluster-sample-fe-2          1/1     Running   0          22h

Note

長時間経過しても一部のポッドが起動しない場合は、kubectl logs -n starrocks <pod_name> を使用してログ情報を表示するか、kubectl -n starrocks describe pod <pod_name> を使用してイベント情報を表示して問題を特定できます。

Manage StarRocks Cluster

Access StarRocks Cluster

StarRocks クラスターのコンポーネントは、FE サービスなどの関連するサービスを通じてアクセスできます。サービスとそのアクセスアドレスの詳細な説明については、api.md および Services を参照してください。

NOTE

• デフォルトでは FE サービスのみがデプロイされます。BE サービスと CN サービスをデプロイする必要がある場合は、StarRocks クラスター設定ファイルで starRocksBeSpec と starRocksCnSpec を設定する必要があります。
• サービスの名前はデフォルトで <cluster name>-<component name>-service です。例えば、starrockscluster-sample-fe-service です。各コンポーネントの spec でサービス名を指定することもできます。

Access StarRocks Cluster from within Kubernetes Cluster

Kubernetes クラスター内からは、StarRocks クラスターは FE サービスの ClusterIP を通じてアクセスできます。

1. FE サービスの内部仮想 IP アドレス CLUSTER-IP とポート PORT(S) を取得します。

   $ kubectl -n starrocks get svc 
   NAME                                 TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                               AGE
   be-domain-search                     ClusterIP   None             <none>        9050/TCP                              23m
   fe-domain-search                     ClusterIP   None             <none>        9030/TCP                              25m
   starrockscluster-sample-fe-service   ClusterIP   10.100.162.xxx   <none>        8030/TCP,9020/TCP,9030/TCP,9010/TCP   25m

2. Kubernetes クラスター内から MySQL クライアントを使用して StarRocks クラスターにアクセスします。

   mysql -h 10.100.162.xxx -P 9030 -uroot

Access StarRocks Cluster from outside Kubernetes Cluster

Kubernetes クラスター外からは、FE サービスの LoadBalancer または NodePort を通じて StarRocks クラスターにアクセスできます。このトピックでは LoadBalancer を例として使用します:

1. コマンド kubectl -n starrocks edit src starrockscluster-sample を実行して StarRocks クラスター設定ファイルを更新し、starRocksFeSpec のサービスタイプを LoadBalancer に変更します。

   starRocksFeSpec:
     image: starrocks/fe-ubuntu:3.0-latest
     replicas: 3
     requests:
       cpu: 4
       memory: 16Gi
     service:            
       type: LoadBalancer # specified as LoadBalancer

2. FE サービスが外部に公開する IP アドレス EXTERNAL-IP とポート PORT(S) を取得します。

   $ kubectl -n starrocks get svc
   NAME                                 TYPE           CLUSTER-IP       EXTERNAL-IP                                                              PORT(S)                                                       AGE
   be-domain-search                     ClusterIP      None             <none>                                                                   9050/TCP                                                      127m
   fe-domain-search                     ClusterIP      None             <none>                                                                   9030/TCP                                                      129m
   starrockscluster-sample-fe-service   LoadBalancer   10.100.162.xxx   a7509284bf3784983a596c6eec7fc212-618xxxxxx.us-west-2.elb.amazonaws.com   8030:30629/TCP,9020:32544/TCP,9030:32244/TCP,9010:32024/TCP   129m               ClusterIP      None            <none>                                                                   9030/TCP                                                      23h

3. マシンホストにログインし、MySQL クライアントを使用して StarRocks クラスターにアクセスします。

   mysql -h a7509284bf3784983a596c6eec7fc212-618xxxxxx.us-west-2.elb.amazonaws.com -P9030 -uroot

Upgrade StarRocks Cluster

Upgrade BE nodes

次のコマンドを実行して、新しい BE イメージファイル（例: starrocks/be-ubuntu:latest）を指定します。

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"image":"starrocks/be-ubuntu:latest"}}}'

Upgrade FE nodes

次のコマンドを実行して、新しい FE イメージファイル（例: starrocks/fe-ubuntu:latest）を指定します。

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksFeSpec":{"image":"starrocks/fe-ubuntu:latest"}}}'

アップグレードプロセスには時間がかかります。kubectl -n starrocks get pods コマンドを実行してアップグレードの進行状況を確認できます。

Scale StarRocks cluster

Scale out BE cluster

次のコマンドを実行して、BE クラスターを 9 ノードにスケールアウトします。

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"replicas":9}}}'

Scale in BE cluster

BE ノードをスケールインする際には、一度に 1 つずつスケールインし、BEs 上のタブレットが再分配されるのを待つ必要があります。単一レプリカのテーブルがある場合、BE ノードをオフラインにすると、タブレットが再分配されない場合にデータが失われる可能性があります。

次のコマンドを実行して、10 BE ノードのクラスターを 9 にスケールインします。

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksBeSpec":{"replicas":9}}}'

スケールイン後、alive ステータスが false のノードを手動で削除する必要があります。

タブレットの再分配には時間がかかります。SHOW PROC '/statistic'; を実行して進行状況を確認できます。

Scale out FE cluster

次のコマンドを実行して、FE クラスターを 4 ノードにスケールアウトします。

kubectl -n starrocks patch starrockscluster starrockscluster-sample --type='merge' -p '{"spec":{"starRocksFeSpec":{"replicas":4}}}'

スケーリングプロセスには時間がかかります。kubectl -n starrocks get pods コマンドを使用してスケーリングの進行状況を確認できます。

Automatic scaling for CN cluster

コマンド kubectl -n starrocks edit src starrockscluster-sample を実行して、CN クラスターの自動スケーリングポリシーを設定します。CN のリソースメトリクスとして、平均 CPU 使用率、平均メモリ使用量、弾性スケーリングのしきい値、上限弾性スケーリング制限、および下限弾性スケーリング制限を指定できます。上限弾性スケーリング制限と下限弾性スケーリング制限は、弾性スケーリングに許可される CN の最大数と最小数を指定します。

NOTE

CN クラスターの自動スケーリングポリシーが設定されている場合、StarRocks クラスター設定ファイルの starRocksCnSpec から replicas フィールドを削除してください。

Kubernetes はまた、ビジネスシナリオに応じてスケーリング動作をカスタマイズするために behavior を使用することをサポートしており、迅速または遅いスケーリングを実現したり、スケーリングを無効にしたりするのに役立ちます。自動スケーリングポリシーの詳細については、Horizontal Pod Scaling を参照してください。

以下は、StarRocks が提供する自動スケーリングポリシーを設定するためのテンプレートです。

  starRocksCnSpec:
    image: starrocks/cn-ubuntu:latest
    limits:
      cpu: 16
      memory: 64Gi
    requests:
      cpu: 16
      memory: 64Gi
    autoScalingPolicy: # CN クラスターの自動スケーリングポリシー。
      maxReplicas: 10 # CN の最大数を 10 に設定します。
      minReplicas: 1 # CN の最小数を 1 に設定します。
      # operator は以下のフィールドに基づいて HPA リソースを作成します。
      # 詳細については、https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/ を参照してください。
      hpaPolicy:
        metrics: # リソースメトリクス
          - type: Resource
            resource:
              name: memory  # CN の平均メモリ使用量をリソースメトリクスとして指定します。
              target:
                # 弾性スケーリングのしきい値は 60% です。
                # CN の平均メモリ使用率が 60% を超えると、スケールアウトのために CN の数が増加します。
                # CN の平均メモリ使用率が 60% 未満になると、スケールインのために CN の数が減少します。
                averageUtilization: 60
                type: Utilization
          - type: Resource
            resource:
              name: cpu # CN の平均 CPU 使用率をリソースメトリクスとして指定します。
              target:
                # 弾性スケーリングのしきい値は 60% です。
                # CN の平均 CPU 使用率が 60% を超えると、スケールアウトのために CN の数が増加します。
                # CN の平均 CPU 使用率が 60% 未満になると、スケールインのために CN の数が減少します。
                averageUtilization: 60
                type: Utilization
        behavior: # ビジネスシナリオに応じてスケーリング動作をカスタマイズし、迅速または遅いスケーリングを実現したり、スケーリングを無効にしたりします。
          scaleUp:
            policies:
              - type: Pods
                value: 1
                periodSeconds: 10
          scaleDown:
            selectPolicy: Disabled

以下の表は、いくつかの重要なフィールドを説明しています。

• 上限と下限の弾性スケーリング制限。

maxReplicas: 10 # CN の最大数を 10 に設定します。
minReplicas: 1 # CN の最小数を 1 に設定します。

• 弾性スケーリングのしきい値。

# 例えば、CN の平均 CPU 使用率をリソースメトリクスとして指定します。
# 弾性スケーリングのしきい値は 60% です。
# CN の平均 CPU 使用率が 60% を超えると、スケールアウトのために CN の数が増加します。
# CN の平均 CPU 使用率が 60% 未満になると、スケールインのために CN の数が減少します。
- type: Resource
  resource:
    name: cpu
    target:
      averageUtilization: 60

FAQ

問題の説明: カスタムリソース StarRocksCluster を kubectl apply -f xxx を使用してインストールすると、The CustomResourceDefinition 'starrocksclusters.starrocks.com' is invalid: metadata.annotations: Too long: must have at most 262144 bytes というエラーが返されます。

原因の分析: kubectl apply -f xxx を使用してリソースを作成または更新するたびに、メタデータ注釈 kubectl.kubernetes.io/last-applied-configuration が追加されます。このメタデータ注釈は JSON 形式で、last-applied-configuration を記録します。kubectl apply -f xxx はほとんどのケースに適していますが、カスタムリソースの設定ファイルが大きすぎる場合など、まれな状況ではメタデータ注釈のサイズが制限を超える可能性があります。

解決策: カスタムリソース StarRocksCluster を初めてインストールする場合は、kubectl create -f xxx を使用することをお勧めします。環境にすでにカスタムリソース StarRocksCluster がインストールされていて、その設定を更新する必要がある場合は、kubectl replace -f xxx を使用することをお勧めします。