Skip to main content

IPsec shares

Frontdoor V2 feature

IPsec shares are available on Frontdoor V2 to customers who have IPsec shares enabled. The endpoints below live under the /frontdoor/v2 base path. Contact your account manager to request access.

This guide explains how to manage IPsec shares — the services published on an IPsec tunnel. For the concepts, see IPsec shares.

Why this matters​

  • An IPsec share maps an ingress port on a tunnel's load balancer to a private target that a hosting agent reaches.
  • Provisioning is asynchronous. A share transitions NEW → DEPLOYED (or ERROR); plan for eventual consistency after create and delete.

Assumptions​

All IPsec share paths are under the /frontdoor/v2/{frontdoorId} base. IPsec shares must be enabled for the Frontdoor.

Operations​

List shares​

Request example:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/v2/$FRONTDOOR_ID/ipsec-shares?page=0&size=20"

You can filter by any property, for example ?status=DEPLOYED&status=NEW, ?target=10.20.100.1:8443, or ?envZId=ijcrWb-ZOq, and sort with ?sort=name,asc.

Get a share​

Request example:

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/v2/$FRONTDOOR_ID/ipsec-shares/$SHARE_ID"

Response example:

{
  "id": "shr-1",
  "name": "app-db",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "ipsecTunnelId": "tnl-1",
  "envZId": "ijcrWb-ZOq",
  "target": "10.20.100.1:8443",
  "ingressPort": 8443,
  "status": "DEPLOYED"
}

Create a share​

Provisioning happens asynchronously. The call returns 202 Accepted; poll the GET endpoint until status is DEPLOYED. The ipsecTunnelId is the tunnel the share is published on.

Request example:

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "app-db",
        "ipsecTunnelId": "tnl-1",
        "envZId": "ijcrWb-ZOq",
        "target": "10.20.100.1:8443",
        "ingressPort": 8443
      }' \
  "https://gateway.production.netfoundry.io/frontdoor/v2/$FRONTDOOR_ID/ipsec-shares"

Request fields:

  • name (required): 1–63 characters; letters, numbers, and hyphens, not starting or ending with a hyphen.
  • ipsecTunnelId (required): The IPsec tunnel this share is created on.
  • envZId (required): The hosting agent's environment (also accepted as envId).
  • target (required): The private host:port the agent connects to.
  • ingressPort (required): The listener port on the tunnel's load balancer (1–65535).
  • locationId (optional): The location/site for the share.

Update a share​

A share update recreates the share with the new configuration, so it runs asynchronously and transitions back through NEW → DEPLOYED (or ERROR), the same as a create. Use PUT for a full update (all required fields) or PATCH for a partial update (only the fields you provide):

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "target": "10.20.100.2:8443" }' \
  "https://gateway.production.netfoundry.io/frontdoor/v2/$FRONTDOOR_ID/ipsec-shares/$SHARE_ID"

Delete a share​

Teardown happens asynchronously (status transitions DELETING → DELETED).

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/v2/$FRONTDOOR_ID/ipsec-shares/$SHARE_ID"

Technical notes​

Metrics​

Share metrics accept an optional duration window (for example, 15m or 1h):

GET /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}/metrics?duration=1h

Paths​

- GET    /frontdoor/v2/\{frontdoorId\}/ipsec-shares[?page=0&size=20]
- GET    /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}
- POST   /frontdoor/v2/\{frontdoorId\}/ipsec-shares
- PUT    /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}
- PATCH  /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}
- DELETE /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}
- GET    /frontdoor/v2/\{frontdoorId\}/ipsec-shares/{id}/metrics[?duration=1h]

Common errors​

400 Bad Request (client error)​

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)​

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)​

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

  • Invalid token: The token is not valid.
  • The token does not grant access to the requested resource.
  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.