Manage connections

As your network infrastructure evolves, you may need to update existing VPN connections. For example, to add new subnets, rotate pre-shared keys, or change BGP settings. Updating connection parameters may trigger a re-negotiation of the IPSec tunnels.

This guide demonstrates how to modify an existing VPN connection.

Prerequisites

Before you update a connection, ensure you have the following:

• The STACKIT project ID and the region of your gateway.
• The unique identifier (gatewayId) of the VPN gateway you want to modify.
• The updated configuration parameters (for example, new remoteSubnets or a new localAsn).

API

Identify the connection

To update a specific connection, you must first retrieve its connectionId.

1. List all connections for your gateway:

   GET /v1beta1/projects/{projectId}/regions/{region}/gateways/{gatewayId}/connections

2. Locate the connection in the response and copy the id field.

Update connection parameters

You can update most parameters of a connection, including the displayName, routing configurations, and tunnel-specific settings.

• Warning: Changing critical IPSec parameters such as the remoteAddress or preSharedKey will cause the tunnels to disconnect and re-establish. Expect a brief interruption in traffic during the re-negotiation process.

Perform the update via API

To apply changes, send a PUT request to the connection endpoint. You must include the full configuration of the connection, as this method replaces the existing resource.

1. Prepare the JSON request body with the updated values.

2. Send the request to the following endpoint:

   PUT /v1alpha1/projects/{projectId}/regions/{region}/gateways/{gatewayId}/connections/{connectionId}

Example request

This example demonstrates updating the remoteSubnets for a policy-based connection.

{
  "displayName": "office-neckarsulm-v2",
  "localSubnets": ["10.0.0.0/16"],
  "remoteSubnets": ["192.168.1.0/24", "192.168.2.0/24"],
  "tunnel1": {
    "remoteAddress": "203.0.113.10",
    "preSharedKey": "new-rotation-secret-key-2025"
  },
  "tunnel2": {
    "remoteAddress": "203.0.113.11",
    "preSharedKey": "new-rotation-secret-key-2025"
  }
}

Portal

Portal integration not yet available.

CLI

CLI functions not yet available.

Terraform

Terraform functions not yet available.

Verify the update

After you initiate the update, the connection status transitions to PENDING.

1. Monitor the status by polling the connection details endpoint.
2. Confirm that the status returns to READY.
3. Test connectivity from your STACKIT SNA to the new subnets to ensure the routing changes were applied successfully.

Troubleshooting update failures

If the update results in an ERROR state or the tunnels fail to come back online:

• Verify PSK symmetry: Ensure the new preSharedKey matches exactly on both the STACKIT gateway and your remote peer device.

• Check CIDR overlaps: Ensure that the new localSubnets or remoteSubnets do not conflict with existing routes in your SNA.

• Audit BGP sessions: If using BGP_ROUTE_BASED routing, verify that the localAsn and remoteAsn are correct and that the peering addresses are reachable.