Accede a registros privados con certificados de la AC privados

Autopilot Estándar

En esta página, se muestra cómo permitir que las cargas de trabajo que se ejecutan en Google Kubernetes Engine (GKE) accedan a los registros de imágenes privadas mediante la clave pública de la autoridad certificadora (CA) que emitió el certificado para el registro.

Cómo funciona

Almacena la clave pública de la CA que se usa a fin de emitir certificados para tus registros privados en Secret Manager y configura qué nombres de dominio completamente calificados (FQDN) usan esa clave pública para la validación de certificados. GKE recupera de forma automática la clave y actualiza la configuración de registro del entorno de ejecución del contenedor durante el arranque de nodos. Cuando implementas una carga de trabajo que usa una imagen de contenedor de tu registro privado, se producen los siguientes pasos:

El kubelet del nodo intenta extraer la imagen del registro privado.
El registro presenta un certificado TLS del servidor.
El entorno de ejecución del contenedor valida el certificado de registro de manera criptográfica y para garantizar que el FQDN coincida con lo que especificaste.
Si la validación se aprueba, GKE extrae la imagen y programa la carga de trabajo.

Ventajas

Este método de acceso a los registros privados proporciona beneficios como los siguientes:

Mejora la confiabilidad de la configuración del entorno de ejecución del contenedor: Usar métodos como DaemonSets para establecer la configuración de containerd agrega un riesgo de que ocurra una condición de carrera, en la que otros DaemonSets pueden ejecutarse antes de tu DaemonSet de configuración.
Reduce la vulnerabilidad de los ataques de elevación de privilegios: Elimina la necesidad de ejecutar DaemonSets con privilegios que modifiquen la configuración del entorno de ejecución del contenedor.
Reduce la sobrecarga de administración: Secret Manager te permite almacenar claves públicas de CA en una ubicación central. administrar el acceso a las claves mediante IAM; e implementar el control de versión y las anotaciones. Para obtener más información, consulta la descripción general del producto Secret Manager.
Mejora la auditabilidad: Cloud Logging ya recopila registros, incluso cuando se agregan certificados a un clúster y cuando los nodos de GKE extraen imágenes.

Precios

En este documento, usarás los siguientes componentes facturables de Google Cloud:

GKE
Secret Manager
Logging: GKE genera registros de auditoría de actividad del administrador y, si están habilitados, registros de auditoría de acceso a los datos para esta característica. Para obtener información sobre los diferentes tipos de registros de auditoría, consulta Registro de auditoría de GKE.

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Antes de comenzar

Antes de comenzar, asegúrate de haber realizado las siguientes tareas:

Habilita la API de Kubernetes Engine de Google.

Habilitar la API de Kubernetes Engine de Google

Si deseas usar Google Cloud CLI para esta tarea, instala y, luego, inicializa gcloud CLI. Si ya instalaste gcloud CLI, ejecuta gcloud components update para obtener la versión más reciente.
Nota: Para las instalaciones de gcloud CLI existentes, asegúrate de configurar las propiedades compute/region y compute/zone. Cuando configuras las ubicaciones predeterminadas, puedes evitar errores en la gcloud CLI como el siguiente: One of [--zone, --region] must be supplied: Please specify location.

Habilita la API de Secret Manager.
Habilita la API
Ya debes tener un registro privado y certificados de la AC privados para acceder al registro. En esta guía, no se abarca la configuración de un registro privado ni la creación de certificados.

Requisitos

Si deseas usar claves públicas de CA privadas para acceder a registros privados, debes cumplir con los siguientes requisitos:

Tus clústeres deben usar la versión 1.27.3-gke.1700 de GKE o una posterior.
Debes usar una imagen de nodo Container-Optimized OS con containerd, que es la opción predeterminada para todos los clústeres de GKE. Las imágenes de nodo de Ubuntu con containerd no son compatibles. Las imágenes de nodos de Windows Server no son compatibles.
Tus grupos de nodos deben tener el permiso de acceso cloud-platform para que los nodos descarguen los certificados. Para obtener más información, consulta Permisos de acceso predeterminados en GKE. En este documento, se incluyen instrucciones para establecer el permiso de acceso cuando creas un clúster o grupo de nodos.

Limitaciones

Ten en cuenta las siguientes limitaciones:

No puedes usar certificados de la AC privados en las imágenes de nodo de Ubuntu.
No puedes usar certificados de la AC privados en los nodos de Windows Server.
Cada clúster admite hasta cinco certificados de la AC privados para registros privados.
Cada certificado puede tener hasta 25 nombres de dominio completamente calificados (FQDN).
Cada dominio solo se puede usar en un único archivo de certificado. Sin embargo, se admiten paquetes de certificados.
Los certificados deben estar codificados con PEM.
El servidor no rota los certificados de forma automática. Para obtener más información, consulta Rota tus certificados de la AC privados en este documento.
Los FQDN tienen las siguientes limitaciones:
- La longitud máxima del FQDN es de 255 caracteres, incluidos los caracteres especiales.
- Los FQDN solo pueden usar letras, números y guiones (-).
- Punycode no es compatible.
- No se admiten caracteres comodín.

Migra desde DaemonSets de configuración

En los clústeres de GKE Standard, puedes implementar DaemonSets con privilegios para modificar la configuración del entorno de ejecución del contenedor. Este método modifica directamente la configuración de containerd en cada nodo.

Si usas DaemonSets con privilegios para configurar el acceso a registros privados, ten en cuenta lo siguiente antes de usar este documento:

El almacenamiento de claves públicas de CA privadas en Secret Manager solo configura el access a registros privados. No se admite otra configuración relacionada con el registro.
Habilitar esta característica hace que tu clúster use el modelo de configuración de ruta de host de CRI de containerd, que no es compatible con el modelo de configuración anterior. Si tienes algún DaemonSet que modifique la configuración del host de containerd, por ejemplo, registros privados no seguros, duplicaciones o proxies, actualiza los DaemonSets para usar el modelo de ruta de host de CRI.

Para conocer los campos disponibles en el modelo de ruta de host de CRI, consulta Configuración del registro en el repositorio de GitHub de containerd.

Nota: Si inhabilitas esta función más adelante, los nodos volverán al modelo anterior para la configuración del registro en containerd. Debes modificar tus DaemonSets para usar el modelo anterior. Para obtener información sobre el modelo de configuración anterior, consulta Configura las credenciales de registro.

Cuando habilitas esta función, GKE aplica el modelo de configuración de ruta de host de CRI a los nodos nuevos del clúster. Los nodos existentes continúan usando el modelo de configuración anterior hasta que se vuelven a crear durante eventos como las actualizaciones.

Para reducir el riesgo de que tus DaemonSets de configuración no funcionen en nodos que usan un modelo de configuración específico, asegúrate de que tus DaemonSets usen de forma condicional un modelo de configuración específico según los archivos de configuración de containerd en el nodo. Este es el enfoque recomendado porque evita los problemas causados por un modelo de configuración incompatible.

Almacena tus claves públicas de CA en Secret Manager

Almacena las claves públicas de las CA privadas que emiten tus certificados de registro privado como secretos en Secret Manager. Para obtener instrucciones, en la documentación de Secret Manager, consulta Crea un secreto.

Configura el acceso a Secret Manager desde GKE

Para garantizar que la cuenta de servicio de IAM del clúster tenga los permisos necesarios para extraer secretos de Secret Manager, pídele a tu administrador que otorgue a la cuenta de servicio de IAM del clúster los siguientes roles de IAM en el secreto:

Accede al contenido de los Secrets: Usuario con acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor)
Accede a los metadatos de Secrets: Visualizador de Secret Manager (roles/secretmanager.viewer)

Si quieres obtener más información para otorgar roles, consulta Administra el acceso.

Estos roles predefinidos contienen los permisos necesarios para extraer secretos de Secret Manager. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para extraer secretos de Secret Manager:

resourcemanager.projects.get
resourcemanager.projects.list
secretmanager.secrets.get
secretmanager.secrets.list
secretmanager.versions.get
secretmanager.versions.list
secretmanager.versions.access

Es posible que tu administrador también pueda otorgar estos permisos a la cuenta de servicio de IAM del clúster con roles personalizados o con otros roles predefinidos.

Si no asociaste una cuenta de servicio de IAM personalizada con tu clúster o grupo de nodos, que es nuestro enfoque recomendado, el clúster usa la cuenta de servicio predeterminada de Compute Engine. Si es posible, te recomendamos que configures tus clústeres y grupos de nodos con una cuenta de servicio de IAM con privilegios mínimos. Para obtener instrucciones, consulta Usa cuentas de servicio con privilegios mínimos.

Crea un archivo de configuración del entorno de ejecución

Para habilitar la capacidad de usar certificados de la AC privados para los registros privados en GKE, crea un archivo YAML a fin de modificar la configuración de containerd.

Obtén tu número de proyecto de Google Cloud:
```
gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"
```
El resultado es el número de proyecto numérico.
Guarda la siguiente configuración como containerd-configuration.yaml.
```
privateRegistryAccessConfig:
enabled: true
certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
      secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION
    fqdns:
      - "FQDN1"
      - "FQDN2"
```
Reemplaza lo siguiente:
- PROJECT_NUMBER: El número de proyecto que obtuviste en el paso anterior.
- SECRET_VERSION: Es el número de versión de tu Secret en Secret Manager. De forma opcional, puedes usar un alias de versión, pero te recomendamos usar el número de versión para evitar la complejidad de la administración.
- FQDN1, FQDN2: Son los nombres de dominio completamente calificados para tus registros privados. También puedes usar una dirección IPv4 si se emitió un certificado para esa dirección, pero no lo recomendamos.

Para obtener una descripción de estos campos, consulta privateRegistryAccessConfig en la tabla de opciones de configuración de containerd disponible.

Aplica la configuración de containerd a clústeres nuevos

En esta sección, se muestra cómo aplicar un archivo de configuración containerd cuando creas un clúster de GKE nuevo.

Ejecuta el siguiente comando:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Reemplaza lo siguiente:

CLUSTER_NAME: Es el nombre del clúster nuevo.
LOCATION: la ubicación de Compute Engine para el clúster nuevo.
PATH_TO_CONFIG_FILE: la ruta de acceso al archivo de configuración que creaste, como ~/containerd-configuration.yaml.

Puedes habilitar la configuración de registro privado en los clústeres estándar nuevos mediante la ejecución del comando gcloud container clusters create con las mismas opciones.

Aplica la configuración de containerd a los clústeres existentes

En esta sección, se muestra cómo aplicar una configuración de containerd a clústeres y nodos existentes.

Verifica los permisos de acceso

Los clústeres existentes deben tener el permiso de acceso cloud-platform para usar esta función. En esta sección, se muestra cómo verificar los permisos de acceso y actualizar un clúster existente con un archivo de configuración de registro privado nuevo o modificado.

Para obtener detalles sobre los permisos de acceso predeterminados en clústeres nuevos, consulta Permisos de acceso en GKE.

Verifica los permisos de acceso de Autopilot

Ejecuta el siguiente comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Si tu clúster no tiene el permiso de acceso https://www.googleapis.com/auth/cloud-platform, crea un clúster nuevo con este permiso de acceso.

Verifica los permisos de acceso de Standard

Para verificar los permisos de acceso al clúster de Standard, verifica un grupo de nodos:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Reemplaza NODE_POOL_NAME por el nombre del grupo de nodos.

Si tu clúster no tiene el permiso de acceso https://www.googleapis.com/auth/cloud-platform, crea un grupo de nodos nuevo con el permiso de acceso cloud-platform y borra tu grupo de nodos existente.

Actualiza el clúster para usar tu archivo de configuración

Ejecuta el siguiente comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Vuelve a crear los nodos en los clústeres de Standard

Si tu clúster de Standard no usa actualizaciones automáticas, debes volver a crear manualmente tus grupos de nodos para aplicar la configuración nueva. Para activar una recreación manual de nodos, actualiza tu clúster a la misma versión de GKE que ya usa.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Reemplaza VERSION por la misma versión del parche de GKE que el clúster ya usa.

Verifica que tu clúster pueda acceder al registro privado

Ejecuta el siguiente comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten="nodePoolDefaults.nodeConfigDefaults.containerdConfig"

El resultado es similar al siguiente:

    containerdConfig:
      privateRegistryAccessConfig:
        certificateAuthorityDomainConfig:
        - fqdns:
          - 203.0.113.105
          gcpSecretManagerCertificateConfig:
            secretUri: projects/123456789012/secrets/example-secret-name/versions/1
        enabled: true

Implementa una carga de trabajo que acceda a una imagen privada

En esta sección, implementarás un Pod estático que hace referencia a una imagen de tu registro privado.

Guarda el siguiente manifiesto como private-registry-pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: private-registry-pod
spec:
  containers:
  - name: private-image
    image: IMAGE_NAME

Reemplaza IMAGE_NAME por el nombre de tu imagen privada.

Implementa el Pod:

kubectl create -f private-registry-pod.yaml

Rota tus certificados de la AC privados

Secret Manager y GKE no pueden rotar de forma automática los certificados de la AC privados en Secret Manager. Para realizar una rotación de certificado, sigue estos pasos. Estos pasos requieren que vuelvas a crear los nodos existentes dos veces. Te recomendamos que realices rotaciones de certificados durante el tiempo de inactividad programado para minimizar el impacto de las interrupciones de la carga de trabajo.

Crea un paquete de certificados con codificación PEM que contenga los certificados antiguos y nuevos.
Agrega el paquete como una versión nueva del secreto en Secret Manager.
Actualiza el campo secretURI del archivo de configuración del entorno de ejecución con el nuevo número de versión del secreto.
Actualiza el clúster para usar la versión nueva del secreto.

Obtén la marca de tiempo de la operación de actualización:

gcloud container operations list \
    --filter="operationType ~ UPDATE_CLUSTER AND targetLink ~ CLUSTER_NAME" \
    --sort-by=startTime \
    --limit=1 \
    --format='value(endTime)'

El resultado es similar al siguiente:

2024-01-31T09:27:30.864308964Z

Busca los nodos que se crearon antes de que finalizara la operación de actualización:
```
kubectl get nodes -o json | jq ".items[] |
select(.metadata.creationTimestamp | fromdateiso8601 < $(date -d
CLUSTER_UPDATE_TIMESTAMP +%s)) | .metadata.name"
```
Reemplaza CLUSTER_UPDATE_TIMESTAMP por la marca de tiempo del paso anterior.

El resultado es una lista de nombres de nodos que no se volvieron a crear con la configuración actualizada. Cuando el resultado esté en blanco, continúa con el siguiente paso.
Crea una versión nueva del secreto en Secret Manager solo con el certificado nuevo.
Repite los pasos anteriores para actualizar tu clúster, obtener la marca de tiempo de la operación y verificar que tus nodos usen la versión nueva del secreto.
Borra la versión anterior del secreto de Secret Manager.

Visualiza registros de auditoría en Logging

En esta sección, se muestra cómo usar Logging para verificar si GKE instaló la versión del secreto en tus nodos.

Ve al Explorador de registros en la consola de Google Cloud:

Ir al Explorador de registros

Especifica la siguiente consulta:

resource.type="gce_instance"
textPayload:"Installed certificate \\\"projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION\\\""

Si la instalación del certificado se realizó de forma correcta, el resultado es similar al siguiente:

"Installed certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Si la instalación del certificado falló, el resultado es similar al siguiente:

"Failed to install certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

prácticas recomendadas

Te recomendamos que uses las siguientes prácticas recomendadas cuando uses esta función:

No uses alias para versiones de secretos de Secret Manager. Usa el número de versión generado automáticamente para cada versión del secreto. Un alias puede apuntar a una versión de certificado diferente a lo largo del tiempo, lo que puede causar complejidades en el seguimiento de las versiones específicas que usan tus cargas de trabajo.
Usa las exclusiones y los períodos de mantenimiento para controlar cuándo GKE puede volver a crear los nodos a fin de aplicar la configuración actualizada de containerd.
Proporciona acceso a los secretos a nivel del secreto, no a nivel del proyecto.

Inhabilita las opciones de configuración de containerd

Para quitar tu configuración personalizada, haz lo siguiente:

Actualiza el archivo de configuración para especificar enabled: false en el elemento de configuración que deseas inhabilitar y borrar cualquier otro campo en el elemento, como en el siguiente ejemplo:
```
privateRegistryAccessConfig:
  enabled: false
```
Aplica la configuración actualizada al clúster. Para obtener instrucciones, consulta Aplica la configuración de containerd a clústeres existentes.

Solución de problemas

Para conocer los pasos de solución de problemas, consulta Soluciona problemas del entorno de ejecución del contenedor.