Saltar a contenido

Configurar AWS

Antes del primer sandbox, tu cuenta necesita tres cosas: permisos (una pila de IAM), un bucket para los artefactos de la imagen y la imagen rayito-base publicada. Se hace una vez por cuenta y región, en unos 15 minutos (casi todo es esperar a que AWS construya la imagen).

Todo queda en tu cuenta

Rayito no tiene servidor ni API key. Lo que creas aquí son recursos tuyos: una pila de CloudFormation con roles y una política, un bucket de S3 y una imagen de Lambda MicroVMs. Borrar la pila y la imagen lo deja todo como estaba.

1. Credenciales y región

Elige una de las diez regiones con Lambda MicroVMs (us-east-1, us-east-2, us-west-2, eu-west-1, eu-central-1, eu-north-1, ap-northeast-1, ap-south-1, ap-southeast-1, ap-southeast-2) y exporta tu perfil:

export AWS_PROFILE=<tu-perfil> AWS_REGION=us-east-1
aws sts get-caller-identity          # comprueba que las credenciales funcionan

Basta con AWS_REGION: los dos SDK y la CLI la leen. Si falta, usan AWS_DEFAULT_REGION y después la región del perfil; region= (Python) o region (TypeScript) gana a todas.

Para estos pasos de preparación hacen falta permisos de administración (crear roles de IAM y un bucket). Para usar el SDK después basta la política mínima que crea el paso 3.

2. Un bucket para los artefactos

El zip de la imagen se sube a un bucket tuyo, bajo el prefijo rayito/. Créalo en la misma región que los sandboxes:

aws s3 mb s3://amzn-s3-demo-bucket --region us-east-1
export RAYITO_BUCKET=amzn-s3-demo-bucket

Sustituye amzn-s3-demo-bucket por un nombre único tuyo. RAYITO_BUCKET evita repetir --bucket en la CLI.

3. La pila de IAM

infra/iam.yaml crea el rol con el que AWS construye la imagen, el rol de ejecución opcional del sandbox y tres políticas mínimas para quien usa el SDK: SandboxLauncherPolicy (rayito-m0-launcher-<región>, sólo lanzar y manejar sandboxes), ImagePublisherPolicy (rayito-m0-publisher-<región>, sólo publicar imágenes) y CallerPolicy (rayito-m0-caller-<región>, las dos juntas). Descarga la plantilla del repositorio y despliégala:

curl -fsSLO https://raw.githubusercontent.com/alejandro-cedeno-10/rayito/main/infra/iam.yaml
aws cloudformation deploy --stack-name rayito-m0-iam \
  --template-file iam.yaml --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides ArtifactBucket=amzn-s3-demo-bucket LogGroupPrefix=/rayito

Asigna a cada identidad sólo lo que hace:

  • Tu usuario de desarrollo (publica la imagen y prueba sandboxes): la del output CallerPolicyArn.
  • El rol de tu servicio o de tu agente (sólo crea sandboxes): la del output SandboxLauncherPolicyArn. Nunca CallerPolicy: un servicio comprometido podría publicar una versión con puerta trasera de la imagen que usarán todos tus sandboxes.
  • Tu CI o pipeline de release (publica imágenes): la del output ImagePublisherPolicyArn (y la del lanzador si además corre pruebas).
policy_arn() {
  aws cloudformation describe-stacks --stack-name rayito-m0-iam \
    --query "Stacks[0].Outputs[?OutputKey=='$1'].OutputValue" --output text
}

# tu usuario de IAM:
aws iam attach-user-policy --user-name <tu-usuario> --policy-arn "$(policy_arn CallerPolicyArn)"
# el rol de tu servicio:
aws iam attach-role-policy --role-name <tu-rol> --policy-arn "$(policy_arn SandboxLauncherPolicyArn)"

Con IAM Identity Center (SSO) no se asigna a un usuario: añade la política al permission set de tu acceso desde la consola de Identity Center.

Parámetros opcionales de la plantilla: TransferBucket y TransferPrefix para ficheros grandes y URLs de S3, y PersistenceBucket y PersistencePrefix para la persistencia. Qué permiso necesita cada función: IAM.

4. Publicar la imagen rayito-base

Cada sandbox arranca desde una imagen de Lambda MicroVMs publicada en tu cuenta. La forma más corta es publicar el rayito-image.zip firmado de la última release, sin compilar nada:

RAYD_VERSION=0.10.0     # la misma versión que tu SDK: python -c "import rayito; print(rayito.__version__)"
BASE=https://github.com/alejandro-cedeno-10/rayito/releases/download/rayd-v${RAYD_VERSION}
curl -fsSLO "$BASE/rayito-image.zip"
curl -fsSLO "$BASE/rayito-image.zip.sigstore.json"    # su firma de Sigstore
curl -fsSLO "$BASE/SHA256SUMS"

cosign verify-blob --bundle rayito-image.zip.sigstore.json \
  --certificate-identity "https://github.com/alejandro-cedeno-10/rayito/.github/workflows/release.yml@refs/tags/rayd-v${RAYD_VERSION}" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  rayito-image.zip
sha256sum -c --ignore-missing SHA256SUMS   # en macOS: shasum -a 256 -c --ignore-missing SHA256SUMS

rayito image publish --artifact rayito-image.zip --base-image-version 1

Comprueba la firma antes de publicar: rayito image publish no verifica nada, y el zip de una release se podría reemplazar con un token del repositorio. Si cosign verify-blob no dice Verified OK, no publiques ese fichero. Necesitas cosign ≥ 2.x; qué prueba la firma y cómo verificar el binario rayd suelto, en Verificar una release.

Usa el rayd de la misma versión que el SDK instalado: si la imagen es más vieja, la comprobación compatibility de rayito doctor lo marca. Todas las versiones están en las releases rayd-v*.

Con la CLI de GitHub (gh, autenticada con gh auth login) la descarga es una línea: gh release download "rayd-v${RAYD_VERSION}" --repo alejandro-cedeno-10/rayito --pattern 'rayito-image.zip*' --pattern SHA256SUMS.

git clone https://github.com/alejandro-cedeno-10/rayito.git && cd rayito
make image-publish BUCKET=amzn-s3-demo-bucket

Compila rayd para aarch64-unknown-linux-musl: necesitas Linux o WSL2 (en macOS, una VM Linux) con Rust y cargo-zigbuild, como explica CONTRIBUTING.md.

rayito image publish sube el zip, pide a AWS que construya la imagen y espera a que la versión sea lanzable (unos 10 minutos). La última línea es RAYITO_TEMPLATE=<arn>. Cada versión publicada cuesta ≈ $0,04 por semana de almacenamiento (Precios).

Las otras variantes: -caps, -poly y la imagen del agente

  • rayito-base-caps es el mismo zip publicado con additionalOsCapabilities ALL; hace falta para la política de red saliente y es la base de la imagen del agente:

    rayito image publish --artifact rayito-image.zip --base-image-version 1 \
  --image-name rayito-base-caps --os-capabilities ALL

  • rayito-base-poly añade los kernels bash, JavaScript y TypeScript (Lenguajes y kernels). Se construye desde el código fuente: make image-publish-poly BUCKET=amzn-s3-demo-bucket.

  • rayito-agent, para el agente en el sandbox, se construye en tu cuenta sobre rayito-base-caps (publícala antes) con OpenCode, ripgrep y deepagents (Templates de agente):

    rayito agent template build --bucket amzn-s3-demo-bucket

Qué imagen necesita cada función: Imágenes.

5. Apunta el SDK a la imagen

export RAYITO_TEMPLATE=rayito-base       # nombre o ARN de la imagen

Con RAYITO_TEMPLATE no hace falta pasar template= en cada create(). Un nombre se resuelve al ARN de tu cuenta y región.

6. Diagnóstico

rayito doctor hace diez comprobaciones de la cuenta (credenciales, imágenes gestionadas, cuotas, IAM, bucket, imagen, sandboxes vivos, token, agente y compatibilidad SDK ↔ rayd) y dice qué falta. Sin --launch, las tres últimas sólo corren si ya hay un sandbox RUNNING de esa imagen; con --launch crea uno efímero de 300 s y lo mata al terminar:

rayito doctor --template rayito-base --launch     # --launch: un sandbox efímero (≈ $0,002)

Una salida típica en una cuenta recién preparada (con el SDK 0.9.0):

OK   credentials     cuenta 123456789012, us-east-1, assumed-role
OK   managed-images  al2023-1 disponible, versión más nueva 1.0
OK   quotas          18 cuotas de MicroVM, ninguna por debajo del default
WARN iam-simulation  sin permiso explícito para lambda:PassNetworkConnector; simulación orientativa: las comprobaciones 2, 5, 6 y 8 son las que cuentan
       policy_source_arn: arn:aws:iam::123456789012:role/<tu-rol>
       explicit_deny: []
       denied_by_organizations: []
       implicit_deny: ['lambda:PassNetworkConnector']
OK   bucket          s3://amzn-s3-demo-bucket accesible en us-east-1
OK   image-gate      rayito-base 1.0 lanzable
OK   sandboxes       ningún MicroVM RUNNING de rayito-base
OK   token           token acuñado por create() para microvm-00000000-0000-0000-0000-000000000001
OK   agent           rayd 0.10.0 agent_ready, kernel_ready=True, imds_blocked=False
OK   compatibility   SDK 0.10.0, agent_version 0.10.0; imagen 1.0 (contador de builds, informativo)

SDK   rayd mínimo  Estado  Nota
0.1   0.1.0                M6: imds_blocked, hook_anomalies y metadata exigen el rayd del tag rayd-v0.1.0
0.2   0.2.0                M7: Checkpoint/Restore (persist=) y language= exigen el rayd del tag rayd-v0.2.0
0.3   0.3.0                M9: max_lifetime/on_timeout, set_timeout, get_metrics_history, network= y los kernels Deno
                           exigen el rayd del tag rayd-v0.3.0
0.4   0.4.0                0.4: UnimplementedError único, SetTimeout validado en el dominio y mensajes del agente en
                           español exigen el rayd del tag rayd-v0.4.0
0.5   0.5.0                0.5: /suspend con sync acotado por sistema de ficheros y las funciones opcionales (secretos,
                           índice, OTel) se validan con el rayd del tag rayd-v0.5.0
0.6   0.6.0                0.6: ConfigureSandbox y las funciones 0.6 (montajes S3, eventos, OTLP, pasarela de secretos,
                           start/ready de templates) exigen el rayd del tag rayd-v0.6.0
0.7   0.7.0                0.7: los volúmenes EFS (create(volumes=)) y el endurecimiento del agente (hooks aislados,
                           persistencia ligada al /run) exigen el rayd del tag rayd-v0.7.0
0.8   0.8.0                0.8: el agente de IA (sbx.agent, AgentTemplate y el warmup de los pools) se valida con el
                           rayd del tag rayd-v0.8.0
0.9   0.9.0                0.9: connect() recupera sbx.gateways desde ConfigureStatus y el arranque rápido del agente
                           sin la opción D se validan con el rayd del tag rayd-v0.9.0
0.10  0.10.0       OK      0.10: el timeout y abort() del agente paran todo el árbol de procesos (kill_tree) y los
                           proveedores del agente se validan con el rayd del tag rayd-v0.10.0

rayito doctor: 9 OK, 1 WARN, 0 FAIL, 0 SKIP
sandbox de --launch terminado: microvm-00000000-0000-0000-0000-000000000001

Cada línea es OK, WARN, FAIL o SKIP; un WARN o FAIL lista debajo sus detalles. Después va la tabla de compatibilidad SDK ↔ rayd, con el estado en la fila de tu SDK, y el recuento. La orden sale con código 1 sólo si hay algún FAIL. --json da lo mismo como un documento JSON.

El WARN de iam-simulation sobre lambda:PassNetworkConnector es esperado: el simulador de IAM lo marca incluso con permisos de administrador y no bloquea nada (las comprobaciones que cuentan son las de imágenes gestionadas, bucket, imagen y token). Qué hacer con cada FAIL: Solución de problemas.

Siguiente paso

Primer sandbox: comandos, ficheros y código en Python y TypeScript.

Fuentes y mediciones