まだプログラマーですが何か?

プログラマーネタ中心。たまに作成したウェブサービス関連の話も https://twitter.com/dotnsf

タグ:kubectl

これは自分のスキル不足が原因だと思っているのですが、Kubernetes や OpenShift といったコンテナクラスタ環境を使ったウェブアプリケーションのデプロイではトラブルシューティングに時間を費やすことが珍しくありません。過去に成功したのと同じようなパターンでデプロイすることばかりではなく、ストレージ含めた新しいチャレンジをすることが多く、一発で成功することはあまりありません。

この「トラブルシューティング」は、現象としては「デプロイしたが想定していた URL でウェブアプリが動いていない」ことで分かるのですが、この原因は(期待通りに動いていない箇所が)様々です。k8s の用語でいうと Pod, Deployment, Service, Ingress, ... といった構成要素があり、まずはこの中のどこで問題が発生しているのかを見極め、その上でその箇所で発生している問題の原因を特定して解決していく必要があります。

この「どの部分で問題が発生しているか」を特定する作業において、"port-forward" と呼ばれる機能に助けられています。この port-forward 機能について自分へのメモ目的も含めてまとめておきます。


【コンテナクラスタのトラブルシューティング】
k8s を使ったウェブアプリケーションのデプロイ作業は手動であったり(半)自動化されていたりしますが、リソースと呼ばれる以下のようなパーツの単位で作成され、これらが組み合わされて1つのウェブアプリケーションとなります(ウェブアプリケーションがうまく動かない場合は、このいずれか(または複数)が想定していたように動いていない、ということになります):
・デプロイメント(Deployment)
 - アプリケーションイメージを1つ以上インスタンス化し、クラスタ内で稼働しているもの
・ポッド(Pod)
 - インスタンス化されたアプリケーションイメージ1つ1つを指すもの
 - デプロイメントを作成した場合はデプロイメントに含まれる
・サービス(Service)
 - コンテナ内で稼働しているポッドやデプロイメントを外部公開方法を定義するもの
・イングレス(Ingress)
 - 複数のサービスを管理し、外部からのリクエストに対してロードバランサーとなるもの

2023090706


コンテナクラスタ環境にウェブアプリケーションが正しくデプロイされた場合、ユーザーはアプリケーションの URL にアクセスすると、まずイングレスがそのリクエストを受け取って正しいサービスに転送し、サービスを経由してアプリケーションインスタンスであるポッド(デプロイメント)にアクセスします(イングレス→サービス→ポッド)。そしてそのリクエストに対してポッドが返したレスポンスは逆の順序(ポッド→サービス→イングレス)を通って返される、ということになります。


「デプロイしたアプリケーションが期待していたように動かない」というのは、この中のどこかが期待していたように動いていなくて、全体として「動かない」ように見えていることになります。したがってトラブルシューティングにおいて、まずはどこで問題が発生しているのかを特定する必要があります。
2023090706


【port-forward 機能】
kubectl や oc といった CLI ツールの機能である port-forwarding を使うと、ポート番号を使ったフォワーディング機能によりイングレスを経由せずにコンテナクラスタ内に定義されているサービスやポッドに直接アクセスできるようになります。

例えばイングレスを経由せずにサービスにアクセスすると期待していた挙動になる(期待していた結果が返ってくる)のであればイングレスやその設定に問題がある可能性が高いことが考えられ、サービスにアクセスしても動かないがポッドに直接アクセスすれば期待していた挙動になるのであればサービスやその設定に問題がある可能性が高いことが考えられます(それでも動かない場合はポッドに問題があると考えられます)。 このような障害発生個所の見極めにおいては port-forwarding が便利に使えることになります。


【port-forward 機能を使ってみる】
試しにわざと正しく動かないことがわかっている以下のようなマニフェストファイル(deployment.yaml)を使ってアプリケーションをデプロイし、port-forward で確認する、ということをやってみます:
apiVersion: apps/v1
kind: Deployment
metadata:
  name: guestbook
  labels:
    app: guestbook
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guestbook
  template:
    metadata:
      labels:
        app: guestbook
    spec:
      containers:
      - name: guestbook
        image: ibmcom/guestbook:v1
        imagePullPolicy: Always
        env:
          - name: NODE_ENV
            value: production
---
apiVersion: v1
kind: Service
metadata:
  name: guestbook-svc
  labels:
    app: guestbook
spec:
  type: ClusterIP
  ports:
  - protocol: TCP
    port: 3000
    targetPort: 3000
  selector:
    app: guestbook
---
apiVersion: route.openshift.io/v1
kind: Route
metadata:
  name: guestbook-route
  labels:
    app: guestbook
spec:
  host: guestbook.(アサインされた ingress サブドメイン)
  to:
    kind: Service
    name: guestbook-svc
    weight: 100
  port:
    targetPort: 4000 # 正しくは3000
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect
  wildcardPolicy: None

ちなみに上記マニフェストの正しい記述は下から5行目の Route の spec.port.targetPort の値が 3000 になっているものです(今回はわざと 4000 を指定しています)。

なお以下の作業は IBM Cloud の Redhat OpenShift コンテナクラスタ環境を使って確認しました。なので Ingress 部分の定義は apiVersion が "route.openshift.io/v1" の Route というリソースを使って定義しています。またこの Route 内の spec.host の値には "guestbook.(アサインされた ingress サブドメイン)" と記載していますが、実行前にこの()内の部分を OpenShift 画面に表示されているサブドメイン名に置き換えて保存しておいてください:
2023090701


oc コマンドでログインし、このマニフェストファイルをデプロイ(oc apply)して、その結果を確認(oc get all)します:
$ oc apply -f deployment.yml

$ oc get all

NAME                             READY   STATUS    RESTARTS   AGE
pod/guestbook-59b85f9654-22wh5   1/1     Running   0          13m

NAME                                TYPE           CLUSTER-IP       EXTERNAL-IP                            PORT(S)    AGE
service/guestbook-svc               ClusterIP      172.21.150.230                                          3000/TCP   13m
service/kubernetes                  ClusterIP      172.21.0.1                                              443/TCP    6h7m
service/openshift                   ExternalName              kubernetes.default.svc.cluster.local                    5h46m
service/openshift-apiserver         ClusterIP      172.21.46.95                                            443/TCP    6h6m
service/openshift-oauth-apiserver   ClusterIP      172.21.98.204                                           443/TCP    6h6m

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/guestbook   1/1     1            1           13m

NAME                                   DESIRED   CURRENT   READY   AGE
replicaset.apps/guestbook-59b85f9654   1         1         1       13m

NAME                                       HOST/PORT                                                                 PATH   SERVICES        PORT   TERMINATION     WILDCARD
route.route.openshift.io/guestbook-route   guestbook.(ingress サブドメイン).jp-tok.containers.appdomain.cloud             guestbook-svc   4000   edge/Redirect   None

"oc get all" の結果は上からポッド、サービス、デプロイメント、レプリカセット、そしてイングレスになっています。ポッドのステータスは Running でちゃんと動いていて、サービスも ClusterIP を使って正しく公開され、イングレスもホスト名が割り当てられています。 この結果だけを見ると正しく動いてそうです。

でも実際にブラウザでイングレスの HOST 名に表示されているサーバーにアクセスするとこのように表示されます(知らない人もいるので補足すると、これは期待していたアプリ画面ではなく、アクセスできなかった場合のエラー画面です):
2023090702


エラー無くデプロイできたけどアプリにアクセスできない、、 こんな時に port-forward の出番です。

まずは(上述の結果で Pod が Running になってるので可能性は低そうですが)ポッドのレベルで正しく動いているかどうかを確認するため、port-forwarding でポッドに直結して動作を確認してみます。

ポッドに対して port-forwarding するには kubectl(または oc )コマンドで以下のように実行します:
$ kubectl port-forward (ポッド名) (ホストのポート番号):(ポッド上で動いているポート番号)

今回の例だと(上述の結果より)ポッド名は "guestbook-svc" だとわかります。また実行したマニフェストファイルより、このサービスは 3000 番ポートで動いているはずです(サービスの spec.ports.targetPort の値)。このポッドにホストの(何番でもいいのですが) 8000 番ポートからフォワーディングして接続させてみます。というわけで、今回のケースであれば以下のコマンドを実行します:
$ kubectl port-forward guestbook-59b85f9654-22wh5 8000:3000

コマンド実行後、ウェブブラウザから http://localhost:8000/ にアクセスしてみます:
2023090703


今回は期待通りの画面が表示されました。ということは「ポッドは正しく動いている」ことが推測できました。Ctrl+C で port-forwarding を解除します。


継はサービスのレベルで正しく動いているかどうかを確認してみます。イングレスを経由せずにサービスにアクセスするため、port-forwarding でサービスに直結して動作を確認してみます。この場合は以下のようなコマンドを実行します:
$ kubectl port-forward service/(サービス名) (ホストのポート番号):(サービスで公開しているポート番号)

今回の例だと(上述の結果より)サービス名は "guestbook-59b85f9654-22wh5" だとわかります。また実行したマニフェストファイルより、このポッド(デプロイメント)は 3000 番ポートで動いているはずです(サービスの spec.ports.port の値)。このポッドにホストの(何番でもいいのですが) 9000 番ポートからフォワーディングして接続させてみます。というわけで、今回のケースであれば以下のコマンドを実行します:
$ kubectl port-forward service/guestbook-svc 9000:3000

コマンド実行後、ウェブブラウザから http://localhost:9000/ にアクセスしてみます:
2023090704


今回は期待通りの画面が表示されました。ということは「サービスも正しく動いている」ことが推測できました。Ctrl+C で port-forwarding を解除します。

これらの結果から、
・ポッド(デプロイメント)は正しく動いていそう
・サービスも正しく動いていそう
・ということはイングレスの設定が間違っていそう?

という切り分けをすることができました。実際、マニフェストの Route 内をわざと間違った内容に弄ったことが分かっているので、正しい切り分けができていることになります。

このケースであればイングレスの設定内容を疑ってみることになります。試しにイングレスの設定名称を指定して describe するとこのようになりました(kubectl の場合は "kubectl describe ingress guestbook-route"):
$ oc describe route guestbook-route 

  :
  :
Path:                   
TLS Termination:        edge
Insecure Policy:        Redirect
Endpoint Port:          4000

Service:        guestbook-svc
Weight:         100 (100%)
Endpoints:      

接続先である Endpoints が空になっていて何も表示されていません。ということは設定内容になんらかの誤りがあってサービスに接続できていないのでは・・・ と考えることができます。実際、今回のマニフェストでは targetPort を 3000 と指定すべきところを 4000 と指定していたため接続できていませんでした。仮に 4000 を 3000 に変更して再度適用した上で接続を試みた所、今度は正しく接続できるようになりました:
2023090705


現実問題として、イングレス部分はポッドやサービスとは異なり Kubernetes からはサードパーティ製品となるので色々な実装があり、トラブルシューティングも実装ごとの方法が考えられるため比較的難しいトラブルシューティングとはなります。それでも「どの部分に設定ミスがあったか」を特定することで解決はしやすくなりますし、その特定において port-forwarding は有効な切り分け方であると思っています。




Windows 10 で kubernates の開発環境を構築する際の方法の1つとして、以下のケースで構築する場合のメモです:
・Kubernetes 本体は minikube を使って Windows 10 に導入
・kubectl は WSL から利用


Kubernetes 本体はローカルで動く minikube を使ってシングルノード環境を構築します。この部分は正しく導入できていさえすれば Windows だろうが、Linux だろうが、Mac だろうが、システム環境の違いを意識することはあまりないと思っています。 ただ実際に利用する段になって kubectl コマンドを実行する環境としては Windows よりもより実践に近い Linux を使いたくなります。というわけで、Windows 10 の WSL (今回は Ubuntu を想定)から利用できるようにしました。

なお、この環境構築をする場合のマシンスペックとして、メモリ 8GB だと構築して minikube start した時点でほぼメモリを使い尽くしてしまいます。動作確認するだけならいいのですが、本格的に開発して動作確認してテストして・・・という段階まで考えるとやはり 16GB くらいはほしいところです。


【前提条件】
- Windows 10
- WSL(Ubuntu 18.0.4) 導入済み


【VirtualBox のインストール】
Windows 10 で minikube を動かす場合、仮想環境のハイパーバイザーが必要です。今回は VirtualBoxを使います。VirtualBox 自体のインストールはごく普通に公式ページから Windows 版をダウンロードし、デフォルト設定のままインストールすればOKです。


【Windows 版 minikube のインストール】
minikube の Github ページから、Windows/amd64 版の minikube 単体をダウンロードします:
2019090801


ダウンロードしたファイルは minikube-windows-amd64.exe というファイル名になっていますが、これを minikube.exe とリネームしてファイルシステムの適当なフォルダに保存します(以下は C:\MyApps\minikube\ というフォルダを作成して、その中に C:\MyApps\minikube\minikube.exe という名前で保存しているものと仮定して以下を続けます)。

このフォルダに PATH を通します。Windows + S キーを押して検索ボックスに「システムの詳細設定」と入力すると「システムの詳細設定の表示」が見つかるので、これを選択します:
2019090802


システムのプロパティウィンドウが表示されたら、「詳細設定」タブを選択し、「環境変数」ボタンをクリック:
2019090803


ユーザー環境変数の Path を選択してから「編集」ボタンをクリック:
2019090804


そして「新規」に minikube.exe が保存されたフォルダ名を追加して、最後に OK ボタンをクリック。これで minikube.exe に PATH が通りました:
2019090805


念の為、動作確認してみます。コマンドプロンプトを起動して、 "minikube version" と入力して実行します。minikube のバージョン番号が表示されれば、ここまでの手順は OK です:
2019090801


【minikube の起動】
コマンドプロンプトから "minikube start" と入力して、minikube を起動します。自動的に必要な VM イメージを見つけて(初回はダウンロードして)自動構築します。通常は minikube が kubectl を見つけてくれるのですが、この方法だと(Windows 版 kubectl を使わない&インストールしていないので)見つからない、という警告が表示されますが、今回は WSL 側に kubectl を用意するので無視します:
2019090802


【WSL に kubectl をインストール】
WSL を起動し、以下のコマンドを入力して kubectl を(/usr/local/bin/ 以下に)導入します:
$ curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl

$ chmod 755 kubectl

$ sudo mv kubectl /usr/local/bin

最後に "kubectl version" を実行して動作確認します(初回は Client Version が表示されれば OK です):
$ kubectl version
Client Version: version.Info{Major:"1", Minor:"15", GitVersion:"v1.15.3", GitCommit:"2d3c76f9091b6bec110a5e63777c332469e0cba2", GitTreeState:"clean", BuildDate:"2019-08-19T11:13:54Z", GoVersion:"go1.12.9", Compiler:"gc", Platform:"linux/amd64"}

【minikube のエンドポイント情報の取得】
コマンドプロンプトに戻って、"minikube status" を実行し、minikube のエンドポイント情報を確認します。以下の例では 192.168.99.100 というアドレスが表示されていますが、これにポート番号 8443 を加えたもの(192.168.99.100:8443)がエンドポイントとなり、以下で利用することになります:
2019090803


【kubectl の設定】
上記で取得したエンドポイント情報を使って kubectl の設定を行います。WSL から以下のコマンドを順次実行します。なお以下で <コマンドプロンプト実行時のユーザー名> と表示されている部分にはコマンドプロンプト実行時のユーザー名がフォルダ名の一部になっているのでそれをそのまま指定します(上記の画像例の場合であれば、ここには KEIKIMURA が入ります)、また 192.168.99.100:8443 部分は上記で取得したエンドポイント情報です:
$ kubectl config set-credentials minikube --client-certificate=/mnt/c/Users/<コマンドプロンプト実行時のユーザー名>/.minikube/client.crt --client-key=/mnt/c/Users/<コマンドプロンプト実行時のユーザー名>/.minikube/client.key

$ kubectl config set-cluster minikube --server=https://192.168.99.100:8443 --certificate-authority=/mnt/c/Users/<コマンドプロンプト実行時のユーザー名>/.minikube/ca.crt

$ kubectl config set-context minikube --user=minikube --cluster=minikube

$ kubectl config use-context minikube

最後に WSL で "kubectl cluster-info" コマンドを実行して動作を確認し、エンドポイントで正しくクラスタ状態が取得できれば kubectl の設定完了です。シングルノードの kubernetes (kubectl) がローカルの WSL から使えるようになりました:
$ kubectl cluster-info

Kubernetes master is running at https://192.168.99.100:8443
KubeDNS is running at https://192.168.99.100:8443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.



(参考)
https://dokupe.hatenablog.com/entry/20180408/1523116886

このページのトップヘ