NavigationContentFooter

Elastic Metal - Flexible IP API

Introduction

Flexible IP addresses are additional public IP addresses that you can hold independently of any Elastic Metal server. They can either be IPv4 (single IP) or IPv6 (/64 IP block).

Flexible IPs can be attached to and detached from any Elastic Metal server within the same zone. You can hold multiple flexible IPs in your account, and a given server can be linked to multiple flexible IPs. When you delete a flexible IP address, it is disassociated from your account.

Flexible IPs can also be used to implement failovers. If any failure or maintenance issue occurs on a given Elastic Metal server, its flexible IP address can be transferred to another server.

Important

This documentation refers to flexible IPs for Elastic Metal servers. Refer to the corresponding product documentation if you are looking for information about flexible IPs for other products.

Concepts

Refer to our dedicated concepts page to find definitions of the different terms referring to Elastic Metal and flexible IPs.

Quickstart

  1. Configure your environment variables.

    export SCW_ACCESS_KEY="<API access key>"
    export SCW_SECRET_KEY="<API secret key>"
    export SCW_DEFAULT_ZONE="<Scaleway default zone>"
    Note

    This is an optional step that seeks to simplify your usage of the APIs. Refer to the Availability Zones section to verify which zones are available for use.

  2. Edit the POST request payload that we will use in the next step to create a flexible IP.

    {
    "project_id": "88f30nda-6768-9293-a89c-2b0b178628a6",
    "description": "This is the description of my fIP",
    "tags": [
    "tag1"
    ],
    "server_id": "9dddd3sa-f13c-4351-9185-18f6b6d97t9w",
    "reverse": "9dddd3se-f14c-4859-9185-18f6b6d78f8b.fr-par-1.baremetal.scw.cloud",
    "is_ipv6": true
    }
    ParameterDescription
    project_idREQUIRED ID of the Project to create your flexible IP in.
    descriptionA description for your flexible IP (max. 255 characters).
    tagsOne or several tags for your flexible IP (optional)
    server_idID of the server on which to attach your newly created flexible IP.
    reverseValue of the server's reverse DNS.
    is_ipv6BOOLEAN Defines whether the flexible IP has an IPv6 address.
    Note

    Except when specified, all values are nullable.

  3. Create a flexible IP: run the following command to create a flexible IP, including the payload you edited in the previous step.

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/flexible-ip/v1alpha1/zones/$SCW_DEFAULT_ZONE/fips" \
    -d '{
    "project_id": "88f30nda-6768-9293-a89c-2b0b178628a6",
    "description": "This is the description of my fIP",
    "tags": [
    "tag1"
    ],
    "server_id": "9dddd3sa-f13c-4351-9185-18f6b6d97t9w",
    "reverse": "9dddd3se-f14c-4859-9185-18f6b6d78f8b.fr-par-1.baremetal.scw.cloud",
    "is_ipv6": true
    }'

    You should get an output similar to the following one, providing details about your flexible IP:

    Note

    This is a response example, the UUIDs and IP address displayed are not real.

    {
    "id": "058d9f12-c33d-523d-b216-da4c9d0f3d66",
    "organization_id": "88f30nda-6768-9293-a89c-2b0b178628a6",
    "project_id": "88f30nda-6768-9293-a89c-2b0b178628a6",
    "description": "This is the description of my fIP",
    "updated_at": "2023-04-04T13:34:19.058178830Z",
    "created_at": "2023-01-31T16:30:54.017824Z",
    "status": "updating",
    "tags": [
    "tag1"
    ],
    "ip_address": "1998:cb9:813:24f3::/75",
    "server_id": null,
    "reverse": "9dddd3se-f14c-4859-9185-18f6b6d78f8b.fr-par-1.baremetal.scw.cloud",
    "mac_address": null,
    "zone": "fr-par-1"
    }
  4. Get a list of your flexible IPs: run the following command to get a list of all the flexible IPs in your account, with their details:

    curl -X GET \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/flexible-ip/v1alpha1/zones/$SCW_DEFAULT_ZONE/fips"
  5. Generate a virtual MAC (Media Access Control) address: run the following command to generate a virtual MAC address on a given flexible IP. Ensure that you replace <FLEXIBLE-IP-ID> in the URL with the ID of the flexible IP you want to create a virtual MAC address for.

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/flexible-ip/v1alpha1/zones/$SCW_DEFAULT_ZONE/fips/<FLEXIBLE-IP-ID>/mac" \
    -d '{
    "mac_type": "<MAC_TYPE>"
    }'

    Payload value

    • mac_type (string): Choose the type of virtual MAC address you want to generate on your flexible IP: vmware, xen or kvm (with the default value being set to unknown_type). To get more information about the available virtual MAC addresses, refer to the "Technical information" part of this quickstart.
  6. Duplicate a virtual MAC (Media Access Control) address: run the following command to duplicate a Virtual MAC from a given flexible IP onto another flexible IP attached to the same server.

    curl -X POST \
    -H "X-Auth-Token: $SCW_SECRET_KEY" \
    -H "Content-Type: application/json" \
    "https://api.scaleway.com/flexible-ip/v1alpha1/zones/$SCW_DEFAULT_ZONE/fips/<fip_id> \
    -d '{
    "duplicate_from_fip_id": "<ID_OF_THE_FIP_TO_DUPLICATE_MAC_FROM>"
    }'

    Payload values

    • fip_id (string): ID of the flexible IP on which to duplicate the Virtual MAC. Note that flexible IPs need to be attached to the same server for the operation to work.
    • duplicate_from_fip_id (string): ID of the flexible IP to duplicate the Virtual MAC from.
Requirements

To perform the following steps, you must first ensure that:

  • You have a Scaleway account
  • You have created an API key and that the API key has sufficient IAM permissions to perform the actions described on this page
  • You have installed curl

Technical information

A virtual MAC (Media Access Control) address can be generated on a flexible IP. Virtual MAC addresses are unique identifiers assigned to a virtual machine's network interface. This is particularly useful for virtualization technologies enabling multiple virtual machines to run on a single host machine (now called a hypervisor).

Flexible IPs can have virtual MAC addresses assigned to them, and it is possible to duplicate these virtual MAC addresses between flexible IPs on the same server. When a virtual MAC address is duplicated onto another flexible IP, the two become part of the same virtual MAC group.

When flexible IPs belong to a given MAC group, they cannot be moved separately to another server. Both must be transferred to the new server, as a group. Subsequently, a MAC group can be moved by providing a list of flexible IP IDs in Attach/Detach requests.

Note that if you detach a single flexible IP from a MAC group, the virtual MAC address will be removed from the detached flexible IP.

Availability Zones

Flexible IPs are available in the following Availability Zones:

NameAPI ID
Parisfr-par-1 fr-par-2
Amsterdamnl-ams-1

Technical limitations

  • Flexible IPs exist for many resources (Instances, Load Balancers, etc). Note, however, that each of these sets of flexible IPs is independent and usable only with that product. This API concerns flexible IPs for Elastic Metal servers only.
  • There is a limit of 64 flexible IPs per server

Going further

For more help using flexible IPs, check out the following resources:

  • Our main documentation
  • Our Slack Community
  • Our support ticketing system.

Flexible IP

A flexible IP can be attached to any Elastic Metal server within the same zone. Multiple flexible IPs can be attached to a server.

GET
/flexible-ip/v1alpha1/zones/{zone}/fips
POST
/flexible-ip/v1alpha1/zones/{zone}/fips
GET
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}
PATCH
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}
DELETE
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}
POST
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}/mac
DELETE
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}/mac
POST
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}/mac/duplicate
POST
/flexible-ip/v1alpha1/zones/{zone}/fips/{fip_id}/mac/move
POST
/flexible-ip/v1alpha1/zones/{zone}/fips/attach
POST
/flexible-ip/v1alpha1/zones/{zone}/fips/detach
Docs APIScaleway consoleDedibox consoleScaleway LearningScaleway.comPricingBlogCarreer
© 2023-2024 – Scaleway