How to manage Network Interfaces (NICs) via IaaS-API

Diese Seite ist noch nicht in deiner Sprache verfügbar. Englische Seite aufrufen

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>

List network interfaces in a project

Use the following call to list all network interfaces in your project (replace $PROJECT_ID with the ID of your STACKIT project):

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

The response will contain a list of items with details such as type, status, IPv4 address, MAC address, labels, attached security groups, and so on, similar to this:

{
 "items": [
 {
 "id": "80333aa1-7833-4ab6-a95a-db5d02e49808",
 "ipv4": "10.0.0.2",
 "labels": {},
 "mac": "fa:16:4f:bc:11:4f",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": false,
 "securityGroups": [],
 "status": "DOWN",
 "type": "metadata"
 },
 {
 "id": "cd5ac25d-2860-4d9f-8a85-3d2abf1f408b",
 "ipv4": "10.0.0.1",
 "labels": {},
 "mac": "fa:16:4f:84:ff:d0",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": false,
 "securityGroups": [],
 "status": "ACTIVE",
 "type": "gateway"
 },
 {
 "id": "d88de6f1-0f30-4e68-bedf-35630bf934f0",
 "ipv4": "192.168.0.239",
 "labels": {
 "req-8487404bbdd07f2460374af51e314b25": ""
 },
 "mac": "fa:16:4f:1e:01:d1",
 "name": "area-309fd1eb-46f0-46a6-94c2-5ab481aa1281",
 "networkId": "77e6fa1b-c0db-42c4-a8ee-a1b806eb052f",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "ACTIVE",
 "type": "gateway"
 }
 ]
}

Note that individual network interfaces can be identified by their id, which is useful for other API calls querying or modifying specific interfaces.

Using a label selector

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

stackit curl \
 "https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/nics?label_selector=app%3Dmy-awesome-application"

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

This will result in a list that only contains network interfaces that match this selector, such as:

{
 "items": [
 {
 "id": "ddc268ea-a8bf-456b-9c3a-d1ecde9452ce",
 "ipv4": "10.0.0.173",
 "labels": {
 "app": "my-awesome-application"
 },
 "mac": "fa:16:4f:58:4c:ec",
 "name": "example-nic-name",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "DOWN",
 "type": "server"
 }
 ]
}

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

Get details of a network interface

Detailed information about a network interface can be obtained with the following command (assuming we want to get details for the NIC with the ID d88de6f1-0f30-4e68-bedf-35630bf934f0):

NIC_ID=d88de6f1-0f30-4e68-bedf-35630bf934f0
stackit curl https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/nics/$NIC_ID

You will get a response similar to the following:

{
 "id": "d88de6f1-0f30-4e68-bedf-35630bf934f0",
 "ipv4": "192.168.0.239",
 "labels": {
 "req-8487404bbdd07f2460374af51e314b25": ""
 },
 "mac": "fa:16:4f:1e:01:d1",
 "name": "area-309fd1eb-46f0-46a6-94c2-5ab481aa1281",
 "networkId": "77e6fa1b-c0db-42c4-a8ee-a1b806eb052f",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "ACTIVE",
 "type": "gateway"
}

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

Create a network interface

Network interfaces can be created in a network in several ways. In the most basic approach, you pass an empty JSON object as the request body to the API endpoint as follows:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
stackit curl -X POST https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics \
--header "Content-Type: application/json" \
--data '{}'

In this case, an IP address will be chosen automatically (depending on the configured address ranges in the network). Furthermore, nicSecurity defaults to true and the project’s default security group will be assigned to the NIC. You will get a response similar to this:

{
 "id": "ddc268ea-a8bf-456b-9c3a-d1ecde9452ce",
 "ipv4": "10.0.0.173",
 "labels": {},
 "mac": "fa:16:4f:58:4c:ec",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "DOWN",
 "type": "server"
}

Note that the status is DOWN, because the NIC is not attached to a server.

Of course, you can override the defaults by supplying the details in the JSON body. For example, if you would like to explicitely specify an IPv4, disable NIC security, and add a label, you could use the following command:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
stackit curl -X POST https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics \
--header "Content-Type: application/json" \
--data '{
 "ipv4": "10.0.0.42",
 "labels": {
 "my-fancy-label": "some-value"
 },
 "nicSecurity": false
}'

That call will result in a response similar to this:

{
 "id": "18b763fa-aa44-4431-90ab-a4660cd0efd6",
 "ipv4": "10.0.0.42",
 "labels": {
 "my-fancy-label": "some-value"
 },
 "mac": "fa:16:4f:9b:5c:9b",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": false,
 "securityGroups": [],
 "status": "DOWN",
 "type": "server"
}

Note that because of disabling NIC security, security groups cannot be assigned to the NIC, therefore the list is empty.

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

Update a network interface

Some details of a network interface can be updated:

name
labels
security groups (see next section)
allowed addresses
NIC security flag

For example, to assign a the name example-nic-name and a label to a NIC identified by ddc268ea-a8bf-456b-9c3a-d1ecde9452ce, use the following command:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
NIC_ID=ddc268ea-a8bf-456b-9c3a-d1ecde9452ce
stackit curl -X PATCH https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics/$NIC_ID \
--header "Content-Type: application/json" \
--data '{
 "name": "example-nic-name",
 "labels": {
 "app": "my-awesome-application"
 }
}'

The response will look similar to this:

{
 "id": "ddc268ea-a8bf-456b-9c3a-d1ecde9452ce",
 "ipv4": "10.0.0.173",
 "labels": {
 "app": "my-awesome-application"
 },
 "mac": "fa:16:4f:58:4c:ec",
 "name": "example-nic-name",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "DOWN",
 "type": "server"
}

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

Associate a security group with a network interface

A special case of updating a network interface is updating its assigned security group. This can be easily achieved by patching the securityGroups property of an existing NIC.

For example, given a NIC that has the following properties (see above for getting the details of a NIC):

{
 "id": "4f59a57a-2caa-4e73-855a-5a4e9570d4bf",
 "ipv4": "10.0.0.225",
 "labels": {},
 "mac": "fa:16:4f:e6:59:32",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59"
 ],
 "status": "DOWN",
 "type": "server"
}

This NIC currently has the default security group 48d2f405-71e6-45df-9687-f1052edcdd59 of the network assigned.

If we want to assign an additional security group, for example a group identified by 3ca1619d-4302-4831-9125-d935c7582126, we would use the following command:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
NIC_ID=4f59a57a-2caa-4e73-855a-5a4e9570d4bf
stackit curl -X PATCH https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics/$NIC_ID \
--header "Content-Type: application/json" \
--data '{
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59",
 "3ca1619d-4302-4831-9125-d935c7582126"
 ]
}'

Note how we included the already existing (default) security group in the JSON body, this is important because the not mentioned groups get removed. The result of the request will look similar to this:

{
 "id": "4f59a57a-2caa-4e73-855a-5a4e9570d4bf",
 "ipv4": "10.0.0.225",
 "labels": {},
 "mac": "fa:16:4f:e6:59:32",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "48d2f405-71e6-45df-9687-f1052edcdd59",
 "3ca1619d-4302-4831-9125-d935c7582126"
 ],
 "status": "DOWN",
 "type": "server"
}

On the other hand, if you want to replace or remove security groups from the NIC, just do not include them in the JSON body. For example, to remove the default security group (which has the ID 48d2f405-71e6-45df-9687-f1052edcdd59 in this case), you can use the command:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
NIC_ID=4f59a57a-2caa-4e73-855a-5a4e9570d4bf
stackit curl -X PATCH https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics/$NIC_ID \
--header "Content-Type: application/json" \
--data '{
 "securityGroups": [
 "3ca1619d-4302-4831-9125-d935c7582126"
 ]
}'

The result will look similar to this:

{
 "id": "4f59a57a-2caa-4e73-855a-5a4e9570d4bf",
 "ipv4": "10.0.0.225",
 "labels": {},
 "mac": "fa:16:4f:e6:59:32",
 "networkId": "d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67",
 "nicSecurity": true,
 "securityGroups": [
 "3ca1619d-4302-4831-9125-d935c7582126"
 ],
 "status": "DOWN",
 "type": "server"
}

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

Delete a network interface

Attention: There is no check whether the network interface is still in use. Deleting a NIC will act like “pulling the cable”.

A network interface can be deleted as follows:

NETWORK_ID=d9a7b06a-ee35-41e1-ae5a-bd06c76e2f67
NIC_ID=ddc268ea-a8bf-456b-9c3a-d1ecde9452ce
stackit curl --include -X DELETE \
 https://iaas.api.eu01.stackit.cloud/v1/projects/$PROJECT_ID/networks/$NETWORK_ID/nics/$NIC_ID

If the call was successful, the response will return status code 204 (No Content) and an empty body.

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