Skip to main content

Connectivity via shuttle

This guide shows you how to connect your Anapaya Appliance to the Anapaya CONSOLE using a shuttle tunnel. The CONSOLE will use this connection to manage and monitor your appliance through its management API configuration.

The shuttle tunnel provides a secure, outbound-initiated connection for management traffic. This approach simplifies your network setup, especially when the appliance is behind a firewall or NAT. The tunnel leverages SCION connectivity, and Anapaya provides a dedicated shuttle server for this purpose.

For alternative connectivity methods, see providing connectivity.

Prerequisites​

Before you begin, verify that:

  • You have administrative access to the appliance (via CLI or API).
  • You have the operator role (or higher) in the CONSOLE organization where you will add the appliance.
  • The appliance is connected to the SCION network.
  • The appliance has management API authentication enabled.

Walkthrough​

Step 1: Configure the shuttle client​

Configure the shuttle client on your appliance by running the following command. Replace the local address with a SCION address configured on your appliance that can reach the shuttle server (typically your SCION control server address).

appliance-cli edit config 'config.interfaces.shuttles[]: {
  name: "shuttle0"
  local: "1-ff00:0:1,172.0.0.1"
  servers[].endpoint: "[64-2:0:0,10.186.36.21]:49420"
  disable: false
}'

If you have a standard setup with a single shuttle interface connecting to the default Anapaya shuttle server, you only need to update the local address. For multiple shuttle interfaces or alternative servers, adjust the other parameters as needed.

Step 2: Register the shuttle client credentials​

Retrieve the automatically generated credentials and send them to Anapaya support for registration:

appliance-cli info shuttle shuttle0

Provide the complete output to Anapaya support, along with the appliance name and ID. They will register your credentials and provide you with the tunnel IP address that will be assigned once the connection is established.

danger

As soon as a client with a certain name, e.g., shuttle0, is removed from the configuration, its associated ID and Certificate are permanently erased. They can never be recovered.

Re-adding the client later with the same name, e.g., shuttle0, only results in creation of a new ID and Certificate, which must be communicated again to operators of all servers in the servers list.

Editing a client does not remove the ID and Certificate.

To disable a client without removing its ID and Certificate, set the disable flag to true.

Step 3: Expose the management API on the shuttle interface​

Configure the management API to accept connections through the shuttle tunnel. Run the following command to add the management API listener:

appliance-cli edit config 'config.management.api.interfaces[]: {
  name: "shuttle0"
  port: 443
  description: "Accept management traffic on shuttle interface"
}'

You can use this command as-is unless you chose a different shuttle interface name in the first step.

Authentication required

Management API authentication must be enabled before this configuration can be applied. If you haven't enabled it yet, follow the management API authentication guide first.

Step 4: Onboard the appliance to the CONSOLE​

With the tunnel established and the management API exposed, you can now onboard your appliance. Follow the appliance onboarding guide.

When configuring access parameters:

  • Endpoint: Enter the tunnel IP address that Anapaya support provided in step 2
  • API path and Metrics URL: Leave empty

Troubleshooting​

If the CONSOLE cannot connect to your appliance, verify the following:

  • Shuttle tunnel status

    Check if the shuttle tunnel is established and healthy:

    appliance-cli info shuttle shuttle0

    The output should show that the client is connected and display tunnel details.

  • Tunnel IP address

    Verify that the IP address configured in the CONSOLE matches the tunnel IP address shown in the shuttle information output.

  • Management API credentials

    Confirm that the credentials configured in the CONSOLE match those on the appliance. Verify both the username and password hash (for basic authentication).