# 使用 kubeconfig 文件配置跨集群認證 Kubernetes 的認證方式對于不同的人來說可能有所不同。 - 運行 kubelet 可能有一種認證方式（即證書）。 - 用戶可能有不同的認證方式（即令牌）。 - 管理員可能具有他們為個人用戶提供的證書列表。 - 我們可能有多個集群，并希望在同一個地方將其全部定義——這樣用戶就能使用自己的證書并重用相同的全局配置。 所以為了能夠讓用戶輕松地在多個集群之間切換，對于多個用戶的情況下，我們將其定義在了一個 kubeconfig 文件中。 此文件包含一系列與昵稱相關聯的身份驗證機制和集群連接信息。它還引入了一個（用戶）認證信息元組和一個被稱為上下文的與昵稱相關聯的集群連接信息的概念。 如果明確指定，則允許使用多個 kubeconfig 文件。在運行時，它們與命令行中指定的覆蓋選項一起加載并合并（參見下面的 [規則](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#loading-and-merging-rules)）。 ## 相關討論 <http://issue.k8s.io/1755> ## Kubeconfig 文件的組成 ### Kubeconifg 文件示例 ```yaml current-context: federal-context apiVersion: v1 clusters: - cluster: api-version: v1 server: http://cow.org:8080 name: cow-cluster - cluster: certificate-authority: path/to/my/cafile server: https://horse.org:4443 name: horse-cluster - cluster: insecure-skip-tls-verify: true server: https://pig.org:443 name: pig-cluster contexts: - context: cluster: horse-cluster namespace: chisel-ns user: green-user name: federal-context - context: cluster: pig-cluster namespace: saw-ns user: black-user name: queen-anne-context kind: Config preferences: colors: true users: - name: blue-user user: token: blue-token - name: green-user user: client-certificate: path/to/my/client/cert client-key: path/to/my/client/key ``` ### 各個組件的拆解/釋意 #### Cluster ```yaml clusters: - cluster: certificate-authority: path/to/my/cafile server: https://horse.org:4443 name: horse-cluster - cluster: insecure-skip-tls-verify: true server: https://pig.org:443 name: pig-cluster ``` `cluster` 中包含 kubernetes 集群的端點數據，包括 kubernetes apiserver 的完整 url 以及集群的證書頒發機構或者當集群的服務證書未被系統信任的證書頒發機構簽名時，設置`insecure-skip-tls-verify: true`。 `cluster` 的名稱（昵稱）作為該 kubeconfig 文件中的集群字典的 key。 您可以使用 `kubectl config set-cluster`添加或修改 `cluster` 條目。 #### user ```yaml users: - name: blue-user user: token: blue-token - name: green-user user: client-certificate: path/to/my/client/cert client-key: path/to/my/client/key ``` `user` 定義用于向 kubernetes 集群進行身份驗證的客戶端憑據。在加載/合并 kubeconfig 之后，`user` 將有一個名稱（昵稱）作為用戶條目列表中的 key。 可用憑證有 `client-certificate`、`client-key`、`token` 和 `username/password`。 `username/password` 和 `token` 是二者只能選擇一個，但 client-certificate 和 client-key 可以分別與它們組合。 您可以使用 `kubectl config set-credentials` 添加或者修改 `user` 條目。 #### context ```yaml contexts: - context: cluster: horse-cluster namespace: chisel-ns user: green-user name: federal-context ``` `context` 定義了一個命名的 [`cluster`](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#cluster)、[`user`](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#user)、[`namespace`](https://kubernetes.io/docs/user-guide/namespaces) 元組，用于使用提供的認證信息和命名空間將請求發送到指定的集群。 三個都是可選的；僅使用 `cluster`、`user`、`namespace` 之一指定上下文，或指定 none。 未指定的值或在加載的 kubeconfig 中沒有相應條目的命名值（例如，如果為上述 kubeconfig 文件指定了 `pink-user` 的上下文）將被替換為默認值。 有關覆蓋/合并行為，請參閱下面的 [加載和合并規則](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#loading-and-merging)。 您可以使用 `kubectl config set-context` 添加或修改上下文條目。 #### current-context ```yaml current-context: federal-context ``` `current-context` 是昵稱或者說是作為 `cluster`、`user`、`namespace` 元組的 ”key“，當 kubectl 從該文件中加載配置的時候會被默認使用。您可以在 kubectl 命令行里覆蓋這些值，通過分別傳入 `—context=CONTEXT`、 `—cluster=CLUSTER`、`--user=USER` 和 `--namespace=NAMESPACE` 。 您可以使用 `kubectl config use-context` 更改 `current-context`。 ```yaml apiVersion: v1 kind: Config preferences: colors: true ``` #### 雜項 `apiVersion` 和 `kind` 標識客戶端解析器的版本和模式，不應手動編輯。 `preferences` 指定可選（和當前未使用）的 kubectl 首選項。 ## 查看 kubeconfig 文件 `kubectl config view` 命令可以展示當前的 kubeconfig 設置。默認將為您展示所有的 kubeconfig 設置；您可以通過傳入 `—minify` 參數，將視圖過濾到與 `current-context` 有關的配額設置。有關其他選項，請參閱 `kubectl config view`。 ## 構建您自己的 kubeconfig 文件 您可以使用上文 [示例 kubeconfig 文件](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#example-kubeconfig-file) 作為 **注意：** 如果您是通過 `kube-up.sh` 腳本部署的 kubernetes 集群，不需要自己創建 kubeconfig 文件——該腳本已經為您創建過了。 當 api server 啟動的時候使用了 `—token-auth-file=tokens.csv` 選項時，上述文件將會與 [API server](https://kubernetes.io/docs/admin/kube-apiserver/) 相關聯，`tokens.csv` 文件看起來會像這個樣子： ```bash blue-user,blue-user,1 mister-red,mister-red,2 ``` **注意：** 啟動 API server 時有很多 [可用選項](https://kubernetes.io/docs/admin/kube-apiserver/)。請您一定要確保理解您使用的選項。 上述示例 kubeconfig 文件提供了 `green-user` 的客戶端憑證。因為用戶的 `current-user` 是 `green-user` ，任何該 API server 的客戶端使用該示例 kubeconfig 文件時都可以成功登錄。同樣，我們可以通過修改 `current-context` 的值以 `blue-user` 的身份操作。 在上面的示例中，`green-user` 通過提供憑據登錄，`blue-user` 使用的是 token。使用 `kubectl config set-credentials` 指定登錄信息。想了解更多信息，請訪問 "[示例文件相關操作命令](https://kubernetes.io/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig#commands-for-the-example-file)"。 ## 加載和合并規則 加載和合并 kubeconfig 文件的規則很簡單，但有很多。最終的配置按照以下順序構建： 1. 從磁盤中獲取 kubeconfig。這將通過以下層次結構和合并規則完成： 如果設置了 `CommandLineLocation` （`kubeconfig` 命令行參數的值），將會只使用該文件，而不會進行合并。該參數在一條命令中只允許指定一次。 或者，如果設置了 `EnvVarLocation` （`$KUBECONFIG` 的值），其將會被作為應合并的文件列表，并根據以下規則合并文件。空文件名被忽略。非串行內容的文件將產生錯誤。設置特定值或 map key 的第一個文件將優先使用，并且值或 map key 也永遠不會更改。 這意味著設置 CurrentContext 的第一個文件將保留其上下文。 這也意味著如果兩個文件同時指定一個 `red-user`，那么將只使用第一個文件中的 `red-user` 的值。 即使第二個文件的 `red-user` 中有非沖突條目也被丟棄。 另外，使用 Home 目錄位置（`~/.kube/config`）將不會合并。 2. 根據此鏈中的第一個命中確定要使用的上下文 1. 命令行參數——`context` 命令行選項的值 2. 來自合并后的 `kubeconfig` 文件的 `current-context` 3. 在這個階段允許空 3. 確定要使用的群集信息和用戶。此時，我們可能有也可能沒有上下文。他們是基于這個鏈中的第一次命中。 （運行兩次，一次為用戶，一次為集群） 1. 命令行參數——`user` 指定用戶，`cluster` 指定集群名稱 2. 如果上下文存在，則使用上下文的值 3. 允許空 4. 確定要使用的實際群集信息。此時，我們可能有也可能沒有集群信息。根據鏈條構建每個集群信息（第一次命中勝出）： 1. 命令行參數——`server`，`api-version`，`certificate-authority` 和 `insecure-skip-tls-verify` 2. 如果存在集群信息，并且存在該屬性的值，請使用它。 3. 如果沒有服務器位置，則產生錯誤。 5. 確定要使用的實際用戶信息。用戶使用與集群信息相同的規則構建，除非，您的每個用戶只能使用一種認證技術。 1. 負載優先級為1）命令行標志 2）來自 kubeconfig 的用戶字段 2. 命令行標志是：`client-certificate`、`client-key`、`username`、`password` 和 `token` 3. 如果有兩種沖突的技術，則失敗。 6. 對于任何仍然缺少的信息，將使用默認值，并可能會提示驗證信息 7. Kubeconfig 文件中的所有文件引用都相對于 kubeconfig 文件本身的位置進行解析。當命令行上顯示文件引用時，它們將相對于當前工作目錄進行解析。當路徑保存在 `~/.kube/config` 中時，相對路徑使用相對存儲，絕對路徑使用絕對存儲。 Kubeconfig 文件中的任何路徑都相對于 kubeconfig 文件本身的位置進行解析。 ## 使用 `kubectl config <subcommand>` 操作 kubeconfig `kubectl config` 有一些列的子命令可以幫助我們更方便的操作 kubeconfig 文件。 請參閱 `kubectl/kubectl_config`。 ### Example ```bash $ kubectl config set-credentials myself --username=admin --password=secret $ kubectl config set-cluster local-server --server=http://localhost:8080 $ kubectl config set-context default-context --cluster=local-server --user=myself $ kubectl config use-context default-context $ kubectl config set contexts.default-context.namespace the-right-prefix $ kubectl config view ``` 產生如下輸出： ```yaml apiVersion: v1 clusters: - cluster: server: http://localhost:8080 name: local-server contexts: - context: cluster: local-server namespace: the-right-prefix user: myself name: default-context current-context: default-context kind: Config preferences: {} users: - name: myself user: password: secret username: admin ``` Kubeconfig 文件會像這樣子： ```yaml apiVersion: v1 clusters: - cluster: server: http://localhost:8080 name: local-server contexts: - context: cluster: local-server namespace: the-right-prefix user: myself name: default-context current-context: default-context kind: Config preferences: {} users: - name: myself user: password: secret username: admin ``` #### 示例文件相關操作命令 ```Bash $ kubectl config set preferences.colors true $ kubectl config set-cluster cow-cluster --server=http://cow.org:8080 --api-version=v1 $ kubectl config set-cluster horse-cluster --server=https://horse.org:4443 --certificate-authority=path/to/my/cafile $ kubectl config set-cluster pig-cluster --server=https://pig.org:443 --insecure-skip-tls-verify=true $ kubectl config set-credentials blue-user --token=blue-token $ kubectl config set-credentials green-user --client-certificate=path/to/my/client/cert --client-key=path/to/my/client/key $ kubectl config set-context queen-anne-context --cluster=pig-cluster --user=black-user --namespace=saw-ns $ kubectl config set-context federal-context --cluster=horse-cluster --user=green-user --namespace=chisel-ns $ kubectl config use-context federal-context ``` ### 最后將它們捆綁在一起 所以，將這一切綁在一起，快速創建自己的 kubeconfig 文件： - 仔細看一下，了解您的 api-server 的啟動方式：在設計 kubeconfig 文件以方便身份驗證之前，您需要知道您自己的安全要求和策略。 - 將上面的代碼段替換為您的集群的 api-server 端點的信息。 - 確保您的 api-server 至少能夠以提供一個用戶（即 `green-user`）憑據的方式啟動。 當然您必須查看 api-server 文檔，以了解當前關于身份驗證細節方面的最新技術。