Iniciar una instancia

Los ejemplos de cliente utilizan CLI v0.21.0 y Go SDK v0.24.0. Consulte Configuración de CLI y Configuración de Go. 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).

Console
API
CLI
Go

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.

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" }
  ]
}

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"}]'

_, 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 | dedicated

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.

general | loadbalancer | database

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.

percent of one vCPU

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.

aggregate throughput

El límite de red de la instancia, en megabits/s, en todas sus interfaces. Ausente significa sin límite. Un 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:

Un nombre desnudo
Nombre: versión
A CRN
Un id de imagen

"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.

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 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í:

"volumes": [
  { "boot": true, "size_gb": 40, "volume_type": "nvme" },
  { "size_gb": 100, "mount_path": "/data", "fstype": "ext4" }
]

boolean

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.

integer, 1–16384

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.

string

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.

boolean

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. 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 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.

Console
API
CLI
Go

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:

{ "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:

{
  "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:

basaltic compute instance create --from-file instance.json

El indicador JSON --volumes acepta las mismas entradas.

Con SDK v0.24.0 o posterior:

_, 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 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.

Console
API
CLI
Go

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:

{
  "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:

basaltic compute instance create --from-file instance.json

El indicador JSON --volumes acepta el mismo array.

Establecer Volumes en compute.InstanceCreateRequest:

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 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 recorre ambos.

Las respuestas de instancia devuelven iam_role como un resumen opcional en lugar de una referencia de cadena o iam_role_id:

{
  "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.

Console
API
CLI
Go

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.

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.

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.

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 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

unique per account

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.

not supported

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.

IAM and cost

Leído por las condiciones de la política de IAM como basalt:RequestTag/<key> en la creación y basalt:ResourceTag/<key> después, y utilizado para la atribución de costos. Consulte policies.

replaced, not merged

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 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.

Primeros pasos

Productos

Plataforma

Ayuda

Iniciar una instancia

Tamaño: tipos de instancia

Elegir una imagen

Discos

Rendimiento y discos existentes

Programas de instantáneas en el lanzamiento

Acceso SSH y cloud-init

Darle una identidad a la instancia

Cambiar el rol de una instancia existente

Nombres, etiquetas y metadatos

Lectura de direcciones de instancia

Referencias de recursos

​Tamaño: tipos de instancia

​Elegir una imagen

​Discos

​Rendimiento y discos existentes

​Programas de instantáneas en el lanzamiento

​Acceso SSH y cloud-init

​Darle una identidad a la instancia

​Cambiar el rol de una instancia existente

​Nombres, etiquetas y metadatos

​Lectura de direcciones de instancia

​Referencias de recursos

Tamaño: tipos de instancia

Elegir una imagen

Discos

Rendimiento y discos existentes

Programas de instantáneas en el lanzamiento

Acceso SSH y cloud-init

Darle una identidad a la instancia

Cambiar el rol de una instancia existente

Nombres, etiquetas y metadatos

Lectura de direcciones de instancia

Referencias de recursos