UCloud Docs
  • Login
  • eScience Center
  • Terms of Service
  • Developer Guide (current)
  • User Guide
  • FAQ

Navigation

  • index
  • next |
  • previous |
  • »
  • Orchestration of Resources »
  • Compute »
  • Public Links (Ingress)

Developer Guide

  • Accounting and Project Management
  • Orchestration of Resources
    • Introduction to Resources
    • Storage
    • Compute
      • Application Store
      • Jobs
      • Public IPs (NetworkIP)
      • Public Links (Ingress)
      • Software Licenses
      • Provider APIs
  • Developing UCloud
  • Core

API Reference

  • Remote Procedure Calls
  • Examples
  • Type Reference
  1. Docs
  2. Orchestration of Resources
  3. Compute
  4. Public Links (Ingress)

Public Links (Ingress)¶

API: Stable

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 useCommon
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(
            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", 
        ), 
        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,
#                     "name": "example-ingress",
#                     "pricePerUnit": 1,
#                     "category": {
#                         "name": "example-ingress",
#                         "provider": "example-ingress"
#                     },
#                     "description": "An example ingress",
#                     "priority": 0,
#                     "version": 1,
#                     "freeToUse": false,
#                     "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¶

API: Stable Auth: Users

Browses the catalog of available resources

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

retrieve¶

API: Stable Auth: Users

Retrieve a single resource

Request Response Error
ResourceRetrieveRequest<IngressIncludeFlags> Ingress CommonErrorMessage

retrieveProducts¶

API: Stable Auth: Users

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¶

API: Stable Auth: Users

Searches the catalog of available resources

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

create¶

API: Stable Auth: Users

Creates one or more resources

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

Data Models¶

Ingress¶

API: Stable

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?

API: Internal/Beta


IngressIncludeFlags¶

API: Stable

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¶

API: Stable

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¶

API: Stable

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¶

API: Stable

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¶

API: Stable

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¶

API: Stable

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?

Previous
Next

Navigation

  • index
  • next |
  • previous |
  • »
  • Orchestration of Resources »
  • Compute »
  • Public Links (Ingress)

eScience Center

  • Home page
  • Staff
  • News
  • Collaborations
User Support

  • Terms of Service
  • Service Desk
  • support@escience.sdu.dk

© Copyright 2020-2022 | SDU eScience | All rights reserved