Configuración del secreto predeterminado de extracción de imágenes

Generalmente, el clúster de IBM Cloud Kubernetes Service se configura para extraer imágenes de todos los dominios icr.io de IBM Cloud Container Registry solo desde el espacio de nombres de Kubernetes default. Revise las siguientes preguntas frecuentes para obtener más información sobre cómo extraer imágenes en otros espacios de nombres o cuentas de Kubernetes, restringir el acceso de extracción o por qué su clúster podría no tener los secretos de extracción de imágenes predeterminados.

¿Cómo está configurado mi clúster para extraer imágenes del espacio de nombres default Kubernetes?

Cuando se crea un clúster, este tiene un ID de servicio de IBM Cloud IAM al que se otorga a una política de rol de acceso al servicio de IAM de Lector sobre IBM Cloud Container Registry. Las credenciales de ID de servicio se copian en una clave de API que no caduca y que se guarda en secretos de extracción de imágenes en el clúster. Los secretos de extracción de imágenes se añaden al espacio de nombres default de Kubernetes y la lista de secretos en la cuenta de servicio default para este espacio de nombres de Kubernetes. Mediante el uso de secretos de extracción de imágenes, los despliegues pueden extraer imágenes (acceso de solo lectura) de IBM Cloud Container Registry global y regional para desplegar contenedores en el espacio de nombres default de Kubernetes.

• El registro global almacena de forma segura imágenes públicas proporcionadas por IBM. Puede hacer referencia a estas imágenes públicas en todos los despliegues en lugar de tener referencias diferentes para las imágenes almacenadas en cada registro regional.
• El registro regional almacena de forma segura sus imágenes de Docker privadas.

¿Qué ocurre si no tengo secretos de extracción de imágenes en el espacio de nombres default Kubernetes?

Puede comprobar los secretos de extracción de imágenes iniciando una sesión en el clúster y ejecutando kubectl get secrets -n default | grep "icr-io". Si no se muestra ningún secreto de icr, es posible que la persona que ha creado el clúster no tuviera los permisos necesarios para IBM Cloud Container Registry en IAM. Consulte Actualización de clústeres existentes para que utilicen el secreto de obtención de imágenes de clave de API.

¿Puedo restringir el acceso a un determinado registro regional?

Sí, puede editar la política IAM del ID de servicio existente que restringe el rol de acceso al servicio Lector a dicho registro regional o a un recurso de registro como, por ejemplo, un espacio de nombres. Para poder personalizar las políticas IAM de registro, hay que habilitar IBM Cloudlas políticas IAM para IBM Cloud Container Registry.

Si desea proteger aún más las credenciales del registro, solicite al administrador del clúster que habilite un proveedor de servicio de gestión de claves en el clúster para cifrar los secretos de Kubernetes del clúster como, por ejemplo, el secreto de extracción de imágenes que almacena las credenciales del registro.

¿Puedo extraer imágenes de un espacio de nombres de Kubernetes que no sea default?

No de forma predeterminada. Utilizando la configuración de clúster predeterminada, puede desplegar contenedores desde cualquier imagen almacenada en su espacio de nombres de IBM Cloud Container Registry al espacio de nombres default de Kubernetes de su clúster. Para utilizar estas imágenes en cualquier otro espacio de nombres de Kubernetes o en otras cuentas de IBM Cloud, tiene la opción de copiar o crear sus propios secretos de extracción de imágenes.

¿Puedo extraer imágenes de una cuenta de IBM Cloud diferente?

Sí, cree una clave de API en la cuenta de IBM Cloud que desea utilizar. A continuación, en cada espacio de nombres de cada clúster del que desee extraer imágenes de la cuenta de IBM Cloud, cree un secreto que contenga la clave de API. Para obtener más información, siga con este ejemplo en el que se utiliza una clave de API de ID de servicio autorizada.

Para utilizar un registro que no sea de IBM Cloud, como por ejemplo Docker, consulte Acceso a imágenes almacenadas en otros registros privados.

¿La clave API debe ser para un ID de servicio? ¿Qué ocurre si alcanzo el límite de identificaciones de servicio para mi cuenta?

La configuración de clúster predeterminada crea un ID de servicio para almacenar las credenciales de clave de API de IBM Cloud IAM en el secreto de extracción de imágenes. No obstante, también puede crear una clave de API para un usuario individual y almacenar esas credenciales en un secreto de extracción de imágenes. Si llega al límite de ID de servicio de IAM, el clúster se crea sin ID de servicio ni secreto de extracción de imágenes y no puede extraer imágenes de los dominios de registro de icr.io de forma predeterminada. Debe crear su propio secreto de extracción de imágenes, pero utilizando una clave de API para un usuario individual como, por ejemplo, un ID funcional, no un ID de servicio de IBM Cloud IAM.

Veo secretos de extracción de imágenes para los dominios de registro regionales y todos los dominios de registro. ¿Cuál debo usar?

Anteriormente, IBM Cloud Kubernetes Service creaba secretos de extracción de imágenes independientes para cada dominio de registro regional público icr.io. Ahora, todos los dominios de registro icr.io públicos y privados para todas las regiones se almacenan en un único secreto de extracción de imágenes all-icr-io que se crea automáticamente en el espacio de nombres default de Kubernetes del clúster.

Para que las cargas de trabajo en otros espacios de nombres de Kubernetes del clúster puedan extraer imágenes de contenedor de un registro privado, ahora puede copiar solo el secreto de extracción de imágenes all-icr-io para dicho espacio de nombres de Kubernetes. A continuación, especifique el secreto all-icr-io en la cuenta de servicio o en el despliegue. Ya no es necesario copiar el secreto de extracción de imágenes que corresponde al registro regional de la imagen. Además, recuerde que no necesita secretos de extracción de de imágenes para los registros públicos, que no requieren autenticación.

Después de copiar o crear un secreto de extracción de imágenes en otro espacio de nombres de Kubernetes, ¿he terminado?

No del todo. Los contenedores deben tener autorización para extraer imágenes utilizando el secreto que ha creado. Puede añadir el secreto de extracción de imágenes a la cuenta de servicio para el espacio de nombres, o bien puede hacer referencia al secreto en cada despliegue. Para obtener instrucciones, consulte Utilización del secreto de extracción de imágenes para desplegar contenedores.

Conexión de red privada con los registros icr.io

Cuando configure la cuenta de IBM Cloud de modo que utilice puntos finales de servicio, puede utilizar una conexión de red privada para enviar imágenes a IBM Cloud Container Registry y para extraer imágenes del mismo.

¿Qué tengo que hacer para configurar mi clúster para utilizar la conexión privada a los registros de icr.io?

1. Habilite una función de direccionador virtual (VRF) para la cuenta de infraestructura de IBM Cloud para poder utilizar el punto final de servicio en la nube privado de IBM Cloud Container Registry. Para habilitar VRF, consulte Habilitación de VRF. Para comprobar si un VRF ya está habilitado, utilice el mandato ibmcloud account show.
2. Habilite la cuenta de IBM Cloud para que utilice puntos finales de servicio.

IBM Cloud Container Registry utiliza automáticamente el punto final del servicio de nube privada. No es necesario habilitar el punto final de servicio de nube privada para los clústeres de IBM Cloud Kubernetes Service.

Actualización del secreto de extracción de imágenes

Para actualizar el secreto de extracción de imágenes en el espacio de nombres Kubernetes default:

1. Obtenga el ID del clúster.

   ibmcloud ks cluster ls
   

2. Ejecute el mandato siguiente para crear un ID de servicio para el clúster y asigne al ID de servicio el rol de acceso al servicio de IAM de Lector sobre IBM Cloud Container Registry. El mandato también crea una clave de API para suplantar las credenciales de ID de servicio y almacena la clave de API en un secreto de extracción de imágenes de Kubernetes en el clúster. El secreto de extracción de imágenes está en el espacio de nombres default de Kubernetes.

   ibmcloud ks cluster pull-secret apply --cluster <cluster_name_or_ID>
   

   Cuando ejecuta este mandato, se inicia la creación de credenciales de IAM y de secretos de extracción de imágenes, que puede tardar un rato en finalizar. No puede desplegar contenedores que extraigan una imagen de los dominios de IBM Cloud Container Registry icr.io hasta que se creen los secretos de extracción de imágenes.

3. Verifique que los secretos de extracción de imágenes se han creado en el clúster.

   kubectl get secrets | grep icr-io
   

   Salida de ejemplo

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

4. Actualice los despliegues de contenedor para que extraigan imágenes del nombre de dominio icr.io.

5. Opcional: Si tiene un cortafuegos, asegúrese de que permite el tráfico de red de salida a las subredes de registro para los dominios que utiliza.

6. Complete la configuración utilizando una de las opciones siguientes.

   • Para extraer imágenes en espacios de nombres de Kubernetes que no sean default o de otras cuentas de IBM Cloud, copie o cree otro secreto de extracción de imágenes.
   • Para restringir el acceso al secreto de extracción de imágenes a determinados recursos de registro, como por ejemplo espacios de nombres o regiones:
     1. Asegúrese de que las políticas de IBM Cloud IAM para IBM Cloud Container Registry estén habilitadas.
     2. Edite las políticas de IBM Cloud IAM para el ID de servicio o cree otro secreto de extracción de imágenes.

Copiar un secreto de extracción de imágenes existente

Puede copiar un secreto de extracción de imágenes, como el que se crea automáticamente para el espacio de nombres default de Kubernetes, a otros espacios de nombres en el clúster. Pero si desea utilizar diferentes credenciales de clave de API de IBM Cloud IAM para este espacio de nombres, como por ejemplo para restringir el acceso a espacios de nombres específicos o para extraer imágenes de otras cuentas de IBM Cloud, se recomienda que cree un secreto de extracción de imágenes.

1. Obtenga una lista de los espacios de nombres de Kubernetes disponibles en el clúster, o cree un espacio de nombres que utilizar.

   kubectl get namespaces
   

   Salida de ejemplo

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

   Para crear una espacio de nombres

   kubectl create namespace <namespace_name>
   

2. Obtenga una lista de los secretos de extracción de imágenes existentes en el espacio de nombres default de Kubernetes para IBM Cloud Container Registry.

   kubectl get secrets -n default | grep icr-io
   

   Salida de ejemplo

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

3. Copie el secreto de extracción de imágenes all-icr-io del espacio de nombres default en el espacio de nombres que elija. Los nuevos secretos de extracción de imágenes se denominan <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. Verifique que los secretos se han creado correctamente.

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

5. Para desplegar contenedores, añada el secreto de extracción de imágenes a cada despliegue o a la cuenta de servicio del espacio de nombres para que cualquier despliegue del espacio de nombres pueda extraer imágenes del registro.

Creación de un secreto de extracción de imágenes con distintas credenciales de clave de API de IAM

Puede asignar políticas de acceso de IBM Cloud IAM a usuarios o a un ID de servicio para restringir los permisos a determinados espacios de nombres de imágenes de registro o acciones (como por ejemplo push o pull). A continuación, cree una clave de API y almacene estas credenciales de registro en un secreto de extracción de imágenes para el clúster.

Por ejemplo, para acceder a las imágenes de otras cuentas de IBM Cloud, cree una clave de API que almacene las credenciales de IBM Cloud Container Registry de un usuario o un ID de servicio en dicha cuenta. A continuación, en la cuenta de su clúster, guarde las credenciales de clave de API en un secreto de extracción de imágenes para cada clúster y cada espacio de nombres de clúster.

En los pasos siguientes se crea una clave de API que almacena las credenciales de un ID de servicio de IBM Cloud IAM. En lugar de utilizar un ID de servicio, es posible que desee crear una clave de API para un ID de usuario que tenga una política de acceso al servicio de IBM Cloud IAM sobre IBM Cloud Container Registry. Sin embargo, asegúrese de que el usuario sea un ID funcional o tenga un plan para que el clúster pueda acceder al registro en el caso de que el usuario se vaya.

1. Obtenga una lista de los espacios de nombres de Kubernetes disponibles en el clúster, o cree un espacio de nombres para utilizar donde desea desplegar los contenedores desde las imágenes de registro.

   kubectl get namespaces
   

   Salida de ejemplo

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

   Para crear una espacio de nombres

   kubectl create namespace <namespace_name>
   

2. Cree un ID de servicio de IBM Cloud IAM para el clúster que se utiliza para las políticas de IAM y las credenciales de clave de API en el secreto de extracción de imágenes. Asegúrese de proporcionar al ID de servicio una descripción que le ayude a recuperar el ID de servicio posteriormente; por ejemplo, puede incluir el nombre del clúster y el del espacio de nombres.

   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. Cree una política de IBM Cloud IAM personalizada para el ID de servicio del clúster que otorgue acceso a 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

   Obligatorio. Sustitúyalo por el ID de servicio de <cluster_name>-<kube_namespace>-id que ha creado anteriormente para el clúster de Kubernetes.

   --service-name container-registry

   Obligatorio. Especifique container-registry para que la política de IAM se aplique a IBM Cloud Container Registry.

   --roles <service_access_role>

   Obligatorio. Especifique el rol de acceso al servicio de IBM Cloud Container Registry del acceso del ID de servicio. Los valores posibles son Reader, Writer y Manager.

   --region <IAM_region>

   Opcional. Si desea limitar la política de acceso a determinadas regiones de IAM, especifique las regiones en una lista separada por comas. Los valores posibles son global y las regiones de registro local.

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

   Opcional. Si desea limitar el acceso sólo a imágenes de determinados espacios de nombres de IBM Cloud Container Registry, especifique namespace para el tipo de recurso y especifique <registry_namespace>. Para ver una lista de los espacios de nombres, ejecute ibmcloud cr namespaces.

4. Cree una clave de API para el ID de servicio. Asigne a la clave API un nombre similar a su ID de servicio e incluya el ID de servicio que creó anteriormente <cluster_name>-<kube_namespace>-id. Asegúrese de especificar para la clave de API una descripción que le ayude a recuperar la clave posteriormente.

   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. Retrieve your API Key value from the output of the previous command.

   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. Cree un secreto de extracción de imágenes para almacenar las credenciales de clave de API en el espacio de nombres del clúster. Repita este paso para cada espacio de nombres de cada clúster de cada dominio icr.io del que desea extraer de imágenes.

   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>

   Obligatorio. Especifique el espacio de nombres de Kubernetes del clúster que ha utilizado para el nombre de ID de servicio.

   <secret_name>

   Obligatorio. Especifique un nombre para el secreto de extracción de imágenes.

   --docker-server <registry_URL>

   Obligatorio. Establezca el URL en el registro de imágenes en el que se ha configurado el espacio de nombres de registro. Para los dominios disponibles, consulte Regiones locales.

   --docker-username iamapikey

   Obligatorio. Especifique el nombre de usuario para iniciar una sesión en su registro privado. Si utiliza IBM Cloud Container Registry, especifique iamapikey.

   --docker-password <token_value>

   Obligatorio. Especifique el valor de API Key que ha recuperado anteriormente.

   --docker-email <docker-email>

   Obligatorio. Si tiene una, especifique la dirección de correo electrónico de Docker. Si no, especifique una dirección de correo ficticia como, por ejemplo, a@b.c. Este correo electrónico es necesario para crear un secreto de Kubernetes, pero no se utiliza después de la creación.

7. Verifique que el secreto se haya creado correctamente. Sustituya <namespace> por el namespace donde ha creado el secreto de extracción de imagen.

   kubectl get secrets --namespace <namespace>
   

8. Añada el secreto de extracción de imágenes a una cuenta de servicio de Kubernetes para que cualquier pod del espacio de nombres pueda utilizar el secreto de extracción de imágenes cuando despliegue un contenedor.

Acceso a imágenes almacenadas en otros registros privados

Si ya tiene un registro privado, debe almacenar las credenciales del registro en un secreto de extracción de imágenes de Kubernetes y hacer referencia a dicho secreto en su archivo de configuración.

Antes de empezar:

1. Cree un clúster.
2. Inicie una sesión en la cuenta. If applicable, target the appropriate resource group. Establezca el contexto para el clúster.

Para crear un secreto de extracción de imágenes:

1. Cree el secreto de Kubernetes para almacenar las credenciales del registro privado.

   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>

   Obligatorio. El espacio de nombres de Kubernetes del clúster en el que desea utilizar el secreto y desplegar los contenedores. Para obtener una lista de los espacios de nombres disponibles del clúster, ejecute el mandato kubectl get namespaces.

   <secret_name>

   Obligatorio. El nombre que desea utilizar para su secreto de extracción de imágenes.

   --docker-server <registry_URL>

   Obligatorio. El URL al registro en el que se están almacenadas sus imágenes privadas.

   --docker-username <docker_username>

   Obligatorio. El nombre de usuario para iniciar sesión en el registro privado.

   --docker-password <token_value>

   Obligatorio. La contraseña para iniciar una sesión en su registro privado, como por ejemplo un valor de clave.

   --docker-email <docker-email>

   Obligatorio. Si tiene una, especifique la dirección de correo electrónico de Docker. Si no tiene ninguna, escriba una dirección de correo electrónico ficticia, como por ejemplo a@b.c. Este correo electrónico es necesario para crear un secreto de Kubernetes, pero no se utiliza después de la creación.

2. Verifique que el secreto se haya creado correctamente. Sustituya <namespace> con el nombre del espacio de nombres en el que ha creado el secreto de extracción de imágenes.

   kubectl get secrets --namespace <namespace>
   

3. Cree un pod que haga referencia al secreto de extracción de imágenes.

Almacenamiento del secreto de extracción de imágenes en la cuenta de servicio de Kubernetes para el espacio de nombres seleccionado

Cada espacio de nombres de Kubernetes tiene una cuenta de servicio de Kubernetes que se denomina default. Dentro del espacio de nombres, puede añadir el secreto de extracción de imágenes a esta cuenta de servicio para otorgar acceso a los pods para extraer imágenes del registro. Los despliegues que no especifican una cuenta de servicio utilizan automáticamente la cuenta de servicio de default para este espacio de nombres de Kubernetes.

1. Compruebe si ya existe un secreto de extracción de imágenes para la cuenta de servicio predeterminada.

   kubectl describe serviceaccount default -n <namespace_name>
   

   Cuando se visualiza <none> en la entrada secretos de extracción de imágenes, no existe ningún secreto de extracción de imágenes.

2. Añada el secreto de extracción de imágenes a su cuenta de servicio predeterminada.

   • Ejemplo de comando de adición de un secreto de extracción de imágenes cuando no hay definido ningún secreto de extracción de imágenes.

     kubectl patch -n <namespace_name> serviceaccount/default -p '{"imagePullSecrets":[{"name": "<image_pull_secret_name>"}]}'
     

   • Ejemplo de comando de adición de un secreto de extracción de imágenes cuando ya hay definido un secreto de extracción de imágenes.

     kubectl patch -n <namespace_name> serviceaccount/default --type='json' -p='[{"op":"add","path":"/imagePullSecrets/-","value":{"name":"<image_pull_secret_name>"}}]'
     

3. Verifique que su secreto de extracción de imágenes se ha añadido a la cuenta de servicio predeterminada.

   kubectl describe serviceaccount default -n <namespace_name>
   

   Salida de ejemplo

   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>
   

   Si el secreto de extracción de imágenes indica <secret> (not found), verifique que el secreto de extracción de imagen existe en el mismo espacio de nombres que la cuenta de servicio ejecutando kubectl get secrets -n namespace.

4. Cree un archivo de configuración de pod denominado mypod.yaml para desplegar un contenedor a partir de una imagen del registro.

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

5. Cree el pod en el clúster aplicando el archivo de configuración mypod.yaml.

   kubectl apply -f mypod.yaml
   

Ejemplo de daemonset para actualizar una configuración de registro personalizado de containerd

Utilice el archivo YAML de ejemplo para definir un daemonset que se ejecute en todos los nodos de trabajador para establecer o actualizar una configuración de host de registro de containerd y montarla en la correspondiente vía de acceso de registro de containerd.

El ejemplo establece la siguiente configuración de host de registro para dockerhub. Esta configuración de host de registro ya se ha proporcionado y configurado automáticamente durante la fase de suministro de trabajadores. El contenedor init inicializa hosts.toml en cada nodo de trabajo después de la implementación y después de que los nodos de trabajo se recarguen o reinicien.

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

Archivo YAML de ejemplo:

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/

Para obtener más información sobre cómo actualizar una configuración de host de registro containerd, consulte la documentación de containerd.