Public IPs (NetworkIP)¶

Network IPs grant users access to an IP address resource.

Rationale¶

📝 NOTE: This API follows the standard Resources API. We recommend that you have already read and understood the concepts described here.

IPs are used in combination with Jobs. This will attach an IP address to the compute resource. For example, on a virtual machine, this might add a new network interface with the IP address.

It is not a strict requirement that the IP address is visible inside the compute environment. However, it is required that users can access the services exposed by a Job through this API.

If the firewall feature is supported by the provider, then users must define which ports are expected to be in use by the Job. If the firewall feature is not supported, then all ports must be open by default or managed from within the compute environment. For example, the firewall feature is not supported if the firewall is controlled by the virtual machine.

Table of Contents¶

1. Examples

Description
Create and configure firewall

2. Remote Procedure Calls

Name	Description
`browse`	Browses the catalog of available resources
`retrieve`	Retrieve a single resource
`retrieveProducts`	Retrieve product support for all accessible providers
`search`	Searches the catalog of available resources
`create`	Creates one or more resources
`delete`	Deletes one or more resources
`init`	Request (potential) initialization of resources
`updateAcl`	Updates the ACL attached to a resource
`updateFirewall`	No description

3. Data Models

Name	Description
`FirewallAndId`	No description
`IPProtocol`	No description
`NetworkIP`	A `NetworkIP` for use in `Job`s
`NetworkIPFlags`	No description
`NetworkIPSpecification`	No description
`NetworkIPSpecification.Firewall`	No description
`NetworkIPState`	No description
`NetworkIPStatus`	The status of an `NetworkIP`
`NetworkIPSupport`	No description
`NetworkIPSupport.Firewall`	No description
`NetworkIPUpdate`	No description
`PortRangeAndProto`	No description

Example: Create and configure firewall¶

Frequency of use	Common
Actors	An authenticated user (`user`)

Communication Flow: Kotlin

/* In this example we will see how to create and manage a public IP address */

NetworkIPs.retrieveProducts.call(
    Unit,
    user
).orThrow()

/*
SupportByProvider(
    productsByProvider = mapOf("example" to listOf(ResolvedSupport(
        product = Product.NetworkIP(
            allowAllocationRequestsFrom = AllocationRequestsGroup.ALL, 
            category = ProductCategoryId(
                id = "example-id", 
                name = "example-id", 
                provider = "example", 
            ), 
            chargeType = ChargeType.ABSOLUTE, 
            description = "A public IP address", 
            freeToUse = false, 
            hiddenInGrantApplications = false, 
            name = "example-ip", 
            pricePerUnit = 1, 
            priority = 0, 
            productType = ProductType.NETWORK_IP, 
            unitOfPrice = ProductPriceUnit.PER_UNIT, 
            version = 1, 
            balance = null, 
            id = "example-ip", 
            maxUsableBalance = null, 
        ), 
        support = NetworkIPSupport(
            firewall = NetworkIPSupport.Firewall(
                enabled = true, 
            ), 
            maintenance = null, 
            product = ProductReference(
                category = "example-ip", 
                id = "example-ip", 
                provider = "example", 
            ), 
        ), 
    ))), 
)
*/

/* We have a single product available to us. It supports the firewall feature. */

NetworkIPs.create.call(
    bulkRequestOf(NetworkIPSpecification(
        firewall = NetworkIPSpecification.Firewall(
            openPorts = listOf(PortRangeAndProto(
                end = 1100, 
                protocol = IPProtocol.TCP, 
                start = 1000, 
            )), 
        ), 
        product = ProductReference(
            category = "example-ip", 
            id = "example-ip", 
            provider = "example", 
        ), 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FindByStringId(
        id = "5123", 
    )), 
)
*/

/* The IP address has been created and has ID 5123 */


/* Updating the firewall causes existing ports to be removed. */

NetworkIPs.updateFirewall.call(
    bulkRequestOf(FirewallAndId(
        firewall = NetworkIPSpecification.Firewall(
            openPorts = listOf(PortRangeAndProto(
                end = 80, 
                protocol = IPProtocol.TCP, 
                start = 80, 
            )), 
        ), 
        id = "5123", 
    )),
    user
).orThrow()

/*
Unit
*/

/* We can read the current state by retrieving the resource */

NetworkIPs.retrieve.call(
    ResourceRetrieveRequest(
        flags = NetworkIPFlags(
            filterCreatedAfter = null, 
            filterCreatedBefore = null, 
            filterCreatedBy = null, 
            filterIds = null, 
            filterProductCategory = null, 
            filterProductId = null, 
            filterProvider = null, 
            filterProviderIds = null, 
            filterState = null, 
            hideProductCategory = null, 
            hideProductId = null, 
            hideProvider = null, 
            includeOthers = false, 
            includeProduct = false, 
            includeSupport = false, 
            includeUpdates = false, 
        ), 
        id = "5123", 
    ),
    user
).orThrow()

/*
NetworkIP(
    createdAt = 1635170395571, 
    id = "5123", 
    owner = ResourceOwner(
        createdBy = "user", 
        project = null, 
    ), 
    permissions = null, 
    resolvedProduct = null, 
    specification = NetworkIPSpecification(
        firewall = NetworkIPSpecification.Firewall(
            openPorts = listOf(PortRangeAndProto(
                end = 80, 
                protocol = IPProtocol.TCP, 
                start = 80, 
            )), 
        ), 
        product = ProductReference(
            category = "example-ip", 
            id = "example-ip", 
            provider = "example", 
        ), 
    ), 
    status = NetworkIPStatus(
        boundTo = emptyList(), 
        ipAddress = null, 
        resolvedProduct = null, 
        resolvedSupport = null, 
        state = NetworkIPState.READY, 
    ), 
    updates = emptyList(), 
    providerGeneratedId = "5123", 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# In this example we will see how to create and manage a public IP address

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/networkips/retrieveProducts" 

# {
#     "productsByProvider": {
#         "example": [
#             {
#                 "product": {
#                     "balance": null,
#                     "maxUsableBalance": null,
#                     "name": "example-ip",
#                     "pricePerUnit": 1,
#                     "category": {
#                         "name": "example-id",
#                         "provider": "example"
#                     },
#                     "description": "A public IP address",
#                     "priority": 0,
#                     "version": 1,
#                     "freeToUse": false,
#                     "allowAllocationRequestsFrom": "ALL",
#                     "unitOfPrice": "PER_UNIT",
#                     "chargeType": "ABSOLUTE",
#                     "hiddenInGrantApplications": false,
#                     "productType": "NETWORK_IP"
#                 },
#                 "support": {
#                     "product": {
#                         "id": "example-ip",
#                         "category": "example-ip",
#                         "provider": "example"
#                     },
#                     "firewall": {
#                         "enabled": true
#                     },
#                     "maintenance": null
#                 }
#             }
#         ]
#     }
# }

# We have a single product available to us. It supports the firewall feature.

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/networkips" -d '{
    "items": [
        {
            "product": {
                "id": "example-ip",
                "category": "example-ip",
                "provider": "example"
            },
            "firewall": {
                "openPorts": [
                    {
                        "start": 1000,
                        "end": 1100,
                        "protocol": "TCP"
                    }
                ]
            }
        }
    ]
}'


# {
#     "responses": [
#         {
#             "id": "5123"
#         }
#     ]
# }

# The IP address has been created and has ID 5123

# Updating the firewall causes existing ports to be removed.

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/networkips/firewall" -d '{
    "items": [
        {
            "id": "5123",
            "firewall": {
                "openPorts": [
                    {
                        "start": 80,
                        "end": 80,
                        "protocol": "TCP"
                    }
                ]
            }
        }
    ]
}'


# {
# }

# We can read the current state by retrieving the resource

curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/networkips/retrieve?includeOthers=false&includeUpdates=false&includeSupport=false&includeProduct=false&id=5123" 

# {
#     "id": "5123",
#     "specification": {
#         "product": {
#             "id": "example-ip",
#             "category": "example-ip",
#             "provider": "example"
#         },
#         "firewall": {
#             "openPorts": [
#                 {
#                     "start": 80,
#                     "end": 80,
#                     "protocol": "TCP"
#                 }
#             ]
#         }
#     },
#     "owner": {
#         "createdBy": "user",
#         "project": null
#     },
#     "createdAt": 1635170395571,
#     "status": {
#         "state": "READY",
#         "boundTo": [
#         ],
#         "ipAddress": null,
#         "resolvedSupport": null,
#         "resolvedProduct": null
#     },
#     "updates": [
#     ],
#     "resolvedProduct": null,
#     "permissions": null
# }

Communication Flow: Visual

Remote Procedure Calls¶

`browse`¶

Browses the catalog of available resources

Request	Response	Error
`ResourceBrowseRequest<NetworkIPFlags>`	`PageV2<NetworkIP>`	`CommonErrorMessage`

`retrieve`¶

Retrieve a single resource

Request	Response	Error
`ResourceRetrieveRequest<NetworkIPFlags>`	`NetworkIP`	`CommonErrorMessage`

`retrieveProducts`¶

Retrieve product support for all accessible providers

Request	Response	Error
`Unit`	`SupportByProvider<Product.NetworkIP, NetworkIPSupport>`	`CommonErrorMessage`

This endpoint will determine all providers that which the authenticated user has access to, in the current workspace. A user has access to a product, and thus a provider, if the product is either free or if the user has been granted credits to use the product.

`search`¶

Searches the catalog of available resources

Request	Response	Error
`ResourceSearchRequest<NetworkIPFlags>`	`PageV2<NetworkIP>`	`CommonErrorMessage`

`create`¶

Creates one or more resources

Request	Response	Error
`BulkRequest<NetworkIPSpecification>`	`BulkResponse<FindByStringId>`	`CommonErrorMessage`

`delete`¶

Deletes one or more resources

Request	Response	Error
`BulkRequest<FindByStringId>`	`BulkResponse<Unit>`	`CommonErrorMessage`

`init`¶

Request (potential) initialization of resources

Request	Response	Error
`Unit`	`Unit`	`CommonErrorMessage`

This request is sent by the client, if the client believes that initialization of resources might be needed. NOTE: This request might be sent even if initialization has already taken place. UCloud/Core does not check if initialization has already taken place, it simply validates the request.

`updateAcl`¶

Updates the ACL attached to a resource

Request	Response	Error
`BulkRequest<UpdatedAcl>`	`BulkResponse<Unit>`	`CommonErrorMessage`

`updateFirewall`¶

Request	Response	Error
`BulkRequest<FirewallAndId>`	`Unit`	`CommonErrorMessage`

Data Models¶

`FirewallAndId`¶

data class FirewallAndId(
    val id: String,
    val firewall: NetworkIPSpecification.Firewall,
)

Properties

id: String

firewall: NetworkIPSpecification.Firewall

`IPProtocol`¶

enum class IPProtocol {
    TCP,
    UDP,
}

Properties

TCP

UDP

`NetworkIP`¶

A NetworkIP for use in Jobs

data class NetworkIP(
    val id: String,
    val specification: NetworkIPSpecification,
    val owner: ResourceOwner,
    val createdAt: Long,
    val status: NetworkIPStatus,
    val updates: List<NetworkIPUpdate>?,
    val resolvedProduct: Product.NetworkIP?,
    val permissions: ResourcePermissions?,
    val providerGeneratedId: String?,
)

Properties

id: String A unique identifier referencing the `Resource`

The ID is unique across a provider for a single resource type.

specification: NetworkIPSpecification

owner: ResourceOwner Information about the owner of this resource

createdAt: Long Information about when this resource was created

status: NetworkIPStatus The current status of this resource

updates: List<NetworkIPUpdate>? A list of updates for this `NetworkIP`

resolvedProduct: Product.NetworkIP?

permissions: ResourcePermissions? Permissions assigned to this resource

A null value indicates that permissions are not supported by this resource type.

providerGeneratedId: String?

`NetworkIPFlags`¶

data class NetworkIPFlags(
    val filterState: NetworkIPState?,
    val includeOthers: Boolean?,
    val includeUpdates: Boolean?,
    val includeSupport: Boolean?,
    val includeProduct: Boolean?,
    val filterCreatedBy: String?,
    val filterCreatedAfter: Long?,
    val filterCreatedBefore: Long?,
    val filterProvider: String?,
    val filterProductId: String?,
    val filterProductCategory: String?,
    val filterProviderIds: String?,
    val filterIds: String?,
    val hideProductId: String?,
    val hideProductCategory: String?,
    val hideProvider: String?,
)

Properties

filterState: NetworkIPState?

includeOthers: Boolean?

includeUpdates: Boolean?

includeSupport: Boolean?

includeProduct: Boolean? Includes `specification.resolvedProduct`

filterCreatedBy: String?

filterCreatedAfter: Long?

filterCreatedBefore: Long?

filterProvider: String?

filterProductId: String?

filterProductCategory: String?

filterProviderIds: String? Filters by the provider ID. The value is comma-separated.

filterIds: String? Filters by the resource ID. The value is comma-separated.

hideProductId: String?

hideProductCategory: String?

hideProvider: String?

`NetworkIPSpecification`¶

data class NetworkIPSpecification(
    val product: ProductReference,
    val firewall: NetworkIPSpecification.Firewall?,
)

Properties

product: ProductReference The product used for the `NetworkIP`

firewall: NetworkIPSpecification.Firewall?

`NetworkIPSpecification.Firewall`¶

data class Firewall(
    val openPorts: List<PortRangeAndProto>?,
)

Properties

openPorts: List<PortRangeAndProto>?

`NetworkIPState`¶

enum class NetworkIPState {
    PREPARING,
    READY,
    UNAVAILABLE,
}

Properties

PREPARING A state indicating that the `NetworkIP` is currently being prepared and is expected to reach `READY` soon.

READY A state indicating that the `NetworkIP` is ready for use or already in use.

UNAVAILABLE A state indicating that the `NetworkIP` is currently unavailable.

This state can be used to indicate downtime or service interruptions by the provider.

`NetworkIPStatus`¶

The status of an NetworkIP

data class NetworkIPStatus(
    val state: NetworkIPState,
    val boundTo: List<String>?,
    val ipAddress: String?,
    val resolvedSupport: ResolvedSupport<Product.NetworkIP, NetworkIPSupport>?,
    val resolvedProduct: Product.NetworkIP?,
)

Properties

state: NetworkIPState

boundTo: List<String>? The ID of the `Job` that this `NetworkIP` is currently bound to

ipAddress: String? The externally accessible IP address allocated to this `NetworkIP`

resolvedSupport: ResolvedSupport<Product.NetworkIP, NetworkIPSupport>?

resolvedProduct: Product.NetworkIP? The resolved product referenced by `product`.

This attribute is not included by default unless includeProduct is specified.

`NetworkIPSupport`¶

data class NetworkIPSupport(
    val product: ProductReference,
    val firewall: NetworkIPSupport.Firewall?,
    val maintenance: Maintenance?,
)

Properties

product: ProductReference

firewall: NetworkIPSupport.Firewall?

maintenance: Maintenance?

`NetworkIPSupport.Firewall`¶

data class Firewall(
    val enabled: Boolean?,
)

Properties

enabled: Boolean?

`NetworkIPUpdate`¶

data class NetworkIPUpdate(
    val timestamp: Long?,
    val state: NetworkIPState?,
    val status: String?,
    val changeIpAddress: Boolean?,
    val newIpAddress: String?,
    val binding: JobBinding?,
)

Properties

timestamp: Long? A timestamp for when this update was registered by UCloud

state: NetworkIPState? The new state that the `NetworkIP` transitioned to (if any)

status: String? A new status message for the `NetworkIP` (if any)

changeIpAddress: Boolean?

newIpAddress: String?

binding: JobBinding?

`PortRangeAndProto`¶

data class PortRangeAndProto(
    val start: Int,
    val end: Int,
    val protocol: IPProtocol,
)

Properties

start: Int

end: Int

protocol: IPProtocol

Public IPs (NetworkIP)¶

Rationale¶

Table of Contents¶

Example: Create and configure firewall¶

Remote Procedure Calls¶

browse¶

retrieve¶

retrieveProducts¶

search¶

create¶

delete¶

init¶

updateAcl¶

updateFirewall¶

Data Models¶

FirewallAndId¶

IPProtocol¶

NetworkIP¶

NetworkIPFlags¶

NetworkIPSpecification¶

NetworkIPSpecification.Firewall¶

NetworkIPState¶

NetworkIPStatus¶

NetworkIPSupport¶

NetworkIPSupport.Firewall¶

NetworkIPUpdate¶

PortRangeAndProto¶

`browse`¶

`retrieve`¶

`retrieveProducts`¶

`search`¶

`create`¶

`delete`¶

`init`¶

`updateAcl`¶

`updateFirewall`¶

`FirewallAndId`¶

`IPProtocol`¶

`NetworkIP`¶

`NetworkIPFlags`¶

`NetworkIPSpecification`¶

`NetworkIPSpecification.Firewall`¶

`NetworkIPState`¶

`NetworkIPStatus`¶

`NetworkIPSupport`¶

`NetworkIPSupport.Firewall`¶

`NetworkIPUpdate`¶

`PortRangeAndProto`¶