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

Visit the STACKIT Portal, select your desired project and follow these steps:

1. In the sidebar under Networking, click on VPN.
2. Locate the VPN Gateway you want to manage the connection for and open its details by clicking on the respective gateway.
3. In the sidebar click on Connections.
4. Locate the VPN Connection you want to manage and open its details or use the actions menu.
5. Click the Edit button in the “General information” section to update the VPN Connection Name or the local and remote Subnets.
6. Click the Edit button in the “Tunnel1” or “Tunnel2 section to update the Tunnel specific parameters such as remote Address, PSK, or the IPSec IKEv2 Phase 1 and Phase 2 parameters.

Once confirmed, the VPN configuration will be updated accordingly. Note that depending on the settings changed there might be a interruption of the connection. Ensure the configured parameters match the configured parameters on the remote site. If parameters don’t match the remote gateway configuration the connection will remain interrupted.

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 in the STACKIT Portal or 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.