How to create/delete Network Areas via IaaS-API

STACKIT Network Area (SNA)

The STACKIT Network Area (SNA) allows projects within an organization to be connected to each other on a network level. For more information and an overview about SNA, see STACKIT Network Area (SNA).

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

stackit auth login

stackit config set --project-id <Project-ID>

Please take note of your organization id. We use the variable $ORG_ID in all commands on this page. You can set it in your shell session with

ORG_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Create a SNA

To create a network area, you need to provide:

name
networkRanges
transferNetworks

Additionally, you can optionally provide

one or more custom nameservers to be used by default in the area,
minimum, maximum and default prefix lengths for networks in the area,
a list of area routes

In the following example, we create a SNA named networkarea01 configured with the transfer network 10.0.0.0/16 and a single network range 10.0.0.0/16

Additionally, we set default, minimum and maximum prefix lengths to 25, 24 and 29 and configure a single default nameserver with the IP 8.8.8.8:

stackit curl -X POST \
 https://iaas.api.eu01.stackit.cloud/v1/organizations/$ORG_ID/network-areas \
 --header "Content-Type: application/json" \
 --data '{
 "name": "networkarea01",
 "addressFamily": {
 "ipv4": {
 "transferNetwork": "10.1.2.0/24",
 "defaultPrefixLen": 25,
 "minPrefixLen": 24,
 "maxPrefixLen": 29,
 "networkRanges": [
 {"prefix": "10.0.0.0/16"}
 ],
 "defaultNameservers": [
 "8.8.8.8"
 ]
 }
 }
}'

You should get a response similar to this:

{
 "areaId": "f1633a76-4893-4300-9b29-65776087e82e",
 "createdAt": "2024-12-11T13:37:00Z",
 "ipv4": {
 "defaultNameservers": [
 "8.8.8.8"
 ],
 "networkRanges": [
 {
 "createdAt": "2024-12-11T13:37:00Z",
 "networkRangeId": "eb3e197b-0b4b-48f1-9a56-22f3e8bd1c3b",
 "prefix": "10.0.0.0/24",
 "updatedAt": "2024-12-11T13:37:00Z"
 }
 ],
 "routes": [],
 "transferNetwork": "10.1.2.0/24",
 "defaultPrefixLen": 25,
 "maxPrefixLen": 29,
 "minPrefixLen": 24
 },
 "labels": {},
 "name": "networkarea01",
 "projectCount": 0,
 "state": "CREATING",
 "updatedAt": "2024-12-11T13:37:00Z"
}

Please take note of the areaId property, which refers to the newly created network area and will be needed for any of the API calls that query or modify the configuration of the area.

A newly created SNA has an initial state of CREATING. Once the creation has finished, the state of the area will change to CREATED. For example, using the areaID from the above output, you can check the current state using the following command:

AREA_ID=f1633a76-4893-4300-9b29-65776087e82e
stackit curl \
 https://iaas.api.eu01.stackit.cloud/v1/organizations/$ORG_ID/network-areas/$AREA_ID

If the creation is finished, you should get a response similar to this:

{
 "areaId": "f1633a76-4893-4300-9b29-65776087e82e",
 "createdAt": "2024-12-11T13:37:00Z",
 "ipv4": {
 "defaultNameservers": [
 "8.8.8.8"
 ],
 "networkRanges": [
 {
 "createdAt": "2024-12-11T13:37:00Z",
 "networkRangeId": "eb3e197b-0b4b-48f1-9a56-22f3e8bd1c3b",
 "prefix": "10.0.0.0/24",
 "updatedAt": "2024-12-11T13:37:00Z"
 }
 ],
 "routes": [],
 "transferNetwork": "10.1.2.0/24",
 "defaultPrefixLen": 25,
 "maxPrefixLen": 29,
 "minPrefixLen": 24
 },
 "labels": {},
 "name": "networkarea01",
 "projectCount": 0,
 "state": "CREATED",
 "updatedAt": "2024-12-11T13:37:30Z"
}

Note the state property changed from CREATING to CREATED.

You can find further information about these and more API calls in the API documentation

Delete a SNA

Before you can delete a SNA, make sure you have deleted all projects that are using this area. It is not possible to delete a Network Area that still has projects attached to it. An easy way to check this is by looking at the projectCount property of the SNA you want to delete.

As an example, to delete the SNA with the id f1633a76-4893-4300-9b29-65776087e82e we created in the previous section, use the following command:

AREAD_ID=f1633a76-4893-4300-9b29-65776087e82e
stackit curl --include -X DELETE \
 https://iaas.api.eu01.stackit.cloud/v1/organizations/$ORG_ID/network-areas/$AREA_ID

Note that we used —include flag to see the response headers, and most importantly, the response code. A successful deletion request will be answered with a HTTP/2.0 “202 Accepted” response and an empty body.

If the deletion is not successful, you will receive the response code 409 (Conflict), for example. You will receive this code if projects are still assigned to the SNA. Further information can be found here.