預設映像檔取回密碼設定

一般而言，您的 IBM Cloud Kubernetes Service 群集設定為只從 default Kubernetes 名稱空間中的所有 IBM Cloud Container Registry icr.io 網域拉取影像。 檢閱下列常見問題，進一步瞭解如何在其他 Kubernetes 命名空間或帳戶中拉取影像、限制拉取存取，或您的群集可能沒有預設影像拉取秘訣的原因。

我的叢集該如何設定，才能從 default 的 Kubernetes 命名空間 拉取映像檔？

當您建立叢集時，叢集具有 IBM Cloud IAM 服務 ID，而此服務 ID 獲提供 IBM Cloud Container Registry 的 IAM Reader 服務存取角色原則。 在叢集的映像檔取回密碼所儲存的未到期 API 金鑰中，模擬服務 ID 認證。 映像拉取密鑰已新增至 default Kubernetes 命名空間，並新增至 default 服務帳戶中此 Kubernetes 命名空間的密鑰清單中。 透過使用映像檔取回密碼，您的部署可以從 廣域及地區 IBM Cloud Container Registry 取回映像檔 (唯讀存取權)，以在 default Kubernetes 名稱空間中部署容器。

• 廣域登錄會安全地儲存 IBM所提供的公用映像檔。 您可以在部署之間參照這些公用映像檔，而不是對儲存在每一個地區登錄中的映像檔具有不同的參照。
• 地區登錄會安全地儲存您自己的專用 Docker 映像檔。

如果我在 default Kubernetes 名稱空間中沒有映像檔取回密碼，怎麼辦?

您可以透過 登入叢集 並執行 kubectl get secrets -n default | grep "icr-io" 來檢查映像檔取回密碼。 如果未列出任何 icr 密碼，則建立叢集的人員可能沒有 IAM 中 IBM Cloud Container Registry 的必要許可權。 請參閱「將現有叢集更新為使用 API 金鑰的映像檔提取密鑰」。

我可以將拉取存取權限限制在特定區域的註冊表上嗎？

是，您可以編輯服務 ID 的現有 IAM 原則，以將 Reader 服務存取角色限制為該地區登錄或登錄資源（例如名稱空間）。 必須為 IBM Cloud 啟用 IBM Cloud Container Registry IAM 原則後，才能自訂登錄 IAM 原則。

想要讓您的註冊表憑證更安全 請您的群集管理 員啟用群集中的金鑰管理服務提供者，以加密群集中的 Kubernetes 秘 密，例如儲存註冊表憑證的映像拉取密碼。

除了 default 之外，我能否從 Kubernetes 命名空間中拉取圖片？

依預設，不可以。 使用預設叢集設定，您可以將容器從儲存在 IBM Cloud Container Registry 名稱空間的任何映像檔中部署至叢集的 default Kubernetes 名稱空間。 若要在其他 Kubernetes 命名空間或 IBM Cloud 帳戶中使用這些映像，您可以選擇複製現有的映像拉取密鑰，或自行建立新的映像拉取密鑰。

我可以從另一個 IBM Cloud 帳戶匯入圖片嗎？

是，在您要使用的 IBM Cloud 帳戶中建立 API 金鑰。 然後，在您要從 IBM Cloud 帳戶取回映像檔的每一個叢集的每一個名稱空間中，建立一個密鑰來保留 API 金鑰。 如需更多資訊，請參考此範例，該範例使用經授權的服務 ID API 金鑰。

若要使用 Docker 這類非 IBM Cloud 登錄，請參閱存取儲存在其他專用登錄中的映像檔。

API 金鑰是否必須對應於某個服務 ID？ 如果我的帳戶達到服務 ID 的上限，會發生什麼情況？

預設叢集設定會建立一個服務 ID，以將 IBM Cloud IAM API 金鑰認證儲存在映像檔取回密碼中。 不過，您也可以建立個別使用者的 API 金鑰，並將那些認證儲存在映像檔取回密碼中。 若您達到 IAM 對服務 ID 的限制，您的叢集將在未包含服務 ID 和映像檔拉取密鑰的情況下建立，且預設無法從 icr.io 註冊表網域拉取映像檔。 您必須建立自己的映像檔取回密碼，但建立時須使用個別使用者（例如功能 ID，而不是 IBM Cloud IAM 服務 ID）的 API 金鑰。

我看到區域登錄網域及所有登錄網域的映像檔取回密碼。 我要用哪一個?

先前，IBM Cloud Kubernetes Service 為每個地區、公用 icr.io 登錄網域建立了個別映像檔取回密碼。 現在，所有地區的所有公用及專用 icr.io 登錄網域都儲存在單一 all-icr-io 映像檔取回密碼中，該密碼會自動建立在叢集的 default Kubernetes 名稱空間中。

對於叢集裡其他 Kubernetes 名稱空間中的工作量，以從專用登錄取回容器映像檔，您現在只能將 all-icr-io 映像檔取回密碼複製到該 Kubernetes 名稱空間。 然後，在服務帳戶或部署中指定 all-icr-io 密碼。 您不再需要複製符合映像檔地區登錄的映像檔取回密碼。 此外，請記住您不需要公用登錄的映像檔取回密碼，這不需要鑑別。

在另一個 Kubernetes 命名空間中複製或建立一個映像拉取密鑰後，是否就大功告成了？

還沒。 容器必須有權使用所建立的密碼來取回映像檔。 您可以將映像檔取回密碼新增至名稱空間的服務帳戶，或在每次部署時參照密碼。 如需指示，請參閱使用映像檔取回密碼部署容器。

icr.io 登錄的專用網路連線

當您設定 IBM Cloud 帳戶以使用服務端點時，您可以使用私人網路連線將影像推送至 IBM Cloud Container Registry，或從 抓取影像。

我需要做什麼才能設定叢集以使用 icr.io 登錄的專用連線?

1. 啟用 IBM Cloud 基礎架構帳戶的 虛擬路由器功能(VRF)，以便您可以使用 IBM Cloud Container Registry 專用雲端服務端點。 若要啟用 VRF，請參閱 啟用 VRF。 若要檢查是否已啟用 VRF，請使用 ibmcloud account show 指令。
2. 啟用 IBM Cloud 帳戶，以使用服務端點。

IBM Cloud Container Registry 會自動使用專用雲端服務端點。 您不需要啟用 IBM Cloud Kubernetes Service 叢集的專用雲端服務端點。

更新映像檔取回密碼

若要更新位於 default Kubernetes 命名空間中的叢集映像拉取祕密。

1. 取得叢集 ID。

   ibmcloud ks cluster ls
   

2. 執行下列指令，以建立叢集的服務 ID，並將 IBM Cloud Container Registry的 IAM 讀者 服務存取角色指派給服務 ID。 該指令還會建立 API 金鑰以模擬服務 ID 認證，並將 API 金鑰儲存在叢集的 Kubernetes 映像檔取回密碼中。 映像檔取回密碼位於 default Kubernetes 名稱空間中。

   ibmcloud ks cluster pull-secret apply --cluster CLUSTER_NAME_OR_ID
   

   當您執行這個指令時，會起始建立 IAM 認證及映像檔取回密碼，這可能需要一點時間才能完成。 在建立映像檔拉取祕密之前，您無法部署從 IBM Cloud Container Registry icr.io 網域拉取映像檔的容器。

3. 驗證已在叢集裡建立映像檔取回密碼。

   kubectl get secrets | grep icr-io
   

   輸出範例

   all-icr-io           kubernetes.io/dockerconfigjson        1         16d
   

4. 更新 容器部署，以從 icr.io 網域名稱取回映像檔。

5. 可選步驟：若您有防火牆，請務必為您使用的網域設定 允許外發網路流量傳輸至註冊表子網。

6. 使用下列其中一個選項來完成設定。

   • 若要取回 default 以外的 Kubernetes 名稱空間中的映像檔，或從其他 IBM Cloud 帳戶中取回映像檔，請複製或建立另一個映像檔取回密碼。
   • 若要限制對特定登錄資源（例如，名稱空間或地區）的映像檔取回密碼存取權，請執行下列動作：
     1. 確保對 IBM Cloud 的 IBM Cloud Container Registry IAM 原則已啟用。
     2. 編輯 IBM Cloud IAM 原則（針對服務 ID），或建立另一個映像檔取回密碼。

複製現有的映像檔取回密碼

您可以將映像檔取回密碼（例如針對 default Kubernetes 名稱空間自動建立的映像檔取回密碼）複製到叢集裡的其他名稱空間。 如果您要針對此名稱空間使用不同的 IBM Cloud IAM API 金鑰認證（例如限制對特定名稱空間的存取），或要從其他 IBM Cloud 帳戶取回映像檔，請改為建立映像檔取回密碼。

1. 列出叢集裡可用的 Kubernetes 名稱空間，或建立要使用的名稱空間。

   kubectl get namespaces
   

   輸出範例

   default          Active    79d
   ibm-cert-store   Active    79d
   ibm-system       Active    79d
   kube-public      Active    79d
   kube-system      Active    79d
   

   建立名稱空間

   kubectl create namespace <namespace_name>
   

2. 列出 IBM Cloud Container Registry 之 default Kubernetes 名稱空間中的現有映像檔取回密碼。

   kubectl get secrets -n default | grep icr-io
   

   輸出範例

   all-icr-io          kubernetes.io/dockerconfigjson        1         16d
   

3. 將 default 命名空間中的「all-icr-io」映像拉取密鑰複製到您選擇的命名空間中。 新的映像拉取密鑰命名為 <namespace_name>-icr-<region>-io。

   kubectl get secret all-icr-io -n default -o yaml | sed 's/default/<new-namespace>/g' | kubectl create -n <new-namespace> -f -   
   

4. 驗證已順利建立密碼。

   kubectl get secrets -n <namespace_name> | grep icr-io
   

5. 若要部署容器，請 新增映像檔取回密碼 至每一個部署或名稱空間的服務帳戶，以便名稱空間中的任何部署都可以從登錄取回映像檔。

使用不同的 IAM API 金鑰認證建立映像檔取回密碼

可以將 IBM Cloud IAM 存取原則指派給使用者或服務 ID，以將許可權作用對象限制為特定登錄映像檔名稱空間或動作（例如，push 或 pull）。 然後，建立 API 金鑰，並將這些登錄認證儲存在叢集的映像檔取回密碼中。

例如，若要存取其他 IBM Cloud 帳戶中的映像檔，請建立 API 金鑰，以將使用者或服務 ID 的 IBM Cloud Container Registry 認證儲存在該帳戶中。 然後，在叢集帳戶中，將 API 金鑰認證儲存在每個叢集和叢集名稱空間的映像檔取回密碼中。

下列步驟會建立 API 金鑰，用來儲存 IBM Cloud IAM 服務 ID 的認證。 您可能希望為具有對 IBM Cloud 的 IBM Cloud Container Registry IAM 服務存取原則的使用者 ID 建立 API 金鑰，而不使用服務 ID。 不過，請確定使用者是一個功能 ID，或具有可在使用者離開時讓叢集仍可存取登錄的方案。

1. 列出叢集裡可用的 Kubernetes 名稱空間，或建立要使用的名稱空間，而您要在其中從登錄映像檔部署容器。

   kubectl get namespaces
   

   輸出範例

   default          Active    79d
   ibm-cert-store   Active    79d
   ibm-system       Active    79d
   kube-public      Active    79d
   kube-system      Active    79d
   

   建立名稱空間

   kubectl create namespace <namespace_name>
   

2. 建立叢集的 IBM Cloud IAM 服務 ID，以用於映像檔取回密碼中的 IAM 原則及 API 金鑰認證。 請務必提供服務 ID 的說明，以協助您稍後擷取服務 ID，例如包括叢集和名稱空間名稱。

   ibmcloud iam service-id-create <cluster_name>-<namespace>-id --description "Service ID for IBM Cloud Container Registry in Kubernetes cluster <cluster_name> namespace <namespace>"
   

3. 建立叢集服務 ID 的自訂 IBM Cloud IAM 原則，以授與 IBM Cloud Container Registry 的存取權。

   ibmcloud iam service-policy-create <cluster_service_ID> --roles <service_access_role> --service-name container-registry [--region <IAM_region>] [--resource-type namespace --resource <registry_namespace>]
   

   cluster_service_ID

   必要。 請將此處替換為您先前為 Kubernetes 叢集所建立的「<cluster_name>-<kube_namespace>-id」服務 ID。

   --service-name container-registry

   必要。 輸入 container-registry，讓 IAM 原則適用於 IBM Cloud Container Registry。

   --roles <service_access_role>

   必要。 請輸入您要對其設定服務 ID 存取範圍的「IBM Cloud Container Registry」服務存取角色。 可能值為 Reader、Writer 及 Manager。

   --region <IAM_region>

   選用。 如果您要將存取原則範圍限定為特定 IAM 地區，請以逗點區隔清單輸入地區。 可能的值為 global 及 local registry regiones。

   --resource-type namespace --resource <registry_namespace>

   選用。 若要將存取權限限制為僅限於特定 IBM Cloud Container Registry 命名空間中的 圖片，請在「資源類型」欄位中輸入 namespace，並指定 <registry_namespace>。 若要列出登錄名稱空間，請執行 ibmcloud cr namespaces。

4. 建立服務 ID 的 API 金鑰。 請將 API 金鑰命名為與您的服務 ID 相似的名稱，並包含您先前建立的服務 ID，<cluster_name>-<kube_namespace>-id 請務必提供 API 金鑰的說明，以協助您稍後擷取該金鑰。

   ibmcloud iam service-api-key-create <cluster_name>-<namespace>-key <cluster_name>-<namespace>-id --description "API key for service ID <service_id> in Kubernetes cluster <cluster_name> namespace <namespace>"
   

5. 從前一個指令的輸出中擷取 API 金鑰值。

   Please preserve the API key! It can't be retrieved after it's created.
   Name          <cluster_name>-<kube_namespace>-key   
   Description   key_for_registry_for_serviceid_for_kubernetes_cluster_multizone_namespace_test   
   Bound To      crn:v1:bluemix:public:iam-identity::a/1bb222bb2b33333ddd3d3333ee4ee444::serviceid:ServiceId-ff55555f-5fff-6666-g6g6-777777h7h7hh   
   Created At    2019-02-01T19:06+0000   
   API Key       i-8i88ii8jjjj9jjj99kkkkkkkkk_k9-llllll11mmm1   
   Locked        false   
   UUID          ApiKey-222nn2n2-o3o3-3o3o-4p44-oo444o44o4o4   
   

6. 建立一個映像拉取密鑰，用以將 API 金鑰憑證儲存於叢集命名空間中。 針對您要從中取回映像檔之每一個 icr.io 網域的每一個叢集的每一個名稱空間，重複此步驟。

   kubectl --namespace <namespace> create secret docker-registry <secret_name> --docker-server=<registry_URL> --docker-username=iamapikey --docker-password=<api_key_value> --docker-email=<docker_email>
   

   --namespace <namespace>

   必要。 指定您用於服務 ID 名稱之叢集的 Kubernetes 名稱空間。

   <secret_name>

   必要。 輸入映像檔取回密碼的名稱。

   --docker-server <registry_URL>

   必要。 設定在其中設定登錄名稱空間的映像檔登錄 URL。 如需可用的網域，請參閱 本端地區。

   --docker-username iamapikey

   必要。 請輸入使用者名稱以登入您的私人註冊庫。 如果您使用 IBM Cloud Container Registry，請輸入 iamapikey。

   --docker-password <token_value>

   必要。 請輸入您先前取得之 API Key 的值。

   --docker-email <docker-email>

   必要。 如果您有 Docker 電子郵件位址，請輸入它。 若您沒有電子郵件地址，請輸入一個虛構的電子郵件地址，例如 a@b.c。 需要有此電子郵件才能建立 Kubernetes 密碼，但在建立之後就不再使用。

7. 驗證已順利建立 Secret。 請將 替換為您建立映像拉取密鑰的 namespace 。

   kubectl get secrets --namespace <namespace>
   

8. 將映像檔取回密碼新增至 Kubernetes 服務帳戶，讓名稱空間中的任何 Pod 在部署容器時都可以使用映像檔取回密碼。

存取儲存在其他專用登錄中的映像檔

如果您已有專用登錄，則必須將登錄認證儲存在 Kubernetes 映像檔取回密碼中，然後從配置檔參照此密碼。

開始之前：

1. 建立叢集。
2. 請登入您的帳戶。 適用的話，請將適當的資源群組設為目標。 設定叢集的環境定義。

若要建立映像檔取回密碼，請執行下列動作：

1. 建立用來儲存專用登錄認證的 Kubernetes 密碼。

   kubectl --namespace <namespace> create secret docker-registry <secret_name>  --docker-server=<registry_URL> --docker-username=<docker_username> --docker-password=<docker_password> --docker-email=<docker_email>
   

   --namespace <namespace>

   必要。 您要使用密碼並在其中部署容器之叢集的 Kubernetes 名稱空間。 若要列出叢集中可用的命名空間，請執行 kubectl get namespaces。

   <secret_name>

   必要。 您要用於映像檔取回密碼的名稱。

   --docker-server <registry_URL>

   必要。 儲存專用映像檔的登錄的 URL。

   --docker-username <docker_username>

   必要。 用於登入您的私人註冊庫的用戶名稱。

   --docker-password <token_value>

   必要。 用來登入專用登錄的密碼，例如記號值。

   --docker-email <docker-email>

   必要。 如果您有 Docker 電子郵件位址，請輸入它。 若您沒有電子郵件地址，請輸入一個虛構的電子郵件地址，例如 a@b.c。 需要有此電子郵件才能建立 Kubernetes 密碼，但在建立之後就不再使用。

2. 驗證已順利建立 Secret。 將 <namespace> 取代為您在其中建立映像檔取回密碼的名稱空間名稱。

   kubectl get secrets --namespace <namespace>
   

3. 建立一個參照映像檔取回密碼的 Pod。

在所選取名稱空間的 Kubernetes 服務帳戶中儲存映像檔取回密碼

每個 Kubernetes 命名空間都有一組名為 default 的 Kubernetes 服務帳戶。 在名稱空間內，您可以將映像檔取回密碼新增至此服務帳戶，以授與 Pod 從登錄取回映像檔的存取權。 若部署未指定服務帳戶，系統會自動為此 Kubernetes 命名空間使用 default 服務帳戶。

1. 檢查預設服務帳戶是否已有映像檔取回密碼。

   kubectl describe serviceaccount default -n <namespace_name>
   

   當「<none>」顯示在「映像檔提取密鑰」欄位中時，表示不存在任何映像檔提取密鑰。

2. 將映像檔取回密碼新增至預設服務帳戶。

   • 當未定義映像拉取密鑰時，用於新增映像拉取密鑰的範例指令。

       kubectl patch -n <namespace_name> serviceaccount/default -p '{"imagePullSecrets":[{"name": "<image_pull_secret_name>"}]}'
       ```
   - 當已定義映像拉取密鑰時，用於新增映像拉取密鑰的範例指令。
   
   ```sh {: pre}
       kubectl patch -n <namespace_name> serviceaccount/default --type='json' -p='[{"op":"add","path":"/imagePullSecrets/-","value":{"name":"<image_pull_secret_name>"}}]'
       ```
   

3. 驗證映像檔取回密碼已新增至預設服務帳戶。

   kubectl describe serviceaccount default -n <namespace_name>
   

   輸出範例

   Name:                default
   Namespace:           <namespace_name>
   Labels:              <none>
   Annotations:         <none>
   Image pull secrets:  <image_pull_secret_name>
   Mountable secrets:   default-token-sh2dx
   Tokens:              default-token-sh2dx
   Events:              <none>
   

   如果 映像檔取回密碼 指出 <secret> (not found)，請執行 kubectl get secrets -n namespace，以驗證映像檔取回密碼存在於與服務帳戶相同的名稱空間中。

4. 建立名為 mypod.yaml 的 Pod 配置檔，以從登錄中的 映像檔 部署容器。

   apiVersion: v1
   kind: Pod
   metadata:
     name: mypod
   spec:
     containers:
       - name: mypod-container
         image: <region>.icr.io/<namespace>/<image>:<tag>
   

5. 透過套用 mypod.yaml 配置檔，在叢集中建立 Pod。

   kubectl apply -f mypod.yaml
   

更新 containerd 自訂登錄配置的 daemonset 範例

使用範例 YAML 檔案來定義在所有工作者節點上執行的 daemonset，以設定或更新 containerd 登錄主機配置，並裝載至對應的 containerd 登錄路徑。

此範例設定 dockerhub 的下列登錄主機配置。 已提供此登錄主機配置，並在工作者節點佈建階段期間自動配置。 在部署之後及工作者節點重新載入或重新啟動之後，init 儲存器會在每個工作者節點上起始設定 hosts.toml。

server = "https://docker.io"
[host."https://registry-1.docker.io"]
capabilities = ["pull", "resolve"]

YAML 檔案範例：

apiVersion: apps/v1
kind: DaemonSet
metadata:
labels:
    name: containerd-dockerhub-registry-config
name: containerd-dockerhub-registry-config
namespace: kube-system
spec:
selector:
    matchLabels:
    name: containerd-dockerhub-registry-config
template:
    metadata:
    labels:
        name: containerd-dockerhub-registry-config
    spec:
    initContainers:
    - image: alpine:3.13.6
        name: containerd-dockerhub-registry-config
        command:
        - /bin/sh
        - -c
        - |
            #!/bin/sh
            set -uo pipefail
            cat << EOF > /etc/containerd/certs.d/docker.io/hosts.toml
            server = "https://docker.io"
            [host."https://registry-1.docker.io"]
            capabilities = ["pull", "resolve"]
            EOF
        volumeMounts:
        - mountPath: /etc/containerd/certs.d/docker.io/
        name: dockerhub-registry-config
    containers:
    - name: pause
        image: "us.icr.io/armada-master/pause:3.5"
        imagePullPolicy: IfNotPresent
    volumes:
    - name: dockerhub-registry-config
        hostPath:
        path: /etc/containerd/certs.d/docker.io/

如需更新 containerd 登錄主機配置的相關資訊，請參閱 containerd 文件。