> ## 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.
# Adjuntar una IP flotante a una interfaz
> Enlaza la IP flotante a la interfaz dada y enruta la IP pública a la instancia detrás de ella. La reasociación idempotente a la misma interfaz es un no-op.
Al conectar una segunda NIC distinta, se devuelve 409 con un mensaje que lo dirige a los grupos de instancias. Los miembros múltiples requieren una dirección de propiedad del grupo; use `POST /v1/instance-pools/{pool_id}/floating-ips` para administrar esos enlaces. Una dirección que ya pertenece a un grupo o está vinculada a un balanceador de carga se rechaza aquí (409). Una NIC conectada manualmente sin una comprobación de estado tiene estado `unknown` y permanece anunciada.
La subred de la interfaz ya debe enrutar `0.0.0.0/0` a una puerta de enlace de Internet, o la dirección se devolvería como inalcanzable (400).
Requiere la acción de IAM **`network:AttachFloatingIP`**. Consulte [permisos de redes](/es/networking/permissions) para obtener la lista completa, lo que cubre cada una y un ejemplo de directiva.
## OpenAPI
````yaml /es/api-reference/specs/network.yaml post /v1/floating-ips/{floating_ip_id}/attach
openapi: 3.0.3
info:
title: Basaltic Network API
version: 1.0.0
description: >
La superficie de VPC: redes y subredes, interfaces, tablas de rutas, grupos
de seguridad, Internet, NAT y puertas de enlace solo de salida, e IP
flotantes.
Las entradas de relación usan un campo de referencia: UUID, CRN o un nombre
exacto cuando la solicitud proporciona su ámbito principal requerido. Las
subredes y las tablas de rutas tienen ámbito de VPC; las interfaces tienen
ámbito de subred./subnet/, vpc//route-table/, y
vpc//subnet//interfaz/Los nombres son inmutables.
Los campos de petición desconocidos y los parámetros de lista son
rechazados. Las referencias vacías suministradas son inválidas y las
búsquedas fallidas nunca caen de nuevo a otro tipo de referencia.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://network.{region}.basaltic.sh
description: Punto final de API regional
variables:
region:
default: sa-saopaulo-1
description: Código de región
security:
- BearerAuth: []
paths:
/v1/floating-ips/{floating_ip_id}/attach:
post:
tags:
- Networking
summary: Adjuntar una IP flotante a una interfaz
description: >
Enlaza la IP flotante a la interfaz dada y enruta la IP pública a la
instancia detrás de ella. La reasociación idempotente a la misma
interfaz es un no-op.
Al conectar una segunda NIC distinta, se devuelve 409 con un mensaje que
lo dirige a los grupos de instancias. Los miembros múltiples requieren
una dirección de propiedad del grupo; use `POST
/v1/instance-pools/{pool_id}/floating-ips` para administrar esos
enlaces. Una dirección que ya pertenece a un grupo o está vinculada a un
balanceador de carga se rechaza aquí (409). Una NIC conectada
manualmente sin una comprobación de estado tiene estado `unknown` y
permanece anunciada.
La subred de la interfaz ya debe enrutar `0.0.0.0/0` a una puerta de
enlace de Internet, o la dirección se devolvería como inalcanzable
(400).
operationId: attachFloatingIp
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
- $ref: '#/components/parameters/FloatingIpId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- interface
- address_id
properties:
interface:
type: string
minLength: 1
description: >-
Interfaz UUID o CRN anidado. Los nombres nulos no tienen
ámbito de subred y se rechazan.
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
address_id:
type: string
format: uuid
responses:
'200':
description: Adjunto
content:
application/json:
schema:
type: object
properties:
floating_ip:
$ref: '#/components/schemas/FloatingIp'
'400':
description: >-
La subred de la interfaz no tiene una ruta predeterminada a una
puerta de enlace de Internet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: >
La interfaz ya lleva una IP flotante diferente (una NIC tiene una
identidad pública); o la IP flotante ya tiene un miembro, y un
segundo lo convertiría en una dirección de anycast, que debe
pertenecer a un grupo de instancias; o está vinculada a un
balanceador de carga / grupo de instancias, que poseen sus propios
enlaces.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
$ref: '#/components/responses/UnprocessableEntity'
security:
- BearerAuth: []
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
description: >-
Clave opcional generada por el cliente que hace que una creación sea
segura para la reproducción. Al volver a intentar una solicitud con la
misma clave, se devuelve el resultado original literalmente en lugar de
crear un recurso duplicado. Se rechaza la reutilización de una clave con
un cuerpo de solicitud diferente (422); una solicitud cuya clave todavía
se está procesando devuelve 409. Los registros se mantienen durante 24
horas. Usa un UUID o un token único similar.
required: false
schema:
type: string
maxLength: 255
example: 550e8400-e29b-41d4-a716-446655440000
FloatingIpId:
name: floating_ip_id
in: path
description: ID IP flotante
required: true
schema:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
schemas:
FloatingIp:
type: object
required:
- id
- crn
- address
- family
- attached_to
- members
- tags
- created_at
- updated_at
- visibility
properties:
id:
type: string
format: uuid
readOnly: true
crn:
type: string
readOnly: true
example: crn:network:sa-saopaulo-1:my-account:floating-ip/
description:
type: string
example: Public IP for the web load balancer
family:
$ref: '#/components/schemas/IpFamily'
attached_to:
type: string
nullable: true
readOnly: true
description: >
CRN canónico de la interfaz vinculada, grupo de instancias o
balanceador de carga; nulo cuando no está conectado. Una dirección
de propiedad de grupo nombra su grupo incluso cuando el grupo tiene
cero miembros. Solo las direcciones de propiedad de grupo pueden
tener varios miembros de NIC. Administre sus enlaces a través de los
extremos IP flotantes del grupo de instancias; se rechazan las
conexiones y desconexiones directas.
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
members:
type: array
description: >
Los enlaces de la IP flotante. Una IP flotante se dirige a 0
miembros (asignados, no adjuntos), 1 miembro (el caso habitual) o N
miembros para un grupo de instancias: una IP flotante de anycast,
donde una IP pública se entrega a N tarjetas NIC de VM en hosts
(cada uno anunciado como un /32 desde el host que lo mantiene).
Los miembros pueden compartir un hipervisor. Dos de ellos en un host
solían significar que uno se servía y el otro estaba silenciosamente
oscuro; la regla de reenvío de un miembro ahora nombra al miembro, y
el host divide las conexiones entre los miembros que tiene, por lo
que donde se encuentran los miembros es una decisión de capacidad en
lugar de una decisión de corrección. La dirección de un grupo de
instancias toma sus miembros de las réplicas activas del grupo, cada
una de ellas, de modo que una escalada hacia afuera se une y una
escalada hacia adentro se va sin un adjunto por réplica.
Con más de un miembro UNO miembro sirve cada conexión, elegida
mediante el hash de las direcciones y puertos del flujo, y cada
paquete de esa conexión va a la misma. Los miembros son instancias
separadas que no comparten nada, por lo que esto extiende las
conexiones y sobrevive a la pérdida de un host; no es un balanceador
de carga: nada comprueba si el servicio dentro de la instancia está
activo, y las conexiones en curso a un miembro que se va no se
mueven, terminan.
La dirección de un POOL es la excepción, y solo para el arranque.
Una réplica se une a la dirección tan pronto como se coloca, pero no
recibe tráfico hasta que ha llegado al servicio de metadatos de la
instancia, lo que demuestra que el invitado arrancó, en lugar de que
se inició su máquina virtual. Hasta entonces es un miembro con
`health` `unhealthy`. Una réplica cuya imagen nunca contacta con el
servicio de metadatos se admite de todos modos después de unos
minutos, por lo que una imagen inusual retrasa el tráfico en lugar
de no obtenerlo nunca.
items:
$ref: '#/components/schemas/FloatingIpMember'
tags:
type: object
additionalProperties:
type: string
health_check:
allOf:
- $ref: '#/components/schemas/FloatingIpHealthCheck'
description: >
La comprobación de preparación se aplicó a los miembros de esta
dirección. Ausente cuando no se configura ninguna. Consulte
`FloatingIpHealthCheck`.
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
address:
type: string
description: Dirección pública o privada asignada.
example: 212.66.52.71
visibility:
type: string
enum:
- public
- private
subnet_id:
type: string
format: uuid
nullable: true
description: Subred de asignación para IPs flotantes privadas.
vpc_id:
type: string
format: uuid
description: Asignación de VPC para IP flotantes privadas.
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Código de error que identifica el tipo de error
example: INVALID_INPUT
message:
type: string
description: Mensaje de error legible por el ser humano
example: Invalid request parameters
params:
type: object
additionalProperties: true
description: >-
Valores no sensibles opcionales para la interpolación de errores
localizados, codificados por código de error. Nunca presente por
errores del servidor.
example:
instances: 2
pools: 0
request_id:
type: string
format: uuid
description: Solicitar ID para depuración
example: 550e8400-e29b-41d4-a716-446655440000
IpFamily:
type: string
enum:
- ipv4
- ipv6
description: >
La familia de direcciones IP. Las IP flotantes admiten cualquier familia
y pueden tener visibilidad pública o privada. Las IP flotantes públicas
se asignan desde el grupo de direcciones públicas de la región; las IP
flotantes privadas se asignan desde el rango de subred seleccionado para
esa familia.
La adscripción de una IP flotante a una interfaz requiere una dirección
de la misma familia en esa interfaz. IPv6 no requiere que IPv4 esté
habilitado en la subred. La accesibilidad a Internet también depende de
las rutas y las reglas de seguridad.
La adscripción de una IP flotante IPv6 no deshabilita la dirección IPv6
nativa de enrutamiento global de la interfaz. Ambas direcciones
permanecen accesibles cuando las reglas de enrutamiento y seguridad lo
permiten, y las respuestas a las conexiones entrantes conservan la
dirección que recibió la conexión. Una dirección IPv6 privada no se
convierte directamente en rutable por Internet al adjuntar una IP
flotante.
example: ipv6
FloatingIpMember:
type: object
description: Una vinculación de una IP flotante.
required:
- interface
- health
- reason
- created_at
properties:
interface:
type: object
nullable: true
description: >-
Resumen de NIC vinculada; nulo para una vinculación de balanceador
de carga nombrada por attached_to.
required:
- id
- crn
- instance
properties:
id:
type: string
format: uuid
crn:
type: string
example: >-
crn:network:sa-saopaulo-1:my-account:vpc/prod/subnet/public/interface/eth0
instance:
type: object
nullable: true
description: >-
Instancia propietaria; null cuando la interfaz no tiene
instancia propietaria.
required:
- id
- crn
- name
properties:
id:
type: string
format: uuid
crn:
type: string
example: crn:compute:sa-saopaulo-1:my-account:instance/web
name:
type: string
health:
type: string
enum:
- unknown
- healthy
- unhealthy
description: >
Lo que la plataforma sabe sobre este miembro.
`unknown` — no hay ninguna comprobación en curso. Es el estado de un
miembro conectado manualmente a una dirección sin comprobación de
estado: tú elegiste cuándo conectarlo, y la plataforma no recibe
señales sobre lo que se ejecuta dentro de la instancia. El miembro
sigue anunciado.
`healthy` — la plataforma tiene pruebas de que el miembro está
activo y, si hay una comprobación de estado configurada en la
dirección, de que esta se supera.
`unhealthy` — la plataforma todavía no ha recibido esa confirmación
o una comprobación configurada está fallando. El miembro permanece
asociado a la dirección, pero no recibe tráfico hasta recuperarse.
Sin una comprobación de estado, `healthy` solo confirma que el
sistema de la instancia está activo, no que el servicio acepte
conexiones. Configura `health_check` en la IP flotante para
comprobar también si la aplicación está preparada.
example: unknown
reason:
type: string
enum:
- unprobed
- booting
- probe_failed
- passing
description: >
Por qué el miembro lee el `health` que hace — así que usted puede
decir "su servicio no está respondiendo" de "el invitado no ha
arrancado todavía".
`unprobed` — nadie está comprobando (sin comprobación de estado,
adjunto a mano). `booting` — la plataforma aún no ha visto al
invitado. `probe_failed` — la comprobación de estado configurada
está fallando. `passing` — el invitado está en marcha y, si se
configura una comprobación, pasa.
example: unprobed
created_at:
type: string
format: date-time
readOnly: true
address_id:
type: string
format: uuid
nullable: true
description: Dirección secundaria de destino en la interfaz de miembro.
FloatingIpHealthCheck:
type: object
description: >
Una comprobación de preparación para los miembros de una IP flotante
compartida (anycast) — el mismo vocabulario que una comprobación de
estado del grupo objetivo del balanceador de carga, una que ya conoces.
La plataforma comprueba la dirección privada de cada miembro dentro de
la VPC. Un miembro que falla deja de recibir tráfico a través de la IP
flotante y regresa cuando pasa de nuevo. Si CADA miembro falla, toda la
dirección se oscurece: una comprobación mal configurada es una
interrupción visible que usted causó, no la plataforma que anuncia
silenciosamente algo que cree que está caído.
La comprobación se realiza en la dirección, no por miembro: los miembros
son backends intercambiables, y un grupo los deriva. Una dirección sin
verificación se comporta exactamente como antes: solo se muestran los
miembros del grupo, siempre se anuncian los que están adjuntos a mano.
required:
- protocol
- port
- interval_sec
- timeout_sec
- healthy_threshold
- unhealthy_threshold
properties:
protocol:
type: string
enum:
- tcp
- http
- https
default: tcp
description: >
`tcp` abre una conexión; `http`/`https` emite un GET y compara el
estado con `matcher`. No hay `udp`: una sonda de preparación
necesita una respuesta — compruebe un servicio udp en un puerto tcp
de salud en su lugar.
example: http
path:
type: string
example: /healthz
description: Ruta HTTP probada; ignorada para tcp.
port:
type: integer
minimum: 1
maximum: 65535
example: 8080
description: Puerto probado en el miembro.
interval_sec:
type: integer
minimum: 1
maximum: 300
default: 30
example: 30
timeout_sec:
type: integer
minimum: 1
maximum: 60
default: 5
example: 5
description: Tiempo de espera por sonda; debe ser menor que interval_sec.
healthy_threshold:
type: integer
minimum: 1
maximum: 10
default: 3
example: 3
description: Pasajes consecutivos antes de que un miembro voltee sano.
unhealthy_threshold:
type: integer
minimum: 1
maximum: 10
default: 3
example: 3
description: Fallos consecutivos antes de que un miembro se vuelva insalubre.
matcher:
type: string
default: '200'
example: 200-299
description: Estado HTTP o rango que cuenta como pasando; ignorado para tcp.
responses:
Unauthorized:
description: Se requiere autenticación o el token no es válido
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Permisos insuficientes
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: No se encontró el recurso
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
request_id: 550e8400-e29b-41d4-a716-446655440000
UnprocessableEntity:
description: >
La solicitud está bien formada, pero no se puede procesar como se envió.
En las operaciones que aceptan `Idempotency-Key` este es el caso de
reutilización de clave: la clave fue vista por primera vez con una carga
de solicitud diferente, por lo que la reproducción del resultado
almacenado respondería a una pregunta que el llamador no hizo.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: IDEMPOTENCY_KEY_REUSED
message: >-
This Idempotency-Key was already used with a different request
payload
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >+
Un token bearer de OAuth 2.0, enviado como `Authorization: Bearer
`. Esta es la forma recomendada de autenticación.
Obtén el token intercambiando el par de claves de acceso de una cuenta
de servicio en `POST /v1/oauth/token` con
`grant_type=client_credentials`. Es el flujo estándar de credenciales de
cliente; las bibliotecas compatibles con OAuth pueden obtener y renovar
el token por ti.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
Los tokens duran una hora por defecto. El mismo par de claves de acceso
también sirve como credencial AWS SigV4 para el endpoint de objetos
compatible con S3, que solo acepta ese método de autenticación.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.