How to manage Networks via IaaS-API

Basic Concepts

The IaaS API allows you to create virtual networks which you can use to attach your VMs to, to enable communication between these VMs. You can also connect a virtual network to an external network that provides internet connectivity.

By default, only networks within one project can be connected. However, using network areas (SNAs, see How to create/delete Network Areas via IaaS-API), you can even connect several virtual networks with a router managed by STACKIT.

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

Create network in a project

Attention: If the project has internetAccess enabled and this is the first network in the project, this operation might incur a monthly fee.

To create a network, you need to provide a network name and the address family (IPv4 or IPv6) together with the desired network prefix length. The network prefix will be chosen automatically.

Optionally, you can provide the following network details:

• up to three custom nameservers (otherwise, the area default nameservers will be used)
• custom network prefix (instead of specifying a prefix length)
• custom gateway configuration or no gateway at all (by default, the first IP of the network will be the gateway)
• custom labels

Furthermore, you can specify if the network should be routable (routed property), i.e., reachable from other networks. Networks are routable by default.

For example, if we want to create an IPv4 network named “my-little-network” with a network prefix 10.0.3.0/24, we could use the following command (replace $PROJECT_ID with the ID of your STACKIT project):

stackit curl -X POST https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks \
--header "Content-Type: application/json" \
--data '{
 "name": "my-little-network",
 "addressFamily": {
 "ipv4": {
 "prefix": "10.0.3.0/24"
 }
 }
}'

The response will be similar to the following:

{
 "createdAt": "2024-12-17T15:51:15Z",
 "labels": {},
 "name": "my-little-network",
 "networkId": "bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3",
 "prefixes": [
 "10.0.3.0/24"
 ],
 "routed": true,
 "state": "CREATING",
 "updatedAt": "2024-12-17T15:51:15Z"
}

Note that the state of the resource initially is CREATING. A background job will take care of the actual creation of the network. Take note of the networkId which is needed in API calls to query or modify the network.

For more information about the API call and the available parameters, please have a look at the docs.

Get the details of a network in a project

You can check the current state and all other details of a network with the following command:

NETWORK_ID=bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3
stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID

You should get a response similar to the following:

{
 "createdAt": "2024-12-17T15:51:15Z",
 "gateway": "10.0.3.1",
 "labels": {},
 "name": "my-little-network",
 "nameservers": [
 "1.1.1.1",
 "9.9.9.9"
 ],
 "nameserversV6": [],
 "networkId": "bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3",
 "prefixes": [
 "10.0.3.0/24"
 ],
 "prefixesV6": [],
 "publicIp": "45.141.74.76",
 "routed": true,
 "state": "CREATED",
 "updatedAt": "2024-12-17T15:51:17Z"
}

If you are inspecting the details of a newly created network, you will notice how the state changed from CREATING to CREATED and some details have been added (if not explicitely specified), such as nameservers, gateway and publicIp.

A publicIp is added for any network created in a project with internetAccess set to true and is assigned to the router which performs SNAT for egress traffic. In other words, this is the IP address that remote sites will see as the origin of requests from within the network. VMs cannot be reached via this IP.

For more information about the API call and the available parameters, please have a look at the docs.

List networks in a project

You can list all networks in a project with the following command (again, replace $PROJECT_ID with the ID of your STACKIT project):

stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks

You should get a response similar to this:

{
 "items": [
 {
 "createdAt": "2024-12-17T15:51:15Z",
 "gateway": "10.0.3.1",
 "labels": {},
 "name": "my-little-network",
 "nameservers": [
 "1.1.1.1",
 "9.9.9.9"
 ],
 "nameserversV6": [],
 "networkId": "bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3",
 "prefixes": [
 "10.0.3.0/24"
 ],
 "prefixesV6": [],
 "publicIp": "45.141.74.76",
 "routed": true,
 "state": "CREATED",
 "updatedAt": "2024-12-17T15:51:17Z"
 }
 ]
}

Using label selectors

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

stackit curl \
 "https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks?label_selector=environment%3Ddev"

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 network items that match this selector, such as:

{
 "items": [
 {
 "createdAt": "2024-12-17T15:51:15Z",
 "gateway": "10.0.3.1",
 "labels": {
 "environment": "dev"
 },
 "name": "my-little-dev-network",
 "nameservers": [
 "1.1.1.1",
 "9.9.9.9"
 ],
 "nameserversV6": [],
 "networkId": "bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3",
 "prefixes": [
 "10.0.3.0/24"
 ],
 "prefixesV6": [],
 "publicIp": "45.141.74.76",
 "routed": true,
 "state": "CREATED",
 "updatedAt": "2024-12-17T16:32:25Z"
 }
 ]
}

For more information about the API call and the available parameters, please have a look at the docs.

Change network details

You can change some of the details of an existing network, such as

• name
• address family and network prefix
• labels
• the routed property

For example, if we want to change the name of the previously created “my-little-network” to “my-little-dev-network” and add a label environment with the value dev, we could use the following command:

NETWORK_ID=bfd1ee99-ca57-4dc8-a362-da5b75d9d7c3
stackit curl --include -X PATCH https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID \
--header "Content-Type: application/json" \
--data '{
 "name": "my-little-dev-network",
 "labels": {
 "environment": "dev"
 }
}'

If successful, you will get a response with status code 202 (Accepted) and an empty body.

For more information about the API call and the available parameters, please have a look at the docs.

Remove a network in a project

You can delete networks via the IaaS API, provided the network is not used.

Attention: If you try to delete a network that is still in use (i.e., still has VMs attached), the API call will return a response with the error code 409 (Conflict).

For example, to delete a network identified by the ID $NETWORK_ID, use the following command:

stackit curl --include -X DELETE \
 https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID

If the request was successful, a response with the status code 202 (Accepted) and an empty body will be returned.

For more information about the API call, please have a look at the docs.