ingress

« Previous section Next section »

UCloud Developer Guide / Orchestration of Resources / Compute / Public Links (Ingress)

Public Links (Ingress)

Ingresses provide a way to attach custom links to interactive web-interfaces.

Rationale

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

---

When an interactive (web) application runs, it typically uses a provider generated URL. The ingress feature allows providers to give access to these Jobs through a custom URL.

Table of Contents

1. Examples

2. Remote Procedure Calls

3. Data Models

Example: Create and configure an Ingress

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

/* In this example, we will see how to create and manage an ingress */

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

/*
SupportByProvider(
    productsByProvider = mapOf("example" to listOf(ResolvedSupport(
        product = Product.Ingress(
            allowAllocationRequestsFrom = AllocationRequestsGroup.ALL, 
            category = ProductCategoryId(
                id = "example-ingress", 
                name = "example-ingress", 
                provider = "example-ingress", 
            ), 
            chargeType = ChargeType.ABSOLUTE, 
            description = "An example ingress", 
            freeToUse = false, 
            hiddenInGrantApplications = false, 
            name = "example-ingress", 
            pricePerUnit = 1, 
            priority = 0, 
            productType = ProductType.INGRESS, 
            unitOfPrice = ProductPriceUnit.PER_UNIT, 
            version = 1, 
            balance = null, 
            id = "example-ingress", 
            maxUsableBalance = null, 
        ), 
        support = IngressSupport(
            domainPrefix = "app-", 
            domainSuffix = ".example.com", 
            maintenance = null, 
            product = ProductReference(
                category = "example-ingress", 
                id = "example-ingress", 
                provider = "example", 
            ), 
        ), 
    ))), 
)
*/

/* We have a single product available. This product requires that all ingresses start with "app-" and 
ends with ".example.com" */


/* 📝 NOTE: Providers can perform additional validation. For example, must providers won't support 
arbitrary levels of sub-domains. That is, must providers would reject the value 
app-this.is.not.what.we.want.example.com. */

Ingresses.create.call(
    bulkRequestOf(IngressSpecification(
        domain = "app-mylink.example.com", 
        product = ProductReference(
            category = "example-ingress", 
            id = "example-ingress", 
            provider = "example", 
        ), 
    )),
    user
).orThrow()

/*
BulkResponse(
    responses = listOf(FindByStringId(
        id = "5127", 
    )), 
)
*/
Ingresses.retrieve.call(
    ResourceRetrieveRequest(
        flags = IngressIncludeFlags(
            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 = "5127", 
    ),
    user
).orThrow()

/*
Ingress(
    createdAt = 1635170395571, 
    id = "5127", 
    owner = ResourceOwner(
        createdBy = "user", 
        project = null, 
    ), 
    permissions = null, 
    specification = IngressSpecification(
        domain = "app-mylink.example.com", 
        product = ProductReference(
            category = "example-ingress", 
            id = "example-ingress", 
            provider = "example", 
        ), 
    ), 
    status = IngressStatus(
        boundTo = emptyList(), 
        resolvedProduct = null, 
        resolvedSupport = null, 
        state = IngressState.READY, 
    ), 
    updates = emptyList(), 
    providerGeneratedId = "5127", 
)
*/

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 an ingress

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

# {
#     "productsByProvider": {
#         "example": [
#             {
#                 "product": {
#                     "balance": null,
#                     "maxUsableBalance": null,
#                     "name": "example-ingress",
#                     "pricePerUnit": 1,
#                     "category": {
#                         "name": "example-ingress",
#                         "provider": "example-ingress"
#                     },
#                     "description": "An example ingress",
#                     "priority": 0,
#                     "version": 1,
#                     "freeToUse": false,
#                     "allowAllocationRequestsFrom": "ALL",
#                     "unitOfPrice": "PER_UNIT",
#                     "chargeType": "ABSOLUTE",
#                     "hiddenInGrantApplications": false,
#                     "productType": "INGRESS"
#                 },
#                 "support": {
#                     "domainPrefix": "app-",
#                     "domainSuffix": ".example.com",
#                     "product": {
#                         "id": "example-ingress",
#                         "category": "example-ingress",
#                         "provider": "example"
#                     },
#                     "maintenance": null
#                 }
#             }
#         ]
#     }
# }

# We have a single product available. This product requires that all ingresses start with "app-" and 
# ends with ".example.com"

# 📝 NOTE: Providers can perform additional validation. For example, must providers won't support 
# arbitrary levels of sub-domains. That is, must providers would reject the value 
# app-this.is.not.what.we.want.example.com.

curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/ingresses" -d '{
    "items": [
        {
            "domain": "app-mylink.example.com",
            "product": {
                "id": "example-ingress",
                "category": "example-ingress",
                "provider": "example"
            }
        }
    ]
}'


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

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

# {
#     "id": "5127",
#     "specification": {
#         "domain": "app-mylink.example.com",
#         "product": {
#             "id": "example-ingress",
#             "category": "example-ingress",
#             "provider": "example"
#         }
#     },
#     "owner": {
#         "createdBy": "user",
#         "project": null
#     },
#     "createdAt": 1635170395571,
#     "status": {
#         "boundTo": [
#         ],
#         "state": "READY",
#         "resolvedSupport": null,
#         "resolvedProduct": null
#     },
#     "updates": [
#     ],
#     "permissions": null
# }

Communication Flow: Visual

Remote Procedure Calls

browse

Browses the catalog of available resources

Request	Response	Error
ResourceBrowseRequest<IngressIncludeFlags>	PageV2<Ingress>	CommonErrorMessage

retrieve

Retrieve a single resource

Request	Response	Error
ResourceRetrieveRequest<IngressIncludeFlags>	Ingress	CommonErrorMessage

retrieveProducts

Retrieve product support for all accessible providers

Request	Response	Error
Unit	SupportByProvider<Product.Ingress, IngressSupport>	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:

• Product

• Grants

search

Searches the catalog of available resources

Request	Response	Error
ResourceSearchRequest<IngressIncludeFlags>	PageV2<Ingress>	CommonErrorMessage

create

Creates one or more resources

Request	Response	Error
BulkRequest<IngressSpecification>	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

Data Models

Ingress

An L7 ingress-point (HTTP)

data class Ingress(
    val id: String,
    val specification: IngressSpecification,
    val owner: ResourceOwner,
    val createdAt: Long,
    val status: IngressStatus,
    val updates: List<IngressUpdate>?,
    val permissions: ResourcePermissions?,
    val providerGeneratedId: String?,
)

Properties

---

IngressIncludeFlags

data class IngressIncludeFlags(
    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 filterState: IngressState?,
    val hideProductId: String?,
    val hideProductCategory: String?,
    val hideProvider: String?,
)

Properties

---

IngressSpecification

data class IngressSpecification(
    val domain: String,
    val product: ProductReference,
)

Properties

---

IngressState

enum class IngressState {
    PREPARING,
    READY,
    UNAVAILABLE,
}

Properties

---

IngressStatus

The status of an Ingress

data class IngressStatus(
    val boundTo: List<String>?,
    val state: IngressState,
    val resolvedSupport: ResolvedSupport<Product.Ingress, IngressSupport>?,
    val resolvedProduct: Product.Ingress?,
)

Properties

---

IngressSupport

data class IngressSupport(
    val domainPrefix: String,
    val domainSuffix: String,
    val product: ProductReference,
    val maintenance: Maintenance?,
)

Properties

---

IngressUpdate

data class IngressUpdate(
    val state: IngressState?,
    val status: String?,
    val timestamp: Long?,
    val binding: JobBinding?,
)

Properties

---