Cassandra のトラブルシューティング ガイド

ここに表示されているのは、ApigeeApigee ハイブリッドのドキュメントです。
このトピックに対応する Apigee Edge のドキュメントはありません。

このトピックでは、Cassandra データストアのトラブルシューティングと問題の修正の手順について説明します。Cassandra は、ハイブリッド ランタイム アーキテクチャcassandra コンポーネントで実行される永続データストアです。ランタイム サービス構成の概要もご覧ください。

Cassandra Pod がリリース状態のままになる

症状

Cassandra Pod の更新を試みた後、データストアがリリース状態のまま停止していると報告されます。

エラー メッセージ

kubectl を使用して Pod の状態を表示すると、1 つ以上の Cassandra Pod がリリース状態で停止していることがわかります。

Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Ack 57s (x7 over 24h) apigee-datastore release started

考えられる原因

Pod がリリース状態のままになる原因には、次のものが考えられます。

原因 説明
ストレージ容量の変更 override.yaml ファイルのストレージ容量を変更する手順が実行されました。
その他の構成の変更 override.yaml ファイルの cassandra プロパティを更新しましたが、変更が反映されませんでした。

ストレージ容量の変更

診断

  1. kubectl を使用して、apigee データストア Pod の現在の状態を確認します。
    kubectl get apigeeds -n apigee
    NAME STATE AGE
    default releasing 122d
  2. override.yaml ファイルに変更が加えられていないかどうかを確認します。
    1. バージョン管理システムを使用して、override.yaml ファイルの以前のバージョンと現在のバージョンを比較します。
      diff OVERRIDES_BEFORE.yaml OVERRIDES_AFTER.yaml
    2. override.yaml の差分出力に、ストレージ容量のサイズに関する問題が表示される可能性があります(例:
      # Overrides.yaml  before:
      cassandra:
         storage:
            capacity: 500Gi
      
      # Overrides.yaml after:
      cassandra:
         storage:
            capacity: 100Gi
      )。

      ストレージ容量を変更するオペレーションで手順がスキップされ、新しい override.yaml が直接適用された場合に、データストアがリリース状態になる可能性があります。

  3. statefulset を確認して、apigee-cassandra-default 用のものが 1 つあることを確認します。
    kubectl describe sts -n apigee

    出力は次のようになります。

    Name:               apigee-cassandra-default
    Namespace:          apigee
    CreationTimestamp:  Tue, 18 Jul 2023 00:40:57 +0000
    Selector:           app=apigee-cassandra,name=default
    Labels:             apigee.cloud.google.com.revision=v1-2cc098050836c6b4
                        apigee.cloud.google.com.version=v1
                        apigee.cloud.google.com/platform=apigee
                        app=apigee-cassandra
                        name=default
    Annotations:        <none>
    Replicas:           3 desired | 3 total
    Update Strategy:    RollingUpdate
      Partition:        0
    Pods Status:        3 Running / 0 Waiting / 0 Succeeded / 0 Failed
    Pod Template:
      Labels:       apigee.cloud.google.com/apigee_servicename=production
                    apigee.cloud.google.com/billing_type=subscription
                    apigee.cloud.google.com/platform=apigee
                    app=apigee-cassandra
                    name=default
                    revision=v1
                    runtime_type=hybrid
      Annotations:  apigee.cloud.google.com/pod-template-spec-hash: 2cc098050836c6b4
                    prometheus.io/path: /metrics
                    prometheus.io/port: 7070
                    prometheus.io/scheme: https
                    prometheus.io/scrape: true
      Containers:
       apigee-cassandra:
        Image:       gcr.io/apigee-release/hybrid/apigee-hybrid-cassandra:1.10.1
        Ports:       7000/TCP, 7001/TCP, 7199/TCP, 9042/TCP, 8778/TCP
        Host Ports:  7000/TCP, 7001/TCP, 7199/TCP, 9042/TCP, 8778/TCP
        Requests:
          cpu:      500m
          memory:   1Gi
        Readiness:  exec [/bin/bash -c /opt/apigee/ready-probe.sh] delay=0s timeout=5s period=10s #success=1 #failure=2
        Environment:
          POD_NAME:                  (v1:metadata.name)
          POD_IP:                    (v1:status.podIP)
          MAX_HEAP_SIZE:            512M
          HEAP_NEWSIZE:             100M
          CASSANDRA_SEEDS:          apigee-cassandra-default-0.apigee-cassandra-default.apigee.svc.cluster.local
          CASSANDRA_CLUSTER_NAME:   apigeecluster
          CASSANDRA_DC:             dc-1
          CASSANDRA_RACK:           ra-1
          CASSANDRA_OPEN_JMX:       true
          CPS_ADMIN_USER:           <set to the key 'admin.user' in secret 'apigee-datastore-default-creds'>        Optional: false
          CPS_ADMIN_PASSWORD:       <set to the key 'admin.password' in secret 'apigee-datastore-default-creds'>    Optional: false
          APIGEE_JMX_USER:          <set to the key 'jmx.user' in secret 'apigee-datastore-default-creds'>          Optional: false
          APIGEE_JMX_PASSWORD:      <set to the key 'jmx.password' in secret 'apigee-datastore-default-creds'>      Optional: false
          CASS_PASSWORD:            <set to the key 'default.password' in secret 'apigee-datastore-default-creds'>  Optional: false
          APIGEE_JOLOKIA_USER:      <set to the key 'jolokia.user' in secret 'apigee-datastore-default-creds'>      Optional: false
          APIGEE_JOLOKIA_PASSWORD:  <set to the key 'jolokia.password' in secret 'apigee-datastore-default-creds'>  Optional: false
        Mounts:
          /opt/apigee/apigee-cassandra/conf from appsfs (rw)
          /opt/apigee/customer from cwc-volume (ro)
          /opt/apigee/data from cassandra-data (rw)
          /opt/apigee/ssl from tls-volume (ro)
          /var/secrets/google from apigee-cassandra-backup (rw)
          /var/secrets/keys from apigee-cassandra-backup-key-file (rw)
      Volumes:
       cwc-volume:
        Type:        Secret (a volume populated by a Secret)
        SecretName:  config-cassandra-default
        Optional:    false
       tls-volume:
        Type:        Secret (a volume populated by a Secret)
        SecretName:  apigee-cassandra-default-tls
        Optional:    false
       appsfs:
        Type:       EmptyDir (a temporary directory that shares a pod's lifetime)
        Medium:
        SizeLimit:  <unset>
       apigee-cassandra-backup:
        Type:        Secret (a volume populated by a Secret)
        SecretName:  apigee-cassandra-backup-svc-account
        Optional:    true
       apigee-cassandra-backup-key-file:
        Type:        Secret (a volume populated by a Secret)
        SecretName:  apigee-cassandra-backup-key-file
        Optional:    true
    Volume Claims:
      Name:          cassandra-data
      StorageClass:
      Labels:        <none>
      Annotations:   <none>
      Capacity:      10Gi
      Access Modes:  [ReadWriteOnce]
    Events:
      Type    Reason            Age   From                    Message
      ----    ------            ----  ----                    -------
      Normal  SuccessfulCreate  47m   statefulset-controller  create Pod apigee-cassandra-default-2 in StatefulSet apigee-cassandra-default successful
    
  4. Apigee コントローラでエラーを確認します。
    kubectl logs -f apigee-controller-manager-59cf595c77-wtwnr -n apigee-system -c manager | grep apigeedatastore
    

    結果:

    "error creating
    apigee-cassandra object: failed to update resource
    apigee/apigee-cassandra-default: StatefulSet.apps \"apigee-cassandra-default\"
    is invalid: spec: Forbidden: updates to statefulset spec for fields other than
    'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy'
    and 'minReadySeconds' are forbiddenerror creating apigee-cassandra object:
    failed to update resource apigee/apigee-cassandra-default: StatefulSet.apps
    \"apigee-cassandra-default\" is invalid: spec: Forbidden: updates to statefulset
    spec for fields other than 'replicas', 'template', 'updateStrategy',
    'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden"
    

解決策

Cassandra の状態は、次の手順でリセットして実行状態に戻すことができます。

  1. apigee-controller を無効にします。
    kubectl -n apigee-system edit deployments and set --enable-controllers=true to --enable-controllers=false
    
  2. PATCH コマンドを使用して、データストアを実行状態に戻します。
    curl -XPATCH \-H "Accept: application/json" -H "Content-Type: application/json-patch+json" --data '[{"op": "replace", "path": "/status/nestedState", "value": ""},{"op": "replace", "path": "/status/state", "value": "running"}]' 'http://127.0.0.1:8001/apis/apigee.cloud.google.com/v1alpha1/namespaces/apigee/apigeedatastores/default/status'
    
  3. 元の override.yaml ファイルを再適用します。
    ./apigeectl apply --datastore -f overrides.yaml
    
  4. apigee-controller を有効にします。
    kubectl -n apigee-system edit deployments and set --enable-controllers=false to --enable-controllers=true
    
  5. データストアが復元されるまで待機し、次のコマンドを使用して検証します。
    kubectl get apigeeds --namespace apigee
    
  6. Apigee のデプロイと Pod が実行状態であり、apigeeds がリリース状態ではなくなっていることを確認します。
    kubectl get ad -n apigee
    
    kubectl get pods -n apigee
    
    kubectl get apigeeds -n apigee
    
    NAME      STATE     AGE
    default   running   24d
    

その他の構成の変更

override.yamlcassandra プロパティの更新を行いましたが、変更が反映されませんでした。パスワードの変更や、override.yaml のリソースの変更が考えられます。または、間違った override.yaml をクラスタに誤って適用したことが考えられます。

診断

診断の手順をご覧ください。

解決策

解決策の手順をご覧ください。

診断情報の収集が必要な場合

上記の手順でも問題が解決しない場合は、次の診断情報を収集して Google Cloud カスタマーケアに連絡してください。

  • インストール内の各クラスタの Overrides.yaml
  • ハイブリッド インストールの kubernetes cluster-info ダンプ:

    kubernetes cluster-info dump を生成します。

    kubectl cluster-info dump -A --output-directory=/tmp/kubectl-cluster-info-dump
    

    zip kubernetes cluster-info dump を使用して圧縮します。

    zip -r kubectl-cluster-info-dump`date +%Y.%m.%d_%H.%M.%S`.zip /tmp/kubectl-cluster-info-dump/*
    

Cassandra Pod が Pending 状態のままになる

症状

起動時の Cassandra Pod の状態が Pending のままです。

エラー メッセージ

kubectl を使用して Pod の状態を表示すると、1 つ以上の Cassandra Pod が Pending 状態で停止していることがわかります。Pending 状態は、Kubernetes がノード上の Pod をスケジュールできないことを示します。Pod を作成することはできません。次に例を示します。

kubectl get pods -n NAMESPACE

NAME                                     READY   STATUS      RESTARTS   AGE
adah-resources-install-4762w             0/4     Completed   0          10m
apigee-cassandra-default-0               0/1     Pending     0          10m
...

考えられる原因

Pod が保留状態のままになる原因は、いくつかあります。次に例を示します。

原因 説明
リソースの不足 Pod を作成するのに十分な CPU またはメモリがありません。
ボリュームが作成されていない Pod が永続ボリュームの作成を待機しています。
Amazon EBS CSI ドライバがない EKS インストールで、必要な Amazon EBS CSI ドライバがインストールされていません。

診断

kubectl を使用して Pod の状態を表示し、エラーの原因を特定します。次に例を示します。

kubectl -n NAMESPACE describe pods POD_NAME

次に例を示します。

kubectl describe pods apigee-cassandra-default-0 -n apigee

出力に次のいずれかの問題が表示されることがあります。

  • 十分なリソースがない場合は、CPU またはメモリの不足を示す警告メッセージが表示されます。
  • エラー メッセージに、Pod にバインドされていない即時 PersistentVolumeClaims(PVC)があることが示されている場合、その Pod は永続ボリュームを作成できません。

解決策

リソースの不足

Cassandra ノードプールを変更して、十分な CPU リソースとメモリリソースを確保します。詳細については、ノードプールのサイズを変更するをご覧ください。

永続ボリュームが作成されない

永続ボリュームの問題を特定する場合は、PersistentVolumeClaim(PVC)の状態を確認し、作成されない理由を特定します。

  1. クラスタ内の PVC を一覧表示します。
    kubectl -n NAMESPACE get pvc
    
    NAME                                        STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
    cassandra-data-apigee-cassandra-default-0   Bound    pvc-b247faae-0a2b-11ea-867b-42010a80006e   10Gi       RWO            standard       15m
    ...
  2. 障害が発生した Pod の PVC の情報を出力します。たとえば、次のコマンドは、Pod apigee-cassandra-default-0 にバインドされた PVC の情報を出力します:
    kubectl apigee describe pvc cassandra-data-apigee-cassandra-default-0
    
    Events:
      Type     Reason              Age                From                         Message
      ----     ------              ----               ----                         -------
      Warning  ProvisioningFailed  3m (x143 over 5h)  persistentvolume-controller  storageclass.storage.k8s.io "apigee-sc" not found

    この例では、apigee-sc という名前の StorageClass が存在しません。この問題を解決するには、デフォルトの StorageClass を変更するの説明に従って、不足している StorageClass をクラスタに作成します。

Pod のデバッグもご覧ください。

Amazon EBS CSI ドライバがない

ハイブリッド インスタンスが EKS クラスタで実行されている場合は、EKS クラスタが Amazon EBS コンテナ ストレージ インターフェース(CSI)ドライバを使用していることを確認します。詳しくは、Amazon EBS CSI の移行に関するよくある質問をご覧ください。

Cassandra Pod が CrashLoopBackoff 状態のままになる

症状

起動時の Cassandra Pod の状態が CrashLoopBackoff のままです。

エラー メッセージ

kubectl を使用して Pod の状態を表示すると、1 つ以上の Cassandra Pod が CrashLoopBackoff 状態になっていることがわかります。この状態は、Kubernetes が Pod を作成できないことを示しています。次に例を示します。

kubectl get pods -n NAMESPACE

NAME                                     READY   STATUS            RESTARTS   AGE
adah-resources-install-4762w             0/4     Completed         0          10m
apigee-cassandra-default-0               0/1     CrashLoopBackoff  0          10m
...

考えられる原因

Pod が CrashLoopBackoff 状態のままになる原因は、いくつかあります。次に例を示します。

原因 説明
データセンターが以前のデータセンターと異なる このエラーは、Cassandra Pod に以前のクラスタのデータが含まれた永続ボリュームがあり、新しい Pod が古いクラスタに参加できないことを示しています。これは通常、同じ Kubernetes ノードに以前の Cassandra クラスタの古い永続ボリュームが残っている場合に発生します。この問題は、クラスタで Cassandra を削除して再作成した場合に発生することがあります。
Kubernetes のアップグレード Kubernetes のアップグレードは、Cassandra クラスタに影響する場合があります。これは、Cassandra Pod をホストする Anthos ワーカーノードが新しい OS バージョンにアップグレードされた場合に発生します。

診断

問題の原因を特定するには、Cassandra のエラーログを確認してください。

  1. Pod を一覧表示して、失敗した Cassandra Pod の ID を取得します。
    kubectl get pods -n NAMESPACE
  2. 失敗した Pod のログを確認します。
    kubectl logs POD_ID -n NAMESPACE

解決策

Pod のログで次の手がかりを探します。

データセンターが以前のデータセンターと異なる

このログ メッセージが表示された場合:

Cannot start node if snitch's data center (us-east1) differs from previous data center
  • クラスタ内に最新ではない PVC があるかどうかを確認し、あれば削除します。
  • これが新規インストールの場合は、すべての PVC を削除して設定しなおします。例:
    kubectl -n NAMESPACE get pvc
    kubectl -n NAMESPACE delete pvc cassandra-data-apigee-cassandra-default-0

Anthos アップグレードがセキュリティ設定を変更する

Cassandra のログで次のエラー メッセージを確認します。

/opt/apigee/run.sh: line 68: ulimit: max locked memory:
  cannot modify limit: Operation not permitted

デバッグ用のクライアント コンテナを作成する

このセクションでは、cqlsh などの Cassandra デバッグ ユーティリティにアクセスできるクライアント コンテナを作成する方法について説明します。これらのユーティリティを使用すると、Cassandra テーブルに対してクエリを実行できるので、デバッグに役立ちます。

クライアント コンテナを作成する

クライアント コンテナを作成する手順は次のとおりです。

  1. コンテナは apigee-cassandra-user-setup Pod からの TLS 証明書を使用する必要があります。これは Kubernetes Secret として保存されます。この証明書を格納する Secret の名前を取得します:
    kubectl get secrets -n apigee --field-selector type=kubernetes.io/tls | grep apigee-cassandra-user-setup | awk '{print $1}'

    このコマンドは、Secret の名前を返します。例: apigee-cassandra-user-setup-rg-hybrid-b7d3b9c-tls。これは、下に示す YAML ファイルの secretName フィールドで使用します。

  2. 新しいファイルを開き、次の Pod 仕様を貼り付けます:
    apiVersion: v1
    kind: Pod
    metadata:
      labels:
      name: CASSANDRA_CLIENT_NAME   # For example: my-cassandra-client
      namespace: apigee
    spec:
      containers:
      - name: CASSANDRA_CLIENT_NAME
        image: "gcr.io/apigee-release/hybrid/apigee-hybrid-cassandra-client:YOUR_APIGEE_HYBRID_VERSION" # For example, 1.10.5.
        imagePullPolicy: Always
        command:
        - sleep
        - "3600"
        env:
        - name: CASSANDRA_SEEDS
          value: apigee-cassandra-default.apigee.svc.cluster.local
        - name: APIGEE_DML_USER
          valueFrom:
            secretKeyRef:
              key: dml.user
              name: apigee-datastore-default-creds
        - name: APIGEE_DML_PASSWORD
          valueFrom:
            secretKeyRef:
              key: dml.password
              name: apigee-datastore-default-creds
        volumeMounts:
        - mountPath: /opt/apigee/ssl
          name: tls-volume
          readOnly: true
      volumes:
      - name: tls-volume
        secret:
          defaultMode: 420
          secretName: YOUR_SECRET_NAME    # For example: apigee-cassandra-user-setup-rg-hybrid-b7d3b9c-tls
      restartPolicy: Never
  3. .yaml という拡張子を付けてファイルを保存します。例: my-spec.yaml
  4. クラスタに仕様を適用します:
    kubectl apply -f YOUR_SPEC_FILE.yaml -n apigee
  5. コンテナにログインします:
    kubectl exec -n apigee CASSANDRA_CLIENT_NAME -it -- bash
  6. 次のコマンドを使用して、Cassandra cqlsh インターフェースに接続します。次のコマンドを正確に入力します。
    cqlsh ${CASSANDRA_SEEDS} -u ${APIGEE_DML_USER} -p ${APIGEE_DML_PASSWORD} --ssl

クライアント Pod の削除

次のコマンドを使用して、Cassandra クライアント Pod を削除します。

kubectl delete pods -n apigee cassandra-client

正しく構成されていないリージョンの拡大: 1 つのデータセンター内のすべての Cassandra ノード

この状況は、GKE と GKE On-Prem(Anthos)のプラットフォームのマルチリージョン拡大で発生します。同じデータセンター内にすべての Cassandra ノードを作成しないようにしてください。

症状

2 番目のリージョンのデータセンターで Cassandra ノードの作成に失敗します。

エラー メッセージ

failed to rebuild from dc-1: java.lang.RuntimeException : Error while rebuilding node: Stream failed

解決策

正しく構成されていないリージョン拡大を次の手順で修復します。

  1. 2 番目のデータセンターの overrides.yaml ファイルで Cassandra replicaCount1 に更新します。例:
    cassandra:
      . . .
      replicaCount: 1

    apigeectl apply で設定を適用します。

    $APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml
  2. kubectl exec を使用し、次のコマンドで残りの Cassandra Pod にアクセスします:
    kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash
  3. 次のコマンドで、残りの Cassandra Pod を廃止します:
    nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD decommission
  4. --datastore 引数を指定した apigeectl delete を使用して、2 番目のデータセンターから Cassandra Pod を削除します。例:
    $APIGEECTL_HOME/apigeectl delete -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
  5. Kubernetes コンテキストを最初のデータセンターのクラスタに変更します:
    kubectl config use-context FIRST_DATACENTER_CLUSTER
  6. 最初のデータセンターにダウン状態の Cassandra ノードがないことを確認します。
    nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status
  7. 正しく構成されていない Cassandra ノード(2 番目のデータセンター用)が最初のデータセンターから削除されていることを確認します。nodetool ステータス出力に表示される IP アドレスが、最初のデータセンター用の Cassandra Pod の IP アドレスのみであることを確認します。たとえば、次の出力では、IP アドレス 10.100.0.39 は最初のデータセンターの Pod 用です。
    kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash
    nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status
    
      Datacenter: dc-1
      ================
      Status=U/D (Up/Down) | State=N/L/J/M (Normal/Leaving/Joining/Moving)
      --  Address      Load      Tokens  Owns (effective)  Host ID                               Rack
      UN  10.100.0.39  4.21 MiB  256     100.0%            a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d  ra-1
  8. 2 番目のデータセンターの overrides.yaml ファイルに、cassandra セクションのデータセンター名の設定が含まれていることを確認します。例:
    cassandra:
      datacenter: DATA_CENTER_2
      rack: "RACK_NAME" # "ra-1" is the default value.
      . . .
  9. 2 番目のデータセンターの overrides.yaml ファイルの cassandra:replicaCount 設定を目的の数値に更新します。例:
    cassandra:
      datacenter: DATA_CENTER_2
      . . .
      replicaCount: 3
  10. --datastore 引数を使用して、2 番目のデータセンターの overrides.yaml ファイルを適用します。例:
    $APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
  11. kubectl exec を使用して、2 番目のデータセンターにある新しい Cassandra Pod の一つにアクセスし、2 つのデータセンターがあることを確認します。
     "nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status"

補足資料

Apigee X と Apigee ハイブリッドのハンドブックの概要をご覧ください。