Trabajar con el registro de contenedores

Acerca del Container registry

El Container registry almacena imágenes de contenedor dentro de tu organización o cuenta personal y te permite asociar una imagen a un repositorio. Puedes elegir si quieres heredar permisos desde un repositorio o si quieres configurar permisos granulares independientemente de un repositorio. También puedes acceder a imágenes de contenedor públicas de forma anónima.

Acerca del soporte para el Container registry

El Container registry es actualmente compatible con los siguientes formatos de contenedores de imagen:

• Docker Image Manifest V2, modelo 2
• Especificaciones de Open Container Initiative (OCI)

Cuando instalas o publicas una imagen de Docker, el Container registry es compatible con capas externas, tales como imágenes de Windows.

Autenticarse en el Container registry

Necesitas un token de acceso para publicar, instalar y eliminar paquetes privados, internos y públicos.

Puedes usar un personal access token (classic) para autenticarte en GitHub Packages o en la API de GitHub. Cuando creas un personal access token (classic), puedes asignar al token diferentes ámbitos en función de tus necesidades. Para obtener más información sobre los ámbitos relacionados con paquetes para unpersonal access token (classic), consulta "Acerca de los permisos para los Paquetes de GitHub".

Para autenticarte en un registro del GitHub Packages dentro de un flujo de trabajo de GitHub Actions, puedes utilizar:

• GITHUB_TOKEN para publicar los paquetes asociados con el repositorio del flujo de trabajo.
• Un personal access token (classic) con, al menos, ámbito de read:packages para instalar los paquetes asociados con otros repositorios privados (a los cuales no puede acceder GITHUB_TOKEN).

Autenticación en un flujo de trabajo de GitHub Actions

Este registro admite permisos granulares. Para los registros que admiten permisos detallados, si en el flujo de trabajo de GitHub Actions se usa un personal access token para autenticarse en un registro, se recomienda encarecidamente actualizar el flujo de trabajo para usar GITHUB_TOKEN. Para obtener instrucciones sobre cómo actualizar los flujos de trabajo que se autentican en un registro con un personal access token, consulta "Actualización de un flujo de trabajo que accede a un registro mediante un personal access token".

Puedes usar GITHUB_TOKEN en un flujo de trabajo de GitHub Actions para eliminar o restaurar paquetes mediante la API de REST, si el token tiene el permiso admin para el paquete. A los repositorios que publican paquetes mediante un flujo de trabajo y a los repositorios que se han conectado explícitamente a los paquetes se les concede automáticamente el permiso admin para los paquetes del repositorio.

Para más información sobre GITHUB_TOKEN, vea "Autenticación en un flujo de trabajo". Para obtener más información sobre los procedimientos recomendados al usar un registro en acciones, consulta "Fortalecimiento de seguridad para Acciones de GitHub".

También puedes optar por conceder permisos de acceso a paquetes de forma independiente para GitHub Codespaces y GitHub Actions. Para obtener más información, consulta "Garantizar el acceso de Codespaces al paquete" y "Garantizar el acceso al flujo de trabajo para tu paquete".

Autenticación con un personal access token (classic)

1. Crea o usa un personal access token (classic) existente con los ámbitos adecuados para las tareas que quieras realizar. Si tu organización requiere SSO, debes hablitarlo para tu token nuevo.

   Nota: De manera predeterminada, cuando seleccionas el ámbito write:packages de tu personal access token (classic) en la interfaz de usuario, también se seleccionará el ámbito repo. El ámbito repo ofrece un acceso amplio e innecesario, el cual te recomendamos no utilices para los flujos de trabajo de GitHub Actions en particular. Para obtener más información, consulte Fortalecimiento de seguridad para GitHub Actions. Como solución alternativa, puedes seleccionar solo el ámbito write:packages de tu personal access token (classic) en la interfaz de usuario con esta URL: https://github.com/settings/tokens/new?scopes=write:packages.

   • Selecciona el ámbito read:packages para descargar imágenes de contenedor y leer sus metadatos.
   • Selecciona el ámbito write:packages para descargar y cargar imágenes de contenedor, así como para leer y escribir sus metadatos.
   • Selecciona el ámbito delete:packages para eliminar imágenes de contenedor.

   Para obtener más información, consulta "Creación de un personal access token para la línea de comandos".

2. Guarda tu personal access token (classic). Te recomendamos guardar tu token como una variable de entorno.

   $ export CR_PAT=YOUR_TOKEN

3. Utilizando el CLI de tu tipo de contenedor, inicia sesión en el servicio de Container registry en ghcr.io.

   $ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
   > Login Succeeded

Subir imágenes de contenedor

En este ejemplo se inserta la versión más reciente de IMAGE_NAME.

$ docker push ghcr.io/OWNER/IMAGE_NAME:latest

En este ejemplo se inserta la versión 2.5 de la imagen.

$ docker push ghcr.io/OWNER/IMAGE_NAME:2.5

Cuando publicas un paquete por primera vez, la visibilidad predeterminada es privada. Cuando se vincula un paquete a un repositorio, la visibilidad del paquete depende de la visibilidad del repositorio. Para cambiar la visibilidad o establecer permisos de acceso, consulte "Configurar la visibilidad y el control de accesos de un paquete". Puedes vincular un paquete publicado a un repositorio mediante la interfaz de usuario o la línea de comandos. Para obtener más información, consulte "Conexión de un repositorio a un paquete".

Extraer imágenes de contenedor

Extraer por resúmen

Para garantizar que siempre usa la misma imagen, puede especificar la versión exacta de la imagen de contenedor que quiere extraer de acuerdo con su valor de SHA de digest.

1. Para buscar el valor de SHA de hash, use docker inspect o docker pull y copie el valor de SHA después de Digest:.

   $ docker inspect ghcr.io/OWNER/IMAGE_NAME

2. Elimina la imagen localmente de acuerdo a tus necesidades.

   $ docker rmi  ghcr.io/OWNER/IMAGE_NAME:latest

3. Extraiga la imagen de contenedor con @YOUR_SHA_VALUE después del nombre de la imagen.

   $ docker pull ghcr.io/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs

Extraer por nombre

$ docker pull ghcr.io/OWNER/IMAGE_NAME

Extraer por nombre y versión

Ejemplo de CLI de Docker que muestra una imagen que se extrae por su nombre y por la etiqueta de la versión 1.14.1:

$ docker pull ghcr.io/OWNER/IMAGE_NAME:1.14.1
  > 5e35bd43cf78: Pull complete
  > 0c48c2209aab: Pull complete
  > fd45dd1aad5a: Pull complete
  > db6eb50c2d36: Pull complete
  > Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
  > Status: Downloaded newer image for ghcr.io/orgname/image-name/release:1.14.1
  > ghcr.io/orgname/image-name/release:1.14.1

Extraer por nombre y última versión

$ docker pull ghcr.io/OWNER/IMAGE_NAME:latest
  > latest: Pulling from user/image-name
  > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
  > Status: Downloaded newer image for ghcr.io/user/image-name:latest
  > ghcr.io/user/image-name:latest

Crear imagenes de contenedor

En este ejemplo se compila la imagen hello_docker:

$ docker build -t hello_docker .

Etiquetar las imágenes de contenedor

1. Encuentra la ID para la imagen de Docker que quieres etiquetar.

   $ docker images
   > REPOSITORY                                            TAG                 IMAGE ID            CREATED             SIZE
   > ghcr.io/my-org/hello_docker         latest              38f737a91f39        47 hours ago        91.7MB
   > ghcr.io/my-username/hello_docker    latest              38f737a91f39        47 hours ago        91.7MB
   > hello-world                                           latest              fce289e99eb9        16 months ago       1.84kB

2. Etiqueta tu imagen de Docker utilizando la ID ed imagen y el nombre que quieras poner a la misma, así como el destino en donde se hospedará ésta.

   $ docker tag 38f737a91f39 ghcr.io/OWNER/NEW_IMAGE_NAME:latest

Etiquetado de imágenes de contenedor

Puedes usar etiquetas claves de anotación predefinidas para agregar metadatos, incluida una descripción, una licencia y un repositorio de origen a la imagen de contenedor. Los valores de las claves admitidas aparecerán en la página del paquete de la imagen.

Para la mayoría de las imágenes, puedes usar etiquetas de Docker para agregar las claves de anotación a una imagen. Para obtener más información, consulta LABEL en la documentación oficial de Docker y Claves de anotación predefinidas en el repositorio de opencontainers/image-spec.

Para las imágenes de varios arcos, puedes agregar una descripción a la imagen agregando la clave de anotación adecuada al campo annotations en el manifiesto de la imagen. Para obtener más información, consulta "Adición de una descripción a imágenes de varios arcos".

Las etiquetas siguientes se admiten en Container registry.

Clave	Descripción
org.opencontainers.image.source	Dirección URL del repositorio asociado al paquete. Para obtener más información, consulte "Conexión de un repositorio a un paquete".
org.opencontainers.image.description	Una descripción de solo texto limitada a 512 caracteres. Esta descripción aparecerá en la página del paquete, debajo del nombre del paquete.
org.opencontainers.image.licenses	Un identificador de licencia SPDX, como "MIT", limitado a 256 caracteres. La licencia aparecerá en la página del paquete, en la barra lateral "Detalles". Para más información, consulta Lista de licencias de SPDX.

Para agregar una clave como etiqueta de Docker, se recomienda usar la instrucción LABEL en tu Dockerfile. Por ejemplo, si eres el usuario monalisa y eres el propietario de my-repo y la imagen se distribuye bajo los términos de la licencia MIT, agregarías las líneas siguientes a Dockerfile:

LABEL org.opencontainers.image.source=https://github.com/monalisa/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT

Como alternativa, puedes agregar etiquetas a una imagen en tiempo de compilación con el comando docker build.

$ docker build \
 --label "org.opencontainers.image.source=https://github.com/monalisa/my-repo" \
 --label "org.opencontainers.image.description=My container image" \
 --label "org.opencontainers.image.licenses=MIT"

Adición de una descripción a imágenes de varios arcos

Una imagen de varios arcos es una imagen que admite varias arquitecturas. Funciona haciendo referencia a una lista de imágenes, cada una de las cuales admite una arquitectura diferente, dentro de un único manifiesto.

La descripción que aparece en la página del paquete para una imagen de varios arcos se obtiene del campo annotations del manifiesto de la imagen. Al igual que las etiquetas de Docker, las anotaciones proporcionan una manera de asociar metadatos a una imagen y admiten claves de anotación predefinidas. Para más información, consulta Anotaciones en el repositorio opencontainers/image-spec.

Para proporcionar una descripción para una imagen de varios arcos, establece un valor para la clave org.opencontainers.image.description en el campo del manifiesto annotations, como se indica a continuación.

"annotations": {
  "org.opencontainers.image.description": "My multi-arch image"
}

Por ejemplo, el siguiente paso del flujo de trabajo GitHub Actions compila e inserta una imagen de varios arcos. El parámetro outputs establece la descripción de la imagen.

# Este flujo de trabajo usa acciones que no GitHub no certifica.
# Estas las proporcionan entidades terceras y las gobiernan
# condiciones de servicio, políticas de privacidad y documentación de soporte
# en línea.

- name: Build and push Docker image
  uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
  with:
    context: .
    file: ./Dockerfile
    platforms: ${{ matrix.platforms }}
    push: true
    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image