Documentation
How-to Guides
Kubernetes
Wireguard VPN

Wireguard VPN

Introduction

This page describes how to use the Wireguard VPN add-on to securely connect to your Kubernetes cluster and AWS VPC. While we recommend using Tailscale as full-fledged solution, we also provide Wireguard as a simple, cheaper and self-managed alternative.

Pre-requisites

  • The Wireguard add-on needs to be enabled in your cluster. Please reach out to our support if you want to use Wireguard and it’s not yet enabled in your cluster.
  • You need to have the Wireguard client installed on your local machine. You can find the installation instructions for your platform on the official Wireguard website
  • You need to have the Wireguard configuration file provided by Skyscrapers (first-time) or generated by your internal platform admin

User guide

After installing the Wireguard client, you can import the provided configuration file via the client’s interface. Please remove the original configuration file, once it’s imported.

A wireguard configuration file will usually look like this (without the comments):

[Interface]
# Your private key, with which you authenticate. NEVER SHARE!
PrivateKey = <REDACTED>
# VPN network
Address = 10.240.0.3/32
# EKS cluster's CoreDNS server + additional search domains
# This is used to auto-configure your workstation's DNS settings
DNS = 172.20.0.10, svc.cluster.local, amazonaws.com
MTU = 1420

[Peer]
# The public key of the Wireguard server, with which you authenticate the server
PublicKey = <REDACTED>
# The preshared key, which adds an additional layer of security to the connection. NEVER SHARE!
PresharedKey = <REDACTED>
# The allowed IPs are the IP ranges that will be routed through the VPN. In this case:
# - The VPN CIDR
# - The AWS VPC CIDR
# - The EKS cluster Service CIDR
# This is used to auto-configure your workstation's routing tables
AllowedIPs = 10.240.0.0/24, 10.0.0.0/16, 172.20.0.0/16
# The server's address and port to connect to
Endpoint = wg.<cluster_fqdn>:51820
PersistentKeepalive = 0

When you have your config file, you can import it into your Wireguard client and connect to the VPN. Once connected, you should be able to access your cluster’s private endpoints and resources as if you were on the same network. For example, you can try to access the Kubernetes API server via kubectl or access any internal services running in your cluster.

Wireguard is a simple VPN protocol and traffic-based. When you activate the VPN, you won’t know for sure if your connection is working until you try to access a resource that should be routed through the VPN. Unlike eg. OpenVPN, there’s no real “connection status” that you can check in the client. If you have trouble connecting to your environment, please reach out to our support and provide the steps you’ve taken and any error messages you might have received.

Note

You can not use the same config to have parallel connections as your client’s IP is fixed. You’ll need to ask a separate config for each device you want to connect with. This is also considered a best practice for security reasons, as we can revoke access for a specific device/user combination without affecting the others.

Important

If you make any change to your profile, you can break your VPN connection. Talk to your platform admin before making any changes to your profile and make sure you understand the implications of the changes you want to make.

Admin guide

Enable

First, make sure to enable the Wireguard add-on through the cluster definition spec and deploy through our CI.

spec:
  wireguard:
    enabled: true

The are a couple more optional parameters available, like nodeSelector/tolerations and resource requests. Check our schema reference and example cluster definition for more details.

Managing VPN profiles

We use wg-easy as a simple Wireguard management interface for the platform admin(s).

The UI can be accessed athttps://wg-admin.<cluster_fqdn>, for example https://wg-admin.development.eks.mycompany.com. Initial config will be provided by Skyscrapers, as a valid VPN connection is required to access this admin interface. Please reach out to our support if you want to use Wireguard and it’s not yet enabled in your environment.

Initial credentials to log are admin as username with a randomly generated password. This password can be extracted from the cluster by an admin with access via: kubectl get secrets -n wireguard wireguard-env -o jsonpath='{.data.INIT_PASSWORD}' | base64 --decode. After initial login, this password can be changed in the UI, as well as setting up MFA.

From within this UI you can create VPN profiles for your users, with or without expiry date. You can also disable/enable or revoke existing profiles, which will immediately cut the VPN access for the respective user. The generated profiles will be available for download as conf files, which can be imported into the user’s Wireguard client to establish the VPN connection.

Important

Once you, the customer’s platform admin, change the password and/or setup MFA, Skyscrapers will no longer have access. This means you become responsible of managing the Wireguard server’s configuration and the VPN profiles for your users. Skyscrapers can still guide you through the process, but we won’t be able to access the admin interface to do it for you, unless we reset the whole system. Please make sure you have a backup of your credentials and understand how to manage the Wireguard server before making any changes to the initial config provided by Skyscrapers.

Known issues

Subnet overlap with eg docker-compose

Our EKS clusters use the 172.20.0.0/16 CIDR for it’s Service network and our environment uses 172.20.0.10 as DNS server to resolve both in-cluster and AWS resources.

Unfortunately it is possible that this subnet overlaps with your local ones, in particular when using docker-compose, which creates networks in the 172.[17-31].0.0/24 range. When you encounter problems with DNS-resolution while connected to the VPN, verify your system’s routes for overlap.

As a general guideline, you can either:

Last updated on
OpenVPN