19. Network gateways

Network gateways connect SDN Private Networks to external IP networks. Currently the service supports NAT gateways which enable outbound Internet connections from SDN Private Networks via SDN routers.

The network gateway service is attached to an SDN router. It can be utilized by one or more SDN private networks attached to the same router. For traffic to land on the network gateway your servers must have the SDN router as their next hop for any destinations you wish to route through the network gateway service.

Available features

Feature	Description
nat	NAT gateway is a network address translation (NAT) service that offers a way for cloud servers in SDN private networks to connect to the Internet through the public IP assigned to the network gateway service

List services

Returns a list of network gateway services.

Request

GET /1.3/gateway HTTP/1.1

Query parameters

Attribute	Accepted value	Default value	Required	Description
limit	0-100	10	no	Number of entries to receive at most.
offset	>= 0	0	no	Offset for retrieved results.
label	String representation of a label.		no	Filter by label. See labels usage.

Normal response

HTTP/1.1 200 OK

[
  {
    "configured_status": "started",
    "created_at": "2022-12-01T09:04:08.529138Z",
    "features": [
      "nat"
    ],
    "name": "example-gateway",
    "operational_state": "running",
    "routers": [
      {
        "created_at": "2022-12-01T09:04:08.529138Z",
        "uuid": "0485d477-8d8f-4c97-9bef-731933187538"
      }
    ],
    "labels":[
      {
        "key":"env",
        "value":"testing"
      }
    ],
    "updated_at": "2022-12-01T19:04:08.529138Z",
    "uuid": "10c153e0-12e4-4dea-8748-4f34850ff55d",
    "zone": "fi-hel1"
  }
]

Notes:

Please see service configured statuses and operational states description.

Label

A label is structured as K/V pair with both the key and value as strings. Label Key (Lowercased alphabet (a-z), any number (0-9), 1-32 characters) Label Value (0-255 characters)

Get service details

Returns network gateway service by given {service_uuid}.

Request

GET /1.3/gateway/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "configured_status": "started",
  "created_at": "2022-12-01T09:04:08.529138Z",
  "features": [
    "nat"
  ],
  "name": "example-gateway",
  "operational_state": "running",
  "routers": [
    {
      "created_at": "2022-12-01T09:04:08.529138Z",
      "uuid": "0485d477-8d8f-4c97-9bef-731933187538"
    }
  ],
  "labels": [
    {
      "key":"env",
      "value":"testing"
    }
  ],
  "updated_at": "2022-12-01T19:04:08.529138Z",
  "uuid": "10c153e0-12e4-4dea-8748-4f34850ff76d",
  "zone": "fi-hel1"
}

Notes:

Please see service configured statuses and operational states description.

Create service

Creates a new network gateway service.

Request

POST /1.3/gateway HTTP/1.1

{
  "name": "example-gateway",
  "zone": "fi-hel1",
  "features": [
    "nat"
  ],
  "routers": [
    {
      "uuid": "0485d477-8d8f-4c97-9bef-731933187538"
    }
  ],
  "labels": [
    {
      "key":"env",
      "value":"testing"
    }
  ],
  "configured_status": "started"
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern `^[a-zA-Z0-9_-]+$`	yes	The name of the service must be unique within customer account.
features	An array of 1 or more gateway features.	yes	See Available features for support features.
zone	A valid zone identifier, e.g. `fi-hel1`	yes	Zone in which the service will be hosted, e.g. `fi-hel1`. Only public zones are supported currently.
routers	An array of 1 router object.	yes	Attached Routers from where traffic is routed towards the network gateway service.
configured_status	`started` / `stopped`	yes	Service status managed by the customer.
labels	An array of 1 or more label	no	See Label

NOTE: Only one router per network gateway is currently supported.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
409 Conflict	DUPLICATE_RESOURCE	Service for router already exists.

Replace service

Replaces an existing network gateway service by given {service_uuid}

Request

PUT /1.3/gateway/{service_uuid} HTTP/1.1

{
  "name": "example-gateway",
  "configured_status": "started"
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern `^[a-zA-Z0-9_-]+$`	yes	The name of the service must be unique within customer account.
configured_status	`started` / `stopped`	yes	Service status managed by the customer.
labels	An array of 1 or more label	no	See Label

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.
409 Conflict	DUPLICATE_RESOURCE	Service for router already exists.

Modify service

Modifies an existing network gateway service by given {service_uuid}.

Request

PATCH /1.3/gateway/{service_uuid} HTTP/1.1

{
  "name": "example-gateway",
  "configured_status": "started",
  "labels": [
    {
      "key": "env",
      "value": "testing"
    }
  ]
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern `^[a-zA-Z0-9_-]+$`	no	The name of the service must be unique within customer account.
configured_status	`started` / `stopped`	no	Service status managed by the customer.
labels	An array of 1 or more label	no	See Label

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.

Delete service

Deletes an existing network gateway service by given {service_uuid}.

Request

DELETE /1.3/gateway/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.

Create service label

Creates a new label by given {service_uuid}.

Labels used for service filtering.

Service labels usage examples

Below are some examples of what certain GET requests might look like.

exact match: GET /1.3/gateway?label=env%3Dstaging
existence: GET /1.3/gateway?label=env
multiple: GET /1.3/gateway?label=env&label=foo%3Dbar

POST /1.3/gateway/{service_uuid}/labels HTTP/1.1

{
    "key": "foo",
    "value": "bar"
}

Attributes

Attribute	Accepted value	Required	Description
key	2-32 characters, regexp pattern `^([a-zA-Z0-9])+([a-zA-Z0-9_-])*$`	yes	Represents the label identifier. The key is unique within a service.
value	0-255 characters, regexp pattern `\A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z`	yes	Represents the label value.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.

List service labels

Returns a list of available service labels by given {service_uuid}.

Request

GET /1.3/gateway/{service_uuid}/labels HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
    {
        "key": "env",
        "value": "staging"
    },
    {
        "key": "foo",
        "value": "bar"
    }
]

Get service label details

Returns label details by given {service_uuid} and {key}.

Request

GET /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
    "key": "env",
    "value": "staging"  
}

Modify service label

Modifies existing label by given {service_uuid} and {key}.

Request

PATCH /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

{
    "key": "env",
    "value": "production"
}

Attributes

Attribute	Accepted value	Required	Description
key	2-32 characters, regexp pattern `^([a-zA-Z0-9])+([a-zA-Z0-9_-])*$`	no	Represents the label identifier. The key is unique within a service.
value	0-255 characters, regexp pattern `\A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z` / `null`	no	Represents the label value.

Normal response

HTTP/1.1 200 OK

Delete service label

Deletes existing label by given {service_uuid} and {key}.

Request

DELETE /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	Resource not found.

Routers

List of router objects should be provided on service create and cannot be changed later. This

Currently, only one router per network gateway is supported.

Attributes

Attribute	Accepted value	Required	Description
uuid	A valid router identifier in UUID format	yes	Router that will be attached to this network gateway service.

Service configured status

The service configured status indicates the service's current intended status. Managed by the customer.

Status	Description
started	The service is running.
stopped	The service is stopped.

Service operational state

The service operational state indicates the service's current operational, effective state. Managed by the system.

State	Description
pending	Indicates newly created service or started reconfiguration.
setup-agent	Configuring management tool.
setup-link-network	Configuring the networking between router and gateway.
setup-server	Configuring gateway nodes.
setup-network	Configuring network.
setup-gw	Configuring gateway.
setup-dns	Updating DNS records.
checkup	Verifying the gateway is correctly configured and running.
running	Indicates service up and running.
delete-dns	Removing DNS records.
delete-network	Reconfiguring network.
delete-server	Deleting gateway nodes.
delete-link-network	Deleting the networking between router and gateway.
delete-service	Deleting the service.