Skip to content

feat(vpc): reorganize troubleshooting and add connectivity testing page #5042

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 11, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -22,4 +22,4 @@ The action to take depends on whether DHCP is [activated](/vpc/reference-content

If it is not, disconnect the Instance from the Private Network, as there may be other factors impacting your Instance, like one of your Instances running a DHCP server.

If it is, this is expected behavior as all the traffic towards your Instance now goes through the Public Gateway. To access your Instance using SSH, first create a static NAT association between a port of your Public Gateway (eg 2222) and the private IP assigned to your Instance, on the SSH port (22 by default). Then, SSH to the Public Gateway's IP on port 2222.
If it is, this is expected behavior as all the traffic towards your Instance now goes through the Public Gateway. The recommended solution to connect to your Instance is to use [SSH bastion](/public-gateways/how-to/use-ssh-bastion/#how-to-connect-to-a-resource-behind-your-ssh-bastion).
2 changes: 1 addition & 1 deletion pages/vpc/reference-content/dns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ If you experience problems with DNS, try the following steps:

3. **Check Private Network name**. Issues can arise with Private Networks who share a name with a TLD. See our [dedicated document](/vpc/troubleshooting/pn-name/) for more help.

4. **Check whether you are using Network Manager**: DNS does not work out of the box for Linux distributions using Network Managed, such as **RockyLinux**. Find out how to resolve this problem [on our troubleshooting page](/vpc/troubleshooting/private-dns-dhcp-not-working/#distributions-running-network-manager)
4. **Check whether you are using Network Manager**: DNS does not work out of the box for Linux distributions using Network Managed, such as **RockyLinux**. Find out how to resolve this problem [on our troubleshooting page](/vpc/troubleshooting/pn-name/#distributions-running-network-manager)

If you are still having problems reaching a resource attached to a Private Network via its hostname, [open a support ticket](https://console.scaleway.com/support).

Expand Down
6 changes: 3 additions & 3 deletions pages/vpc/troubleshooting/autoconfig-not-working.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
meta:
title: My Instance is attached to a Private Network but auto-configuration is not working
title: My legacy Instance is attached to a Private Network but auto-configuration is not working
description: Troubleshoot VPC autoconfiguration issues with this guide. Find solutions to common problems and ensure smooth network setup on Scaleway.
content:
h1: My Instance is attached to a Private Network but auto-configuration is not working
h1: My legacy Instance is attached to a Private Network but auto-configuration is not working
paragraph: Troubleshoot VPC autoconfiguration issues with this guide. Find solutions to common problems and ensure smooth network setup on Scaleway.
tags: resource instance private-network auto-configuration auto configuration dhcp default-route
dates:
Expand All @@ -21,7 +21,7 @@ They leverage helper scripts provided by the `scaleway-ecosystem` package. These
- When Instances are attached to Private Networks plugged into Public Gateways, make the default route received by DHCP the primary route for all traffic on the Instance
- Keep the route to the Scaleway Metadata API more specific (see below).

If your Instance does not get auto-configured, it may be that you are using an old version of the `scaleway-ecosystem` package. `scaleway-ecosystem` version 0.0.4 or later is required. Use the following command to update it:
If your Instance does not get auto-configured, it may be that you are using an old Instance that has an old version of the `scaleway-ecosystem` package. `scaleway-ecosystem` version 0.0.4 or later is required. Use the following command to update it:

- On Ubuntu (Focal and Jammy) or Debian (Stretch and Buster):

Expand Down
125 changes: 125 additions & 0 deletions pages/vpc/troubleshooting/connectivity-tests.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
---
meta:
title: Connectivity tests for unreachable Instances in a Private Network
description: When your Scaleway Instance is unreachable via its attached Private Network, this page sets out a detailed testing process to help you diagnose and resolve the issue.
content:
h1: Connectivity tests for unreachable Instances in a Private Network
paragraph: When your Scaleway Instance is unreachable via its attached Private Network, this page sets out a detailed testing process to help you diagnose and resolve the issue.
tags: resource private-network connectivity ping test
dates:
validation: 2025-05-30
posted: 2025-05-30
categories:
- network
---

When an Instance becomes unreachable over a Private Network, it can be challenging to diagnose and resolve the issue.

To help streamline the troubleshooting process, the Scaleway Network team has developed a step-by-step technique that can help identify and potentially fix connectivity problems.

This technique involves a series of tests and checks to determine the root cause of the issue, including DNS resolution, ARP table verification, and Link-Local Address (LLA) calculation.

By following these steps, you can quickly determine if the issue is related to DNS, network configuration, or resource-specific problems, and take corrective action to restore connectivity.

It is particularly useful to carry out these steps before opening a support ticket, and supplying the results of the tests. This enables a swifter and more efficient resolution of your problem.

## Step-by-step connectivity testing process

### Step 1: Ping the non-communicating Instance from another Instance in the Private Network

1. [Connect to another Instance](/instances/how-to/connect-to-instance/) in the same Private Network as the non-communicating Instance.

2. Try to reach the non-communicating Instance with a ping via `ping instance-name` (where `instance-name` is the name you gave your Instance upon creation.)

3. Carry out the same test for both IPv4 and IPv6, ie `ping -4 instance-name` and `ping -6 instance-name`.

- If these tests fail, there may be a DNS issue meaning the Instance's hostname cannot be resolved, see step 4 directly below.
- Otherwise, if the tests succeed, continue to the section [Check ARP](#step-2-check-arp)

4. Consider checking DNS records via the Scaleway Domains and DNS CLI as documented [here](/vpc/reference-content/dns/#troubleshooting), to see if the private DNS zone is correctly configured and the Instance's DNS records are up-to-date.

<Message type="important">
Note that we do not recommend editing these records yourself, rather open a support ticket with the information you have gathered.
</Message>

### Step 2: Check ARP

A server's **A**ddress **R**esolution **P**rotocol (ARP) table maps IP addresses to MAC addresses on a local network. Use this data to find the probe state for the target Instance's MAC address.

1. From another Instance in the same Private Network as the non-communicating Instance, view ARP information via an `ip neigh` command.

You should see an output of many lines in the following format:

```
172.16.8.2 dev ens5 lladdr 02:00:00:1c:0d:9b REACHABLE
```

2. Find the line beginning with the non-communicating Instance's private IP address, and containing also its MAC address. You can check both via the Scaleway console in the Private Network's **Attached resources** tab. You can use the following command to identify the line, replacing `<MAC_ADDRESS>` with the Instance's MAC address:

```
ip neigh | grep --ignore-case <MAC_ADDRESS>
```

The line ends with the state of the probe for that Instance's MAC address.

`FAILED` shows that the system tried to resolve the MAC address but did not get a response.

Continue to the next stage of testing.

### Step 3: Try reaching the Instance using its LLA

If the Instance could not be reached via the resolution of its MAC address, next you should try to reach it via its IPv6 **L**ink **L**ocal **A**ddress (LLA) in the Private Network.

The LLA is calculated from the Instance's MAC address.

1. Use an online tool or guide to carry out the standardized process of calculating the Instance's LLA from its MAC address. Remember that you can view its MAC address from the Scaleway console, in the Private Network's **Attached Resources** tab.

<Message type="tip">
You can use the following code snippet to calculate the LLA:

```
bash-5.2$ mac_to_ipv6_ll() {
IFS=':'; set $1; unset IFS
echo "fe80::$(printf %02x $((0x$1 ^ 2)))$2:${3}ff:fe$4:$5$6"
}
```
<br/>
Example usage and output for a MAC address of `02:00:00:23:e4:01`:

```
bash-5.2$ mac_to_ipv6_ll 02:00:00:23:e4:01
fe80::0000:00ff:fe23:e401
```
</Message>

2. Ping the LLA. Ensure that you specify which interface to ping over (the Private Network) by adding the `%interface` zone index to the end of the ping command. For example, for a LLA of `fe80::0:0ff:fe1c:d9b` and a Private Network interface name of `ens5`, use the following command:

```
ping -6 fe80::0:0ff:fe1c:d9b%ens5
```

<Message type="tip">
The interface name depends on the Instance type and OS. You can use the following command to get a compact summary of all network interfaces on your Instance:

```
ip -brief -color addr show
```
</Message>

A successful ping will show results similar to the following:

```
PING fe80::0:0ff:fe1c:d9b%ens5 (fe80::ff:fe1c:d9b%ens5) 56 data bytes
64 bytes from fe80::ff:fe1c:d9b%ens5: icmp_seq=1 ttl=64 time=1.27 ms
64 bytes from fe80::ff:fe1c:d9b%ens5: icmp_seq=2 ttl=64 time=0.652 ms
64 bytes from fe80::ff:fe1c:d9b%ens5: icmp_seq=3 ttl=64 time=0.632 ms
--- fe80::0:0ff:fe1c:d9b%ens5 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2042ms
rtt min/avg/max/mdev = 0.632/0.850/1.266/0.294 ms
```

This response suggests the Instance is attached to the Private Network, but has lost its IPAM-provided IPv4 and IPv6 addresses. There could be a configuration issue on the Instance, such as DHCP client issue, a problem with `iptables` rules, or another parameter you may have manually altered.

You can connect to your Instance via SSH using the LLA, to take control and attempt to fix the issue.

If you do not believe you have modified any parameters affecting the Instance's DHCP or IP configuration over the Private Network, open a support ticket providing the full output from all of the above tests.
10 changes: 5 additions & 5 deletions pages/vpc/troubleshooting/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,11 @@ categories:
## VPC troubleshooting pages

<LinksList>
- <LinkList to="/vpc/troubleshooting/resource-attached-no-ip/" label="My resource has no IP address on a Private Network" />
- <LinkList to="/vpc/troubleshooting/cant-delete-vpc-pn/" label="I can't delete my VPC or Private Network" />
- <LinkList to="/vpc/troubleshooting/autoconfig-not-working/" label="My Instance is attached to a Private Network but auto-configuration is not working" />
- <LinkList to="/vpc/troubleshooting/private-dns-dhcp-not-working/" label="Private DNS and/or DHCP are not working" />
- <LinkList to="/vpc/troubleshooting/pn-name/" label="I am experiencing SSL or DNS errors and conflicts with my Private Network" />
- <LinkList to="/vpc/troubleshooting/resource-attached-no-ip/" label="My resource has no IP address on a Private Network (DHCP problems)" />
- <LinkList to="/vpc/troubleshooting/pn-name/" label="I am experiencing DNS or SSL errors and conflicts with my Private Network" />
- <LinkList to="/vpc/troubleshooting/vpc-pn-routing-connectivity-issues/" label="I am experiencing connectivity or routing issues with my VPC or Private Network" />
- <LinkList to="/vpc/troubleshooting/cant-delete-vpc-pn/" label="I can't delete my VPC or Private Network" />
- <LinkList to="/vpc/troubleshooting/connectivity-tests/" label="Connectivity tests for unreachable Instances in a Private Network" />
- <LinkList to="/vpc/troubleshooting/autoconfig-not-working/" label="My legacy Instance is attached to a Private Network but auto-configuration is not working" />
- <LinkList to="/vpc/troubleshooting/vpc-limitations/" label="VPC limitations" />
</LinksList>
44 changes: 36 additions & 8 deletions pages/vpc/troubleshooting/pn-name.mdx
Original file line number Diff line number Diff line change
@@ -1,26 +1,36 @@
---
meta:
title: I am experiencing SSL or DNS errors and conflicts with my Private Network
description: This page helps you troubleshoot problems that can occur when you have given your Private Network a name that is also a TLD, which can cause errors and conflicts with SSL, DNS and addressing.
title: I am experiencing DNS or SSL errors and conflicts with my Private Network
description: This page helps you troubleshoot problems that can occur when accessing your resource by its hostname over a Private Network
content:
h1: I am experiencing SSL or DNS errors and conflicts with my Private Network
paragraph: This page helps you troubleshoot problems that can occur when you have given your Private Network a name that is also a TLD, which can cause errors and conflicts with SSL, DNS and addressing.
h1: I am experiencing DNS or SSL errors and conflicts with my Private Network
paragraph: This page helps you troubleshoot problems that can occur when accessing your resource by its hostname over a Private Network
tags: private-network tld ssl ssl-validation-failed dns name addressing
dates:
validation: 2025-02-13
validation: 2025-05-30
posted: 2024-01-31
categories:
- network
---

## TLD naming problem with Private Networks
Scaleway VPC and Private Networks integrate managed DNS, for the effective resolution of hostnames to IP addresses. You may be experiencing DNS and/or related SSL errors when attempting to access your resource over its [hostname](/vpc/reference-content/dns/#hostname-format) on a Private Network.

This document guides you through solutions to this type of problem.

## Basic steps to try first

- Make sure that [DHCP is activated](/vpc/how-to/activate-dhcp/) on your Private Network.
- Ensure that you have tried [detaching/reattaching](/vpc/troubleshooting/resource-attached-no-ip/#no-ip-address-is-displayed-but-i-have-activated-dhcp) the affected resources from/to the Private Network, particularly if they are older resources or you have [changed their name](/vpc/how-to/attach-resources-to-pn/#how-to-access-a-resource-on-a-private-network-via-its-hostname-dns).
- Ensure that you are correctly addressing resources attached to a Private Network, using the format `resource-name.private-network-name.internal`. The `.internal` is important to allow Scaleway DNS to distinguish public and private hostnames and correctly resolve requests. [Find out more about DNS](/vpc/reference-content/dns/).

## Check for TLD naming problem

If you have given your Private Network a name that is also a **T**op **L**evel **D**omain, you may experience SSL or addressing errors and conflicts when you try to access resources on the public internet with the same TLD as your Private Network, or when trying to reach resources on your Private Network from the public internet. Examples are:

- Errors when trying to reach `google.dev` from a Private Network named `dev`
- Errors when trying to reach `scw.cloud.network` from a Private Network named `network`

## Solutions
### Solution

Scaleway is working on a solution to allow users to name their Private Networks with a TLD name without experiencing any conflicts. In the meantime, until this solution is deployed, you should **not** give your Private Network a name that is also a TLD.

Expand All @@ -38,4 +48,22 @@ You can change your Private Network name at any time in the [Scaleway console](h
- After changing the name of Private Network, it can take up to five minutes for the new name to be propagated.
- You should also renew DHCP leases in order to update the list of search domains for the Private Network: do this by running `netplan apply` on Ubuntu servers.
- Note that resources in a Private Network are in any case always reachable by their IP address.
</Message>
</Message>

## Check whether resource has a dot in its hostname

Issues may arise with internal addressing if you give your resource a name that includes a dot (`.`).

### Solution

Try renaming your resource to a name that does not include a dot, then detach/reattach it to the Private Network in order to update DNS.

## Distributions running Network Manager

Private DNS should work out of the box for attached resources with Debian-based distributions, and for distributions using `systemd-resolved`, such as Ubuntu.

It does **not** work out of the box for Linux distributions using Network Manager, such as **RockyLinux**.

### Solution

If your resource is running RockyLinux, or another distribution using Network Manager, you should manually configure the system to use the nameserver `169.254.169.254`. You will then be able to resolve the name of your resources, as well as public domain names.
Loading