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

Description
Create and configure an Ingress

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

3. Data Models

Name	Description
`Ingress`	An L7 ingress-point (HTTP)
`IngressIncludeFlags`	No description
`IngressSpecification`	No description
`IngressState`	No description
`IngressStatus`	The status of an `Ingress`
`IngressSupport`	No description
`IngressUpdate`	No description

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.

`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

id: String A unique identifier referencing the `Resource`

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

specification: IngressSpecification

owner: ResourceOwner Information about the owner of this resource

createdAt: Long Information about when this resource was created

status: IngressStatus The current status of this resource

updates: List<IngressUpdate>? A list of updates for this `Ingress`

permissions: ResourcePermissions? Permissions assigned to this resource

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

providerGeneratedId: String?

`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

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.

filterState: IngressState?

hideProductId: String?

hideProductCategory: String?

hideProvider: String?

`IngressSpecification`¶

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

Properties

domain: String The domain used for L7 load-balancing for use with this `Ingress`

product: ProductReference The product used for the `Ingress`

`IngressState`¶

enum class IngressState {
    PREPARING,
    READY,
    UNAVAILABLE,
}

Properties

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

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

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

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

`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

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

state: IngressState

resolvedSupport: ResolvedSupport<Product.Ingress, IngressSupport>?

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

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

`IngressSupport`¶

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

Properties

domainPrefix: String

domainSuffix: String

product: ProductReference

maintenance: Maintenance?

`IngressUpdate`¶

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

Properties

state: IngressState? The new state that the `Ingress` transitioned to (if any)

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

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

binding: JobBinding?

Public Links (Ingress)¶

Rationale¶

Table of Contents¶

Example: Create and configure an Ingress¶

Remote Procedure Calls¶

browse¶

retrieve¶

retrieveProducts¶

search¶

create¶

delete¶

init¶

updateAcl¶

Data Models¶

Ingress¶

IngressIncludeFlags¶

IngressSpecification¶

IngressState¶

IngressStatus¶

IngressSupport¶

IngressUpdate¶

`browse`¶

`retrieve`¶

`retrieveProducts`¶

`search`¶

`create`¶

`delete`¶

`init`¶

`updateAcl`¶

`Ingress`¶

`IngressIncludeFlags`¶

`IngressSpecification`¶

`IngressState`¶

`IngressStatus`¶

`IngressSupport`¶

`IngressUpdate`¶