Kubernetes APIを使用してクラスターにアクセスする

このページでは、Kubernetes APIを使用してクラスターにアクセスする方法を説明します。

始める前に

Kubernetesクラスターが必要、かつそのクラスターと通信するためにkubectlコマンドラインツールが設定されている必要があります。 このチュートリアルは、コントロールプレーンのホストとして動作していない少なくとも2つのノードを持つクラスターで実行することをおすすめします。 まだクラスターがない場合、minikubeを使って作成するか、 以下のいずれかのKubernetesプレイグラウンドも使用できます:

バージョンを確認するには次のコマンドを実行してください: kubectl version.

Kubernetes APIへのアクセス

kubectlを使用した初回アクセス

Kubernetes APIに初めてアクセスする際は、Kubernetesコマンドラインツールのkubectlを使用します。

クラスターにアクセスするには、クラスターのロケーションを知り、アクセス用の認証情報が必要です。 通常、これははじめにを進めていく中で自動的に設定されるか、他の誰かがクラスターをセットアップしてあなたに認証情報とロケーションを提供してくれます。

このコマンドで、kubectlが認識しているロケーションと認証情報を確認できます:

kubectl config view

多くのでkubectlの使用方法について紹介しています。 完全なドキュメントはkubectlマニュアルにあります。

REST APIへの直接アクセス

kubectlはAPIサーバーの特定と認証を扱います。 curlwgetなどのHTTPクライアント、またはブラウザでREST APIに直接アクセスしたい場合は、APIサーバーを特定して認証する方法がいくつかあります:

  1. kubectlをプロキシモードで実行する(推奨)。 この方法は、保存されたAPIサーバーのロケーションを使用し、自己署名証明書を使用してAPIサーバーを検証するため、推奨されます。 この方法では中間者攻撃(MITM)は不可能です。
  2. あるいは、ロケーションと認証情報をHTTPクライアントに直接提供することもできます。 これはプロキシに混乱するクライアントコードで機能します。 中間者攻撃から保護するには、ブラウザにルート証明書をインポートする必要があります。

GoまたはPythonのクライアントライブラリを使用すると、プロキシモードでkubectlにアクセスできます。

kubectl proxyの使用

次のコマンドは、kubectlをリバースプロキシとして動作するモードで実行します。 APIサーバーの特定と認証を扱います。

次のように実行します:

kubectl proxy --port=8080 &

詳細については、kubectl proxyを参照してください。

その後、curl、wget、またはブラウザでAPIを探索できます。次のように:

curl http://localhost:8080/api/

出力は次のとおりです:

{
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

kubectl proxyを使用しない

認証トークンをAPIサーバーに直接渡すことで、kubectl proxyの使用を避けることが可能です。 次のように:

grep/cutアプローチを使用:


# .KUBECONFIGが複数コンテキストを含む可能性があるため、接続可能なすべてのクラスターをチェックする
kubectl config view -o jsonpath='{"Cluster name\tServer\n"}{range .clusters[*]}{.name}{"\t"}{.cluster.server}{"\n"}{end}'

# 上記出力結果から接続したいクラスター名を選択する:
export CLUSTER_NAME="some_server_name"

# クラスター名を参照してAPIサーバーを指定する
APISERVER=$(kubectl config view -o jsonpath="{.clusters[?(@.name==\"$CLUSTER_NAME\")].cluster.server}")

# デフォルトのService Accountのトークンを保持するSecretを作成する
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: default-token
  annotations:
    kubernetes.io/service-account.name: default
type: kubernetes.io/service-account-token
EOF

# トークンコントローラーがSecretを追加するまで待つ:
while ! kubectl describe secret default-token | grep -E '^token' >/dev/null; do
  echo "waiting for token..." >&2
  sleep 1
done

# トークンの値を取得する
TOKEN=$(kubectl get secret default-token -o jsonpath='{.data.token}' | base64 --decode)

# TOKENを利用してAPIを調査する
curl -X GET $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure

出力結果は次のとおりです:

{
  "kind": "APIVersions",
  "versions": [
    "v1"
  ],
  "serverAddressByClientCIDRs": [
    {
      "clientCIDR": "0.0.0.0/0",
      "serverAddress": "10.0.1.149:443"
    }
  ]
}

上記の例では--insecureフラグを使用しています。 これは、MITM攻撃を受ける可能性があります。 kubectlがクラスターにアクセスする際は、保存されたルート証明書とクライアント証明書を使用してサーバーにアクセスします(これらは~/.kubeディレクトリにインストールされています)。 クラスター証明書は通常自己署名されているため、HTTPクライアントにルート証明書を使用させるには特別な設定が必要な場合があります。

一部のクラスターでは、APIサーバーは認証を必要としません。 localhostで提供される場合や、ファイアウォールで保護されている場合などです。 このように、認証を必要としない構成を行うための標準的な方法はありません。 Kubernetes APIへのアクセスコントロールでは、クラスター管理者としてこれを設定する方法を説明しています。

APIへのプログラムによるアクセス

Kubernetesは、公式にGoPythonJavadotnetJavaScriptHaskellのクライアントライブラリをサポートしています。 Kubernetesチームではなく、それぞれのライブラリの作成者によって提供および保守されている他のクライアントライブラリもあります。 他の言語からAPIにアクセスする方法と認証方法については、クライアントライブラリを参照してください。

Goクライアント

  • ライブラリを取得するには、次のコマンドを実行します: go get k8s.io/client-go@kubernetes-<kubernetes-version-number>。 サポートされているバージョンについては、https://github.com/kubernetes/client-go/releasesを参照してください。
  • client-goクライアントを用いて、アプリケーションを記述します。

Goクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

package main

import (
  "context"
  "fmt"
  "k8s.io/apimachinery/pkg/apis/meta/v1"
  "k8s.io/client-go/kubernetes"
  "k8s.io/client-go/tools/clientcmd"
)

func main() {
  // kubeconfigのcurrent contextを使用する
  // path-to-kubeconfig -- 例として /root/.kube/config
  config, _ := clientcmd.BuildConfigFromFlags("", "<path-to-kubeconfig>")
  // creates the clientset
  clientset, _ := kubernetes.NewForConfig(config)
  // Podを一覧するためにAPIにアクセスする
  pods, _ := clientset.CoreV1().Pods("").List(context.TODO(), v1.ListOptions{})
  fmt.Printf("There are %d pods in the cluster\n", len(pods.Items))
}

もしアプリケーションがクラスター内のPodとしてデプロイされているのであれば、Pod内からAPIにアクセスするを参照してください。

Pythonクライアント

Pythonクライアントを使用するには、次のコマンドを実行します: pip install kubernetes。 その他のインストールオプションについては、Pythonクライアントライブラリページを参照してください。

Pythonクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

from kubernetes import client, config

config.load_kube_config()

v1=client.CoreV1Api()
print("Listing pods with their IPs:")
ret = v1.list_pod_for_all_namespaces(watch=False)
for i in ret.items:
    print("%s\t%s\t%s" % (i.status.pod_ip, i.metadata.namespace, i.metadata.name))

Javaクライアント

Javaクライアントをインストールするには、次を実行します:

# Clone java library
git clone --recursive https://github.com/kubernetes-client/java

# Installing project artifacts, POM etc:
cd java
mvn install

サポートされているバージョンについては、https://github.com/kubernetes-client/java/releasesを参照してください。

Javaクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

package io.kubernetes.client.examples;

import io.kubernetes.client.ApiClient;
import io.kubernetes.client.ApiException;
import io.kubernetes.client.Configuration;
import io.kubernetes.client.apis.CoreV1Api;
import io.kubernetes.client.models.V1Pod;
import io.kubernetes.client.models.V1PodList;
import io.kubernetes.client.util.ClientBuilder;
import io.kubernetes.client.util.KubeConfig;
import java.io.FileReader;
import java.io.IOException;

/**
 * Kubernetesクラスター外のアプリケーションからJava APIを利用する簡単な例
 *
 * <p>最も簡単に実行する方法: mvn exec:java
 * -Dexec.mainClass="io.kubernetes.client.examples.KubeConfigFileClientExample"
 *
 */
public class KubeConfigFileClientExample {
  public static void main(String[] args) throws IOException, ApiException {

    // KubeConfigへのファイルパス
    String kubeConfigPath = "~/.kube/config";

    // クラスター外の設定(ファイルシステム上のkubeconfig)を読み込む
    ApiClient client =
        ClientBuilder.kubeconfig(KubeConfig.loadKubeConfig(new FileReader(kubeConfigPath))).build();

    // 上記のクラスター内api-clientをグローバル標準api-clientに設定する
    Configuration.setDefaultApiClient(client);

    // the CoreV1Api loads default api-client from global configuration.
    // CoreV1Apiはグローバル設定から標準のapi-clientを読み込む
    CoreV1Api api = new CoreV1Api();

    // CoreV1Api clientを呼び出す
    V1PodList list = api.listPodForAllNamespaces(null, null, null, null, null, null, null, null, null);
    System.out.println("Listing all pods: ");
    for (V1Pod item : list.getItems()) {
      System.out.println(item.getMetadata().getName());
    }
  }
}

dotnetクライアント

dotnetクライアントを使用するには、次のコマンドを実行します: dotnet add package KubernetesClient --version 1.6.1。 その他のインストールオプションについては、dotnetクライアントライブラリページを参照してください。 サポートされているバージョンについては、https://github.com/kubernetes-client/csharp/releasesを参照してください。

dotnetクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

using System;
using k8s;

namespace simple
{
    internal class PodList
    {
        private static void Main(string[] args)
        {
            var config = KubernetesClientConfiguration.BuildDefaultConfig();
            IKubernetes client = new Kubernetes(config);
            Console.WriteLine("Starting Request!");

            var list = client.ListNamespacedPod("default");
            foreach (var item in list.Items)
            {
                Console.WriteLine(item.Metadata.Name);
            }
            if (list.Items.Count == 0)
            {
                Console.WriteLine("Empty!");
            }
        }
    }
}

JavaScriptクライアント

JavaScriptクライアントをインストールするには、次のコマンドを実行します: npm install @kubernetes/client-node。 サポートされているバージョンについては、https://github.com/kubernetes-client/javascript/releasesを参照してください。

JavaScriptクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

const k8s = require('@kubernetes/client-node');

const kc = new k8s.KubeConfig();
kc.loadFromDefault();

const k8sApi = kc.makeApiClient(k8s.CoreV1Api);

k8sApi.listNamespacedPod({ namespace: 'default' }).then((res) => {
    console.log(res);
});

Haskellクライアント

サポートされているバージョンについては、https://github.com/kubernetes-client/haskell/releasesを参照してください。

Haskellクライアントは、kubectl CLIと同じkubeconfigファイルを使用して、APIサーバーを特定し、認証できます。 このを参照してください:

exampleWithKubeConfig :: IO ()
exampleWithKubeConfig = do
    oidcCache <- atomically $ newTVar $ Map.fromList []
    (mgr, kcfg) <- mkKubeClientConfig oidcCache $ KubeConfigFile "/path/to/kubeconfig"
    dispatchMime
            mgr
            kcfg
            (CoreV1.listPodForAllNamespaces (Accept MimeJSON))
        >>= print

次の項目