fbpx

連載: Kubernetesでカスタムコントローラを作ろう！ ～第2回 Kubernetes APIについて～

DockerKubernetes

この記事は1年以上前に投稿されました。情報が古い可能性がありますので、ご注意ください。

Kubernetesのコントローラを開発するには、前回のコンポーネントのおさらいで確認したkube-apiserverと通信する必要があります。
では一体kube-apiserverはどのようにAPIを公開しているのでしょうか。今回はkube-apiserverが公開するAPIについて簡単に説明します。

kube-apiserverが公開するパス

kube-apiserverに対しては、HTTPで通信することができます。DeploymentやPodなどリソースは、/apisや/apiのパスの下で公開されています。例えばDeploymentであれば/apis/apps/v1/deployments、Podであれば/api/v1/podsというパスでアクセスできます。

グループとバージョン

Kubernetesのリソースはグループとバージョンにより管理されます。グループはDeployment, StatefulSetなどが含まれるappsグループ、Ingressなどが含まれるnetworking.k8s.ioグループ、CronJobなどが含まれるbatchグループなどがあります。バージョンにはalphaやbetaなどの文字列を含むものがあります。

alphaのものは、v1alpha1などバージョン名にalphaという文字列が含まれています。
alphaのものは今後のリリースで互換性のない方法で変更が加えられたり、機能のサポートが予告なく中止されたり、導入されたばかりの機能だったりで安定性の問題があったりするため気を付けて利用すべきものです。基本的に本番環境での利用はおすすめしません。利用したい場合はデフォルトでは有効化されていないため、明示的に有効化して利用する必要があります。

betaのものはバージョン名にv1beta1などbetaという文字列が含まれています。alphaのものほどアグレッシブな変更があるものではありませんが、その後のリリースでまだ大きな変更の可能性があるため、こちらも本番環境での利用は注意が必要です。betaのものはalphaと異なり十分にテストされておりデフォルトで有効化されているものがほとんどですが、今後新たに追加されていくものは明示的に有効化する必要があります。有効化方法に関しては公式ドキュメントをご参照ください。

安定したAPIのバージョンはv1やv2など数字の後ろに何もつかないものです。特別な理由がない限り、このバージョンを利用していくのが無難です。

これらバージョンの安定性やサポートレベルの詳細は公式ドキュメントをご参照ください。

/apis以下でアクセスできるものの場合、/apis/GROUP名/VESRION となります。Cluster-wideなリソースではない、Namespace-scopedなリソースであれば、Namespaceが指定できます。その場合/apis/GROUP名/VESRION/namespaces/NAMESPACE名というパスでアクセスできます。kube-systemのDeploymentへアクセスする場合以下の図のようなパスとなります。

特殊なグループとしてcore(またはleagcy)と呼ばれるものがあり、KubernetesのマニフェストではapiVersionが apiVersion: v1 となるものです。PodやConfigMapなどがこれに属しています。
このグループは/api以下のパスで公開されており、パスにグループ名を含みません。

一つのリソースに異なるバージョンでアクセスする

少し前からKubernetesを触っていた方なら、Deploymentがapps/v1、apps/v1beta2、extensions/v1beta1など複数のグループ・バージョンで提供されていたことを知っている方もいるかもしれません。(v1.25現在ではapps/v1以外は提供されていません)Kubernetesでは、オブジェクトに対して複数のバージョンでアクセスすることが可能です。

kube-apiserverはリクエストされたバージョンがどれであれ、内部バージョンへ情報の欠損がないように変換します。この内部バージョンは外向けには公開されていないため、直接触れることはないでしょう。一度内部バージョンへ変換されると、これはどのバージョンへも変換が可能となっています。これにより異なるバージョン間で変換が可能となっています。そのためリクエストにどのバージョンを利用してもアクセス可能です。ちなみにetcdへ実際に保存されるバージョンは、この内部バージョンではなくストレージバージョンと呼ばれる特定のバージョンで記録されます。

実際にリクエストを投げる

kube-apiserverへリクエストを投げる場合には、認証に関する情報を含める必要があります。kubectlにはkubectl proxyという便利なサブコマンドがあり、これはkubectlの現在の設定で認証を行い、リクエストをproxyしてくれるコマンドです。このコマンドとcurlコマンドを用いて、kube-systemのDeploymentのリストを取得してみましょう。以下のコマンドを入力し、別のターミナルを起動してそこでcurlを実行します。

$ kubectl proxy
Starting to serve on 127.0.0.1:8001

上記から127.0.0.1:8001でプロキシしていることがわかります。先ほど説明したパスでアクセスしてみましょう。

$ curl "http://127.0.0.1:8001/apis/apps/v1/namespaces/kube-system/deployments"
{
  "kind": "DeploymentList",
  "apiVersion": "apps/v1",
  "metadata": {
    "resourceVersion": "71335"
  },
  "items": [
    {
      "metadata": {
        "name": "coredns",
        "namespace": "kube-system",
        "uid": "c403eb4f-8683-4f80-8b76-c7cd9543b351",
        "resourceVersion": "46749",
        "generation": 1,
        "creationTimestamp": "2022-09-03T15:31:45Z",
        "labels": {
          "k8s-app": "kube-dns"
        },
        "annotations": {
          "deployment.kubernetes.io/revision": "1"
        },
        "managedFields": [
          {
            "manager": "kubeadm",
            "operation": "Update",
...(省略)

Deploymentのリストが取得できました。

最後に

今回はKubetnetesのAPIについて簡単に説明し、また実際にcurlを用いてリソースへアクセスしました。これだけでも何かツールを作成できるような気がしてきたのではないでしょうか？次回はもう少しAPIについて説明した後、今回とは別の操作も実施予定です。

クリエーションラインではKubernetesに関する様々なトレーニングを提供しております。詳しくはこちらをご参照ください。また、この連載の更新通知を受け取りたい方は、Twitterアカウントのフォローや、このページ下部にリンクのあるCL LAB MAIL MAGAZINEへの登録をぜひお願いします！

参考

新規CTA