copyright

lastupdated

keywords

subcollection

years
2022, 2023

2023-01-30

access, wireguard, private, containers,

containers

Accessing private clusters by using the WireGuard VPN

{: #cluster-access-wireguard}

You can use the WireGuard VPN to securely connect to Kubernetes clusters with only a private network connection. {: shortdesc}

Before you begin, make sure that you have a Kubernetes cluster with a private-only network connection and that the cluster is assigned a private service endpoint.

Create a virtual server instance (VSI) that is connected to the same private network that your Kubernetes cluster runs in. This VSI serves as a jumpbox for your cluster. For example, if you have a private VPC cluster, make sure that you create the VSI in the same VPC. For more information about creating the VSI, consult your infrastructure provider's documentation. The VSI must meet the following specifications:
- The VSI must have a minimum of 2 vCPUs, 8 GB memory, and 25 GB of disk space.
- The VSI must run an operating system that is supported by WireGuard. For example, the steps in this topic were tested on an Ubuntu VSI.
- You must create an SSH key that is stored on the VSI so that you can connect to your VSI via SSH.
- You must assign a public IP address to your VSI so that your VSI is accessible over the public network.
- Your VSI must allow at least the following network traffic. You can optionally open up more network traffic on your VSI if required for the apps that run on your cluster.
  - Inbound TCP traffic on port 22 for SSH connections
  - Inbound UDP traffic on port 51820 for the WireGuard server
  - All outbound traffic
Log in to your VSI by using the public IP address of the VSI.
```
ssh -i <filepath_to_sshkey> root@<public_IP>
```
{: pre}
Install the WireGuard server.

The following steps are specific to VSIs that run Ubuntu. If you run a different Linux distribution, refer to the WireGuard documentation{: external}. {: note}
1. Update the Ubuntu operating system.
```
apt update
```
  {: pre}
```
apt upgrade
```
  {: pre}
2. Check if your VSI requires a reboot to apply the updates.
```
cat /var/run/reboot-required
```
  {: pre}
  
  Example output
```
*** System restart required ***
```
  {: screen}
3. If a reboot is required, reboot the VSI.
```
reboot
```
  {: pre}
4. Wait for the reboot to finish. Then, log in to your VSI again.
```
ssh -i <filepath_to_sshkey> root@<public_IP>
```
  {: pre}
5. Install the WireGuard server.
```
apt install wireguard
```
  {: pre}
Create WireGuard server keys.
1. On your VSI, create a new directory to store your keys.
```
mkdir -p /etc/wireguard/keys
```
  {: pre}
2. Create a private and a public WireGuard server key.
```
wg genkey | tee /etc/wireguard/keys/server.key | wg pubkey | tee /etc/wireguard/keys/server.key.pub
```
  {: pre}
3. Display the public and the private key that you created. Private key:
```
cat /etc/wireguard/keys/server.key
```
  {: pre}
  
  Public key:
```
cat /etc/wireguard/keys/server.key.pub
```
  {: pre}
Retrieve the network interface that your VSI uses to route traffic.
```
ip -o -4 route show to default | awk '{print $5}'
```
{: pre}

Example output
```
ens3
```
{: screen}
Create the WireGuard server configuration.
1. Open the WireGuard server configuration. The configuration is initially empty.
```
nano /etc/wireguard/wg0.conf
```
  {: pre}
2. Add the following content to your configuration. In the Interface section, enter the private key from your WireGuard server that you created and change <eth0> to the network interface that you retrieved earlier. The IP address is a random address within the VPN tunnel that you assign to the WireGuard server.
  
  The server configuration does not yet include the WireGuard client configuration (Peer). You add the client configuration after you set up the WireGuard client on your local machine in a later step. {: note}
```
[Interface]
PrivateKey = <wireguard_server_private_key>
Address = 172.16.0.1/24
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o <eth0> -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o <eth0> -j MASQUERADE
ListenPort = 51820
```
  {: codeblock}
3. Save your changes and exit the nano editor.
4. Change the permissions to your WireGuard configuration and server key file.
```
chmod 600 /etc/wireguard/wg0.conf /etc/wireguard/keys/server.key
```
  {: pre}
Start the WireGuard server.
1. Start the WireGuard server.
```
wg-quick up wg0
```
  {: pre}
2. Show the status of your WireGuard server connections. Note that your output only shows an interface section and no peer section as the WireGuard client is not successfully configured yet.
```
wg show
```
  {: pre}
3. Change the VSI system settings to automatically start the WireGuard server every time the VSI is booted.
```
systemctl enable wg-quick@wg0
```
  {: pre}

Enable IPv4 forwarding on the WireGuard server.

Open the VSI system and network settings.
```
nano /etc/sysctl.conf
```
{: pre}

Remove the comment (#) from the net.ipv4.ip_forward=1 line. Your configuration looks similar to the following:

...
# Uncomment the next line to enable TCP/IP SYN cookies
# See http://lwn.net/Articles/277146/
# Note: This may impact IPv6 TCP sessions too
#net.ipv4.tcp_syncookies=1

# Uncomment the next line to enable packet forwarding for IPv4
net.ipv4.ip_forward=1
...

{: screen}

Enable IPv4 forwarding on your VSI.
```
sysctl -p
```
{: pre}

Retrieve the list of IP addresses that you need to allow in your WireGuard client configuration so that you can successfully connect to your private Kubernetes cluster.
1. Get the details of your cluster and note the Ingress Subdomain and the Private Service Endpoint URL.
```
ibmcloud ks cluster get --cluster <cluster_name_or_ID>
```
  {: pre}
2. Retrieve the IP address that is assigned to the Ingress subdomain and your private service endpoint URL.
```
nslookup <ingress_subdomain>
```
  {: pre}
```
nslookup <private_service_endpoint_URL>
```
  {: pre}
  
  To successfully run an nslookup command on your private service endpoint URL, remove https:// and the port from your URL. Alternatively, you can note all IP address CIDRs for the region that your cluster master is in as shown in step 3 of Opening required ports in a private firewall. {: tip}
3. Get the IP address CIDR of all the VPC subnets, private VLANs, or on-prem networks that your cluster worker nodes are connected to. For example, if you created a VPC cluster in {{site.data.keyword.cloud_notm}}, you can get the subnet CIDR by getting the details for each worker node.
```
ibmcloud ks worker get --worker <worker_ID> --cluster <cluster_name_or_ID>
```
  {: pre}
Install, configure, and activate the WireGuard client.
1. Follow the instructions{: external} to install the WireGuard client on your local machine.
2. Open the client.
3. Click + to create an empty VPN tunnel. A WireGuard private and public key is automatically created for you and displayed in the client configuration.
4. Enter a name for your client configuration.
5. Add the following configuration after the PrivateKey that is displayed in the Interface section. The CIDR 192.168.3.217/32 is a random CIDR that you assign to the client to use within the VPN tunnel.
  
  Do not change the PrivateKey field, which can alter your WireGuard client private key and make the tunnel that you created unusable. {: important}
  
  In the Peer section, enter the following information:
  - PublicKey: The WireGuard server public key that you created earlier.
  - AllowedIPs: The IP address CIDRs of worker nodes, Ingress subdomain, the private service endpoint URL, and the WireGuard server that you retrieved earlier, separated by commas.
  - Endpoint: The public IP address of the jumpbox VSI.
```
Address = 192.168.3.217/32

[Peer]
PublicKey = <public_wireguard_server_key>
AllowedIPs = <worker_CIDR>,<ingress_subdomain_CIDR>,<private_service_endpoint_URL_CIDR>,<wireguard_server_CIDR>
Endpoint = <vsi_public_IP>:51820
```
  {: codeblock}
  
  Your final client configuration looks similar to the following:
```
[Interface]
PrivateKey = aAAA1a1AAAAAaaaaa1aaa1AAAa1AaAAaAaAAAaAaaAa=
Address = 192.168.3.217/32

[Peer]
PublicKey = Aaaa1A1aaaaaaaaa1aaa1AAAa1AaAAAAAAAAAAaAaaAa=
AllowedIPs = 166.9.58.104, 10.241.0.0/24, 172.16.0.1/24
Endpoint = 167.63.170.188:51820
```
  {: codeblock}
6. Save your configuration.
7. Click Activate to start your WireGuard client. If the client is activated successfully, the status changes to Active.
8. Copy the WireGuard client public key.

Finish the WireGuard server configuration.

On your VSI, open the WireGuard server configuration again.
```
nano /etc/wireguard/wg0.conf
```
{: pre}

Add the Peer section to your WireGuard server configuration to add the WireGuard client. Enter the WireGuard client public key in the PublicKey field and the IP address CIDR that you assigned to the client in the AllowedIPs field.

...
[Peer]
PublicKey = <wireguard_client_public_key>
AllowedIPs = 192.168.3.217/32

{: codeblock}

Your server configuration looks similar to the following:

[Interface]
PrivateKey = <wireguard_server_private_key>
Address = 172.16.0.1/24
PostUp = iptables -A FORWARD -i wg0 -j ACCEPT; iptables -t nat -A POSTROUTING -o ens3 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -t nat -D POSTROUTING -o ens3 -j MASQUERADE
ListenPort = 51820

[Peer]
PublicKey = <wireguard_client_public_key>
AllowedIPs = 192.168.3.217/32

{: codeblock}

Stop the WireGuard server and start it again to apply your changes.
```
wg-quick down wg0
```
{: pre}
```
wg-quick up wg0
```
{: pre}

Show the updated status of your WireGuard server connections. The interface and peer connections are displayed in your CLI output.

wg show wg0

{: pre}

Example output

interface: wg0
public key: AA11aa1aa/aa1AaA1AaaaAAAaa1AAaaA1aAAAAaaAAA=
private key: (hidden)
listening port: 51820

peer: a11aAaA+AaaaaaaaA1aAAaAA1/1AaAaAaaAA1AAA/aA=
allowed ips: 192.168.3.217/32

{: screen}

Check that you can connect to the private Kubernetes cluster from your local machine.
1. From the Kubernetes clusters console{: external}, select your private cluster that you want to connect to.
2. On the cluster overview page, go to the Networking section and copy the Ingress subdomain.
3. Ping the Ingress subdomain to verify that you can connect to your private Kubernetes cluster.
4. From the cluster overview page, open the Kubernetes web console.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cluster-access-wireguard.md

cluster-access-wireguard.md

Accessing private clusters by using the WireGuard VPN

Files

cluster-access-wireguard.md

Latest commit

History

cluster-access-wireguard.md

File metadata and controls

Accessing private clusters by using the WireGuard VPN