API reference · Networking

Tunnels

6 operations of the Ankra Cloud API: Ankra Tunnel - publish HTTP services that have only outbound connectivity. A tunnel's connector dials the Ankra relay; the relay serves the tunnel's hostnames (in the account's hosted DNS zones, behind the zone's WAF) with certificates it obtains itself and proxies each request to the hostname's origin through the connector.

List the account's tunnels, newest first, with their hostnames and connector status#

GET/v1/tunnels

Operation: list_tunnels
Credentials: API token, Portal session
Requires: Permission read

Parameters

Parameters
Name	In	Type	Description
`cursor`	query	string	The `next_cursor` of the previous page.
`limit`	query	integer	Page size; the server applies its default and maximum.

Responses

200A page of tunnels.application/json

200 response fields
Field	Type	Description
`items`required	array of Tunnel
`id`required	string
`name`required	string
`status`required	string	One of `connected`, `disconnected`, `inactive`
`token_prefix`required	string	The start of the connector token, to tell tokens apart.
`token_rotated_at`required	string (date-time)
`hostnames`required	array of TunnelHostname
`hostname`required	string
`origin_url`required	string
`zone_id`required	string
`zone_name`required	string
`created_at`required	string (date-time)
`connectors`required	array of TunnelConnector
`name`required	string	The connector's name (its pod or host name).
`remote`required	string	The address the connector's session came from.
`connected_at`required	string (date-time)
`status_reported_at`required	string (date-time) \| null
`last_connected_at`required	string (date-time) \| null
`install`required	object
`relay_address`required	string
`image`required	string \| null
`available`required	boolean	False while no relay is configured; tunnels cannot change then.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`next_cursor`required	string \| null	Pass as `?cursor=` for the next page; null on the last page.

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/tunnels' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Create a tunnel with its public hostnames and mint its connector token#

POST/v1/tunnels

Operation: create_tunnel
Credentials: API token, Portal session
Requires: Permission operate
Note: Reveals a credential or a live view; read-only support sessions are refused.

Each hostname must sit in a verified hosted DNS zone of this account (the closest zone above it; a subzone delegated elsewhere answers it) and names the origin_url the connector proxies it to, as the connector sees it (an in-cluster Service, http://localhost:8080). The zone publishes the relay's A and AAAA at the hostname and applies the zone's WAF policy. A hostname has one owner: 409 hostname_taken when another tunnel holds it, hostname_proxied when a Proxied record sits there and hostname_has_records when an A, AAAA or CNAME record does (delete it first). 400 hostname_zone_not_found, invalid_hostname, invalid_origin_url, invalid_tunnel_name, duplicate_hostname, too_many_hostnames (50). 409 tunnel_name_taken, tunnel_limit_reached (100). 503 tunnels_unavailable while no relay is configured. The token is in this answer only (only its SHA-256 is stored); run the connector with it. Audited as tunnel.created.

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`required	string
`hostnames`	array of TunnelHostnameInput
`hostname`required	string
`origin_url`required	string	An http or https URL as the connector reaches it, without credentials, query or fragment.

Responses

201The tunnel and its connector token, shown this once.application/json · TunnelWithToken

201 response fields
Field	Type	Description
`tunnel`required	Tunnel	An Ankra Tunnel. `connectors` are the sessions the relay reported within the last 90 seconds. `install` is what a connector runs with: the relay's connector address and the published connector image (null until the control plane names one).
`id`required	string
`name`required	string
`status`required	string	One of `connected`, `disconnected`, `inactive`
`token_prefix`required	string	The start of the connector token, to tell tokens apart.
`token_rotated_at`required	string (date-time)
`hostnames`required	array of TunnelHostname
`hostname`required	string
`origin_url`required	string
`zone_id`required	string
`zone_name`required	string
`created_at`required	string (date-time)
`connectors`required	array of TunnelConnector
`name`required	string	The connector's name (its pod or host name).
`remote`required	string	The address the connector's session came from.
`connected_at`required	string (date-time)
`status_reported_at`required	string (date-time) \| null
`last_connected_at`required	string (date-time) \| null
`install`required	object
`relay_address`required	string
`image`required	string \| null
`available`required	boolean	False while no relay is configured; tunnels cannot change then.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`token`required	string	The connector token. It is shown this once.

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
409The resource's state does not allow this now.
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/tunnels' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "production"
}'

Show a tunnel with its hostnames, connected connectors and install settings#

GET/v1/tunnels/{id}

Operation: get_tunnel
Credentials: API token, Portal session
Requires: Permission read

status is connected while the relay reports at least one connector, disconnected once connectors were seen and are gone (or the relay stopped reporting), and inactive before any connector connected.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The tunnel.application/json

200 response fields
Field	Type	Description
`tunnel`required	Tunnel	An Ankra Tunnel. `connectors` are the sessions the relay reported within the last 90 seconds. `install` is what a connector runs with: the relay's connector address and the published connector image (null until the control plane names one).
`id`required	string
`name`required	string
`status`required	string	One of `connected`, `disconnected`, `inactive`
`token_prefix`required	string	The start of the connector token, to tell tokens apart.
`token_rotated_at`required	string (date-time)
`hostnames`required	array of TunnelHostname
`hostname`required	string
`origin_url`required	string
`zone_id`required	string
`zone_name`required	string
`created_at`required	string (date-time)
`connectors`required	array of TunnelConnector
`name`required	string	The connector's name (its pod or host name).
`remote`required	string	The address the connector's session came from.
`connected_at`required	string (date-time)
`status_reported_at`required	string (date-time) \| null
`last_connected_at`required	string (date-time) \| null
`install`required	object
`relay_address`required	string
`image`required	string \| null
`available`required	boolean	False while no relay is configured; tunnels cannot change then.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl 'https://cloud.ankra.app/v1/tunnels/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Rename a tunnel or replace its hostnames#

PATCH/v1/tunnels/{id}

Operation: update_tunnel
Credentials: API token, Portal session
Requires: Permission operate

hostnames is the complete list: hostnames left out stop being served and their names fall back to the zone's own records. Connected connectors reconnect within seconds and serve the new list. The same hostname rules and codes as create_tunnel apply. Audited as tunnel.updated.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Request bodyapplication/json

Request body fields
Field	Type	Description
`name`	string
`hostnames`	array of TunnelHostnameInput
`hostname`required	string
`origin_url`required	string	An http or https URL as the connector reaches it, without credentials, query or fragment.

Responses

200The changed tunnel.application/json

200 response fields
Field	Type	Description
`tunnel`required	Tunnel	An Ankra Tunnel. `connectors` are the sessions the relay reported within the last 90 seconds. `install` is what a connector runs with: the relay's connector address and the published connector image (null until the control plane names one).
`id`required	string
`name`required	string
`status`required	string	One of `connected`, `disconnected`, `inactive`
`token_prefix`required	string	The start of the connector token, to tell tokens apart.
`token_rotated_at`required	string (date-time)
`hostnames`required	array of TunnelHostname
`hostname`required	string
`origin_url`required	string
`zone_id`required	string
`zone_name`required	string
`created_at`required	string (date-time)
`connectors`required	array of TunnelConnector
`name`required	string	The connector's name (its pod or host name).
`remote`required	string	The address the connector's session came from.
`connected_at`required	string (date-time)
`status_reported_at`required	string (date-time) \| null
`last_connected_at`required	string (date-time) \| null
`install`required	object
`relay_address`required	string
`image`required	string \| null
`available`required	boolean	False while no relay is configured; tunnels cannot change then.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)

400The request is invalid; detail says why.
401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
409The resource's state does not allow this now.
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
503No capacity or address is free, or a host did not answer; try again later.
defaultAny other error, usually 500.

Example

bash

curl -X PATCH 'https://cloud.ankra.app/v1/tunnels/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "hostnames": [
    {
      "hostname": "app.example.com",
      "origin_url": "http://ingress-nginx-controller.ingress-nginx.svc.cluster.local:80"
    }
  ]
}'

Delete a tunnel; its hostnames stop being served within seconds#

DELETE/v1/tunnels/{id}

Operation: delete_tunnel
Credentials: API token, Portal session
Requires: Permission operate

Connected connectors are disconnected and refused from then on. Audited as tunnel.deleted.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

204Deleted.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X DELETE 'https://cloud.ankra.app/v1/tunnels/<id>' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Mint a new connector token; the old one stops working within seconds#

POST/v1/tunnels/{id}/token/rotate

Operation: rotate_tunnel_token
Credentials: API token, Portal session
Requires: Permission operate
Note: Reveals a credential or a live view; read-only support sessions are refused.

Sessions opened with the old token end at the relay's next directory refresh, so update the connector's token right after. The new token is in this answer only. Audited as tunnel.token_rotated.

Parameters

Parameters
Name	In	Type	Description
`id`required	path	string

Responses

200The tunnel and its new connector token, shown this once.application/json · TunnelWithToken

200 response fields
Field	Type	Description
`tunnel`required	Tunnel	An Ankra Tunnel. `connectors` are the sessions the relay reported within the last 90 seconds. `install` is what a connector runs with: the relay's connector address and the published connector image (null until the control plane names one).
`id`required	string
`name`required	string
`status`required	string	One of `connected`, `disconnected`, `inactive`
`token_prefix`required	string	The start of the connector token, to tell tokens apart.
`token_rotated_at`required	string (date-time)
`hostnames`required	array of TunnelHostname
`hostname`required	string
`origin_url`required	string
`zone_id`required	string
`zone_name`required	string
`created_at`required	string (date-time)
`connectors`required	array of TunnelConnector
`name`required	string	The connector's name (its pod or host name).
`remote`required	string	The address the connector's session came from.
`connected_at`required	string (date-time)
`status_reported_at`required	string (date-time) \| null
`last_connected_at`required	string (date-time) \| null
`install`required	object
`relay_address`required	string
`image`required	string \| null
`available`required	boolean	False while no relay is configured; tunnels cannot change then.
`created_at`required	string (date-time)
`updated_at`required	string (date-time)
`token`required	string	The connector token. It is shown this once.

401Not signed in, or the credential is invalid or expired.
403The role lacks the permission, the token is read-only (a read-only token also gets reason: read_only_token_cannot_read_credentials on every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified).
404No such resource in the caller's account.
429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the X-RateLimit-* headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out.
defaultAny other error, usually 500.

Example

bash

curl -X POST 'https://cloud.ankra.app/v1/tunnels/<id>/token/rotate' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"