ips

UCloud Developer Guide / Orchestration of Resources / Compute / Public IPs (NetworkIP)

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.

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Create and configure firewall

Frequency of use Common

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

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

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

ResourceBrowseRequest<NetworkIPFlags>

PageV2<NetworkIP>

CommonErrorMessage

`retrieve`

Retrieve a single resource

Request Response Error

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

ResourceRetrieveRequest<NetworkIPFlags>

NetworkIP

CommonErrorMessage

`retrieveProducts`

Retrieve product support for all accessible providers

Request Response Error

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

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

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

ResourceSearchRequest<NetworkIPFlags>

PageV2<NetworkIP>

CommonErrorMessage

`create`

Creates one or more resources

Request Response Error

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

BulkRequest<NetworkIPSpecification>

BulkResponse<FindByStringId>

CommonErrorMessage

`delete`

Deletes one or more resources

Request Response Error

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

BulkRequest<FindByStringId>

BulkResponse<Unit>

CommonErrorMessage

`init`

Request (potential) initialization of resources

Request Response Error

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

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

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

BulkRequest<UpdatedAcl>

BulkResponse<Unit>

CommonErrorMessage

`updateFirewall`

Request Response Error

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

BulkRequest<FirewallAndId>

Unit

CommonErrorMessage

Data Models

`FirewallAndId`

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

Properties

`IPProtocol`

enum class IPProtocol {
    TCP,
    UDP,
}

Properties

`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

`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

`NetworkIPSpecification`

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

Properties

`NetworkIPSpecification.Firewall`

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

Properties

`NetworkIPState`

enum class NetworkIPState {
    PREPARING,
    READY,
    UNAVAILABLE,
}

Properties

`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

`NetworkIPSupport`

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

Properties

`NetworkIPSupport.Firewall`

data class Firewall(
    val enabled: Boolean?,
)

Properties

`NetworkIPUpdate`

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

Properties

`PortRangeAndProto`

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

Properties

Previousingress Nextjobs

Last updated 6 days ago

SDUCloud

ips

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`