How to manage Public IPs via IaaS-API

Basic Concepts

Public IPs are IPv4 addresses can be assigned to servers to make them reachable from the internet. For more information about that topic, please have a look at Basic Concepts Public IPs.

Prerequisites

• Your organization has a customer account (Create a customer account).
• You have a user account with the necessary permissions (Identity and Access Management).
• You have a Project in your customer account (Create a Project).
• You’ll need to be authenticated with the CLI (STACKIT CLI).

Listing Public IPs in a project

You can get list of all Public IPs allocated in your project using the following command (replace $PROJECT_ID with the ID of your STACKIT project):

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips

The response will look similar to this:

{
 "items": [
 {
 "id": "7068d6ab-7956-4d05-ba1c-32ce5cde2343",
 "ip": "192.214.174.83",
 "labels": {},
 "networkInterface": "cfe0edb8-0448-43ac-9d58-55e0fcd8f49c",
 },
 {
 "id": "90e4e256-35c2-48f0-b552-719f7e9a396d",
 "ip": "192.214.174.148",
 "labels": {},
 "networkInterface": null
 },
 {
 "id": "a2a450f5-6cf2-49cf-bb32-ffb08a52a024",
 "ip": "192.214.173.156",
 "labels": {},
 "networkInterface": null,
 },
 {
 "id": "c896bf99-3495-4c72-ad56-1b84da6e9eae",
 "ip": "192.214.174.9",
 "labels": {
 "my-label": "example"
 },
 "networkInterface": "18b763fa-aa44-4431-90ab-a4660cd0efd6"
 }
 ]
}

Take note of the id which is needed in API calls to query or modify the respective public IP.

The property networkInterface tells whether the public IP is currently attached to a network interface.

Using label selectors

If you are using labels to organize your public IPs, you can pass a label_selector query parameter to filter the resulting list. For example, if you have a label my-label and want to filter for the label value example, you would append ?label_selecter=<expr>, where <expr> is the URL-quoted form of the string my-label=example:

stackit curl \
 "https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips?label_selector=my-label%3Dexample"

Note that we have put the URL in quotes, because some shells (e.g., zsh) try to interpret the ? character.

This would result in a list that only contains public IPs that match this selector, such as:

{
 "items": [
 {
 "id": "c896bf99-3495-4c72-ad56-1b84da6e9eae",
 "ip": "192.214.174.9",
 "labels": {
 "my-label": "example"
 },
 "networkInterface": "18b763fa-aa44-4431-90ab-a4660cd0efd6"
 }
 ]
}

Get details of a Public IP

You can get the details of a Public IP using the following command:

PUBLIC_IP_ID=a2a450f5-6cf2-49cf-bb32-ffb08a52a024
stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips/$PUBLIC_IP_ID

You will get a response like this:

{
 "id": "a2a450f5-6cf2-49cf-bb32-ffb08a52a024",
 "ip": "192.214.173.156",
 "labels": {},
 "networkInterface": null
}

Creating a Public IP in a project

Creating a Public IP can be done in two ways:

• Option A: allocate a Public IP and attach it to a network interface at a later point int time (directly or through attaching to a server), or
• Option B: create a Public IP and attach it directly to a network interface.

Option A: Without specifying an interface

Allocate a public IP without attaching it to an interface by sending an empty JSON object in the request body, for example with:

stackit curl -X POST https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips \
--header "Content-Type: application/json" \
--data '{}'

This will return a response similar to the following:

{
 "id": "90e4e256-35c2-48f0-b552-719f7e9a396d",
 "ip": "192.214.174.148",
 "labels": {},
 "networkInterface": null
}

Take note of the id, so you can refer to it later when you want to attach to a NIC or a server.

Option B: With specifying an interface

Allocate a public IP and immediately attach it to an interface, for example to an interface with the ID cfe0edb8-0448-43ac-9d58-55e0fcd8f49c:

stackit curl -X POST https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips \
--header "Content-Type: application/json" \
--data '{
 "networkInterface": "cfe0edb8-0448-43ac-9d58-55e0fcd8f49c",
}'

This will return a response similar to the following:

{
 "id": "7068d6ab-7956-4d05-ba1c-32ce5cde2343",
 "ip": "192.214.174.83",
 "labels": {},
 "networkInterface": "cfe0edb8-0448-43ac-9d58-55e0fcd8f49c",
},

Assigning a Public IP to a server

As an alternative to attaching the public IP to an existing network interface, you can also attach it to an existing server. Behind the scences, this will automatically choose an appropriate network interface of the server and attach the public IP to it.

This can be achieved by the following command, for example for the public IP that we created above (option A):

SERVER_ID=8e7217f2-830f-4c6c-9cf3-44a5d4da6309
PUBLIC_IP_ID=90e4e256-35c2-48f0-b552-719f7e9a396d
stackit curl --include -X PUT \
 https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/servers/$SERVER_ID/public-ips/$PUBLIC_IP_ID

If the request was successful, you will get a response with status code 202 (Accepted). Furthermore, if you query the public IP details again, you will see that it now has an networkInterface assigned (which belongs to the server).

Update a Public IP

You can update the labels and the network interface of a public IP. For example, to assign an existing public IP to a specific network interface and add a label, you can use this command:

PUBLIC_IP_ID=a2a450f5-6cf2-49cf-bb32-ffb08a52a024
stackit curl -X PATCH https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips/$PUBLIC_IP_ID \
--header "Content-Type: application/json" \
--data '{
 "labels": {
 "example-label": "example-value"
 },
 "networkInterface": "a507736a-3b09-47cd-9113-5c279633e302"
}'

The result will look similar to this:

{
 "id": "a2a450f5-6cf2-49cf-bb32-ffb08a52a024",
 "ip": "192.214.173.156",
 "labels": {
 "example-label": "example-value"
 },
 "networkInterface": "a507736a-3b09-47cd-9113-5c279633e302"
}

Delete a Public IP

Attention: You have to make sure yourself that the Public IP is not in use anymore.

A public IP can be deleted as follows:

PUBLIC_IP_ID=a2a450f5-6cf2-49cf-bb32-ffb08a52a024
stackit curl --include -X DELETE \
 https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/public-ips/$PUBLIC_IP_ID

If the deletion request was successful, you will get a response with status code 204 (No Content) and an empty body.