> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Iniciar una instancia
> Flavors, imágenes, discos, claves y cloud-init — y los dos campos cuya ausencia silenciosamente le cuesta una red.
Los ejemplos de cliente utilizan CLI v0.21.0 y Go SDK v0.24.0. Consulte [Configuración de CLI](/es/cli) y [Configuración de Go](/es/reference-resolution#released-go-sdk). Los fragmentos de Go asumen un `cfg` configurado, un `ctx` de `context.Background()`, e importaciones para `log`, `basaltic` (`github.com/basaltic-sh/sdk-go`) y `compute` (`github.com/basaltic-sh/sdk-go/compute`).
Vaya a **Compute → Instances** y elija **Create instance**. El formulario es una tarjeta por decisión: **Details**, **Flavor**, **Boot
volume**, **Data volumes**, **Networking**, **IAM role**, **User data**, con un resumen en ejecución junto a ellos.
**Networking** es la tarjeta para reducir la velocidad. Cada interfaz tiene su propio **VPC**, **Subnet**, **Security groups** y **Public floating IPs**; **Add network interface** agrega otra, y la primera en la lista es la NIC primaria.
Reemplaza las identidades de ejemplo con los recursos de tu cuenta. Esta solicitud mezcla un UUID de tipo de instancia, un nombre de imagen actual y un CRN de subred anidado.
```bash theme={null}
POST https://compute.sa-saopaulo-1.basaltic.sh/v1/instances
{
"name": "web-01",
"flavor": "550e8400-e29b-41d4-a716-446655440000",
"image": "debian-13",
"networks": [
{ "subnet": "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private",
"security_groups": ["c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"],
"floating_ip_assignment": "ipv4" }
]
}
```
```bash theme={null}
basaltic compute instance create --name web-01 \
--flavor 550e8400-e29b-41d4-a716-446655440000 --image debian-13 \
--networks '[{"subnet":"crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private","security_groups":["c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"],"floating_ip_assignment":"ipv4"}]'
```
```go theme={null}
_, err := compute.New(cfg).CreateInstance(ctx, &compute.InstanceCreateRequest{
Name: "web-01", Flavor: "550e8400-e29b-41d4-a716-446655440000",
Image: basaltic.String("debian-13"),
Networks: []*compute.NetworkConfig{{
Subnet: "crn:network:sa-saopaulo-1:my-account:vpc/production/subnet/private",
SecurityGroups: []string{"c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"},
FloatingIPAssignment: basaltic.String("ipv4"),
}},
})
if err != nil {
log.Fatal(err)
}
```
La llamada responde **`202`** con la instancia en `pending`. La construcción del disco de arranque, las interfaces y la semilla ocurre después de la respuesta, por lo que consulte `GET /v1/instances/{instance_id}` y observe `current_state`.
**Los grupos de seguridad son por interfaz.** Pertenecen a `networks[].security_groups`, no a un campo de nivel superior. Una NIC aprovisionada con una lista vacía no obtiene ningún filtrado por interfaz, lo que no es lo mismo que una instancia cerrada.
**Una instancia sin entrada de `networks` arranca sin conexión en red.** Nada falla y nada le advierte: el invitado no tiene interfaz, por lo que nada lo alcanza y no alcanza nada. Envíe al menos una entrada; el índice 0 se convierte en la NIC principal, la que lleva la ruta predeterminada del invitado y su ruta al servicio de metadatos.
## Tamaño: tipos de instancia
Un tipo de instancia es CPU y memoria, y nada más. Lleva **sin tamaño de disco** — el disco de arranque es un volumen de tamaño al inicio — así que `GET /v1/flavors` es un catálogo de formas de computación, no de tipos de máquina.
`shared` sobresuscribe CPU para mayor densidad. `dedicated` conecta cada vCPU 1:1 a un núcleo físico. Ambas clases se ejecutan en los mismos hosts; la clase decide cómo la instancia se basa en los subprocesos de un host.
Solo las versiones `general` pueden ejecutar instancias y grupos de instancias. Los otros dos están reservados para los productos gestionados, cuyos nodos son operados y valorados por la plataforma, y se rechazan aquí. Pasa `?family=general` al listar.
El piso garantizado y el techo. La instancia tiene derecho a `vcpus × cpu_baseline_pct / 100` núcleos, sin importar cuán ocupados estén sus vecinos, y no puede exceder el límite de ráfaga incluso en un host inactivo. Ausente significa que la variante no garantiza ningún límite mínimo ni impone ningún límite máximo más allá del recuento de vCPU.
El límite de red de la instancia, en megabits/s, en todas sus interfaces. Ausente significa sin límite. Un [resize](/es/compute/lifecycle#resize) lo mueve con el tipo de instancia.
El catálogo es pequeño y se muestra en una sola página — `GET /v1/flavors` no está paginado.
## Elegir una imagen
`image` toma cuatro formas, y la diferencia importa para la reproducibilidad:
`"image": "debian-13"` sigue a la etiqueta. Obtienes la compilación que esté vigente en el momento en que se crea la instancia, por lo que dos lanzamientos con un mes de diferencia pueden arrancar bits diferentes.
`"image": "debian-13:20260807"` fija una compilación. Así es como se puede optar por no tener la etiqueta moviéndose debajo de usted.
`crn:compute:sa-saopaulo-1:platform:image/debian-13/architecture/amd64/version/20260807` fija el propietario, nombre, arquitectura y versión.
Un UUID también identifica una compilación, y es lo que la API te devuelve.
Los nombres se resuelven en sus propias imágenes más el catálogo de plataforma pública, y se utiliza la arquitectura de solicitud (por defecto `amd64`). Una imagen completa de CRN pins su arquitectura. Vea [Images](/es/compute/images) para saber cómo se mueve una etiqueta y qué muestra o no el listado.
## Discos
`volumes` es una lista, y el disco de arranque es la entrada que dice así:
```json theme={null}
"volumes": [
{ "boot": true, "size_gb": 40, "volume_type": "nvme" },
{ "size_gb": 100, "mount_path": "/data", "fstype": "ext4" }
]
```
Marca el disco de arranque, ya sea clonado desde `image` o seleccionado con `volume`. **Puede establecerlo como máximo una entrada**. Una entrada de arranque no toma `mount_path` o `fstype`; su sistema de archivos viene de la imagen o del disco existente.
Cuando se usa `image`, omita la entrada de arranque y obtendrá su `min_disk_gb` en el nivel predeterminado de la región.
Se requiere para discos de datos nuevos; se omite para discos existentes. En una nueva entrada de arranque, esto no puede ir por debajo de la imagen `min_disk_gb`. Cualquier cosa menor es un `400` antes de que exista la fila de instancia, no una compilación fallida.
Con una ruta de montaje establecida, el agente invitado formatea el disco — solo si está en blanco — y lo monta allí, usando `fstype`: `ext4` por defecto, o `xfs`.
Los nuevos volúmenes de tiempo de inicio tienen el valor predeterminado true. Los discos existentes tienen el valor predeterminado de false y no pueden establecerlo en true durante el inicio. Los discos conectados después del lanzamiento también se establecen por defecto en false.
**Los nuevos volúmenes de arranque y de datos se eliminan con la instancia por defecto.** Establezca `delete_on_termination: false` en sus entradas de lanzamiento para conservarlos, o cambie el adjunto después del lanzamiento — vea [what survives a delete](/es/compute/lifecycle#what-survives-a-delete). Se conservan los discos existentes seleccionados durante el inicio.
### Rendimiento y discos existentes
Los nuevos discos de arranque y datos pueden aprovisionar IOPS y rendimiento independientemente de la capacidad. La asignación incluida es de 3.000 IOPS / 125 MiB/s. La SSD admite hasta 8.000 IOPS/250 MiB/s, y NVMe hasta 12.000 IOPS/500 MiB/s, sujeto a las cuotas de cuenta y la capacidad regional. El resumen muestra el rendimiento adicional independientemente de la capacidad de almacenamiento; 3.500 IOPS / 250 MiB/s agrega R\$35/mes. Consulte [volume pricing](/es/storage/volumes) para ver las tarifas y la prorrateación.
También puede iniciar desde un disco de arranque existente y adjuntar discos de datos existentes. Deben estar disponibles en la misma cuenta y región, sin un cambio de rendimiento pendiente. Cada disco puede aparecer solo una vez. Los discos existentes conservan sus datos, rendimiento, programaciones de instantáneas y cargas actuales. Se conservan si el lanzamiento falla o se elimina la instancia, y sus cargos en curso se excluyen de la estimación de nuevos recursos. Esto requiere `compute:AttachVolume` además de `compute:CreateInstance`.
En **Create instance**, use **Boot volume** para elegir **New volume from
image** o **Existing volume**. Un nuevo disco de arranque ofrece **Provisioned IOPS** y **Provisioned throughput (MiB/s)**. Cada entrada bajo **Data volumes** ofrece la misma opción. Los discos existentes muestran su rendimiento actual. El resumen enumera **Additional performance** por separado.
Para un disco nuevo, añada performance a su entrada `volumes`:
```json theme={null}
{ "boot": true, "size_gb": 40, "volume_type": "ssd",
"performance": { "iops": 3500, "throughput_mib_s": 250 } }
```
Para discos existentes, omita el nivel superior `image` y use referencias `volume`:
```json theme={null}
{
"name": "web-02",
"flavor": "s1.medium",
"networks": [{ "subnet": "private" }],
"volumes": [
{ "boot": true, "volume": "saved-root" },
{ "volume": "saved-data" }
]
}
```
`volume` acepta un UUID, nombre o CRN. Las entradas existentes tampoco pueden establecer capacidad, tipo, rendimiento, programación de instantáneas o `delete_on_termination: true`.
Con CLI v0.21.0 o posterior, guarde la solicitud completa como `instance.json` y ejecute:
```bash theme={null}
basaltic compute instance create --from-file instance.json
```
El indicador JSON `--volumes` acepta las mismas entradas.
Con SDK v0.24.0 o posterior:
```go theme={null}
_, err := compute.New(cfg).CreateInstance(ctx, &compute.InstanceCreateRequest{
Name: "web-02", Flavor: "s1.medium",
Networks: []*compute.NetworkConfig{{Subnet: "private"}},
Volumes: []*compute.InstanceLaunchVolume{
{Boot: basaltic.Bool(true), Volume: basaltic.String("saved-root")},
{Volume: basaltic.String("saved-data")},
},
})
```
Los discos nuevos usan `Performance` con `compute.VolumePerformanceRequest`. `SizeGB` es opcional en v0.24.0; use `basaltic.Int(40)` para un nuevo disco de 40 GB.
Estas opciones se aplican a instancias individuales. Las plantillas de grupo de instancias no pueden reutilizar discos existentes ni proporcionar rendimiento adicional al iniciar.
### Programas de instantáneas en el lanzamiento
Cada nuevo volumen de arranque o de datos puede tener hasta 16 [programas de instantáneas](/es/storage/snapshots#snapshot-policies) independientes. Esto requiere `storage:CreateSnapshotPolicy` además de los permisos para iniciar una instancia. Los nombres de programación deben ser únicos en toda la cuenta, incluidos los demás volúmenes de la misma solicitud.
En **Boot volume** o en una nueva entrada **Data volumes**, utilice **Add snapshot schedule**. Establezca **Schedule name**, **Every (minutes)**, **Keep snapshots** y, opcionalmente, **Maximum age (days)**. Desactive **Enabled** para crear una programación en pausa. El resumen de lanzamiento incluye los horarios solicitados.
Incluya `snapshot_schedules` dentro de cada entrada en la matriz `volumes` de la solicitud de creación. Por ejemplo:
```json theme={null}
{
"boot": true,
"size_gb": 40,
"snapshot_schedules": [
{"name": "web-boot-daily", "interval_minutes": 1440, "retention_count": 7},
{"name": "web-boot-weekly", "interval_minutes": 10080, "retention_count": 4}
]
}
```
Añada los horarios anidados a `volumes` en su archivo de solicitud de instancia completa:
```bash theme={null}
basaltic compute instance create --from-file instance.json
```
El indicador JSON `--volumes` acepta el mismo array.
Establecer `Volumes` en `compute.InstanceCreateRequest`:
```go theme={null}
Volumes: []*compute.InstanceLaunchVolume{{
Boot: basaltic.Bool(true),
SizeGB: basaltic.Int(40),
SnapshotSchedules: []*compute.SnapshotScheduleSettings{{
Name: "web-boot-daily",
IntervalMinutes: 1440,
RetentionCount: 7,
}},
}},
```
El conjunto de programación completo se crea durante el aprovisionamiento. Al volver a intentar el aprovisionamiento no se crean programaciones duplicadas. Si el lanzamiento falla y se revierte, se eliminan sus programaciones; las instantáneas ya enviadas se conservan. Los volúmenes adjuntos posteriormente mantienen sus programaciones existentes. Las plantillas de grupo de instancias no admiten `snapshot_schedules`.
## Acceso SSH y cloud-init
Usa [SSH access with IAM](/es/compute/ssh) para inicios de sesión humanos y de automatización. Agregue una clave pública a la identidad y conceda acceso a la instancia. La plataforma instala IAM SSH durante el primer arranque en imágenes compatibles; la creación de instancias no tiene un campo de adjunto de claves y no crea un usuario de inicio de sesión compartido.
`user_data` es base64-codificado cloud-init. La configuración base deshabilita la contraseña y el inicio de sesión de root. Las claves de nivel superior del cliente reemplazan los valores de base, mientras que la plataforma agrega su ruta de metadatos y la instalación del agente invitado después. Su propio bloque `users:` puede crear usuarios de aplicaciones locales sin cambiar la identidad y los permisos de los usuarios de IAM.
Sus datos de usuario deben ser decodificados a un documento cuya primera línea sea `#cloud-config`. No se fusiona un script de shell o un paquete MIME de varias partes. Ponga los comandos de shell en `runcmd` de cloud-init en su lugar.
Un documento `#cloud-config` que contiene YAML no válido falla al aprovisionar.
## Darle una identidad a la instancia
Al inicio, `iam_role` acepta un nombre de rol, UUID o CRN y adjunta ese rol IAM. El software dentro del invitado luego obtiene credenciales de corta duración del servicio de metadatos en `169.254.169.254` — no se escribe ninguna clave de acceso en la instancia, y nada tiene que ser rotado.
Dos condiciones, y ambas son fáciles de pasar por alto. La **directiva de confianza** del rol debe aceptar `crn:compute:*:*:instance/*` (o el CRN de la instancia específica), y el principal que realiza la llamada de lanzamiento necesita **`iam:PassRole`** en el rol, por separado de `compute:CreateInstance`. Sin la política de confianza, la instancia se inicia y las credenciales nunca se crean; sin `iam:PassRole`, el inicio en sí se deniega. [Roles e identidad de instancia](/es/iam/roles) recorre ambos.
Las respuestas de instancia devuelven `iam_role` como un resumen opcional en lugar de una referencia de cadena o `iam_role_id`:
```json theme={null}
{
"iam_role": {
"id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1",
"crn": "crn:iam::my-account:role/deploy",
"name": "deploy"
}
}
```
El resumen es visible con acceso de lectura de instancia; no requiere `iam:GetRole`. Contiene solo `id`, `crn` y `name`, excluyendo campos de rol sensibles como las políticas. El campo se omite cuando no se adjunta ningún rol, el rol se ha eliminado o pertenece a otra cuenta. La apertura de los detalles de IAM del rol todavía requiere `iam:GetRole`.
### Cambiar el rol de una instancia existente
Puede adjuntar, reemplazar o quitar un rol de carga de trabajo mientras una instancia se está ejecutando o deteniendo, sin ninguna operación en curso. Estos cambios no requieren reiniciar. Hay un rol adjunto por instancia. La sustitución es atómica; si falla la validación, el rol anterior permanece adjunto.
Abra la instancia y seleccione **Settings**. En **IAM role**, seleccione un rol y haga clic en **Save IAM role**. Para desvincularlo, haga clic en **Remove role** y, a continuación, en **Remove IAM role**.
```bash theme={null}
curl -X PATCH "https://compute.sa-saopaulo-1.basaltic.sh/v1/instances/$INSTANCE_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Account-Id: $ACCOUNT" \
-H "Content-Type: application/json" \
-d '{"iam_role":"workload-role"}'
```
Enviar `{"iam_role":""}` para desacoplar. Omita `iam_role` para mantener la asociación actual. No se aceptan objetos de rol `null` y incrustados.
```bash theme={null}
basaltic compute instance update "$INSTANCE_ID" --iam-role workload-role
basaltic compute instance update "$INSTANCE_ID" --iam-role=""
```
El primer comando adjunta o reemplaza el rol; el segundo lo desata. Requiere CLI v0.17.0 o posterior.
```go theme={null}
role := "workload-role"
_, err := compute.New(cfg).UpdateInstance(ctx, instanceID, &compute.InstanceUpdateRequest{
IAMRole: &role,
})
```
Establezca `role` a `""` para separar. Deja `IAMRole` nil para preservarlo. Requiere SDK v0.20.0 o posterior.
Cada edición requiere `compute:UpdateInstance` en la instancia. Adjuntar y reemplazar también requieren `iam:PassRole` en el rol seleccionado, que debe pertenecer a la misma cuenta y confiar en esta instancia. La lista de roles de la consola requiere `iam:ListRoles`. El desmontaje no requiere pasar un rol.
Las nuevas solicitudes de metadatos observan la asociación guardada inmediatamente. Una solicitud ya en curso puede completarse con la asociación anterior. Al desconectar se detiene la recuperación de credenciales posterior; al volver a conectar el mismo rol se obtiene un nuevo conjunto de credenciales. Las solicitudes que se superponen a un cambio de rol pueden necesitar volver a intentar la detección de rol. Las ediciones concurrentes se aplican en orden de confirmación, y repetir la asociación actual la deja sin cambios.
Las credenciales emitidas anteriormente no se revocan cuando se reemplaza o se separa un rol. Permanecen válidos hasta su vencimiento existente, hasta por una hora. Las credenciales de almacenamiento en caché de aplicaciones pueden seguir utilizando el rol antiguo hasta que se actualice.
Las instancias administradas por el servicio no se pueden editar de esta manera. Para un miembro de un grupo de instancias, cambia la plantilla [launch template](/es/compute/instance-pools) del grupo; la plantilla establece el rol utilizado por las instancias de reemplazo. Una edición de instancia nunca modifica su plantilla de grupo.
## Nombres, etiquetas y metadatos
1-128 caracteres, seguros para DNS: letras, dígitos, punto, guion, subrayado, alfanuméricos iniciales y finales. Un nombre que choca con otra instancia en la cuenta es un `409`.
`PATCH /v1/instances/{instance_id}` edita `description`, `metadata`, `tags` y `iam_role`. Se fija un nombre para la vida de la instancia.
En la consola, estas son las tarjetas **Details**, **Tags**, **Metadatos** y **IAM role** en la pestaña **Settings** de la instancia. Ninguno tiene un campo de nombre.
Leído por las condiciones de la política de IAM como `basalt:RequestTag/` en la creación y `basalt:ResourceTag/` después, y utilizado para la atribución de costos. Consulte [policies](/es/iam/policies).
El mapa que `PATCH` se convierte en el conjunto completo de sus claves.
Las claves de metadatos bajo el espacio de nombres `basalt:` son estados de plano de control, es decir, cómo una instancia demuestra a qué grupo o recurso administrado pertenece. No se pueden establecer, y no se pueden eliminar: se conservan a través de un `PATCH`, ya sea que se los devuelva o no, y proponer un valor *diferente* para uno es un `400` en lugar de una caída silenciosa. Leer-modificar-escribir contra todo el mapa de metadatos es por lo tanto seguro.
## Lectura de direcciones de instancia
La tabla de instancias muestra **IPv4 privado**, **IPv4 público** y **IPv6** de la NIC principal. Los detalles de instancia muestran esos mismos valores individualmente. La pestaña **Networking** muestra cada NIC con sus direcciones primarias. Se muestra una IP flotante IPv6 adjunta en lugar de la dirección IPv6 directamente adjunta de la NIC.
La descripción general muestra una dirección por instancia, con preferencia por IPv4 público, luego IPv6 público y luego IPv4 privado.
## Referencias de recursos
Consulte [Referencias de recursos](/es/reference-resolution) para obtener información sobre clasificación, versiones de imágenes y obtención de una instancia por nombre o CRN.
`flavor`, `iam_role`, y por-NIC `security_groups` aceptan un UUID, un CRN, o un nombre exacto. Los tipos de instancia son regionales; los grupos de seguridad pertenecen a su cuenta y los roles de IAM pertenecen a su cuenta. `subnet` acepta un UUID o un CRN completo de VPC/subred. Un nombre de subred desnudo no se puede resolver sin su VPC principal. La adjunción de interfaz también requiere un UUID o un CRN completo de VPC/subred/interfaz.
Cada lista de computación acepta filtros exactos `name` y `crn`. Se cruzan con otros filtros y paginación. Un CRN extraño o no coincidente no coincide con ninguna fila; un CRN malformado o vacío devuelve 400. Los nombres vacíos no amplían la lista. Las listas de instancias también aceptan referencias `flavor` e `image`. Los nombres de la lista de NIC coinciden con los nombres de interfaz dentro de las vinculaciones de instancia; los nombres duplicados pueden devolver varias interfaces. Las IP flotantes no tienen identidad de nombre.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.