メインコンテンツまでスキップ

トラブルシューティング

このページでは、Platform as VM デプロイのよくある問題を一覧にまとめています。記載のない問題に直面した場合は、次の一般的な進め方を使用します。

  1. kubectl get pods -A を実行して、失敗している Pod を特定します。
  2. kubectl logs <pod> -n <namespace> --tail 200 を実行して、その出力を確認します。
  3. kubectl describe pod <pod> -n <namespace> を実行して、末尾の最近のイベントを確認します。

インストーラーの失敗​

このセクションでは、インストーラーの実行中に発生するエラーと停止について説明します。

「This playbook is only for RedHat-family systems」​

インストーラーがサポートするのは RHEL 系 9.x（RHEL 9、AlmaLinux 9、Rocky Linux 9）のみです。Ubuntu、Debian、SUSE はサポートされていません。サポート対象の OS で VM をプロビジョニングし直してください。要件 を参照してください。

このチェックは OS のファミリーのみを検査し、バージョンは確認しません。RHEL 系 8 や 10 では通常どおり開始され、後の工程で分かりにくい形で失敗する可能性があります。これらのバージョンは未検証かつサポート対象外です。

「Minimum 32 GB RAM required」/「Minimum 4 CPU cores required」​

VM のスペックが不足しています。継続する前に VM をリサイズしてください。回避策はありません。

RAM のチェックには、厳密な 32 GB よりわずかに低い値まで許容する余裕が設けられています。ハイパーバイザーやクラウドプロバイダーが公称値より少ない値を報告するためです。32 GB として提供された VM はチェックを通過します。16 GB の VM は通過しません。

sudo パスワードプロンプトで「Authentication failure」​

入力したパスワードが誤っているか、ユーザーに sudo 権限がありません。次のコマンドで確認します。

sudo -v

失敗する場合は、VM をプロビジョニングした担当者に sudo 権限の付与を依頼してください。

インストーラーが「Wait for K3s to be ready」で応答しなくなるのはなぜですか？​

K3s のダウンロード中、または API サーバーの起動が遅いだけのことが多いです。5 分待っても K3s の準備が完了しない場合は、別の SSH セッションを開いて確認します。

sudo systemctl status k3s
sudo journalctl -u k3s --no-pager --since "5 minutes ago"

最も多い原因は、VM から get.k3s.io への送信 HTTPS アクセスができないことです。プロキシまたはファイアウォールを修正し、インストーラーをもう一度実行してください。

インストーラーが「Helm install」で失敗するのはなぜですか？​

インストーラーの出力中の Helm エラーメッセージを確認します。典型的な原因は次のとおりです。

  • タイムアウト: チャートの Pod が時間内に Ready 状態にならない。kubectl get pods -n openlm-infrastructure を実行し、失敗している Pod のイベントを確認します。
  • ImagePullBackOff: VM がコンテナイメージレジストリに到達できない。public.ecr.aws と docker.io への送信 HTTPS を確認してください。
  • ディスク容量不足: df -h を実行し、/var/lib/rancher/k3s の領域を空けます。

根本原因を修正してから、./entrypoint.sh をもう一度実行します。playbook は各手順を再確認し、すでに完了している作業はスキップするため、再実行しても安全です。

インストール後の問題​

このセクションでは、インストーラーの完了後に発生する問題について説明します。

Pod が Pending のままになるのはなぜですか？​

次のコマンドを実行します。

kubectl describe pod <pod> -n openlm | tail -20

Events セクションを確認します。典型的な原因は次のとおりです。

  • メモリまたは CPU 不足: VM がオーバーサブスクライブされている。VM をリサイズするか、重要度の低いサービスをスケールダウンしてください。
  • PVC が Pending のまま: kubectl get pvc -n openlm-infrastructure。PVC が Pending の場合、ストレージクラスがプロビジョニングできません。kube-system 内で local-path-provisioner が稼働していることを確認してください。
  • ディスク不足: ノードがディスク圧迫状態にあり、スケジューラは新しい Pod を配置しません。df -h を確認し、VM のディスク容量を空けるにはどうすればよいですか？ を参照してください。
  • ノードアフィニティを満たせない: config.yaml で affinity_label_main_workload または affinity_label_reporting_workload を設定している場合、単一 VM デプロイには存在しないノードラベルを Pod が要求します。両方のフィールドを空にして、インストーラーをもう一度実行してください。

Pod が ImagePullBackOff のままになるのはなぜですか？​

次のコマンドを実行します。

kubectl describe pod <pod> -n openlm | grep -i image

そこに表示されるイメージタグが public.ecr.aws/r3q3q2f4/ 上に存在することを確認します。タグが正しいように見える場合、原因はネットワークの問題です。次のコマンドを実行します。

curl -I https://public.ecr.aws/r3q3q2f4/olm-server/manifests/latest 2>&1 | head -5

ここで TLS エラーやタイムアウトが返る場合、VM はレジストリに到達できていません。プロキシまたはファイアウォールを修正してください。

タグ自体が誤っている、または見覚えのないタグであれば、デプロイパッケージが破損している可能性があります。OpenLM からもう一度ダウンロードしてください。

Pod が CrashLoopBackOff のままになるのはなぜですか？​

次のコマンドを実行します。

kubectl logs <pod> -n openlm --previous --tail 100

--previous フラグが重要です。直前にクラッシュしたコンテナのログを表示し、新しい（空の）コンテナのログは表示しません。よくあるパターン:

  • データベース接続失敗: サービスがデータベースに到達できない。mariadb-0、postgres-postgresql-0、mongodb-0 が Running であること、passwords.yaml のパスワードがデータベース初期化時のものと一致していることを確認してください。
  • Kafka トピックがない: サービスが必要なトピックを参照しているのに作成されていない。トピック作成スクリプトをもう一度実行してください（Kafka トピックがないのはなぜですか？ を参照）。
  • スキーマの不整合: データベーススキーマが古い。AllDbUpgradeAPI サービスが起動時にスキーマを移行します。Running 状態であることを確認し、ログを確認してください。

OpenLM Platform の URL が 404 または Bad Gateway を返すのはなぜですか？​

次のコマンドを実行します。

# Is Traefik routing the request?
kubectl logs -n kube-system -l app.kubernetes.io/name=traefik --tail 50

# Does the ingress exist?
kubectl get ingress -n openlm | grep <path-prefix>

想定する Ingress が存在しない場合、OpenLM Platform の Helm リリースが完全にインストールされていません。./entrypoint.sh をもう一度実行してください。

ブラウザに証明書エラーが表示されるのはなぜですか？​

ブラウザに次のいずれかのエラーが表示されます。

  • NET::ERR_CERT_AUTHORITY_INVALID: 証明書が自己署名、またはブラウザが信頼していない CA から発行されている。本番外の構成では想定どおりです。
  • NET::ERR_CERT_COMMON_NAME_INVALID: 証明書が使用中の FQDN を含んでいない。正しい名前で証明書を再発行し、インストーラーをもう一度実行してください。インストーラーは証明書ファイルを再読み込みし、Kubernetes Secret を更新します。
  • "certificate has expired": 直前のエラーと同じく、証明書を再発行してインストーラーをもう一度実行します。インストーラーは常に、Kubernetes Secret 上の証明書を現在のファイル内容で上書きします。

証明書と鍵が一致しているか確認するには、次のコマンドを実行します。

openssl x509 -noout -modulus -in /etc/openlm/certs/tls.crt | md5sum
openssl rsa  -noout -modulus -in /etc/openlm/certs/tls.key | md5sum

2 つの出力は同一でなければなりません。

DNS の問題​

このセクションでは、クラスタ内外の名前解決の問題について説明します。

OpenLM Platform のドメインで「host not found」と出てサービスがクラッシュするのはなぜですか？​

  • 症状: OpenLM Platform に対してコールバックするサービス（例: トークンを発行する identity サービス）が host not found で失敗します。
  • 原因: クラスタの内部 DNS が openlm_system_domain を解決できません。VM が、その FQDN が公開されていないネットワークに置かれている場合に発生しがちです。

修正するには、config.yaml に CoreDNS の hosts エントリを設定し、インストーラーをもう一度実行します。

add_coredns_hosts_entry: true
coredns_hosts_entry_ip:  "<vm-ip-address>"

<vm-ip-address> を、VM の IP アドレスに置き換えます。

完全なパターンについては DNS のないエアギャップネットワーク を参照してください。

エンドユーザーが OpenLM Platform に到達できないのはなぜですか？​

VM 上ではなくユーザーのマシンで dig <openlm_system_domain> +short を実行します。VM の IP に解決されない場合は、DNS A レコードを修正してください。解決はされているのに接続が確立しない場合は、外部ファイアウォールを確認してください。ユーザーのネットワークから 443 番ポートを通す必要があります。

データベースの問題​

このセクションでは、パスワードのリセットと、同梱データベースへの接続について説明します。

PostgreSQL または MariaDB のパスワードをリセットするにはどうすればよいですか？​

同梱データベースのパスワードはインストール時に一度だけ設定されます。その後、passwords.yaml は真の値の出所ではなくなります。パスワードをリセットするには、使用しているデータベース用のコマンドを実行します。

PostgreSQL​

kubectl exec -n openlm-infrastructure -it postgres-postgresql-0 -- \
  psql -U postgres -c "ALTER USER postgres WITH PASSWORD '<new-password>';"

MariaDB​

kubectl exec -n openlm-infrastructure -it mariadb-0 -- \
  mysql -uroot -p'<old-password>' -e \
  "ALTER USER 'root'@'%' IDENTIFIED BY '<new-password>'; FLUSH PRIVILEGES;"

コマンド内の <new-password> を新しいパスワードに、<old-password> を現在のパスワードに置き換えます。

その後 passwords.yaml を更新し、OpenLM Platform サービスが新しいパスワードを使用するようインストーラーをもう一度実行します。

同梱データベースに直接接続するにはどうすればよいですか？​

使用しているデータベース用のコマンドを実行します。

# PostgreSQL
kubectl port-forward -n openlm-infrastructure svc/postgres-postgresql 5432:5432

# MariaDB
kubectl port-forward -n openlm-infrastructure svc/mariadb 3306:3306

# MongoDB
kubectl port-forward -n openlm-infrastructure svc/mongodb 27017:27017

その後、別のターミナルから psql、mysql、mongosh を localhost に向けて実行します。

Kafka の問題​

このセクションでは、不足しているトピックと、その確認方法について説明します。

Kafka トピックがないのはなぜですか？​

サービスのログに topic does not exist や Unknown topic or partition が出る場合は、トピック作成スクリプトをもう一度実行します。

kubectl cp installation_files/kafka_topics/full_topic_list_create.sh \
  openlm-infrastructure/kafka-controller-0:/tmp/create-topics.sh
kubectl exec -n openlm-infrastructure kafka-controller-0 -- \
  bash /tmp/create-topics.sh

このスクリプトは安全に再実行できます。既に存在するトピックはスキップします。

既存の Kafka トピックを一覧表示するにはどうすればよいですか？​

次のコマンドを実行します。

kubectl exec -n openlm-infrastructure kafka-controller-0 -- \
  /opt/bitnami/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --list

単一の Kafka トピックを調べるにはどうすればよいですか？​

トピックのパーティション数、レプリケーションファクター、設定を確認するには次を実行します。

kubectl exec -n openlm-infrastructure kafka-controller-0 -- \
  /opt/bitnami/kafka/bin/kafka-topics.sh \
  --bootstrap-server localhost:9092 --describe --topic <topic-name>

VM のディスク容量を空けるにはどうすればよいですか？​

K3s、コンテナイメージ、データベースデータはすべて VM のプライマリディスクに置かれます。Pod が Eviction 警告とともに失敗し始めたら、ディスク使用量を確認します。

df -h
sudo du -sh /var/lib/rancher/k3s/*
sudo du -sh /var/lib/rancher/k3s/storage/*   # persistent volume data

/var/lib/rancher/k3s が満杯であれば、最も単純な対策はディスクを拡張することです。コンテナイメージの掃除は一時的な回避策にすぎません。Pod が再スケジュールまたはアップグレードされた時点でイメージが再度取得されるためです。イメージを掃除するには、次のコマンドを実行します。

sudo k3s crictl images        # list
sudo k3s crictl rmi --prune   # remove unused

/var/lib/rancher/k3s/storage/ 配下は絶対に削除しないでください。そこはデータベースを含む、稼働中の永続ボリュームのデータです。

サポートを受ける​

OpenLM サポートに連絡する際は、次の情報を添えてください。

  1. kubectl get pods -A の出力。
  2. helm list -A の出力。
  3. 失敗している Pod のログ: kubectl logs <pod> -n <namespace> --tail 500。
  4. Pod が起動していない場合は kubectl describe pod <pod> -n <namespace> の出力。
  5. config.yaml（パスワードは伏せ字にする）と、デプロイパッケージのバージョン。

ドキュメントチームは、大規模言語モデルを使ってこのページを下書きすることがあります。公開前に、テクニカルライターがすべてのページをレビューし、製品と照らし合わせて検証します。最終的な判断は人間が行います。