[client, management] Add port forwarding (#3275)

Add initial support to ingress ports on the client code.

- new types where added
- new protocol messages and controller
This commit is contained in:
Viktor Liu
2025-03-09 16:06:43 +01:00
committed by GitHub
parent ae6b61301c
commit fc1da94520
84 changed files with 4471 additions and 1196 deletions

View File

@@ -29,6 +29,9 @@ tags:
description: View information about the account and network events.
- name: Accounts
description: View information about the accounts.
- name: Ingress Ports
description: Interact with and view information about the ingress peers and ports.
x-cloud-only: true
components:
schemas:
Account:
@@ -1597,6 +1600,223 @@ components:
- initiator_email
- target_id
- meta
IngressPeerCreateRequest:
type: object
properties:
peer_id:
description: ID of the peer that is used as an ingress peer
type: string
example: ch8i4ug6lnn4g9hqv7m0
enabled:
description: Defines if an ingress peer is enabled
type: boolean
example: true
fallback:
description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
required:
- peer_id
- enabled
- fallback
IngressPeerUpdateRequest:
type: object
properties:
enabled:
description: Defines if an ingress peer is enabled
type: boolean
example: true
fallback:
description: Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
required:
- enabled
- fallback
IngressPeer:
type: object
properties:
id:
description: ID of the ingress peer
type: string
example: ch8i4ug6lnn4g9hqv7m0
peer_id:
description: ID of the peer that is used as an ingress peer
type: string
example: x7p3kqf2rdd8j5zxw4n9
ingress_ip:
description: Ingress IP address of the ingress peer where the traffic arrives
type: string
example: 192.34.0.123
available_ports:
$ref: '#/components/schemas/AvailablePorts'
enabled:
description: Indicates if an ingress peer is enabled
type: boolean
example: true
connected:
description: Indicates if an ingress peer is connected to the management server
type: boolean
example: true
fallback:
description: Indicates if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
type: boolean
example: true
region:
description: Region of the ingress peer
type: string
example: germany
required:
- id
- peer_id
- ingress_ip
- available_ports
- enabled
- connected
- fallback
- region
AvailablePorts:
type: object
properties:
tcp:
description: Number of available TCP ports left on the ingress peer
type: integer
example: 45765
udp:
description: Number of available UDP ports left on the ingress peer
type: integer
example: 50000
required:
- tcp
- udp
IngressPortAllocationRequest:
type: object
properties:
name:
description: Name of the ingress port allocation
type: string
example: Ingress Port Allocation 1
enabled:
description: Indicates if an ingress port allocation is enabled
type: boolean
example: true
port_ranges:
description: List of port ranges that are forwarded by the ingress peer
type: array
items:
$ref: '#/components/schemas/IngressPortAllocationRequestPortRange'
direct_port:
description: Direct port allocation
$ref: '#/components/schemas/IngressPortAllocationRequestDirectPort'
required:
- name
- enabled
IngressPortAllocationRequestPortRange:
type: object
properties:
start:
description: The starting port of the range of forwarded ports
type: integer
example: 80
end:
description: The ending port of the range of forwarded ports
type: integer
example: 320
protocol:
description: The protocol accepted by the port range
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: tcp
required:
- start
- end
- protocol
IngressPortAllocationRequestDirectPort:
type: object
properties:
count:
description: The number of ports to be forwarded
type: integer
example: 5
protocol:
description: The protocol accepted by the port
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: udp
required:
- count
- protocol
IngressPortAllocation:
type: object
properties:
id:
description: ID of the ingress port allocation
type: string
example: ch8i4ug6lnn4g9hqv7m0
name:
description: Name of the ingress port allocation
type: string
example: Ingress Peer Allocation 1
ingress_peer_id:
description: ID of the ingress peer that forwards the ports
type: string
example: x7p3kqf2rdd8j5zxw4n9
region:
description: Region of the ingress peer
type: string
example: germany
enabled:
description: Indicates if an ingress port allocation is enabled
type: boolean
example: true
ingress_ip:
description: Ingress IP address of the ingress peer where the traffic arrives
type: string
example:
port_range_mappings:
description: List of port ranges that are allowed to be used by the ingress peer
type: array
items:
$ref: '#/components/schemas/IngressPortAllocationPortMapping'
required:
- id
- name
- ingress_peer_id
- region
- enabled
- ingress_ip
- port_range_mappings
IngressPortAllocationPortMapping:
type: object
properties:
translated_start:
description: The starting port of the translated range of forwarded ports
type: integer
example: 80
translated_end:
description: The ending port of the translated range of forwarded ports
type: integer
example: 320
ingress_start:
description: The starting port of the range of ingress ports mapped to the forwarded ports
type: integer
example: 1080
ingress_end:
description: The ending port of the range of ingress ports mapped to the forwarded ports
type: integer
example: 1320
protocol:
description: Protocol accepted by the ports
type: string
enum: [ "tcp", "udp", "tcp/udp" ]
example: tcp
required:
- translated_start
- translated_end
- ingress_start
- ingress_end
- protocol
responses:
not_found:
description: Resource not found
@@ -2009,6 +2229,17 @@ paths:
summary: List all Peers
description: Returns a list of all peers
tags: [ Peers ]
parameters:
- in: query
name: name
schema:
type: string
description: Filter peers by name
- in: query
name: ip
schema:
type: string
description: Filter peers by IP address
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
@@ -2152,6 +2383,335 @@ paths:
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/ingress/ports:
get:
x-cloud-only: true
summary: List all Ingress Port Allocations for a Peer
description: Returns a list of all ingress port allocations for a peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: query
name: name
schema:
type: string
description: Filters ingress port allocations by name
responses:
'200':
description: A JSON Array of Ingress Port Allocations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
x-cloud-only: true
summary: Create a Ingress Port Allocation
description: Creates a new ingress port allocation for a peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
requestBody:
description: New Ingress Port Allocation request
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPortAllocationRequest'
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/peers/{peerId}/ingress/ports/{allocationId}:
get:
x-cloud-only: true
summary: Retrieve a Ingress Port Allocation
description: Get information about an ingress port allocation
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
x-cloud-only: true
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
requestBody:
description: update an ingress port allocation
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocationRequest'
responses:
'200':
description: A Ingress Port Allocation object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPortAllocation'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
x-cloud-only: true
summary: Delete a Ingress Port Allocation
description: Delete an ingress port allocation
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: peerId
required: true
schema:
type: string
description: The unique identifier of a peer
- in: path
name: allocationId
required: true
schema:
type: string
description: The unique identifier of an ingress port allocation
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/ingress/peers:
get:
x-cloud-only: true
summary: List all Ingress Peers
description: Returns a list of all ingress peers
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
responses:
'200':
description: A JSON Array of Ingress Peers
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
post:
x-cloud-only: true
summary: Create a Ingress Peer
description: Creates a new ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
requestBody:
description: New Ingress Peer request
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPeerCreateRequest'
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/ingress/peers/{ingressPeerId}:
get:
x-cloud-only: true
summary: Retrieve a Ingress Peer
description: Get information about an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
put:
x-cloud-only: true
summary: Update a Ingress Peer
description: Update information about an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
requestBody:
description: update an ingress peer
content:
'application/json':
schema:
$ref: '#/components/schemas/IngressPeerUpdateRequest'
responses:
'200':
description: A Ingress Peer object
content:
application/json:
schema:
$ref: '#/components/schemas/IngressPeer'
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
delete:
x-cloud-only: true
summary: Delete a Ingress Peer
description: Delete an ingress peer
tags: [ Ingress Ports ]
security:
- BearerAuth: [ ]
- TokenAuth: [ ]
parameters:
- in: path
name: ingressPeerId
required: true
schema:
type: string
description: The unique identifier of an ingress peer
responses:
'200':
description: Delete status code
content: { }
'400':
"$ref": "#/components/responses/bad_request"
'401':
"$ref": "#/components/responses/requires_authentication"
'403':
"$ref": "#/components/responses/forbidden"
'500':
"$ref": "#/components/responses/internal_error"
/api/setup-keys:
get:
summary: List all Setup Keys

View File

@@ -83,6 +83,27 @@ const (
GroupMinimumIssuedJwt GroupMinimumIssued = "jwt"
)
// Defines values for IngressPortAllocationPortMappingProtocol.
const (
IngressPortAllocationPortMappingProtocolTcp IngressPortAllocationPortMappingProtocol = "tcp"
IngressPortAllocationPortMappingProtocolTcpudp IngressPortAllocationPortMappingProtocol = "tcp/udp"
IngressPortAllocationPortMappingProtocolUdp IngressPortAllocationPortMappingProtocol = "udp"
)
// Defines values for IngressPortAllocationRequestDirectPortProtocol.
const (
IngressPortAllocationRequestDirectPortProtocolTcp IngressPortAllocationRequestDirectPortProtocol = "tcp"
IngressPortAllocationRequestDirectPortProtocolTcpudp IngressPortAllocationRequestDirectPortProtocol = "tcp/udp"
IngressPortAllocationRequestDirectPortProtocolUdp IngressPortAllocationRequestDirectPortProtocol = "udp"
)
// Defines values for IngressPortAllocationRequestPortRangeProtocol.
const (
IngressPortAllocationRequestPortRangeProtocolTcp IngressPortAllocationRequestPortRangeProtocol = "tcp"
IngressPortAllocationRequestPortRangeProtocolTcpudp IngressPortAllocationRequestPortRangeProtocol = "tcp/udp"
IngressPortAllocationRequestPortRangeProtocolUdp IngressPortAllocationRequestPortRangeProtocol = "udp"
)
// Defines values for NameserverNsType.
const (
NameserverNsTypeUdp NameserverNsType = "udp"
@@ -253,6 +274,15 @@ type AccountSettings struct {
RoutingPeerDnsResolutionEnabled *bool `json:"routing_peer_dns_resolution_enabled,omitempty"`
}
// AvailablePorts defines model for AvailablePorts.
type AvailablePorts struct {
// Tcp Number of available TCP ports left on the ingress peer
Tcp int `json:"tcp"`
// Udp Number of available UDP ports left on the ingress peer
Udp int `json:"udp"`
}
// Checks List of objects that perform the actual checks
type Checks struct {
// GeoLocationCheck Posture check for geo location
@@ -426,6 +456,139 @@ type GroupRequest struct {
Resources *[]Resource `json:"resources,omitempty"`
}
// IngressPeer defines model for IngressPeer.
type IngressPeer struct {
AvailablePorts AvailablePorts `json:"available_ports"`
// Connected Indicates if an ingress peer is connected to the management server
Connected bool `json:"connected"`
// Enabled Indicates if an ingress peer is enabled
Enabled bool `json:"enabled"`
// Fallback Indicates if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
Fallback bool `json:"fallback"`
// Id ID of the ingress peer
Id string `json:"id"`
// IngressIp Ingress IP address of the ingress peer where the traffic arrives
IngressIp string `json:"ingress_ip"`
// PeerId ID of the peer that is used as an ingress peer
PeerId string `json:"peer_id"`
// Region Region of the ingress peer
Region string `json:"region"`
}
// IngressPeerCreateRequest defines model for IngressPeerCreateRequest.
type IngressPeerCreateRequest struct {
// Enabled Defines if an ingress peer is enabled
Enabled bool `json:"enabled"`
// Fallback Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
Fallback bool `json:"fallback"`
// PeerId ID of the peer that is used as an ingress peer
PeerId string `json:"peer_id"`
}
// IngressPeerUpdateRequest defines model for IngressPeerUpdateRequest.
type IngressPeerUpdateRequest struct {
// Enabled Defines if an ingress peer is enabled
Enabled bool `json:"enabled"`
// Fallback Defines if an ingress peer can be used as a fallback if no ingress peer can be found in the region of the forwarded peer
Fallback bool `json:"fallback"`
}
// IngressPortAllocation defines model for IngressPortAllocation.
type IngressPortAllocation struct {
// Enabled Indicates if an ingress port allocation is enabled
Enabled bool `json:"enabled"`
// Id ID of the ingress port allocation
Id string `json:"id"`
// IngressIp Ingress IP address of the ingress peer where the traffic arrives
IngressIp string `json:"ingress_ip"`
// IngressPeerId ID of the ingress peer that forwards the ports
IngressPeerId string `json:"ingress_peer_id"`
// Name Name of the ingress port allocation
Name string `json:"name"`
// PortRangeMappings List of port ranges that are allowed to be used by the ingress peer
PortRangeMappings []IngressPortAllocationPortMapping `json:"port_range_mappings"`
// Region Region of the ingress peer
Region string `json:"region"`
}
// IngressPortAllocationPortMapping defines model for IngressPortAllocationPortMapping.
type IngressPortAllocationPortMapping struct {
// IngressEnd The ending port of the range of ingress ports mapped to the forwarded ports
IngressEnd int `json:"ingress_end"`
// IngressStart The starting port of the range of ingress ports mapped to the forwarded ports
IngressStart int `json:"ingress_start"`
// Protocol Protocol accepted by the ports
Protocol IngressPortAllocationPortMappingProtocol `json:"protocol"`
// TranslatedEnd The ending port of the translated range of forwarded ports
TranslatedEnd int `json:"translated_end"`
// TranslatedStart The starting port of the translated range of forwarded ports
TranslatedStart int `json:"translated_start"`
}
// IngressPortAllocationPortMappingProtocol Protocol accepted by the ports
type IngressPortAllocationPortMappingProtocol string
// IngressPortAllocationRequest defines model for IngressPortAllocationRequest.
type IngressPortAllocationRequest struct {
DirectPort *IngressPortAllocationRequestDirectPort `json:"direct_port,omitempty"`
// Enabled Indicates if an ingress port allocation is enabled
Enabled bool `json:"enabled"`
// Name Name of the ingress port allocation
Name string `json:"name"`
// PortRanges List of port ranges that are forwarded by the ingress peer
PortRanges *[]IngressPortAllocationRequestPortRange `json:"port_ranges,omitempty"`
}
// IngressPortAllocationRequestDirectPort defines model for IngressPortAllocationRequestDirectPort.
type IngressPortAllocationRequestDirectPort struct {
// Count The number of ports to be forwarded
Count int `json:"count"`
// Protocol The protocol accepted by the port
Protocol IngressPortAllocationRequestDirectPortProtocol `json:"protocol"`
}
// IngressPortAllocationRequestDirectPortProtocol The protocol accepted by the port
type IngressPortAllocationRequestDirectPortProtocol string
// IngressPortAllocationRequestPortRange defines model for IngressPortAllocationRequestPortRange.
type IngressPortAllocationRequestPortRange struct {
// End The ending port of the range of forwarded ports
End int `json:"end"`
// Protocol The protocol accepted by the port range
Protocol IngressPortAllocationRequestPortRangeProtocol `json:"protocol"`
// Start The starting port of the range of forwarded ports
Start int `json:"start"`
}
// IngressPortAllocationRequestPortRangeProtocol The protocol accepted by the port range
type IngressPortAllocationRequestPortRangeProtocol string
// Location Describe geographical location information
type Location struct {
// CityName Commonly used English name of the city
@@ -1466,6 +1629,21 @@ type UserRequest struct {
Role string `json:"role"`
}
// GetApiPeersParams defines parameters for GetApiPeers.
type GetApiPeersParams struct {
// Name Filter peers by name
Name *string `form:"name,omitempty" json:"name,omitempty"`
// Ip Filter peers by IP address
Ip *string `form:"ip,omitempty" json:"ip,omitempty"`
}
// GetApiPeersPeerIdIngressPortsParams defines parameters for GetApiPeersPeerIdIngressPorts.
type GetApiPeersPeerIdIngressPortsParams struct {
// Name Filters ingress port allocations by name
Name *string `form:"name,omitempty" json:"name,omitempty"`
}
// GetApiUsersParams defines parameters for GetApiUsers.
type GetApiUsersParams struct {
// ServiceUser Filters users and returns either regular users or service users
@@ -1490,6 +1668,12 @@ type PostApiGroupsJSONRequestBody = GroupRequest
// PutApiGroupsGroupIdJSONRequestBody defines body for PutApiGroupsGroupId for application/json ContentType.
type PutApiGroupsGroupIdJSONRequestBody = GroupRequest
// PostApiIngressPeersJSONRequestBody defines body for PostApiIngressPeers for application/json ContentType.
type PostApiIngressPeersJSONRequestBody = IngressPeerCreateRequest
// PutApiIngressPeersIngressPeerIdJSONRequestBody defines body for PutApiIngressPeersIngressPeerId for application/json ContentType.
type PutApiIngressPeersIngressPeerIdJSONRequestBody = IngressPeerUpdateRequest
// PostApiNetworksJSONRequestBody defines body for PostApiNetworks for application/json ContentType.
type PostApiNetworksJSONRequestBody = NetworkRequest
@@ -1511,6 +1695,12 @@ type PutApiNetworksNetworkIdRoutersRouterIdJSONRequestBody = NetworkRouterReques
// PutApiPeersPeerIdJSONRequestBody defines body for PutApiPeersPeerId for application/json ContentType.
type PutApiPeersPeerIdJSONRequestBody = PeerRequest
// PostApiPeersPeerIdIngressPortsJSONRequestBody defines body for PostApiPeersPeerIdIngressPorts for application/json ContentType.
type PostApiPeersPeerIdIngressPortsJSONRequestBody = IngressPortAllocationRequest
// PutApiPeersPeerIdIngressPortsAllocationIdJSONRequestBody defines body for PutApiPeersPeerIdIngressPortsAllocationId for application/json ContentType.
type PutApiPeersPeerIdIngressPortsAllocationIdJSONRequestBody = IngressPortAllocationRequest
// PostApiPoliciesJSONRequestBody defines body for PostApiPolicies for application/json ContentType.
type PostApiPoliciesJSONRequestBody = PolicyUpdate