Public IPs (NetworkIP)

API: Stable

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 useCommon
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

API: Stable Auth: Users

Browses the catalog of available resources

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

retrieve

API: Stable Auth: Users

Retrieve a single resource

Request Response Error
ResourceRetrieveRequest<NetworkIPFlags> NetworkIP CommonErrorMessage

retrieveProducts

API: Stable Auth: Users

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.

See also:

create

API: Stable Auth: Users

Creates one or more resources

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

delete

API: Stable Auth: Users

Deletes one or more resources

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

init

API: Stable Auth: Users

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

API: Stable Auth: Users

Updates the ACL attached to a resource

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

updateFirewall

API: Stable Auth: Users

Request Response Error
BulkRequest<FirewallAndId> Unit CommonErrorMessage

Data Models

FirewallAndId

API: Stable

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

IPProtocol

API: Stable

enum class IPProtocol {
    TCP,
    UDP,
}
Properties
TCP
UDP

NetworkIP

API: Stable

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?

API: Internal/Beta


NetworkIPFlags

API: Stable

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

API: Stable

data class NetworkIPSpecification(
    val product: ProductReference,
    val firewall: NetworkIPSpecification.Firewall?,
)
Properties
product: ProductReference The product used for the `NetworkIP`
firewall: NetworkIPSpecification.Firewall?

NetworkIPSpecification.Firewall

API: Stable

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

NetworkIPState

API: Stable

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

API: Stable

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

API: Stable

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

NetworkIPSupport.Firewall

API: Stable

data class Firewall(
    val enabled: Boolean?,
)
Properties
enabled: Boolean?

NetworkIPUpdate

API: Stable

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

API: Stable

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