Certificates
This document describes the Unikraft Cloud Services API (v1) for managing TLS certificates for custom domains.
Certificates for Custom Domains
Unikraft Cloud allows you to host your deployment at subdomains of <metro>.kraft.host
and/or use custom domains (e.g., example.com
).
For subdomains, your deployment will use the wildcard TLS certificate of the respective Unikraft Cloud metro.
For custom domains, you need a TLS certificate specifically generated for your domain.
Unikraft Cloud automatically configures the correct TLS certificate for you for non-wildcard domains.
To specify a custom domain, provide the fully-qualified domain name in POST /v1/instances
or POST /v1/services
.
Unikraft Cloud will check if any of your existing certificates applies to the domain, and if not request one using Let’s Encrypt™.
For wildcard domains you have to supply your own certificate. If you want to use Let’s Encrypt™ you can use their DNS-based challenge and upload the resulting certificate to Unikraft Cloud.
Certificate States
A certificate can be in one of the following states:
State | Description |
---|---|
pending | The certificate request is pending while the certificate is being requested from the certification authority. During this phase any service using this certificate is not available if this is not a renewal |
valid | The certificate is valid and can be used by your services |
error | The certificate request failed after multiple attempts. This can happen, for example, if your DNS configuration is not correct, you run into Let’s Encrypt™ quota limits, or the domain validation process failed for some other reason. There won’t be any further automatic attempts. If you need assistence please contact us via support@unikraft.cloud. |
These are reported as certificate state
by the endpoints.
API Endpoints
The Unikraft Cloud Services API provides the following endpoints:
Method | Endpoint | Purpose and Description |
---|---|---|
POST | /v1/certificates | Uploads an existing certificate |
GET | /v1/certificates | Returns the current state and properties of certificates |
DELETE | /v1/certificates | Deletes the specified certificates |
GET | /v1/certificates/list | Lists all existing certificates |
In the following, the API endpoints are specified relative to this base URL:
With X
being the IATA metro code.
We use fra0
as an example in the documentation.
See the introduciton for more information on how to connect to the API.
Uploading an Existing Certificate
Create a new certificate object and upload an existing certificate chain and private key.
Request
Endpoints:
POST /v1/certificates
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | Name | The name of the certificate to upload | ||
cn | string | ✔️ | The common name of the certificate | |
chain | string | ✔️ | The chain of the certificate in PEM format | |
pkey | string | ✔️ | The private key of the certificate in PEM format |
1 If no name is specified a random name of the form <cn>-X
is auto-generated, where <cn>
is the common name and X
is a 5 character long random alphanumeric suffix. For wildcard domains the wildcard part is cut off.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
Getting the Status of a Certificate
Returns the current status and the properties of a certificate.
Request
Endpoints:
GET /v1/certificates
GET /v1/certificates/<UUID>
Query Parameter | Type | Default | Required | Description |
---|---|---|---|---|
details | bool | true | Whether to provide detailed status and configuration information | |
name 1 | string | list of strings | Names of certificates to return as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of certificates to return as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | Name | ✔️ | UUID or name of the certificate to get the status for |
1 Not allowed in local scope.
2 You need to specify either uuid
or name
within the same body object.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status 1 | string | success on success, or error if the request failed |
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
created_at | string | Date and time of creation in ISO8601 |
common_name | string | Common name of the certificate |
state | State | Current state of the certificate |
validation | object | Validation status (only while pending ) |
attempt | int | Number of validation attempts made |
next | string | Date and time of next validation attempt in ISO8601 |
subject | string | Certificate subject |
issuer | string | Certificate issuer (usually Let’s Encrypt) |
serial_number | string | Certificate serial number |
not_before | string | Date and time of beginning of validity in ISO8601 |
not_after | string | Expiration date and time in ISO8601 |
service_groups | array of objects | Services using this certificate |
uuid | UUID | UUID of the service |
name | Name | Name of the service |
1 Not when listing all existing certificates.
Deleting a Certificate
Deletes the specified certificate. Fails if the certificate is still attached to a service. After this call the IDs associated with the certificate are no longer valid.
Request
Endpoints:
DELETE /v1/certificates
DELETE /v1/certificates/<UUID>
Query Parameter | Type | Default | Required | Description |
---|---|---|---|---|
name 1 | string | list of strings | Names of certificates to delete as comma-separated list | ||
uuid 1 | string | list of strings | UUIDs of certificates to delete as comma-separated list |
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
uuid | name 1,2 | UUID | Name | ✔️ | UUID or name of the certificate to delete |
1 Not allowed in local scope.
2 You need to specify either uuid
or name
within the same body object.
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
status | string | success on success, or error if the request failed |
uuid | UUID | UUID of the certificate |
name | Name | Name of the certificate |
List Existing Certificates
Lists all existing certificates. You can filter by common name. The returned certificates fulfill all provided filter criteria. No particular value is assumed if a filter is not part of the request.
Request
Endpoints:
GET /v1/certificates/list
Body Parameter | Type | Default | Required | Description |
---|---|---|---|---|
common_name | string | Common name of the certificate |
Response
The response is embedded in a JSON object as described in API Responses.
Field | Type | Description |
---|---|---|
uuid | UUID | UUID of the certificates |
name | Name | Name of the certificates |