DEV Community: Destiny Obs

Build an Ubuntu WireGuard gateway to access private cloud VMs from your laptop

Destiny Obs — Wed, 04 Nov 2026 10:14:48 +0000

A customer’s virtual machines do not all need public IP addresses for administrators to reach them. One Ubuntu VM can provide the VPN entry point: connect a laptop to WireGuard, then use SSH, RDP or another service directly against each VM’s private IP.

This guide follows that process from creating the private network to logging in to a separate Ubuntu VM over the VPN. It finishes with the complete Python script that automates the gateway configuration, followed by its prompts and expected output. Everything needed to save and run the script is included here.

The implementation was tested with Ubuntu Server 24.04 and a macOS WireGuard client. A successful SSH login to a second private Ubuntu VM confirmed the full path. Windows RDP is included as the equivalent service configuration, but was not part of that live test.

Summary

Build one Ubuntu VPN gateway on a customer’s private cloud LAN, connect a laptop through WireGuard, then reach private VMs directly by IP. This guide covers network creation, gateway preparation, DNS, public access, laptop setup and a real SSH test. The complete automation script and its prompts/output are included at the end; no companion document is required.

What we are building
1. Create the private LAN and router
2. Create the Ubuntu VPN gateway
3. Give the gateway a public VPN endpoint
4. Understand the gateway configuration
5. Prepare the laptop and run the installer
6. Update the laptop tunnel
7. Create a private VM and SSH into it
8. Use the same VPN for Windows RDP and other services
When a connection fails
Before using it for a customer
Complete automated gateway script
Running the script: prompts and expected output
Adding and removing devices after installation

What we are building

The laptop connects to the Ubuntu gateway’s public endpoint. The gateway forwards traffic into the customer LAN, where Linux and Windows VMs keep their private addresses.

There are two separate networks:

Component	Example address or name
Customer private network	`CUSTOMER-LAN`, `10.50.10.0/24`
SDDC router’s LAN address	`10.50.10.1`
Ubuntu VPN gateway’s LAN address	`10.50.10.10`
VPN gateway’s public endpoint	`vpn.example.com:51820`
WireGuard tunnel network	`10.200.50.0/24`
Gateway’s tunnel address	`10.200.50.1`
First laptop’s tunnel address	`10.200.50.2`
Private Linux VM	`10.50.10.20`
Private Windows VM	`10.50.10.30`

Replace these examples with your own addresses. vpn.example.com is a placeholder for a real hostname or public IP. Choose LAN and VPN ranges that do not overlap with each other or with networks already used by the laptop.

Only one private LAN needs to be created in the cloud platform. The WireGuard tunnel network is configured inside WireGuard; it does not need another SDDC virtual network.

This design grants access to the configured customer LAN. VMs on other subnets require additional routing and policy changes. The gateway does not act as an Internet exit for the laptop.

1. Create the private LAN and router

In the cloud or SDDC portal, create a private virtual network named CUSTOMER-LAN with these settings:

Setting	Example value
IPv4 subnet	`10.50.10.0/24`
Gateway	`10.50.10.1`
DHCP	Enabled
DNS	Your provider’s or customer’s DNS servers

Supply DNS through DHCP where possible so new VMs receive working resolver settings. If the customer uses Active Directory, use their internal DNS servers. Otherwise, permitted public resolvers such as 1.1.1.1 and 8.8.8.8 can be used.

Next, create a virtual router. Select the provider’s external network as its external gateway, enable outbound SNAT if the platform requires it, and attach CUSTOMER-LAN as an internal interface. That interface should use 10.50.10.1.

The virtual router provides the LAN’s normal external connectivity. The Ubuntu VPN VM will have its own address, 10.50.10.10. These are different devices and must not share an IP.

Keep 10.50.10.1 as the normal default gateway on workload VMs. The VPN design below does not require changing their default gateway to the Ubuntu VM.

2. Create the Ubuntu VPN gateway

Create a dedicated VM with the following starting configuration:

Setting	Value
Name	`VPN-GW01`
OS	Ubuntu Server 24.04 LTS
CPU	2 vCPUs
RAM	2–4 GB
Disk	20–30 GB
Network	`CUSTOMER-LAN`
Private IP	`10.50.10.10`, reserved or fixed on the VM’s cloud port

Enable OpenSSH during installation, or use the cloud console to install it. Keep console access available while configuring networking. Use a fresh gateway: the automation stops if it detects active UFW, firewalld, Docker or certain existing firewall rules that need manual integration.

On the gateway, check its address, route, DNS and Python:

ip -4 -brief address
ip -4 route
resolvectl status
python3 --version

The LAN interface should have the reserved private IP and a default route through 10.50.10.1. The interface name in this example is enp1s0; use the actual name shown on your VM.

If DNS is missing

During the build, package downloads failed with Temporary failure resolving archive.ubuntu.com. The VM could reach an external IP, but had no working DNS servers.

For an immediate repair on the gateway:

sudo resolvectl dns enp1s0 1.1.1.1 8.8.8.8
sudo resolvectl domain enp1s0 '~.'
sudo resolvectl default-route enp1s0 yes
resolvectl query archive.ubuntu.com

These settings are temporary. For a VM whose existing Netplan entry is enp1s0 with dhcp4: true, make DNS persistent using an overlay:

sudo netplan get
sudo nano /etc/netplan/99-vpn-dns.yaml

Add:

network:
  version: 2
  ethernets:
    enp1s0:
      dhcp4: true
      dhcp4-overrides:
        use-dns: false
      nameservers:
        addresses:
          - 1.1.1.1
          - 8.8.8.8

If the interface name or existing network configuration differs, update the matching entry instead. Keep the existing addressing and routes.

sudo chmod 600 /etc/netplan/99-vpn-dns.yaml
sudo netplan generate
sudo netplan try --timeout 120

Press Enter to accept while connectivity is working. Keep the console open and verify any rollback if the trial fails. Editing /etc/resolv.conf directly may restore DNS temporarily, but the system can overwrite it later.

Verify package access:

resolvectl query archive.ubuntu.com
sudo apt update

Python 3 is normally already present on Ubuntu Server. If it is missing:

sudo apt install -y python3

3. Give the gateway a public VPN endpoint

Assign a floating public IP to the Ubuntu gateway’s private address, 10.50.10.10. If the platform uses an edge firewall instead, forward UDP 51820 from a public address to 10.50.10.10:51820.

If using a hostname, create its DNS record pointing to that public address. Leave the guest NIC configured with its private IP; the cloud platform normally handles the floating-IP translation.

Apply the following security-group or edge-firewall rules:

Location	Rule
VPN gateway inbound	Allow UDP 51820 from the intended clients’ public IPs, or any source for roaming clients
VPN gateway management	Allow TCP 22 only from approved administration sources
VPN gateway outbound	Allow required DNS, package downloads and traffic to the customer LAN
Linux workload inbound	Allow TCP 22 from `10.50.10.10/32`
Windows workload inbound	Allow TCP 3389 from `10.50.10.10/32`; UDP 3389 is optional

Check all groups attached to the VM’s actual interface. In platforms with cumulative allow rules, an unrestricted default group can undermine a restrictive additional group.

The automation configures the Ubuntu guest. The public-IP mapping and cloud security rules remain portal-side tasks.

4. Understand the gateway configuration

The script at the end of this article performs the gateway setup. Read this section to understand what it creates; you do not need to create these configuration files manually before running it.

It installs WireGuard and nftables, generates server keys, assigns 10.200.50.1/24 to wg0, registers the laptop’s public key and enables IPv4 forwarding.

A first device receives 10.200.50.2/32. On the server, its peer configuration permits that device to use only its assigned tunnel address. The laptop configuration routes the customer LAN through the gateway.

The script also configures source NAT. An SSH packet leaves the laptop with source 10.200.50.2 and destination 10.50.10.20:22. Before entering the LAN, its source becomes the gateway’s address, 10.50.10.10. The target replies to the gateway, which translates and encrypts the reply back to the laptop.

That is why workload firewall rules use the gateway’s LAN IP as their source. Individual workload login accounts still identify the user, but target network logs see the NAT address.

Forwarding is allowed for IPv4 services across the configured LAN, not only RDP. Traffic outside that LAN and forwarding between VPN clients are blocked. The script enables systemd startup for WireGuard and its firewall rules.

5. Prepare the laptop and run the installer

Install the official WireGuard client on the laptop. In the app, create an empty tunnel named CustomerVPN-Client. Copy its public key and keep its private key on the laptop.

This is the WireGuard public key, not the SSH public key used to log into a Linux VM. Do not generate another laptop key after registering it unless you also update the server.

On the Ubuntu gateway, create the script file:

nano ~/vpn-gateway.py

Paste the complete Python code at the end of this article, save the file, then run:

sudo python3 ~/vpn-gateway.py install

The installer asks for the public endpoint, LAN CIDR, tunnel CIDR, a device name and the laptop public key. A complete prompt-and-output example appears immediately after the code.

No pip packages are required. The script uses Python’s standard library and installs its OS packages with APT. Once it finishes, it prints the laptop settings, including the new server public key.

6. Update the laptop tunnel

In the laptop’s WireGuard app, edit CustomerVPN-Client. Keep its existing private key and use the address and peer settings printed by the installer:

[Interface]
PrivateKey = YOUR_EXISTING_LAPTOP_PRIVATE_KEY
Address = 10.200.50.2/32

[Peer]
PublicKey = SERVER_PUBLIC_KEY_PRINTED_BY_INSTALLER
Endpoint = vpn.example.com:51820
AllowedIPs = 10.200.50.1/32, 10.50.10.0/24
PersistentKeepalive = 25

Replace the placeholders with actual values. Do not paste a placeholder over your generated private key. If reusing a tunnel from an older gateway, update its peer public key, endpoint and AllowedIPs.

Save and activate the tunnel. The laptop now routes traffic to 10.50.10.0/24 through WireGuard, while ordinary Internet traffic continues using its normal connection.

On macOS, test the gateway tunnel address:

ping -c 4 10.200.50.1

On the Ubuntu gateway, check:

sudo wg show wg0

Look for a recent handshake and traffic in both directions. An Active badge alone does not prove the remote connection works. In the completed test, all four tunnel pings returned successfully with zero loss.

7. Create a private VM and SSH into it

Create a second Ubuntu VM on the same CUSTOMER-LAN. For this example, its address is 10.50.10.20. It does not need a floating public IP, a WireGuard installation or another laptop VPN connection.

Use its console to confirm the address and enable SSH:

# Run on the new private Ubuntu VM
hostname -I
sudo apt update
sudo apt install -y openssh-server
sudo systemctl enable --now ssh
sudo ss -lntp | grep ':22'

The cloud security group must allow TCP 22 from 10.50.10.10/32. If UFW is already active on this workload VM, add the corresponding guest rule:

sudo ufw allow from 10.50.10.10 to any port 22 proto tcp

From the Mac with WireGuard active, connect directly:

ssh appadmin@10.50.10.20

Use the account created on that VM. Verify its host-key fingerprint through the console before accepting a first connection. You can display the target fingerprint on its console with:

sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Our first attempt returned Connection refused. Installing/enabling the SSH server resolved it; the next attempt reached the host-key prompt, accepted authentication and opened the separate VM’s Ubuntu shell.

That login confirmed the complete path: laptop → WireGuard gateway → private workload VM.

New VMs on this subnet are covered by the existing 10.50.10.0/24 client route. They still need their own services, credentials and firewall rules configured.

8. Use the same VPN for Windows RDP and other services

For a Windows VM at 10.50.10.30, enable Remote Desktop, keep Network Level Authentication enabled and grant the intended account permission to sign in remotely.

Allow TCP 3389 from the VPN gateway in the Windows guest firewall and cloud security group. Example in Administrator PowerShell on the Windows workload:

New-NetFirewallRule `
  -DisplayName "RDP from VPN gateway" `
  -Direction Inbound `
  -Action Allow `
  -Protocol TCP `
  -LocalPort 3389 `
  -RemoteAddress 10.50.10.10 `
  -Profile Any

Review existing broader RDP rules as well. With the laptop VPN active, open your RDP client and connect to 10.50.10.30. A public RDP port is not needed.

Web applications and other services follow the same pattern: connect to the private IP, with the service listening and its firewall permitting the gateway’s source. The gateway is not restricted to SSH or RDP.

When a connection fails

Symptom	Check
No handshake	Public endpoint, floating-IP association, UDP 51820 rules and reciprocal public keys
Handshake works but tunnel ping fails	Laptop tunnel address, client routes and gateway firewall
Tunnel ping works but workload times out	Workload LAN attachment, forwarding/NAT, cloud security group and guest firewall
SSH says `Connection refused`	SSH server installation, service/socket and listener on the workload
SSH says `Permission denied`	Workload username, password/SSH key and login policy
Private IP works but hostname does not	Internal DNS server reachability and laptop DNS configuration

For a Linux target, these are the first checks to run in its console:

sudo systemctl status ssh --no-pager
sudo ss -lntp | grep ':22'
sudo ufw status

On the gateway:

sudo customer-vpn status
sudo nft list table inet customer_vpn
sudo journalctl -u wg-quick@wg0 -u customer-vpn-firewall -n 50 --no-pager

Before using it for a customer

The successful test demonstrated the tunnel and SSH access to a separate Ubuntu VM. Test Windows RDP if required, device revocation and access after a planned gateway reboot before handover.

The script enables startup automatically. You can inspect that configuration with:

sudo systemctl is-enabled customer-vpn-firewall.service wg-quick@wg0.service

Keep the gateway IP reserved and back up its secret configuration through your approved process. /etc/customer-vpn/state.json and /etc/wireguard/wg0.conf contain the server private key and must not be published.

This implementation supports one customer IPv4 LAN and a /24 VPN pool. All enrolled devices share that LAN access. It does not configure MFA, high availability or per-user destination restrictions. Its host firewall preserves normal non-VPN access, so retain the cloud-side restrictions on public services. Re-running install preserves existing settings and peers; it does not prompt to change the stored network or endpoint.

Complete automated gateway script

Save the following code as vpn-gateway.py on a fresh Ubuntu gateway. It installs and configures WireGuard, forwarding, LAN NAT, startup services and the first device. It also installs the customer-vpn command for adding and revoking later devices.

The endpoint prompt defaults to the example vpn.example.com; enter your real endpoint when asked. The public example default is the only change from the script used in the successful deployment.

#!/usr/bin/env python3
"""Dedicated Ubuntu WireGuard gateway. sudo python3 vpn-gateway.py install
Commands: install, add-peer, revoke-peer NAME, client NAME, status, firewall.
All VPN peers may initiate any IPv4 protocol to the configured customer LAN.
Does not expose the whole SDDC or provide an Internet exit VPN.
"""
import argparse
import base64
import fcntl
import ipaddress
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import sys
import tempfile

ROOT = Path('/etc/customer-vpn')
STATE = ROOT / 'state.json'
WG = Path('/etc/wireguard/wg0.conf')
SELF = Path('/usr/local/sbin/customer-vpn')
TABLE = 'customer_vpn'

def run(*args, data=None, check=True):
    return subprocess.run(args, input=data, text=True, stdout=subprocess.PIPE,
                          stderr=subprocess.PIPE, check=check).stdout.strip()

def put(path, text, mode=0o600):
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    fd, name = tempfile.mkstemp(dir=path.parent)
    try:
        os.fchmod(fd, mode)
        with os.fdopen(fd, 'w') as out:
            out.write(text)
            out.flush()
            os.fsync(out.fileno())
        os.replace(name, path)
    finally:
        if os.path.exists(name):
            os.unlink(name)

def ask(label, default=None):
    value = input(label + (f' [{default}]' if default else '') + ': ').strip()
    value = value or default
    if not value:
        raise ValueError('A value is required.')
    return value

def pubkey(value):
    if len(base64.b64decode(value, validate=True)) != 32:
        raise ValueError('WireGuard public key must decode to 32 bytes.')
    return value

def peername(value):
    if not re.fullmatch(r'[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}', value):
        raise ValueError('Device name: 1–32 letters, digits, hyphens or underscores.')
    return value

def endpoint(value):
    try:
        ipaddress.IPv4Address(value)
    except ValueError:
        if not re.fullmatch(r'(?=.{1,253}$)[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?', value):
            raise ValueError('Enter a public IPv4 address or DNS hostname, without a port.')
    return value

def validate_networks(lan, tunnel):
    a, b = ipaddress.IPv4Network(lan), ipaddress.IPv4Network(tunnel)
    if a.overlaps(b) or b.prefixlen != 24:
        raise ValueError('VPN must be a /24 and must not overlap the customer LAN.')
    return a, b

def load():
    if not STATE.exists():
        raise ValueError('Run install first.')
    return json.loads(STATE.read_text())

def config(s):
    lines = ['[Interface]', f"PrivateKey = {s['private_key']}",
             f"Address = {s['gateway']}/24", f"ListenPort = {s['port']}", '']
    for name, p in sorted(s['peers'].items()):
        lines += [f'# {name}', '[Peer]', f"PublicKey = {p['key']}",
                  f"AllowedIPs = {p['ip']}/32", '']
    return '\n'.join(lines) + '\n'

def rules(s):
    lan, vpn, iface = s['lan'], s['vpn'], s['interface']
    # Only own table is replaced. Other host input/output rules remain untouched.
    return f'''table inet {TABLE} {{
 chain input {{
  type filter hook input priority -10; policy accept;
  iifname "wg0" ip saddr {vpn} meta l4proto icmp counter accept
  iifname "wg0" ip saddr {vpn} tcp dport 22 counter accept
  iifname "wg0" counter drop
  udp dport {s['port']} counter accept
 }}
 chain forward {{
  type filter hook forward priority -10; policy accept;
  iifname "wg0" oifname "{iface}" ip saddr {vpn} ip daddr {lan} ct state new,established,related counter accept
  iifname "{iface}" oifname "wg0" ip saddr {lan} ip daddr {vpn} ct state established,related counter accept
  iifname "wg0" counter drop
  oifname "wg0" counter drop
 }}
 chain postrouting {{
  type nat hook postrouting priority srcnat; policy accept;
  oifname "{iface}" ip saddr {vpn} ip daddr {lan} counter masquerade
 }}
}}
'''

def firewall(s):
    exists = subprocess.run(['nft', 'list', 'table', 'inet', TABLE],
                            stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode == 0
    transaction = (f'delete table inet {TABLE}\n' if exists else '') + rules(s)
    run('nft', '-c', '-f', '-', data=transaction)
    run('nft', '-f', '-', data=transaction)

def sync():
    stripped = run('wg-quick', 'strip', 'wg0')
    fd, path = tempfile.mkstemp(dir=ROOT)
    try:
        with os.fdopen(fd, 'w') as out:
            out.write(stripped + '\n')
        run('wg', 'syncconf', 'wg0', path)
    finally:
        os.unlink(path)

def commit(s, live=True):
    old_state = STATE.read_text() if STATE.exists() else None
    old_wg = WG.read_text() if WG.exists() else None
    if old_state:
        put(ROOT / 'state.previous.json', old_state)
    try:
        put(WG, config(s))
        if live:
            sync()
        put(STATE, json.dumps(s, indent=2) + '\n')
    except Exception:
        if old_wg is not None:
            put(WG, old_wg)
            if live:
                sync()
        if old_state is not None:
            put(STATE, old_state)
        raise

def allocate(s, name, key):
    peername(name)
    pubkey(key)
    if key == s['public_key']:
        raise ValueError('Use the laptop public key, not the server public key.')
    for n, p in s['peers'].items():
        if p['key'] == key and n != name:
            raise ValueError('This key already belongs to another device.')
    if name in s['peers']:
        if s['peers'][name]['key'] != key:
            raise ValueError('Name already exists with another key. Revoke it first.')
        return
    used = {p['ip'] for p in s['peers'].values()} | {s['gateway']}
    for ip in ipaddress.IPv4Network(s['vpn']).hosts():
        if str(ip) not in used:
            s['peers'][name] = {'key': key, 'ip': str(ip)}
            return
    raise ValueError('VPN address pool is full.')

def client(s, name):
    p = s['peers'].get(name)
    if p is None:
        raise ValueError('Unknown device name.')
    print(f'''\nKeep your laptop's EXISTING PrivateKey line. Use the settings below.
Do not import the placeholder literally.

[Interface]
PrivateKey = KEEP_YOUR_LAPTOP_PRIVATE_KEY
Address = {p['ip']}/32

[Peer]
PublicKey = {s['public_key']}
Endpoint = {s['endpoint']}:{s['port']}
AllowedIPs = {s['gateway']}/32, {s['lan']}
PersistentKeepalive = 25
''')

def preflight():
    release = Path('/etc/os-release').read_text()
    if not re.search(r'^ID=ubuntu$', release, re.M) or not re.search(r'^VERSION_ID="?(22.04|24.04)"?$', release, re.M):
        raise ValueError('Supported: Ubuntu Server 22.04 or 24.04 LTS.')
    if shutil.which('ufw') and 'Status: active' in run('ufw', 'status'):
        raise ValueError('Active UFW detected. Integrate it separately; this installer will not disable it.')
    for service in ('docker', 'firewalld'):
        if subprocess.run(['systemctl', 'is-active', '--quiet', service]).returncode == 0:
            raise ValueError(f'Active {service} detected. Use a dedicated gateway.')
    if WG.exists() and not STATE.exists():
        raise ValueError('Unmanaged wg0.conf exists. Refusing to overwrite it.')

def install():
    preflight()
    if STATE.exists():
        s = load()
        print('Existing installation found. Keeping server keys and devices.')
    else:
        public = endpoint(ask('Floating public IPv4 or VPN hostname', 'vpn.example.com'))
        lan = ask('Customer LAN CIDR', '10.50.10.0/24')
        vpn = ask('VPN tunnel CIDR (must not overlap laptop networks)', '10.200.50.0/24')
        lan_net, vpn_net = validate_networks(lan, vpn)
        route = json.loads(run('ip', '-j', '-4', 'route', 'get', str(next(lan_net.hosts()))))[0]
        iface = route['dev']
        if not re.fullmatch(r'[a-zA-Z0-9_.:-]+', iface):
            raise ValueError('Unsupported interface name.')
        addresses = json.loads(run('ip', '-j', '-4', 'address', 'show', 'dev', iface))
        local = [a['local'] for item in addresses for a in item['addr_info'] if a['family'] == 'inet']
        if not any(ipaddress.IPv4Address(a) in lan_net for a in local):
            raise ValueError('No address on customer LAN. Correct the VM network first.')
        for item in json.loads(run('ip', '-j', '-4', 'address', 'show')):
            for addr in item.get('addr_info', []):
                if addr.get('family') == 'inet':
                    connected = ipaddress.IPv4Network(f"{addr['local']}/{addr['prefixlen']}", strict=False)
                    if connected.overlaps(vpn_net):
                        raise ValueError('VPN range overlaps an existing server network.')
        name = peername(ask('First device name', 'my-laptop'))
        key = pubkey(ask('Paste the LAPTOP public key (never its private key)'))
        s = {'endpoint': public, 'lan': str(lan_net), 'vpn': str(vpn_net),
             'gateway': str(next(vpn_net.hosts())), 'interface': iface, 'port': 51820, 'peers': {}}
        print(f"LAN interface: {iface}; VM IPs: {', '.join(local)}")
    env = dict(os.environ, DEBIAN_FRONTEND='noninteractive')
    subprocess.run(['apt-get', 'update'], check=True, env=env)
    subprocess.run(['apt-get', 'install', '-y', 'wireguard', 'nftables'], check=True, env=env)
    # Refuse conflicting rule managers rather than pretending accept overrides drop.
    tables = json.loads(run('nft', '-j', 'list', 'tables'))['nftables']
    other = [x['table']['name'] for x in tables if 'table' in x and x['table']['name'] != TABLE]
    if other:
        raise ValueError('Existing nftables tables found: ' + ', '.join(other) + '. Use a clean gateway or integrate rules manually.')
    if shutil.which('iptables-save'):
        saved = run('iptables-save')
        if re.search(r'^-A |^:\S+ DROP ', saved, re.M):
            raise ValueError('Existing iptables filtering detected; manual integration required.')
    run('modprobe', 'wireguard')
    ROOT.mkdir(mode=0o700, parents=True, exist_ok=True)
    os.chmod(ROOT, 0o700)
    WG.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
    if not STATE.exists():
        s['private_key'] = run('wg', 'genkey')
        s['public_key'] = run('wg', 'pubkey', data=s['private_key'] + '\n')
        allocate(s, name, key)
        commit(s, live=False)
    source = Path(__file__).resolve()
    if source != SELF:
        put(SELF, source.read_text(), 0o700)
    put('/etc/sysctl.d/90-customer-vpn.conf', 'net.ipv4.ip_forward = 1\n')
    run('sysctl', '-p', '/etc/sysctl.d/90-customer-vpn.conf')
    put('/etc/systemd/system/customer-vpn-firewall.service', '''[Unit]
Description=Customer VPN firewall (own table only)
After=network-online.target nftables.service
Wants=network-online.target
Before=wg-quick@wg0.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/customer-vpn firewall
ExecReload=/usr/local/sbin/customer-vpn firewall
[Install]
WantedBy=multi-user.target
''', 0o644)
    put('/etc/systemd/system/wg-quick@wg0.service.d/customer-vpn.conf', '''[Unit]
Requires=customer-vpn-firewall.service
After=customer-vpn-firewall.service
''', 0o644)
    run('systemctl', 'daemon-reload')
    # The firewall subprocess takes the same lock; parent releases it beforehand.
    run('systemctl', 'enable', 'customer-vpn-firewall.service', 'wg-quick@wg0.service')
    firewall(s)
    print('Configuration written. Starting services after releasing installer lock.')
    return s

def status(s):
    print('Customer LAN:', s['lan'], '| LAN interface:', s['interface'])
    print('Endpoint:', f"{s['endpoint']}:{s['port']}")
    print('Server public key:', s['public_key'])
    for n, p in s['peers'].items():
        print('Device:', n, '| VPN IP:', p['ip'])
    print(run('wg', 'show', 'wg0'))
    print('IPv4 forwarding:', run('sysctl', '-n', 'net.ipv4.ip_forward'))
    print('Handshake and service reachability still require a connected laptop test.')

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('command', choices=['install', 'add-peer', 'revoke-peer', 'client', 'status', 'firewall'])
    parser.add_argument('name', nargs='?')
    args = parser.parse_args()
    if os.geteuid() != 0:
        raise ValueError('Run with sudo.')
    os.umask(0o077)
    lock = open('/run/customer-vpn.lock', 'w')
    fcntl.flock(lock, fcntl.LOCK_EX)
    if args.command == 'install':
        s = install()
        fcntl.flock(lock, fcntl.LOCK_UN)
        # dependency invokes this script's firewall command, which acquires the lock
        run('systemctl', 'start', 'customer-vpn-firewall.service')
        run('systemctl', 'start', 'wg-quick@wg0.service')
        sync()
        status(s)
        for name in s['peers']:
            client(s, name)
        return
    s = load()
    if args.command == 'firewall':
        firewall(s)
    elif args.command == 'status':
        status(s)
    elif args.command == 'client':
        client(s, args.name or ask('Device name'))
    elif args.command == 'add-peer':
        name = peername(args.name or ask('Device name'))
        allocate(s, name, pubkey(ask('Laptop public key')))
        commit(s)
        client(s, name)
    elif args.command == 'revoke-peer':
        name = args.name or ask('Device name to revoke')
        if name not in s['peers']:
            raise ValueError('Unknown device name.')
        del s['peers'][name]
        commit(s)
        print('Revoked:', name)

if __name__ == '__main__':
    try:
        main()
    except (ValueError, OSError, subprocess.CalledProcessError) as exc:
        # Never print command stdin or state: these can contain private keys.
        if isinstance(exc, subprocess.CalledProcessError):
            print('ERROR:', exc.cmd[0], 'failed:', exc.stderr or 'check service logs', file=sys.stderr)
        else:
            print('ERROR:', exc, file=sys.stderr)
        sys.exit(1)

Running the script: prompts and expected output

Run this on the Ubuntu gateway after saving the code:

sudo python3 ~/vpn-gateway.py install

The following is an illustrative transcript. Addresses and key placeholders are examples; package versions and interface names depend on the VM.

Prompt 1: the public endpoint

Floating public IPv4 or VPN hostname [vpn.example.com]: YOUR_REAL_PUBLIC_IP_OR_HOSTNAME

Enter the public address assigned to this Ubuntu VM, or a hostname that resolves to it. Do not enter the private LAN address. If the cloud platform uses port forwarding, enter the public address on that mapping.

Prompt 2: the customer LAN

Customer LAN CIDR [10.50.10.0/24]: 10.50.10.0/24

Enter the subnet containing the gateway and the customer’s workload VMs. Press Enter to accept the example only if it matches the actual LAN.

Prompt 3: the WireGuard subnet

VPN tunnel CIDR (must not overlap laptop networks) [10.200.50.0/24]:

Press Enter to use 10.200.50.0/24, or enter another non-overlapping /24. This is the tunnel address pool, not another cloud LAN to create. The script uses its first usable address for the gateway and allocates subsequent addresses to devices.

Prompt 4: the first device name

First device name [my-laptop]: admin-mac-1

Choose a recognizable inventory name. Names accept 1–32 letters, digits, hyphens and underscores, starting with a letter or digit.

Prompt 5: the laptop public key

Paste the LAPTOP public key (never its private key): YOUR_LAPTOP_WIREGUARD_PUBLIC_KEY

Paste the actual public key shown by the laptop’s WireGuard client. The placeholder above is not a valid key. The script checks the key format; the laptop must retain the matching private key.

Automatic installation

After the last answer, no additional configuration input is required. The installer detects the LAN interface, updates APT indexes and installs WireGuard/nftables. Typical progress includes:

LAN interface: enp1s0; VM IPs: 10.50.10.10
Hit:1 ... noble InRelease
Reading package lists... Done
...
Setting up wireguard-tools ...
Setting up wireguard ...
Configuration written. Starting services after releasing installer lock.

APT may also report updates, pending kernel changes or deferred service restarts. Read those messages, but distinguish them from an installer error. If a reboot is needed, schedule it after configuration and repeat the VPN/workload tests afterward.

If a preflight check stops the installation, the message identifies the issue. For example:

ERROR: Active UFW detected. Integrate it separately; this installer will not disable it.

Use a dedicated gateway or deliberately integrate existing rules. Do not remove firewall protection just to bypass the check. Installation failures can leave packages or partial configuration present, so inspect the error before retrying.

Completion output

A completed installation prints a summary like this:

Customer LAN: 10.50.10.0/24 | LAN interface: enp1s0
Endpoint: YOUR_REAL_PUBLIC_IP_OR_HOSTNAME:51820
Server public key: GENERATED_SERVER_PUBLIC_KEY
Device: admin-mac-1 | VPN IP: 10.200.50.2
interface: wg0
  public key: GENERATED_SERVER_PUBLIC_KEY
  private key: (hidden)
  listening port: 51820

peer: YOUR_LAPTOP_WIREGUARD_PUBLIC_KEY
  allowed ips: 10.200.50.2/32
IPv4 forwarding: 1
Handshake and service reachability still require a connected laptop test.

The actual output contains real public keys. The server private key is not printed. A missing handshake at this stage is normal if the laptop has not yet been updated and activated.

Laptop configuration printed by the script

The installer then prints:

[Interface]
PrivateKey = KEEP_YOUR_LAPTOP_PRIVATE_KEY
Address = 10.200.50.2/32

[Peer]
PublicKey = GENERATED_SERVER_PUBLIC_KEY
Endpoint = YOUR_REAL_PUBLIC_IP_OR_HOSTNAME:51820
AllowedIPs = 10.200.50.1/32, 10.50.10.0/24
PersistentKeepalive = 25

Apply this to the laptop tunnel, keeping its actual existing private key. KEEP_YOUR_LAPTOP_PRIVATE_KEY is an instruction placeholder, not a usable value.

After activating the client and testing traffic, sudo wg show wg0 should include a recent latest handshake, a learned client endpoint and transfer counters. The subsequent SSH login to a separate private VM confirms LAN access beyond the VPN gateway.

Running installation again

On a managed installation, the script reports:

Existing installation found. Keeping server keys and devices.

It reapplies the stored setup and prints the existing device templates. It does not regenerate server keys or ask again for the endpoint/network settings. This prevents a routine rerun from unexpectedly replacing the identity already configured on laptops.

Adding and removing devices after installation

The installer makes the management command available as customer-vpn. Run it on the Ubuntu gateway.

Add a device

sudo customer-vpn add-peer customer-laptop-2

It asks:

Laptop public key: SECOND_LAPTOP_WIREGUARD_PUBLIC_KEY

The command allocates the next unused tunnel IP and prints that device’s client template. If 10.200.50.2 is already assigned, a new device will normally receive 10.200.50.3/32. Keep the second laptop’s own private key when applying its settings.

Using an already registered name with the same key retains that peer. A duplicate key under a different name, or an existing name with a different key, produces an error instead of silently replacing another device.

Display a device’s settings again

sudo customer-vpn client customer-laptop-2

This prints the template for that device without asking for its key again. The template contains a placeholder for the private key because the gateway never needs the laptop’s private key.

Revoke a device

sudo customer-vpn revoke-peer customer-laptop-2

Expected confirmation:

Revoked: customer-laptop-2

This removes its peer from the saved and running WireGuard configuration. It is an allow-list/revocation mechanism, not a separate permanent blocklist. Test that the removed device can no longer access the LAN. Adding and revoking devices expects the gateway tunnel to be running.

Check status or reapply the gateway firewall

sudo customer-vpn status
sudo customer-vpn firewall

status prints the LAN, endpoint, registered devices, WireGuard interface and forwarding state. firewall reapplies the script-owned nftables table and normally returns without output on success. Neither command modifies the provider’s security groups or public-IP mapping.

With the gateway configured, everyday use is straightforward: activate WireGuard on the laptop, then connect directly to a workload’s private IP using SSH, RDP or its application client.

The Complete Beginner's Guide to vpcctl: Building Virtual Networks on Linux

Destiny Obs — Tue, 11 Nov 2025 08:20:11 +0000

A hands-on, beginner-friendly guide to understanding Virtual Private Clouds and building isolated networks on a single Linux machine

Introduction: What Problem Are We Solving?
Understanding the Basics
- What is a VPC?
- What is a Subnet?
- What is NAT?
- What is Peering?
Real-World Scenario: The Coffee Shop Network
How vpcctl Works Under the Hood
Prerequisites and Installation
Quick Start: Your First VPC
Deep Dive: Understanding Each Command
Architecture Overview
Command Reference
Advanced Scenarios
Troubleshooting Common Issues
Complete Code Reference
Best Practices
Learning Resources
Credits

Introduction: What Problem Are We Solving?

Imagine you're a developer working on a web application with:

A web server that customers access
A database that stores customer data
An admin panel for internal staff

You want to:

Isolate your database so random people on the internet can't access it
Allow your web server to talk to the database
Control which ports and services are accessible from outside
Test everything locally before deploying to the cloud

Cloud providers (AWS, Azure, Google Cloud) solve this with VPCs (Virtual Private Clouds). vpcctl lets you simulate VPCs locally on Linux using native networking features.

Understanding the Basics

What is a VPC?

VPC stands for Virtual Private Cloud. It's a logically isolated network where you control IP ranges, routing, internet access, and security rules. Think of it like an office building where you control entrances, floors, and WiFi.

What is a Subnet?

A subnet is a smaller network inside your VPC with its own IP range and purpose (e.g., public web, private database). Common types:

Public subnet: can reach the internet and may accept inbound traffic
Private subnet: no direct internet access; used for internal services

What is NAT?

NAT (Network Address Translation) lets private subnets access the internet without exposing them. Like a hotel reception calling restaurants on behalf of guests—responses come back via reception.

What is Peering?

Peering connects two VPCs so they can talk privately. Useful for connecting apps across isolated networks while allowing only specific subnets to communicate.

Real-World Scenario: The Coffee Shop Network

Picture a coffee shop:

Customer Area = Public subnet (internet access, open to customers)
Kitchen = Private subnet (staff-only, no direct internet from outside)
Office = Another private subnet (admin-only)

Translating to vpcctl, creating a VPC is like building that coffee shop; adding subnets creates the areas; NAT is the WiFi router; firewall rules control who gets in.

How vpcctl Works Under the Hood

vpcctl uses Linux primitives:

Network namespaces: isolated network environments per subnet
veth pairs: virtual cables connecting namespaces to the VPC
Linux bridges: the VPC switch interconnecting subnets
iptables: firewall rules, NAT, and peering enforcement

Prerequisites and Installation

System Requirements

Linux (Ubuntu 20.04+/Debian 10+ recommended). Use WSL/VM on Windows if needed.
Root access (sudo) required
Tools: Python 3.6+, iproute2 (ip), iptables, curl, tcpdump, bridge-utils

Install Steps

1) Install required packages

sudo apt update
sudo apt install -y python3 iproute2 iptables curl tcpdump bridge-utils
# CentOS/RHEL: sudo yum install -y python3 iproute iptables curl tcpdump bridge-utils

2) Get vpcctl

git clone https://github.com/DestinyObs/HNGi13-Stage4-vpcctl
cd HNGi13-Stage4-vpcctl

3) Make it available as a command

chmod +x vpcctl.py
sudo ln -s "$(pwd)/vpcctl.py" /usr/local/bin/vpcctl
vpcctl --help
sudo vpcctl flag-check  # safe: validates parser only

Quick Start: Your First VPC

We'll use these consistent names and CIDRs everywhere:

myvpc: 10.10.0.0/16
- public: 10.10.1.0/24
- private: 10.10.2.0/24
othervpc: 10.20.0.0/16
- public: 10.20.1.0/24

Step 0: One-Time Checks

sudo vpcctl --help | head -n 5
sudo vpcctl flag-check

Step 1: Create the VPC

sudo vpcctl create myvpc --cidr 10.10.0.0/16

Step 2: Add Subnets

sudo vpcctl add-subnet myvpc public  --cidr 10.10.1.0/24
sudo vpcctl add-subnet myvpc private --cidr 10.10.2.0/24

Step 3: Deploy Test Apps

sudo vpcctl deploy-app myvpc public  --port 8080
sudo vpcctl deploy-app myvpc private --port 8081

Step 4: Enable NAT (Internet Access for public)

IFACE=$(ip route get 1.1.1.1 | awk '{print $5; exit}')
echo "Using host interface: $IFACE"
sudo vpcctl enable-nat myvpc --interface "$IFACE"

Step 5: Test Connectivity

# Private -> Public (intra-VPC)
sudo ip netns exec ns-myvpc-private curl -s http://10.10.1.2:8080 | head -n 1

# Public -> Internet (NAT)
sudo ip netns exec ns-myvpc-public curl -I http://1.1.1.1 | head -5 

# Host -> Private (should fail)
curl -s --connect-timeout 2 http://10.10.2.2:8081 || echo "private not reachable from host (expected)"

Step 6: Show VPC Isolation

sudo vpcctl create othervpc --cidr 10.20.0.0/16
sudo vpcctl add-subnet othervpc public --cidr 10.20.1.0/24
sudo vpcctl deploy-app othervpc public --port 8080
sudo ip netns exec ns-myvpc-public curl -s --connect-timeout 2 http://10.20.1.2:8080 || echo "blocked by default (expected)"

Step 7: Peer VPCs (Allow Only Public↔Public)

sudo vpcctl peer myvpc othervpc --allow-cidrs 10.10.1.0/24,10.20.1.0/24
sudo ip netns exec ns-myvpc-public curl -s http://10.20.1.2:8080 | head -n 1

Step 8: Apply Security Policy

sudo vpcctl apply-policy myvpc policy_examples/example_ingress_egress_policy.json

Step 9: Inspect and List

sudo vpcctl list
sudo vpcctl inspect myvpc | head -n 30

Step 10: Cleanup

sudo vpcctl delete othervpc
sudo vpcctl delete myvpc
sudo vpcctl list

Deep Dive: Understanding Each Command

Below are the key commands and what happens under the hood.

create

Command

sudo vpcctl create myvpc --cidr 10.10.0.0/16

What happens

Creates a Linux bridge br-myvpc and assigns 10.10.0.1/16
Enables routing and prepares an iptables chain vpc-myvpc
Records metadata to .vpcctl_data/vpc_myvpc.json

Under the hood

Creates a Linux bridge device (br-myvpc) and brings it up
Assigns the VPC gateway IP to the bridge interface and enables IPv4 forwarding (sysctl)
Creates/uses a dedicated host iptables chain (vpc-myvpc) to keep VPC rules isolated and easy to clean up

Example commands

# Create bridge for the VPC and assign gateway IP
sudo ip link add name br-myvpc type bridge
sudo ip addr add 10.10.0.1/16 dev br-myvpc
sudo ip link set br-myvpc up

# Enable kernel forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# Create isolated chain for VPC rules and hook into FORWARD
sudo iptables -N vpc-myvpc 2>/dev/null || true
sudo iptables -C FORWARD -j vpc-myvpc 2>/dev/null || sudo iptables -A FORWARD -j vpc-myvpc

add-subnet

Command

sudo vpcctl add-subnet myvpc public --cidr 10.10.1.0/24

What happens

Creates namespace ns-myvpc-public
Creates a veth pair; one end attaches to br-myvpc, the other goes into the namespace
Assigns 10.10.1.1/24 to the bridge and 10.10.1.2/24 inside the namespace; sets default route via 10.10.1.1

Under the hood

Adds a network namespace (ns-myvpc-public) and a veth pair (host end on br-myvpc, peer moved into the namespace)
Configures IP addresses on both ends and sets the subnet's default route to the VPC bridge gateway
Ensures interfaces are up and connected via the bridge for L2 switching between subnets in the same VPC

Example commands (public subnet 10.10.1.0/24)

# Create namespace and veth pair
sudo ip netns add ns-myvpc-public
sudo ip link add v-myvpc-public type veth peer name v-myvpc-public-ns

# Attach host end to the VPC bridge
sudo ip link set v-myvpc-public master br-myvpc
sudo ip link set v-myvpc-public up

# Move peer into the namespace and configure IPs
sudo ip link set v-myvpc-public-ns netns ns-myvpc-public
sudo ip addr add 10.10.1.1/24 dev br-myvpc
sudo ip netns exec ns-myvpc-public ip addr add 10.10.1.2/24 dev v-myvpc-public-ns
sudo ip netns exec ns-myvpc-public ip link set lo up
sudo ip netns exec ns-myvpc-public ip link set v-myvpc-public-ns up
sudo ip netns exec ns-myvpc-public ip route add default via 10.10.1.1

deploy-app

Command

sudo vpcctl deploy-app myvpc public --port 8080

What happens

Runs python3 -m http.server PORT in the target namespace
Captures PID and stores it in metadata for reliable stop/cleanup

Under the hood

Executes the HTTP server with ip netns exec so the process is fully inside the subnet namespace
Starts the server in the background and records its PID/command so it can be stopped and cleaned up deterministically

Example commands (serve 8080 from ns-myvpc-public)

sudo ip netns exec ns-myvpc-public nohup python3 -m http.server 8080 \
  > /tmp/ns-myvpc-public-8080.log 2>&1 &
echo $!  # PID recorded to metadata

stop-app

Command

sudo vpcctl stop-app myvpc public

What happens

Looks up the PID from metadata and terminates the app in the namespace
Updates metadata

Under the hood

Reads the stored PID/command and sends a graceful SIGTERM; falls back to stronger signals if needed
Removes the application entry from the VPC metadata to keep state consistent

Example commands

sudo kill -TERM <PID>
# If needed after timeout: sudo kill -KILL <PID>

enable-nat

Command

sudo vpcctl enable-nat myvpc --interface eth0

What happens

Enables IPv4 forwarding
Adds NAT (MASQUERADE) and FORWARD rules to let selected subnets reach the internet via the host interface

Under the hood

Turns on kernel routing (net.ipv4.ip_forward=1)
Installs an iptables NAT POSTROUTING MASQUERADE rule on the chosen egress interface, scoped to the VPC/subnets
Adds FORWARD rules to permit established/related return traffic, keeping the ruleset minimal and safe

Example commands (egress via $IFACE)

IFACE=$(ip route | awk '/default/ {print $5; exit}')
sudo sysctl -w net.ipv4.ip_forward=1

# NAT for the VPC CIDR
sudo iptables -t nat -C POSTROUTING -s 10.10.0.0/16 -o "$IFACE" -j MASQUERADE \
  2>/dev/null || sudo iptables -t nat -A POSTROUTING -s 10.10.0.0/16 -o "$IFACE" -j MASQUERADE

# Forwarding rules: allow outbound and established return
sudo iptables -C FORWARD -i br-myvpc -o "$IFACE" -j ACCEPT \
  2>/dev/null || sudo iptables -A FORWARD -i br-myvpc -o "$IFACE" -j ACCEPT
sudo iptables -C FORWARD -i "$IFACE" -o br-myvpc -m state --state RELATED,ESTABLISHED -j ACCEPT \
  2>/dev/null || sudo iptables -A FORWARD -i "$IFACE" -o br-myvpc -m state --state RELATED,ESTABLISHED -j ACCEPT

peer

Command

sudo vpcctl peer myvpc othervpc --allow-cidrs 10.10.1.0/24,10.20.1.0/24

What happens

Creates a veth pair connecting br-myvpc and br-othervpc
Adds iptables rules to allow only the specified CIDR pairs; everything else remains blocked

Under the hood

Connects the two VPC bridges with a veth pair to provide L2 reachability between VPCs
Adds explicit host-level iptables rules to allow only the permitted CIDR ranges; a final DROP ensures least-privilege

Example commands (peer myvpc ↔ othervpc, allow public↔public only)

# Wire the bridges with a veth pair
sudo ip link add pv-myvpc-otherv-a type veth peer name pv-myvpc-otherv-b
sudo ip link set pv-myvpc-otherv-a master br-myvpc
sudo ip link set pv-myvpc-otherv-b master br-othervpc
sudo ip link set pv-myvpc-otherv-a up
sudo ip link set pv-myvpc-otherv-b up

# Allow only specific CIDR pairs
sudo iptables -C vpc-myvpc   -s 10.10.1.0/24 -d 10.20.1.0/24 -j ACCEPT 2>/dev/null \
  || sudo iptables -A vpc-myvpc   -s 10.10.1.0/24 -d 10.20.1.0/24 -j ACCEPT
sudo iptables -C vpc-othervpc -s 10.20.1.0/24 -d 10.10.1.0/24 -j ACCEPT 2>/dev/null \
  || sudo iptables -A vpc-othervpc -s 10.20.1.0/24 -d 10.10.1.0/24 -j ACCEPT
# (Default-deny handled by chain policy or fallback rules)

apply-policy

Command

sudo vpcctl apply-policy myvpc policy_examples/example_ingress_egress_policy.json

What happens

Parses JSON and applies ingress/egress rules with iptables inside the target subnet namespace
Uses rule comments to stay idempotent on re-apply

Under the hood

Enters the subnet namespace and writes INPUT/OUTPUT rules with iptables
Uses consistent comments/tags so re-applying the same policy updates rules without duplication

Example commands (inside ns-myvpc-public)

# Allow HTTP/HTTPS, deny SSH
sudo ip netns exec ns-myvpc-public iptables -C INPUT -p tcp --dport 80  -j ACCEPT 2>/dev/null \
  || sudo ip netns exec ns-myvpc-public iptables -A INPUT -p tcp --dport 80  -j ACCEPT -m comment --comment vpcctl:allow-80
sudo ip netns exec ns-myvpc-public iptables -C INPUT -p tcp --dport 443 -j ACCEPT 2>/dev/null \
  || sudo ip netns exec ns-myvpc-public iptables -A INPUT -p tcp --dport 443 -j ACCEPT -m comment --comment vpcctl:allow-443
sudo ip netns exec ns-myvpc-public iptables -C INPUT -p tcp --dport 22  -j DROP   2>/dev/null \
  || sudo ip netns exec ns-myvpc-public iptables -A INPUT -p tcp --dport 22  -j DROP   -m comment --comment vpcctl:deny-22

list / inspect / delete

list: shows all VPCs (based on metadata files)
inspect: pretty-prints full metadata (subnets, apps, NAT, peers, policies)
delete: stops apps, removes namespaces, veths, bridge, and rules; then deletes metadata

Under the hood

list: enumerates JSON files in .vpcctl_data to discover VPCs
inspect: reads and pretty-prints the VPC's metadata to reflect actual state
delete: reverses creation steps in a safe order (stop apps → tear down rules → remove namespaces/veths → delete bridge → purge metadata)

Example commands

# list
ls -1 .vpcctl_data | sed -n 's/^vpc_\(.*\)\.json$/\1/p'

# inspect
jq . .vpcctl_data/vpc_myvpc.json

# delete (excerpt)
sudo ip netns del ns-myvpc-public || true
sudo ip netns del ns-myvpc-private || true
sudo ip link del br-myvpc || true
sudo iptables -F vpc-myvpc 2>/dev/null || true
sudo iptables -X vpc-myvpc 2>/dev/null || true
rm -f .vpcctl_data/vpc_myvpc.json

Architecture Overview

Single VPC

VPC Peering (VPC ↔ VPC)

Command Reference

Command	Description	Example
create	Create a new VPC	`sudo vpcctl create myvpc --cidr 10.10.0.0/16`
add-subnet	Add a subnet to a VPC	`sudo vpcctl add-subnet myvpc public --cidr 10.10.1.0/24`
deploy-app	Start HTTP server in subnet	`sudo vpcctl deploy-app myvpc public --port 8080`
stop-app	Stop running application	`sudo vpcctl stop-app myvpc public`
enable-nat	Enable internet access via NAT	`sudo vpcctl enable-nat myvpc --interface eth0`
peer	Connect two VPCs	`sudo vpcctl peer myvpc othervpc --allow-cidrs 10.10.1.0/24,10.20.1.0/24`
apply-policy	Apply firewall rules (JSON)	`sudo vpcctl apply-policy myvpc policy.json`
list	List all VPCs	`sudo vpcctl list`
inspect	Show VPC metadata	`sudo vpcctl inspect myvpc`
delete	Delete a VPC	`sudo vpcctl delete myvpc`
cleanup-all	Delete all VPCs	`sudo vpcctl cleanup-all`
verify	Check for orphaned resources	`sudo vpcctl verify`

Troubleshooting Common Issues

Issue 1: "Permission denied" or "Operation not permitted"

Symptom:

Error: Operation not permitted

Cause: Not running with root privileges.

Solution:

# Always use sudo
sudo vpcctl create myapp --cidr 10.10.0.0/16

Issue 2: "Cannot find command: ip"

Symptom:

Error: Cannot find required command: ip

Cause: Missing iproute2 package.

Solution:

# Ubuntu/Debian
sudo apt install -y iproute2

# CentOS/RHEL
sudo yum install -y iproute

Issue 3: "Bridge already exists"

Symptom:

Error: RTNETLINK answers: File exists

Cause: You already created a VPC with this name.

Solutions:

Option A: Use a different name

sudo vpcctl create myapp2 --cidr 10.10.0.0/16

Option B: Delete the existing VPC first

sudo vpcctl delete myapp
sudo vpcctl create myapp --cidr 10.10.0.0/16

Issue 4: Namespace Cannot Access Internet

Symptom:

sudo ip netns exec ns-myapp-web curl -I http://1.1.1.1 | head -5
# Hangs or fails

Possible causes and solutions:

Cause 1: NAT not enabled

sudo vpcctl enable-nat myapp --interface eth0

Cause 2: Wrong host interface

# Find correct interface
ip route | grep default

# Use the interface shown
sudo vpcctl enable-nat myapp --interface <correct-interface>

Cause 3: Firewall blocking

# Check iptables
sudo iptables -t nat -L -n -v

# Check for MASQUERADE rule
sudo iptables -t nat -L POSTROUTING -n -v | grep MASQUERADE

Cause 4: DNS not configured in namespace

# Copy resolv.conf into namespace
sudo mkdir -p /etc/netns/ns-myapp-web
sudo cp /etc/resolv.conf /etc/netns/ns-myapp-web/

# Test again
sudo ip netns exec ns-myapp-web curl -I http://1.1.1.1 | head -5

Issue 5: Subnets Cannot Communicate

Symptom:

# From subnet A trying to reach subnet B
sudo ip netns exec ns-myapp-web curl http://10.10.2.2:5432
# Connection refused or timeout

Debugging steps:

Step 1: Verify both subnets are in the same VPC

sudo vpcctl inspect myapp
# Check that both subnets appear in the output

Step 2: Check if application is running in target subnet

sudo vpcctl inspect myapp | grep apps
# Or
sudo ip netns exec ns-myapp-database netstat -tlnp

Step 3: Verify routing

# Check routing table in source namespace
sudo ip netns exec ns-myapp-web ip route

Step 4: Check firewall rules

# Check iptables in target namespace
sudo ip netns exec ns-myapp-database iptables -L -n -v

Step 5: Test basic connectivity (ping)

sudo ip netns exec ns-myapp-web ping -c 3 10.10.2.2

Issue 6: "Cannot delete VPC: bridge is busy"

Symptom:

Error: RTNETLINK answers: Device or resource busy

Cause: Something is still using the bridge (running app, existing veth).

Solution:

# Force stop all apps first
sudo vpcctl cleanup-all

# Or manually kill processes
sudo pkill -f "ip netns exec ns-myapp"

# Then try deleting again
sudo vpcctl delete myapp

Issue 7: Peered VPCs Cannot Communicate

Symptom:

sudo vpcctl peer vpc1 vpc2 --allow-cidrs 10.10.1.0/24,10.20.1.0/24
# But curl between VPCs times out

Debugging steps:

Step 1: Verify peering exists

sudo vpcctl inspect vpc1 | grep peers
sudo vpcctl inspect vpc2 | grep peers

Step 2: Check allowed CIDRs

# Make sure the source and destination subnets are in the allowed list
sudo vpcctl inspect vpc1

Step 3: Check iptables rules

sudo iptables -L vpc-vpc1 -n -v
# Look for ACCEPT rules with peer CIDRs

Step 4: Test with specific IPs

# From vpc1 subnet to vpc2 subnet
sudo ip netns exec ns-vpc1-web curl http://10.20.1.2:8080

Issue 8: High CPU Usage from Python HTTP Server

Symptom: System becomes slow after deploying multiple apps.

Cause: Python's simple HTTP server is not designed for high performance.

Solution:

Option A: Limit number of test apps

# Only deploy what you need
sudo vpcctl stop-app myapp web

Option B: Use lighter alternatives
Instead of using deploy-app, manually run a lighter server:

# Use busybox httpd (if available)
sudo ip netns exec ns-myapp-web busybox httpd -f -p 8080

Issue 9: "Address already in use"

Symptom:

Error: bind: address already in use

Cause: Port is already taken by another application.

Solution:

Option 1: Use a different port

sudo vpcctl deploy-app myapp web --port 8081

Option 2: Stop the conflicting app

# Find what's using the port
sudo lsof -i :8080

# Stop it
sudo kill <PID>

# Or use vpcctl
sudo vpcctl stop-app myapp web

Issue 10: Metadata File Corruption

Symptom:

Error: JSON decode error

Cause: Metadata file .vpcctl_data/vpc_<name>.json got corrupted.

Solution:

Option 1: Delete and recreate

# Remove corrupted metadata
rm .vpcctl_data/vpc_myapp.json

# Recreate VPC
sudo vpcctl create myapp --cidr 10.10.0.0/16

Option 2: Manual cleanup

# Remove namespace
sudo ip netns del ns-myapp-web

# Remove bridge
sudo ip link del br-myapp

# Remove metadata
rm .vpcctl_data/vpc_myapp.json

Debugging Tips

Enable verbose output:

# Add debugging to see all iptables operations
sudo vpcctl create myapp --cidr 10.10.0.0/16 2>&1 | tee debug.log

Check system logs:

# View kernel network messages
dmesg | tail -50

# System logs
journalctl -xe

Verify bridge state:

# List all bridges
ip link show type bridge

# Show bridge details
bridge link show

Verify namespace state:

# List all namespaces
sudo ip netns list

# Show interfaces in a namespace
sudo ip netns exec ns-myapp-web ip addr

Verify iptables rules:

# NAT table
sudo iptables -t nat -L -n -v

# Filter table
sudo iptables -L -n -v

# Check specific chain
sudo iptables -L vpc-myapp -n -v

Complete Code Reference

Metadata File Structure

Every VPC has a JSON metadata file stored in .vpcctl_data/vpc_<name>.json:

{
  "name": "myapp",
  "cidr": "10.10.0.0/16",
  "bridge": "br-myapp",
  "chain": "vpc-myapp",
  "subnets": [
    {
      "name": "web",
      "cidr": "10.10.1.0/24",
      "ns": "ns-myapp-web",
      "gw": "10.10.1.1",
      "host_ip": "10.10.1.2",
      "veth": "v-myapp-web"
    }
  ],
  "host_iptables": [
    ["iptables", "-A", "vpc-myapp", "-s", "10.10.0.0/16", "-d", "10.10.0.0/16", "-j", "ACCEPT"]
  ],
  "apps": [
    {
      "ns": "ns-myapp-web",
      "port": 8080,
      "pid": 12345,
      "cmd": ["ip", "netns", "exec", "ns-myapp-web", "python3", "-m", "http.server", "8080"]
    }
  ],
  "peers": [
    {
      "peer_vpc": "otherapp",
      "veth_a": "pv-myapp-other-va",
      "veth_b": "pv-myapp-other-vb",
      "allowed": ["10.10.1.0/24", "10.20.1.0/24"]
    }
  ],
  "nat": {
    "interface": "eth0"
  }
}

Policy File Structure

Policy files define ingress and egress firewall rules:

{
  "subnet": "10.10.1.0/24",
  "ingress": [
    {"port": 80, "protocol": "tcp", "action": "allow"},
    {"port": 443, "protocol": "tcp", "action": "allow"},
    {"port": 22, "protocol": "tcp", "action": "deny"},
    {"port": 3389, "protocol": "tcp", "action": "deny"}
  ],
  "egress": [
    {"port": 25, "protocol": "tcp", "action": "deny"},
    {"port": 80, "protocol": "tcp", "action": "allow"},
    {"port": 443, "protocol": "tcp", "action": "allow"}
  ]
}

Fields:

subnet: CIDR of the subnet this policy applies to
ingress: Rules for incoming traffic
egress: Rules for outgoing traffic
port: Port number
protocol: tcp, udp, or icmp
action: allow or deny

Common IP Address Ranges (CIDR)

Private IP ranges (safe to use):

10.0.0.0/8: 10.0.0.0 to 10.255.255.255 (16 million IPs)
172.16.0.0/12: 172.16.0.0 to 172.31.255.255 (1 million IPs)
192.168.0.0/16: 192.168.0.0 to 192.168.255.255 (65,534 IPs)

CIDR notation explained:

/8: 16,777,216 addresses
/16: 65,536 addresses
/24: 256 addresses
/28: 16 addresses
/32: 1 address

Examples:

10.0.0.0/16 = 10.0.0.1 to 10.0.255.254
192.168.1.0/24 = 192.168.1.1 to 192.168.1.254
172.16.0.0/20 = 172.16.0.1 to 172.16.15.254

Quick Command Cheat Sheet

# Create VPC
sudo vpcctl create <name> --cidr <ip-range>

# Add subnet
sudo vpcctl add-subnet <vpc> <subnet-name> --cidr <ip-range>

# Deploy test app
sudo vpcctl deploy-app <vpc> <subnet> --port <port>

# Enable internet
sudo vpcctl enable-nat <vpc> --interface <iface>

# Peer VPCs
sudo vpcctl peer <vpc1> <vpc2> --allow-cidrs <cidr1>,<cidr2>

# Apply policy
sudo vpcctl apply-policy <vpc> <policy-file.json>

# List VPCs
sudo vpcctl list

# Inspect VPC
sudo vpcctl inspect <vpc>

# Delete VPC
sudo vpcctl delete <vpc>

# Test connectivity
sudo ip netns exec ns-<vpc>-<subnet> curl http://<ip>:<port>

# Run command in namespace
sudo ip netns exec ns-<vpc>-<subnet> <command>

# Check namespace IPs
sudo ip netns exec ns-<vpc>-<subnet> ip addr

# Check namespace routing
sudo ip netns exec ns-<vpc>-<subnet> ip route

# Check namespace firewall
sudo ip netns exec ns-<vpc>-<subnet> iptables -L -n -v

Best Practices

1. Plan Your IP Address Space

Bad:

# Random, overlapping ranges
sudo vpcctl create app1 --cidr 10.0.0.0/24
sudo vpcctl create app2 --cidr 10.0.0.0/24  # CONFLICT!

Good:

# Organized, non-overlapping ranges
sudo vpcctl create dev --cidr 10.10.0.0/16
sudo vpcctl create staging --cidr 10.20.0.0/16
sudo vpcctl create prod --cidr 10.30.0.0/16

2. Use Descriptive Names

Bad:

sudo vpcctl create vpc1 --cidr 10.0.0.0/16
sudo vpcctl add-subnet vpc1 sub1 --cidr 10.0.1.0/24

Good:

sudo vpcctl create ecommerce-app --cidr 10.0.0.0/16
sudo vpcctl add-subnet ecommerce-app web-tier --cidr 10.0.1.0/24
sudo vpcctl add-subnet ecommerce-app database --cidr 10.0.2.0/24

3. Document Your Network

Create a simple diagram:

VPC: ecommerce-app (10.0.0.0/16)
├── web-tier (10.0.1.0/24) - Public, NAT enabled
│   └── nginx on 10.0.1.2:80
├── app-tier (10.0.2.0/24) - Private
│   └── node.js on 10.0.2.2:3000
└── database (10.0.3.0/24) - Private
    └── postgres on 10.0.3.2:5432

4. Test Before Applying Policies

# First, get everything working without restrictions
sudo vpcctl create test --cidr 10.99.0.0/16
sudo vpcctl add-subnet test web --cidr 10.99.1.0/24
sudo vpcctl deploy-app test web --port 8080

# Test connectivity
sudo ip netns exec ns-test-web curl localhost:8080

# THEN apply policies
sudo vpcctl apply-policy test restrictive_policy.json

5. Clean Up After Testing

# Always cleanup when done
sudo vpcctl delete test-vpc

# Or nuke everything
sudo vpcctl cleanup-all

6. Use Dry-Run First

# Preview before executing
vpcctl --dry-run create prod --cidr 10.30.0.0/16
# Review the commands
# Then run for real:
sudo vpcctl create prod --cidr 10.30.0.0/16

Learning Resources

Understanding Linux Networking

Concepts to research:

Network namespaces
Virtual Ethernet (veth) pairs
Linux bridges
iptables and netfilter
IP routing and forwarding
NAT and MASQUERADE

Conclusion

You now have a complete understanding of:

What VPCs and subnets are
Why we need network isolation
How vpcctl works under the hood
Every command and function in vpcctl
How to build realistic network architectures
How to troubleshoot common issues

Remember: vpcctl is a learning tool. It helps you understand cloud networking concepts without needing an AWS/Azure account. Once you master it, you'll find cloud provider VPCs much easier to work with!

Author's Note: This guide was written to be beginner-friendly. If you're reading this and something is unclear, that's a bug in the documentation, not in your understanding. Re-read the section, try the examples, and experiment!

Credits

Author: DestinyObs

Tagline: iBuild | iDeploy | iSecure | iSustain

GitHub: https://github.com/DestinyObs/HNGi13-Stage4-vpcctl

Happy networking!

Building a Self-Healing Blue/Green Deployment with Nginx & Docker

Destiny Obs — Sat, 25 Oct 2025 08:29:04 +0000

The 2:47 AM Lesson That Changed Everything

It was 2:47 AM.
Our backend service had gone quiet — not a hard crash, not an obvious error, just silence.
Nginx sat waiting, clients kept retrying, and every second felt longer than the last.

That was the night I learned the real definition of downtime:

“Downtime isn’t just when the server stops — it’s when users stop trusting your system.”

So when the HNG DevOps Stage 2 task came, I didn’t just want to make a deployment work.
I wanted to build something that heals itself.

My goal was clear:

Run two identical app containers — Blue and Green.
Let Nginx automatically fail over if one goes down.
Keep responses clean, fast, and consistent.
Never show a 5xx error again.

What Blue/Green Deployment Really Means

A Blue/Green Deployment is a release strategy where two identical environments live side-by-side:

Environment	Role	Purpose
Blue	Active	Serves live user traffic
Green	Standby	Runs silently, ready to take over

When Blue fails or you roll out an update, Green steps up instantly.
Traffic switches without downtime.

Think of it like a plane with two engines — both spinning, but only one giving thrust.
If the active engine fails, you flip a switch, and the passengers never notice.
That’s exactly what we achieve in DevOps terms:

Blue = Active upstream
Green = Backup upstream
Nginx = Pilot deciding which one should fly

My Three-Layer Architecture Stack

Here’s the structure I built from the ground up:

All services live in a single Docker Network, communicating through internal DNS.
Nginx listens on port 8080, while both app containers expose /healthz and /version endpoints.

Inside the Intelligence of Nginx Failover

Failover magic starts inside the upstream block of the Nginx configuration:

Let’s break this down:

app_blue is the primary server.
app_green is marked as backup — it stays idle until Blue fails.
max_fails=1 means one failure is enough to demote Blue.
fail_timeout=3s decides how long Blue stays on the bench.

When Blue fails once within 3 seconds, Nginx instantly reroutes traffic to Green — no manual restart, no DNS propagation, no human intervention.

That tiny keyword backup turns Nginx from a static load balancer into a self-healing reverse proxy.

Retry Logic — The Secret Behind Zero Downtime

To make the transition invisible to users, I implemented this retry policy:

Here’s what happens:

A request hits Blue.
Blue delays or sends a 500.
Nginx checks: “Is this retriable?”
It retries once, this time on Green.
Green returns 200 OK — the user never notices.

It even retries POST requests (non_idempotent) safely.
Because in real life, reliability > rigidity.

Docker Compose — Orchestrating Everything

This was my docker-compose.yml setup:

Two services (app_blue, app_green) are identical, except for color tags.
Nginx uses environment variables like ACTIVE_POOL to decide which one is live.

⚙️ The Active Pool Switch Script

To make switching seamless, I wrote a small shell script — render-and-reload.sh.

So with one command:

docker compose exec -T nginx sh -lc 'ACTIVE_POOL=green /opt/nginx/render-and-reload.sh'"

I can flip traffic instantly from Blue to Green — no rebuild, no downtime.

The Moment of Truth — Chaos Testing

Once everything was running, I simulated failure with a secret robust script to break things.

bash scripts/verify.sh

The results were satisfying:

Every request kept returning 200 OK even while Blue was being stressed.
That’s not just a passing test — that’s trust preserved.

Key Concepts I Learned (Definitions for Interns Coming After Me)

Term	Definition
Upstream	A group of backend servers that Nginx load-balances between.
Backup	A server only used when primaries fail.
Failover	Automatic switch to a standby system upon failure.
Healthcheck	Automated test to ensure a container is alive and healthy.
Zero-Downtime Deployment	Releasing new versions without interrupting service availability.

Why This Matters in the Real World

In real production systems, even a minute of downtime can cost users, transactions, or trust.
What this setup teaches is graceful failure — planning for the moment things go wrong.

And the best part?
It’s all built with open-source tools:

Docker for container orchestration
Nginx for reverse proxy and failover
Shell scripts for automation
No fancy load balancer bills, no proprietary magic

Final Thoughts

This project wasn’t just about passing a task — it was a lesson in resilience.

In all my DevOps Practices i never thougth about this or implementing such cause they are many tools to do this
I learned that DevOps isn’t only about deployment pipelines or automation scripts.
It’s about ensuring that no matter what happens, your users stay unaffected.

When the next 2:47 AM crash happens — your system won’t panic.
It’ll heal itself.
GitHub Repo: DestinyObs/HNGi13-Stage2-Task

I’m DestinyObs| iDeploy | iSecure | iSustain

Building an AWS Microservices Infrastructure with Terraform — First Industry-like approach

Destiny Obs — Wed, 28 May 2025 14:33:28 +0000

It all started with food.
Yeah… food.

I was minding my business, doing my daily scroll through food content (don’t judge), when a friend dropped a Twitter link.
“See what I’m working on,” he said.
Spoiler alert: it was not jollof rice.

It was a Task definition thread on setting up an AWS infrastructure using Terraform. I had never done it before. But hey, curiosity (and maybe hunger) kicked in. So I tried it.

Why This Article Tastes Different

Let’s be honest — I’m not your go-to “10 years in the trenches” DevOps guy. I’m just someone who’s curious, hungry (literally and metaphorically), and absolutely allergic to boring tech content.

This is my first clean, modular, industry-grade Infrastructure as Code setup.
Yes, something might break.
Yes, you’ll probably fix something when you try it yourself.
And yes, I’m totally okay with that.

So grab a snack and vibe with me as we walk through:

How I planned the whole setup (inspired by that wild Twitter link)
Why Terraform modules became my besties
The microservices app I didn’t containerize — but my friend did
My “trust me, it works” folder structure

Project Overview

Here’s what I built: an AWS infrastructure to host a microservices-based app made up of:

A React frontend
Two APIs — one in Node.js, one in Go
A PostgreSQL database
A Python load generator to keep things spicy

All deployed on ECS Fargate, orchestrated by the real MVP: Terraform.

Architecture Flow

Public Subnets – for the ALB to accept traffic like a bouncer at an exclusive party.
Private Subnets – where ECS and RDS live in peace, away from public scrutiny.
Secrets Manager – because plain-text passwords are a crime.
CloudWatch – watching so I don’t have to.
ALB → ECS → RDS – like a well-oiled relay team.

Folder Structure

.
├── env/
│   └── dev/
│       ├── backend.tf         # S3 state backend
│       ├── main.tf            # Main config
│       ├── outputs.tf         # What Terraform spits out
│       ├── providers.tf       # AWS provider config
│       ├── terraform.tfvars   # Your environment’s juicy secrets
│       └── variables.tf       # Input variables
├── modules/
│   ├── alb/                   # Load balancer setup
│   ├── ecr/                   # ECR repos
│   ├── ecs/                   # ECS cluster
│   ├── monitoring/            # CloudWatch logs + alarms
│   ├── rds/                   # PostgreSQL config
│   ├── secrets_manager/       # For hiding your sins (passwords)
│   ├── security_groups/       # Fine-grained access control
│   └── vpc/                   # VPC + networking
├── .gitignore
└── README.md

Modular. Reusable. Tidy. Just like the way I my kitchen looks.

Modules Breakdown

VPC

Sets up networking: public + private subnets, NAT, IGW, route tables.
Outputs subnet IDs for other modules to use.

Security Groups

ALB talks to the world.
ECS talks to ALB.
RDS? Strictly ECS only. No loose lips.

ECR

One repo per service: frontend, node API, go API, load generator.
Push your Docker images here. Clean, secure, efficient.

RDS

PostgreSQL DB in a private subnet.
Encrypted. Multi-AZ. Passwords stored in Secrets Manager.
Fancy, right?

Secrets Manager

All environment variables + credentials stored here as a single JSON blob.
Because leaking secrets is so 2015.

ECS

Fargate cluster — because I don’t babysit EC2s.
(Tasks and services coming soon.)

ALB

In public subnet, routing traffic to ECS via target groups.
Listener rules? We’ll wire those up later.

Monitoring

CloudWatch log groups + a CPU alarm.
(Still cooking memory + RDS alarms.)

How the App Connects (from Docker Compose to ECS)

My friend had the app in Docker Compose.
I mapped each service to a future ECS task:

Client (React) → ALB → ECS Task
Node API & Go API → ALB paths → ECS
PostgreSQL already containerized, now replaced with managed RDS
Load Generator → ECS task to simulate real-world chaos

All environment variables are injected from Secrets Manager.
Container images are stored in ECR, pulled at deploy.

Deployment Steps

Clone the repo

git clone https://github.com/DestinyObs/terraform-ecs.git
cd terraform-ecs/env/dev

Initialize Terraform

terraform init

Preview your infrastructure

terraform plan

Apply the config

terraform apply

Destroy it when you’re done playing God

terraform destroy

What’s Next (on My DevOps Menu)

Add ECS task definitions + services
ALB listener rules for routing by path (/api, /client, etc.)
Memory + DB monitoring
SSM integration for better secret hygiene
Full CI/CD pipeline for image builds + infra deploys

Final Thoughts

This project was:

curiosity
hunger
pure Terraform joy

If you’re just starting with cloud infra, this is a fun sandbox.
If you’re an experienced engineer, fork it and show me what I missed.

The goal isn’t perfection. The goal is progress — and maybe a snack break along the way.

Try the code or roast my setup here:
GitHub: DestinyObs/terraform-ecs

I’m DestinyObs
iDeploy | iSecure | iSustain | iLikeFood

Why This Matters: Streamlined Deployment for ASP.NET Core on IIS

Destiny Obs — Mon, 14 Apr 2025 14:56:21 +0000

Deploying web applications manually on a Windows Server can be tedious, error-prone, and time-consuming. Every new server setup requires multiple steps — installing IIS, configuring app pools, setting permissions, publishing code, assigning ports, and so on.

What if you could skip all of that?

What if you could go from zero to a fully running ASP.NET Core application hosted on IIS with just one command?

That’s exactly what this PowerShell script is designed to do.

What Are We Automating?

We’re automating the entire process of deploying an ASP.NET Core web application (SGBookPortal) onto IIS (Internet Information Services) on a Windows Server machine.

By the end of the script, you’ll have:

IIS installed and ready
Your application cloned from GitHub
Code built and published to the right folder
Folder permissions properly set
An IIS site and application pool fully configured
Your app running and accessible via http://localhost:<your_port>

How This Would Be Done Manually on Windows Server

Here’s a step-by-step explanation of what this deployment would look like if you were to do it manually without automation:

Step 1: Launch PowerShell as Administrator

Why? Most IIS, system configurations, and software installations require elevated privileges.

Step 2: Install IIS

Go to Server Manager > Add Roles and Features
Select the Web Server (IIS) role
Enable management tools like IIS Management Console
Complete the wizard and restart if required

Purpose: IIS is the Windows component that will host and serve our ASP.NET Core site.

Step 3: Install Git

Download and install Git from https://git-scm.com/download/win.

This is needed to clone the code repository.

Step 4: Install .NET SDK and Hosting Bundle

Install the appropriate .NET SDK version from https://dotnet.microsoft.com/download.

Purpose: We use the SDK to build and publish the ASP.NET Core project to a deployable format.

Step 5: Clone the Repository

Open PowerShell or Git Bash
Run git clone <repo_url> to download the project into your local file system

Step 6: Create Web Root Directory

Manually go to C:\inetpub\wwwroot
Create a folder named sgbookportal
This will serve as the deployment folder for the app files

Step 7: Publish the ASP.NET Core App

Navigate to the project folder
Run:

  dotnet publish BookPortel.csproj -c Release -o C:\inetpub\wwwroot\sgbookportal

This compiles the application and outputs the binaries, views, configs, and dependencies needed for production.

Step 8: Set Folder Permissions

Right-click the deployment folder
Go to Properties > Security
Grant Read and Execute permission to the user group: IIS_IUSRS

Purpose: IIS worker process needs permissions to serve the app from this directory.

Step 9: Assign an Available Port

Since IIS sites bind to specific ports, you need to:

Check which ports are already in use (especially 80/443)
Pick an unused one (e.g., 8081)

Step 10: Create IIS Website and Application Pool

Open IIS Manager
Right-click Sites > Add Website
- Site name: SGBookPortal
- Physical path: C:\inetpub\wwwroot\sgbookportal
- Port: e.g., 8081
Click OK

Note: For ASP.NET Core, App Pool should be configured with “No Managed Code” since .NET Core apps run as standalone processes (Kestrel).

However, IIS auto-generates and manages this App Pool when you create the site via PowerShell, so no need to configure it manually.

Step 11: Start the Website

From IIS Manager, select the site and click Start in the right-hand panel.

Visit http://localhost:8081/swagger/index.html to test the app.

Now Let's Explain the Script in Bits

Now we’ll walk through and explain each part of the script — line by line.

1. Ensure Script is Run as Administrator

if (-not ([Security.Principal.WindowsPrincipal] ...)) {
    Write-Host "This script must be run as Administrator." -ForegroundColor Red
    exit 1
}

Checks if the current PowerShell session is running with admin privileges. If not, it exits to prevent permission errors.

2. Install IIS

Install-WindowsFeature -Name Web-Server -IncludeManagementTools

Installs the Web-Server (IIS) role along with tools like the IIS Manager GUI.

3. Ensure Git is Installed

if (-not (Get-Command git ...)) {
    Write-Host "Git is not installed..."
}

Checks for Git. If not available, asks the user to install it manually.

4. Ensure .NET SDK is Installed

if (-not (Get-Command dotnet ...)) {
    Write-Host ".NET SDK is not installed..."
}

Checks for the dotnet CLI which is used to build and publish .NET apps.

5. Define Variables

$repoUrl   = "https://github.com/softwaregurukulamdevops/SGbookportal.git"
$clonePath = "C:\SGbookportal"
$sitePath  = "C:\inetpub\wwwroot\sgbookportal"
$siteName  = "SGBookPortal"
$poolName  = "SGBookPortalPool"

These variables define:

The GitHub repo URL
Local directory to clone the repo
Final publish target (IIS web root)
IIS site and app pool names

6. Clone the Repository

if (-not (Test-Path $clonePath)) {
    git clone $repoUrl $clonePath
}

Clones the codebase from GitHub if it doesn't already exist.

7. Create Web Root Directory

New-Item -Path $sitePath -ItemType Directory -Force

Creates the folder under IIS's wwwroot where the app will live.

8. Publish the App

dotnet publish "$clonePath\BookPortel\BookPortel.csproj" -c Release -o $sitePath

Builds the app in Release mode and deploys it to $sitePath.

9. Set IIS Permissions

icacls $sitePath /grant "IIS_IUSRS:(OI)(CI)RX" /T

Grants Read/Execute permissions to IIS user groups on the deployed folder recursively.

10. Assign Available Port

$startingPort = 80
$usedPorts = (Get-NetTCPConnection -State Listen).LocalPort
$port = $startingPort
while ($usedPorts -contains $port) { $port++ }

Checks for an unused port starting from 80 and selects the first one available.

11. Configure IIS

Import-Module WebAdministration

Loads IIS management commands into the session.

if (Get-Website | Where-Object { $_.Name -eq $siteName }) {
    Remove-Website -Name $siteName
}

Removes any existing IIS site with the same name.

if (-not (Test-Path "IIS:\AppPools\$poolName")) {
    New-WebAppPool -Name $poolName
    Set-ItemProperty ... -Name "managedRuntimeVersion" -Value ""
}

Creates an App Pool with No Managed Code, suitable for .NET Core apps.

New-Website -Name $siteName -Port $port -PhysicalPath $sitePath -ApplicationPool $poolName

Creates a new IIS site, bound to the selected port, and linked to the specified app pool.

12. Start the Website

Start-Website -Name $siteName

Starts the newly created site.

User is informed they can access the app at http://localhost:$port/swagger/index.html.

Summary

This script removes all the manual overhead of:

Installing necessary tools
Publishing the application
Setting permissions
Configuring IIS (sites + app pool)
Starting the hosted service

Troubleshooting IIS Deployment Issues for ASP.NET Core

During my deployment of an ASP.NET Core application to IIS, I encountered two major errors that I think are common and worth documenting for others:

Error 1: While Performing Authentication Settings in IIS

There was an error while performing this operation.
Details:
Filename: \\?\C:\users\...\.config
Error:

Error 2: HTTP Error 500.19 – Internal Server Error

The requested page cannot be accessed because the related configuration data for the page is invalid.
Error Code: 0x8007000d

What to Check When You See These Errors:

Check for web.config File
- Go to your published folder (e.g., bin\release\net8.0\publish) and make sure the file is named web.config and not just web.
- IIS requires a proper web.config file to know how to run your ASP.NET Core app. If it’s missing or malformed, IIS won't know how to serve your application.
Check if the .NET Core Hosting Bundle is Installed Correctly
- These types of errors can also mean that the ASP.NET Core Hosting Bundle is either not installed or not configured correctly.
- This bundle allows IIS to run ASP.NET Core applications using the in-process hosting model.

Recommended Fix:

If you run into these kinds of issues:

Start Fresh:
- Uninstall any previous hosting bundle installations if you're unsure of their integrity.
- Reinstall the latest .NET Core Hosting Bundle compatible with your app version. > You can download it from Microsoft's official .NET download page.
🛠️ Re-Publish Your Application:
- Use Visual Studio or dotnet publish again to regenerate the files, ensuring the web.config is created properly.

In Summary

These are the errors I personally faced during deployment. If you run into something similar, start by checking the web.config presence and reinstalling the .NET Hosting Bundle. That’s what worked for me!

# Deploys the SGBookPortal ASP.NET Core application to IIS

# Step 1: Ensure script is run as Administrator
if (-not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltinRole] "Administrator")) {
    Write-Host "This script must be run as Administrator." -ForegroundColor Red
    exit 1
}

# Step 2: Install IIS
Write-Host "Installing IIS..."
try {
    Install-WindowsFeature -Name Web-Server -IncludeManagementTools -ErrorAction Stop
} catch {
    Write-Host "Failed to install IIS: $_" -ForegroundColor Red
    exit 1
}

# Step 3: Check for Git
if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
    Write-Host "Git is not installed. Install Git from https://git-scm.com/download/win and rerun the script." -ForegroundColor Red
    exit 1
}

# Step 4: Check for .NET SDK
if (-not (Get-Command dotnet -ErrorAction SilentlyContinue)) {
    Write-Host ".NET SDK is not installed. Install from https://dotnet.microsoft.com/download and rerun the script." -ForegroundColor Red
    exit 1
}

# Step 5: Define variables
$repoUrl   = "https://github.com/softwaregurukulamdevops/SGbookportal.git"
$clonePath = "C:\SGbookportal"
$sitePath  = "C:\inetpub\wwwroot\sgbookportal"
$siteName  = "SGBookPortal"
$poolName  = "SGBookPortalPool"

# Step 6: Clone the repository if not already present
if (-not (Test-Path $clonePath)) {
    try {
        Write-Host "Cloning repository..."
        git clone $repoUrl $clonePath
    } catch {
        Write-Host "Repository clone failed: $_" -ForegroundColor Red
        exit 1
    }
} else {
    Write-Host "Repository already exists. Skipping clone."
}

# Step 7: Create web root directory
if (-not (Test-Path $sitePath)) {
    try {
        Write-Host "Creating web root directory..."
        New-Item -Path $sitePath -ItemType Directory -Force
    } catch {
        Write-Host "Failed to create web root directory: $_" -ForegroundColor Red
        exit 1
    }
}

# Step 8: Publish the ASP.NET Core project
try {
    Write-Host "Publishing the application..."
    dotnet publish "$clonePath\BookPortel\BookPortel.csproj" -c Release -o $sitePath
} catch {
    Write-Host "Publish failed: $_" -ForegroundColor Red
    exit 1
}

# Step 9: Grant IIS read/execute permissions
try {
    Write-Host "Setting permissions..."
    icacls $sitePath /grant "IIS_IUSRS:(OI)(CI)RX" /T | Out-Null
} catch {
    Write-Host "Failed to set folder permissions: $_" -ForegroundColor Red
    exit 1
}

# Step 10: Check and assign available port (start from 80)
$startingPort = 80
$usedPorts = (Get-NetTCPConnection -State Listen).LocalPort | Sort-Object -Unique
$port = $startingPort
while ($usedPorts -contains $port) {
    $port++
}
Write-Host "Selected port: $port"

# Step 11: Configure IIS - Remove existing site and create app pool
Import-Module WebAdministration

# Remove existing site if it exists
if (Get-Website | Where-Object { $_.Name -eq $siteName }) {
    try {
        Write-Host "Removing existing site '$siteName'..."
        Remove-Website -Name $siteName
    } catch {
        Write-Host "Failed to remove existing IIS site: $_" -ForegroundColor Red
        exit 1
    }
}

# Create App Pool (No Managed Code for .NET Core)
if (-not (Test-Path "IIS:\AppPools\$poolName")) {
    New-WebAppPool -Name $poolName
    Set-ItemProperty "IIS:\AppPools\$poolName" -Name "managedRuntimeVersion" -Value ""
}

# Create new IIS website
try {
    Write-Host "Creating IIS site '$siteName'..."
    New-Website -Name $siteName -Port $port -PhysicalPath $sitePath -ApplicationPool $poolName
} catch {
    Write-Host "Failed to create IIS site: $_" -ForegroundColor Red
    exit 1
}

# Step 12: Start the website
try {
    Start-Website -Name $siteName
    Write-Host "`nDeployment completed successfully."
    Write-Host "You can access the application at: http://localhost:$port/swagger/index.html`n"
} catch {
    Write-Host "Failed to start IIS site: $_" -ForegroundColor Red
    exit 1
}

Automating Cloud Deployments (AWS): Terraform, Docker, and CI/CD

Destiny Obs — Mon, 31 Mar 2025 18:44:00 +0000

Project Overview

Imagine a world where infrastructure provisions itself, deployments happen at the speed of light, and applications run seamlessly in containers. Sounds like DevOps heaven, right? Well, that’s exactly what we’ve built! This project is a Flask API running on AWS EC2, with a PostgreSQL database, fully automated using Terraform, Docker, and GitHub Actions. No more manual configurations—just pure DevOps wizardry! 🧙‍♂️✨

Why This Project?

We set out to create a fully automated deployment pipeline with a few key objectives:
✅ Automate Deployments – Because clicking buttons is overrated.

✅ Infrastructure as Code (IaC) – Terraform makes provisioning as easy as writing poetry.

✅ Containerization – So our app runs smoothly, anywhere, anytime.

✅ AWS Deployment – Because cloud is king, and EC2 is our throne.

🛠 Tech Stack & Tools Used

Infrastructure & Deployment

🔹 AWS EC2 → Our app’s luxurious penthouse in the cloud.

🔹 Terraform → Automates infrastructure like a charm.

🔹 GitHub Actions → Our deployment butler, making CI/CD effortless.

🔹 Docker & Docker Compose → Containers keep our app lightweight and portable.

🔹 SSH (appleboy/ssh-action) → Because deploying securely is non-negotiable.

Backend & Database

🔹 Flask → Python’s sleek and simple web framework.

🔹 PostgreSQL → The brain storing all our precious data.

Version Control & Registry

🔹 Git & GitHub → Our code’s happy place.

🔹 Docker Hub → The treasure chest for our container images.

Security & Networking

🔹 IAM Roles & Policies → Guarding AWS like a bouncer at an exclusive club.

🔹 Security Groups → Keeping unwanted traffic out like a medieval fortress.

📌 Project Setup & Installation Guide

This guide will walk you through setting up the project from scratch. No magic wands required, just follow these steps! 🧙‍♂️

🛠 Prerequisites

Before you dive in, ensure you have these installed:

🔹 On Your Local Machine:

✅ Git → Version control is life.

✅ Docker & Docker Compose → Containerization makes life easier.

✅ Python 3.x & pip → Flask won’t run without it.

✅ Terraform → Because writing YAML files is old school.

✅ AWS CLI → Talking to AWS like a pro.

🔹 On AWS EC2 Instance:

✅ Ubuntu 22.04 (or latest stable version).

✅ Docker & Docker Compose installed.

✅ PostgreSQL installed manually or via Docker.

📂 Cloning the Repositories

Now let’s grab the code and start the fun!

# Clone the main project repo
git clone https://github.com/DestinyObs/ictg_task.git
cd ictg_task

# Clone the Terraform automation repo
git clone https://github.com/DestinyObs/ictg_automate_v2.git
cd ictg_automate_v2

⚙️ Setting Up Infrastructure on AWS with Terraform

Terraform is our infrastructure wizard, automating EC2 provisioning and security configurations so we don’t have to click around AWS like it’s 2010.

🏗️ Provisioning an EC2 Instance with Terraform

🔹 Steps to Deploy:

1️⃣ Navigate to the Terraform automation repository:

   cd ictg_automate_v2

2️⃣ Initialize Terraform:

   terraform init

3️⃣ Validate the configuration:

   terraform validate

4️⃣ Preview what Terraform is about to create:

   terraform plan

5️⃣ Apply and deploy the infrastructure:

   terraform apply -auto-approve

💡 After execution, Terraform will provide the EC2 instance details like IP address and security settings.

🛠️ 1. Infrastructure Setup (Terraform)

🔑 1.1 Generating an SSH Key Pair

Before launching the EC2 instance, we need an SSH key to securely connect to it.

resource "tls_private_key" "ec2_key" {
  algorithm = "RSA"
  rsa_bits  = 2048
}

📌 Explanation:
✅ Generates an RSA 2048-bit private key for SSH authentication. No more passwords—only secure keys!

🔑 1.2 Creating a Key Pair in AWS

To allow SSH access, we need to register the public key with AWS.

resource "aws_key_pair" "ictg_key" {
  key_name   = var.key_name
  public_key = tls_private_key.ec2_key.public_key_openssh
}

📌 Explanation:
✅ This creates an AWS Key Pair using our generated SSH key.
✅ The private key remains local for secure SSH connections.

📂 1.3 Storing the Private Key Locally

Terraform saves the private key to a file for authentication.

resource "local_file" "ssh_key" {
  content  = tls_private_key.ec2_key.private_key_pem
  filename = "${path.module}/ictg_automate_key.pem"
}

📌 Important: Keep this key safe—losing it is like losing your house keys, but worse.

🔒 1.4 Security Group Configuration

A Security Group defines what network traffic is allowed.

resource "aws_security_group" "ictg_automate_sg" {
  name        = var.security_group_name
  description = "Allow SSH, HTTP, and necessary ports"

  ingress {
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] # Open for SSH (Restrict in production)
  }

  ingress {
    from_port   = 8000
    to_port     = 8000
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] # Backend API access
  }

  ingress {
    from_port   = 5173
    to_port     = 5173
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] # Frontend access
  }

  ingress {
    from_port   = 5432
    to_port     = 5432
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"] # PostgreSQL database access
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"] # Allow all outbound traffic
  }
}

📌 Explanation:
✅ SSH (22) → Remote access.
✅ Backend (8000) → API communication.
✅ Frontend (5173) → Web app access.
✅ Database (5432) → PostgreSQL connectivity.
✅ Outbound rule → Allows all outgoing traffic for smooth operations.

💻 1.5 Creating the EC2 Instance

Finally, let’s provision our EC2 instance with Terraform.

resource "aws_instance" "app_server" {
  ami           = var.ami_id
  instance_type = var.instance_type
  key_name      = aws_key_pair.ictg_key.key_name
  security_groups = [aws_security_group.ictg_automate_sg.name]

  user_data = file("${path.module}/app-setup.sh")

  provisioner "file" {
    source      = "app-setup.sh"
    destination = "/home/ubuntu/app-setup.sh"
  }

  provisioner "remote-exec" {
    inline = [
      "chmod +x /home/ubuntu/app-setup.sh",
      "sudo /home/ubuntu/app-setup.sh"
    ]
  }

  connection {
    type        = "ssh"
    user        = "ubuntu"
    private_key = tls_private_key.ec2_key.private_key_pem
    host        = self.public_ip
  }

  tags = {
    Name = "ICTG App Server"
  }
}

📌 Explanation:
✅ Uses an Ubuntu AMI (adjust as needed).
✅ Attaches the Security Group.
✅ Uploads and executes a setup script (app-setup.sh).
✅ Establishes an SSH connection.

📍 1.6 Outputting Important Details

Terraform outputs key details so you don’t have to dig around AWS.

output "instance_public_ip" {
  description = "Public IP of the EC2 instance"
  value       = aws_instance.app_server.public_ip
}

output "private_key_file" {
  description = "Path to the private key file"
  value       = local_file.ssh_key.filename
}

output "security_group_id" {
  description = "ID of the created security group"
  value       = aws_security_group.ictg_automate_sg.id
}

📌 Explanation:
✅ Public IP → Needed to access the server.
✅ Private Key File → Used for SSH login.
✅ Security Group ID → For managing network rules.

🚀 Next Steps: Now that our infrastructure is live, let’s move on to containerizing the application with Docker! 🐳

🐳 2. Containerizing the Application (Docker Setup)

The application is containerized using Docker for consistency and portability.

🔹 Steps to Build and Run Locally:

1️⃣ Navigate to the project directory:

cd ictg_task

2️⃣ Build and start the containers using Docker Compose:

docker-compose up --build -d

3️⃣ Verify that the containers are running:

docker ps

🔹 Docker Compose Configuration

version: "3.8"
services:
  backend:
    build:
      context: ./backend
    container_name: backend_service
    ports:
      - "8000:8000"
    depends_on:
      - database
    env_file:
      - ./backend/.env
    networks:
      - devops-network
    restart: unless-stopped

  frontend:
    build:
      context: ./frontend
    container_name: frontend_service
    ports:
      - "5173:5173"
    env_file:
      - ./frontend/.env
    networks:
      - devops-network
    restart: unless-stopped

  database:
    image: postgres:latest
    container_name: postgres_database
    ports:
      - "5432:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    env_file:
      - ./backend/.env
    networks:
      - devops-network
    restart: unless-stopped

networks:
  devops-network:
    driver: bridge

📌 Explanation:
✅ Backend (Flask API) → Runs on port 8000.
✅ Frontend (React/Vue) → Runs on port 5173.
✅ Database (PostgreSQL) → Runs on port 5432.
✅ Uses Environment Variables from .env files.
✅ Ensures services restart if they fail (restart: unless-stopped).

🚀 3. Deploying the Application to EC2

Once Terraform provisions the EC2 instance, GitHub Actions will handle automatic deployment.

🔹 Manual Deployment via SSH (Optional Alternative to CI/CD)

If needed, you can manually deploy using SSH:
1️⃣ SSH into the EC2 instance:

ssh -i your-key.pem ubuntu@<EC2_PUBLIC_IP>

2️⃣ Pull the latest Docker images from Docker Hub:

docker pull destinyobs/ictg_task-backend:latest
docker pull destinyobs/ictg_task-frontend:latest

3️⃣ Run the application using Docker:

docker-compose up -d

🎯 4. Verifying the Deployment

Once deployed, test the setup:
✅ Backend:

curl -X GET http://<EC2_PUBLIC_IP>:8000/health

Expected Response: { "status": "ok" }

✅ Frontend: Open http://:5173 in a browser.

🪔 3. CI/CD Pipeline Setup for EC2 Deployment Using GitHub Actions

To streamline the deployment process of our application to an AWS EC2 instance, we leverage GitHub Actions. This setup ensures that every push to the main branch triggers an automated build and deployment of our backend and frontend applications.

Workflow Overview

This GitHub Actions workflow:
✅ Triggers on every push to the main branch.
✅ Builds Docker images for the frontend and backend.
✅ Pushes the images to Docker Hub.
✅ Connects to the EC2 instance via SSH.
✅ Deploys the updated containers automatically.

Workflow Breakdown

1. Define the Workflow

name: Deploy to EC2

on:
  push:
    branches:
      - main

This triggers the workflow when a push occurs on the main branch.

2. Define the Deployment Job

jobs:
  deploy:
    runs-on: ubuntu-latest

Defines a job called deploy that runs on an Ubuntu-based GitHub Actions runner.

3. Checkout the Repository

steps:
  - name: Checkout Repository
    uses: actions/checkout@v3

Fetches the repository code for further processing.

4. Authenticate with Docker Hub

  - name: Log in to Docker Hub
    uses: docker/login-action@v2
    with:
      username: ${{ secrets.DOCKER_USERNAME }}
      password: ${{ secrets.DOCKER_PASSWORD }}

Logs into Docker Hub securely using GitHub Secrets.

5. Build and Push Docker Images

  - name: Build and Push Backend Image
    run: |
      docker build -t ${{ secrets.DOCKER_USERNAME }}/ictg_task-backend:latest ./backend
      docker push ${{ secrets.DOCKER_USERNAME }}/ictg_task-backend:latest

  - name: Build and Push Frontend Image
    run: |
      docker build -t ${{ secrets.DOCKER_USERNAME }}/ictg_task-frontend:latest ./frontend
      docker push ${{ secrets.DOCKER_USERNAME }}/ictg_task-frontend:latest

Builds and pushes Docker images for both the backend and frontend.

6. Connect to EC2 and Deploy Containers

  - name: Deploy to EC2
    uses: appleboy/ssh-action@v0.1.10
    with:
      host: ${{ secrets.EC2_HOST }}
      username: ${{ secrets.EC2_USER }}
      key: ${{ secrets.EC2_PRIVATE_KEY }}
      script: |

Securely connects to the EC2 instance using SSH.

7. Remove Old Containers

        docker stop backend_service frontend_service postgres_database || true
        docker rm backend_service frontend_service postgres_database || true

Stops and removes any existing containers to prevent conflicts.

8. Pull the Latest Docker Images

        docker pull ${{ secrets.DOCKER_USERNAME }}/ictg_task-backend:latest
        docker pull ${{ secrets.DOCKER_USERNAME }}/ictg_task-frontend:latest

Retrieves the latest versions of the images from Docker Hub.

9. Ensure Docker Network Exists

        docker network inspect devops-network >/dev/null 2>&1 || docker network create devops-network

Checks for the network and creates it if missing.

10. Run PostgreSQL Container

        docker run -d \
          --name postgres_database \
          --network devops-network \
          -e POSTGRES_USER=app \
          -e POSTGRES_PASSWORD=${{ secrets.POSTGRES_PASSWORD }} \
          -e POSTGRES_DB=ictg_db \
          -p 5432:5432 \
          --restart unless-stopped \
          postgres:latest

Ensures the database container runs with the correct configurations.

11. Ensure PostgreSQL Readiness

        retries=10
        until docker exec postgres_database pg_isready -U app || [ $retries -eq 0 ]; do
          echo "Waiting for PostgreSQL to be ready..."
          sleep 5
          retries=$((retries - 1))
        done
        if [ $retries -eq 0 ]; then
          echo "PostgreSQL failed to start." >&2
          exit 1
        fi

Waits for PostgreSQL to be fully initialized.

12. Run Backend and Frontend Services

        docker run -d \
          --name backend_service \
          --network devops-network \
          -e DATABASE_URL="postgresql://app:${{ secrets.POSTGRES_PASSWORD }}@postgres_database:5432/ictg_db" \
          -p 8000:8000 \
          --restart unless-stopped \
          ${{ secrets.DOCKER_USERNAME }}/ictg_task-backend:latest

        docker run -d \
          --name frontend_service \
          --network devops-network \
          -p 5173:5173 \
          --restart unless-stopped \
          ${{ secrets.DOCKER_USERNAME }}/ictg_task-frontend:latest

Deploys the backend and frontend services.

13. Clean Up Unused Docker Resources

        docker system prune -af

Frees up disk space by removing unused containers and images.

Security Considerations

✅ Secrets Management: All sensitive credentials are stored securely in GitHub Secrets.
✅ Access Restrictions: The EC2 Security Group is configured to allow only necessary traffic.

✅ Database Security: PostgreSQL password is stored securely and not hardcoded.

Why This Setup?

✅ Fully Automated Deployment – Code push triggers deployment.
✅ Zero Downtime – Smooth updates without disruptions.
✅ Security First – No hardcoded credentials.
✅ Efficient Resource Management – Cleanup ensures optimal performance.

Conclusion & Next Steps

Summary of Achievements

We successfully automated the deployment of a full-stack application using Terraform, Docker, and GitHub Actions. The key milestones included:

🔹 Infrastructure Setup – Provisioned an AWS EC2 instance using Terraform.
🔹 Containerization – Dockerized backend, frontend, and database services.
🔹 CI/CD Pipeline – Automated build and deployment using GitHub Actions.
🔹 Automated Deployment – Utilized SSH actions to update containers smoothly.

Potential Improvements

🚀 Enhanced Security: Implement IAM roles, security best practices, and database access restrictions.
🚀 Automated Scaling: Leverage AWS Auto Scaling and Load Balancing.
🚀 Monitoring & Logging: Integrate Prometheus, Grafana, and centralized logging.
🚀 Infrastructure as Code Refinement: Use remote state management (S3) and modularized configurations.
🚀 Nginx Reverse Proxy & SSL: Implement Nginx for traffic management and SSL security.

This project provides a strong foundation for continuous deployment and scaling in a DevOps-oriented environment. 🚀

Note: This setup is a foundational approach as I continue expanding my expertise in this field. I hope this guide proves useful to fellow DevOps enthusiasts tackling similar challenges!

Maintenance Script: Keeping Your Linux Box in Check

Destiny Obs — Thu, 27 Mar 2025 10:56:30 +0000

Introduction

Welcome, esteemed engineer, noble sysadmin, or brave soul who just realized their server is on fire. 🎩🔥

System maintenance is like brushing your teeth—you can skip it, but eventually, it’ll cost you. This script is your trusty sidekick, automating crucial tasks like monitoring CPU and disk usage, restarting critical services, and applying security updates. Think of it as a tiny, relentless janitor for your Linux system, sweeping up messes before they turn into disasters.

This guide will walk you through the script’s functions, ensuring that you understand what each piece does instead of just running it blindly and praying to the Bash gods.

And no, this knowledge is NOT a waste—whether you’re a rookie or a battle-hardened sysadmin, mastering these skills will make you the unsung hero of your team.

Why Is This Important?

1. Monitoring Resource Usage

Ever had a server slow down so badly you suspected it had just given up on life? Monitoring CPU, RAM, and disk usage helps you spot trouble before your users start screaming on Twitter.

This script logs system metrics and warns you when things start going south.

2. Detecting Security Threats

Hackers never sleep, and your logs are proof. SSH brute-force attacks happen all the time, and failed logins pile up like rejection emails from that dream job you applied for.

This script helps you keep an eye on unauthorized access attempts and system errors.

3. Ensuring Critical Services Stay Running

Imagine waking up to find out your database crashed hours ago, and now your boss is calling. 😱

The script monitors essential services (e.g., Nginx, MySQL) and restarts them if they go down—because humans need sleep, but servers don’t.

4. Automating System Cleanup & Updates

Old temp files waste space. Security patches are life-saving. This script takes care of both, so you don’t have to do it manually like some medieval peasant.

Deep Dive Into the Code

1. Setting Up Logging

LOG_DIR="./logs"
LOG_FILE="$LOG_DIR/system_maintenance.log"

All script actions are recorded in a custom logging directory to avoid system-level permission issues. This ensures the logs are accessible without requiring elevated privileges.

Additionally, the script ensures the log directory exists:

if [ ! -d "$LOG_DIR" ]; then
    mkdir -p "$LOG_DIR"
fi

2. Placeholder Log Files

The script creates placeholders for missing log files (auth.log and syslog):

AUTH_LOG="./auth.log"
SYS_LOG="./syslog"

if [ ! -f "$AUTH_LOG" ]; then
    touch "$AUTH_LOG"
    log "ℹ️ Created placeholder for auth.log."
fi

if [ ! -f "$SYS_LOG" ]; then
    touch "$SYS_LOG"
    log "ℹ️ Created placeholder for syslog."
fi

This step eliminates execution errors caused by non-existent files.

3. Defining Important Variables

TEMP_DIR="/tmp"
CRITICAL_SERVICES=("nginx" "mysql")
DISK_THRESHOLD=80
CPU_THRESHOLD=75
MEM_THRESHOLD=75

TEMP_DIR: Temporary files older than 7 days are deleted.
CRITICAL_SERVICES: Defines services critical to your environment.
Thresholds: Sets alarm limits for resource usage.

4. Logging Function

log() {
    echo "$(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
}

Messages are logged with timestamps for easy troubleshooting.

5. Monitoring System Resources

CPU_USAGE=$(top -bn1 | grep "Cpu(s)" | awk '{print $2 + $4}')
MEM_USAGE=$(free | awk '/Mem/{printf("%.2f"), $3/$2 * 100}')
DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')

Extracts CPU, memory, and disk usage.
Checks resource levels against thresholds:

  if (( $(echo "$CPU_USAGE > $CPU_THRESHOLD" | bc -l) )); then
      log "⚠️ High CPU Usage detected: ${CPU_USAGE}%"
  fi

Warnings are raised if limits are exceeded.

6. Analyzing Logs for Security & Errors

The script analyzes failed SSH login attempts and system errors:

FAILED_LOGINS=$(grep "Failed password" ./auth.log | wc -l)
SYSTEM_ERRORS=$(grep -i "error" ./syslog | wc -l)

if [ "$FAILED_LOGINS" -gt 5 ]; then
    log "🚨 Multiple failed SSH login attempts detected!"
fi

if [ "$SYSTEM_ERRORS" -gt 10 ]; then
    log "⚠️ High number of system errors detected!"
fi

This ensures you stay informed of potential security risks or system instability.

7. Cleaning Up Temporary Files

find "$TEMP_DIR" -type f -atime +7 -delete

Old temporary files are cleared to improve system performance.

8. Restarting Critical Services

The script checks critical services and restarts them if they are not running:

for service in "${CRITICAL_SERVICES[@]}"; do
    if systemctl is-active --quiet "$service"; then
        log "✅ $service is running."
    else
        log "⚠️ $service is not running. Restarting..."
        systemctl restart "$service"
        if systemctl is-active --quiet "$service"; then
            log "🔄 Successfully restarted $service."
        else
            log "❌ Failed to restart $service!"
        fi
    fi
done

9. Applying System Updates

To avoid permission issues, the script checks for elevated privileges before attempting updates:

if [ "$EUID" -ne 0 ]; then
    log "⚠️ System updates require elevated permissions. Please run the script with sudo."
    return
fi

apt update && apt upgrade -y

if [ $? -eq 0 ]; then
    log "✅ System updates completed successfully."
else
    log "❌ System updates failed! Check the logs for details."
fi

This ensures you know when and how to address missing updates.

10. Running Everything in Sequence

main() {
    log "===== System Maintenance Script Started ====="
    monitor_system
    analyze_logs
    optimize_performance
    apply_updates
    log "===== System Maintenance Script Completed ====="
}
main

The script smoothly executes all steps, keeping your system maintained with minimal intervention.

Automating with Cron

To schedule the script daily at midnight:

0 0 * * * /path/to/script.sh

Paste this into crontab via crontab -e for automatic maintenance tasks.

Ensure the script has execution permissions (`chmod +x script.sh`) and is run with `sudo` to function correctly.

Final Thoughts

This script is just one of many ways to automate system maintenance. It’s a simple yet effective tool to help you monitor and manage your system natively. More advanced methods exist, but this provides a solid foundation for understanding how things work under the hood.

Happy automating! 🛠️🚀

I’m DestinyObs | iBuild | iDeploy | iSecure | iSustain

Automating AWS S3 Bucket Setup with Bash and PowerShell

Destiny Obs — Thu, 27 Mar 2025 10:27:15 +0000

Managing AWS S3 buckets manually is fine—until it isn't. If you've ever found yourself clicking around the AWS Console or typing out endless CLI commands just to set up a simple S3 bucket, then this automation script is for you. With Bash and PowerShell, we’ll make the process seamless, efficient, and (most importantly) repeatable.

🚀 What This Script Does

Checks for AWS CLI: If AWS CLI isn’t installed, it installs it and configures credentials.
Creates an S3 Bucket: Takes user input for bucket name and sets it up in a secure manner.
Secures the Bucket: Ensures no public access is allowed.
Uploads a File: Lets the user upload a file from their local machine.
Generates a Pre-signed URL: Creates a time-limited download link for the uploaded file.

🏗️ The Bash Script (Linux/macOS)

#!/bin/bash

# Function to check if AWS CLI is installed and install it if necessary
check_aws_cli() {
    # Check if the 'aws' command is available in the system
    if ! command -v aws &> /dev/null; then
        echo "AWS CLI not found. Installing AWS CLI..."

        # Download the AWS CLI installation package
        curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"

        # Unzip the downloaded file
        unzip awscliv2.zip

        # Install AWS CLI using sudo privileges
        sudo ./aws/install

        # Clean up by removing unnecessary installation files
        rm -rf aws awscliv2.zip

        echo "AWS CLI installed successfully."
    else
        echo "AWS CLI is already installed."
    fi
}

# Function to configure AWS CLI with user-provided credentials
configure_aws() {
    echo "Configuring AWS CLI..."
    # Run the interactive AWS CLI configuration command
    aws configure
}

# Function to create an S3 bucket securely
create_s3_bucket() {
    local bucket_name=$1  # First argument: Name of the S3 bucket
    local region=$2       # Second argument: AWS region

    echo "Creating S3 bucket: $bucket_name in region: $region..."
    # Create an S3 bucket using AWS CLI
    aws s3api create-bucket --bucket "$bucket_name" --region "$region"

    # Check if the bucket creation was successful
    if [ $? -eq 0 ]; then
        echo "Bucket created successfully: $bucket_name"
    else
        echo "Failed to create bucket."
        exit 1  # Exit script if bucket creation fails
    fi

    # Apply security settings to block public access to the bucket
    aws s3api put-public-access-block --bucket "$bucket_name" \
        --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

    echo "Bucket secured: Public access blocked."
}

# Function to upload a file to an S3 bucket
upload_file() {
    local file_path=$1    # First argument: Path to the file to be uploaded
    local bucket_name=$2  # Second argument: S3 bucket name

    echo "Uploading file: $file_path to S3 bucket: $bucket_name..."
    # Use AWS CLI to copy the file to the specified S3 bucket
    aws s3 cp "$file_path" "s3://$bucket_name/"

    # Check if the upload was successful
    if [ $? -eq 0 ]; then
        echo "File uploaded successfully."
    else
        echo "File upload failed."
        exit 1  # Exit script if upload fails
    fi
}

# Function to generate a pre-signed URL for an S3 object (file)
generate_presigned_url() {
    local bucket_name=$1  # First argument: S3 bucket name
    local file_name=$2    # Second argument: Name of the file in the bucket
    local expiry=$3       # Third argument: Expiry time in seconds for the URL

    echo "Generating pre-signed URL..."
    # Generate a pre-signed URL that allows temporary access to the file
    presigned_url=$(aws s3 presign "s3://$bucket_name/$file_name" --expires-in "$expiry")

    echo "Pre-signed URL (valid for $expiry seconds):"
    echo "$presigned_url"
}

# Main script execution begins here

# Step 1: Ensure AWS CLI is installed
check_aws_cli

# Step 2: Configure AWS CLI with user credentials
configure_aws

# Step 3: Prompt the user for S3 bucket details
read -p "Enter S3 bucket name: " bucket_name  # Get bucket name from user
read -p "Enter AWS region (e.g., us-east-1): " region  # Get AWS region from user

# Step 4: Create the S3 bucket securely
create_s3_bucket "$bucket_name" "$region"

# Step 5: Prompt the user for the file to upload
read -p "Enter file path to upload: " file_path  # Get file path from user

# Step 6: Upload the specified file to the created S3 bucket
upload_file "$file_path" "$bucket_name"

# Step 7: Extract file name from file path
file_name=$(basename "$file_path")

# Step 8: Generate a pre-signed URL valid for 1 hour (3600 seconds)
generate_presigned_url "$bucket_name" "$file_name" 3600

🛠️ Breakdown

Checking for AWS CLI: If it's missing, the script downloads and installs it.
Configuring AWS CLI: It prompts the user to enter AWS credentials.
Bucket Creation: Ensures a unique bucket is created.
Security Setup: Disables public access to prevent unwanted exposure.
Uploading Files: User can specify a file to upload.
Generating Pre-signed URL: Provides a temporary download link for file sharing.

📚 How to Save and Run the Script

Saving the Script

Open a terminal and navigate to your desired directory.
Create a new script file:

   nano s3_script.sh

Copy and paste the script content into the file.
Save and exit (Press CTRL + X, then Y, and hit Enter).

Running the Script

Grant execute permission:

   chmod +x s3_script.sh

Run the script:

   ./s3_script.sh

Follow the on-screen prompts to configure AWS CLI, create a bucket, upload a file, and generate a pre-signed URL.

🖥️ The PowerShell Script (Windows)

# Check if AWS CLI is installed
if (-not (Get-Command aws -ErrorAction SilentlyContinue)) {
    Write-Output "AWS CLI not found! Installing..."
    Invoke-WebRequest -Uri "https://awscli.amazonaws.com/AWSCLIV2.msi" -OutFile "AWSCLIV2.msi"
    Start-Process msiexec.exe -ArgumentList "/i AWSCLIV2.msi /quiet" -Wait
    Remove-Item "AWSCLIV2.msi"
}

Write-Output "Configuring AWS CLI..."
Start-Process aws -ArgumentList "configure" -NoNewWindow -Wait

# Get user input for bucket name
$BucketName = Read-Host "Enter a unique S3 bucket name"

# Create S3 Bucket
aws s3api create-bucket --bucket $BucketName --region us-east-1

Write-Output "Blocking public access..."
aws s3api put-public-access-block --bucket $BucketName --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true

# Upload a file
$FilePath = Read-Host "Enter the file path to upload"
aws s3 cp "$FilePath" s3://$BucketName/

# Generate pre-signed URL
$FileName = Split-Path $FilePath -Leaf
$PresignedUrl = aws s3 presign "s3://$BucketName/$FileName" --expires-in 3600

Write-Output "Your pre-signed URL: $PresignedUrl"

🔍 Breakdown

Checks and installs AWS CLI if missing.
Configures AWS credentials.
Creates a bucket and secures it.
Uploads a user-specified file.
Generates a pre-signed URL for sharing.

📚 How to Save and Run the Script

Saving the Script

Open a terminal and navigate to your desired directory.
Create a new script file: s3_script.ps1
Copy and paste the script content into the file.
Save and exit (Press CTRL + X, then Y, and hit Enter).

Running the Script

Grant execute permission: Allow script execution (if restricted): Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
Run the script: .\s3_script.ps1
Follow the on-screen prompts to configure AWS CLI, create a bucket, upload a file, and generate a pre-signed URL.

🏆 Final Thoughts

With these scripts, setting up an S3 bucket, securing it, and sharing files is now effortless. Whether you're on Windows or Linux/macOS, you’re covered. No more manual work—just automation magic! ✨

🚀 Happy Automating!

Cloud Computing Explained: IaaS, PaaS, SaaS – What the Heck Are They?

Destiny Obs — Mon, 24 Mar 2025 10:13:45 +0000

🚀 So, You Want to Understand Cloud Computing?

Great! But let me warn you—if you've ever tried explaining cloud computing to a friend, you’ve probably seen their eyes glaze over like a Windows update stuck at 99%.

Fear not! I’m here to decode the cloud madness, break down IaaS, PaaS, and SaaS, and—who knows?—maybe even make you laugh a little.

Let’s dive in.

Welcome to the Cloud Buffet ☁️🍽️

Well, cause i love food, let's use this... Imagine you walk into a cloud computing restaurant. You’re hungry, but how much effort do you want to put into your meal?

You’ve got three choices:

IaaS (Infrastructure as a Service): You buy raw ingredients, rent a kitchen, and cook your own meal.
PaaS (Platform as a Service): You get a prepped kitchen, pre-cut ingredients, and just need to cook.
SaaS (Software as a Service): You sit back, order from the menu, and enjoy—zero effort.

Let’s break them down properly.

IaaS: The DIY Cloud (You Like Full Control, Eh?)

🛠️ What is IaaS?

Infrastructure as a Service (IaaS) is like renting a virtual data center. You get bare-bones computing power—servers, storage, networking—but you are responsible for installing, configuring, and managing everything on top.

It’s perfect for DevOps engineers and sysadmins who love control and don’t mind getting their hands dirty.

🔥 Real-world Example

Think AWS EC2, Google Compute Engine, Microsoft Azure VMs. You spin up a virtual machine, install an OS, configure networking, and boom—you have a server in the cloud.

💡 Why Choose IaaS?

✅ You need full control over the system.

✅ You want to run custom applications or complex enterprise software.

✅ You enjoy feeling like a cloud god, managing your own infrastructure.

⛔ But Beware!

❌ You’re responsible for security, patches, and scaling.

❌ Misconfigurations can lead to crazy costs. (Ever left an AWS EC2 instance running all month? RIP your wallet.)

PaaS: The "Chef-Prepared" Cloud (For Developers Who Hate DevOps)

👨‍🍳 What is PaaS?

Platform as a Service (PaaS) is IaaS with the hard parts managed for you. It gives you a pre-configured environment with an OS, middleware, and runtime—just bring your code and deploy.

PaaS is like walking into a restaurant with everything prepped—just follow the recipe, and your dish is ready.

🔥 Real-world Example

Think Heroku, AWS Elastic Beanstalk, Google App Engine, or Azure App Service. You just push your app, and the platform handles infrastructure, scaling, and networking.

💡 Why Choose PaaS?

✅ You’re a developer and don’t want to waste time setting up infrastructure.

✅ You want auto-scaling and managed deployments.

✅ You like focusing on coding while someone else handles servers.

⛔ But Beware!

❌ Less flexibility—you can’t tweak everything.

❌ Some platforms lock you into their ecosystem. (Vendor lock-in is real, folks.)

SaaS: The Lazy Cloud (Just Use It, No Work Needed)

🛋️ What is SaaS?

Software as a Service (SaaS) is ready-to-use software in the cloud. No installation, no configuration—just log in and get to work.

Imagine walking into a restaurant, ordering from a menu, and having a delicious meal served. No cooking, no stress.

🔥 Real-world Example

Gmail? SaaS.

Netflix? SaaS.

Google Docs, Zoom, Slack? All SaaS.

💡 Why Choose SaaS?

✅ You want something that just works without setting up infrastructure.

✅ You need easy access from any device.

✅ Your company doesn’t want to manage software updates.

⛔ But Beware!

❌ You have zero control over the software.

❌ If the provider goes down, you go down with them. (Looking at you, Zoom outage of 2020.)

IaaS vs. PaaS vs. SaaS – The Ultimate Showdown

Feature	IaaS	PaaS	SaaS
Who manages it?	You	Cloud provider (mostly)	Cloud provider (completely)
Flexibility	High	Medium	Low
Ease of Use	Hard	Medium	Easy
Examples	AWS EC2, Google Compute Engine	Heroku, Google App Engine	Gmail, Netflix, Zoom
Best for?	DevOps engineers	Developers	End-users

Beyond IaaS, PaaS, and SaaS: The Other "aaS" Models You Should Know

Cloud computing doesn’t stop at these three—oh no, the aaS (as a Service) family has expanded like a Marvel franchise:

🕵️ FaaS (Function as a Service) → Serverless computing where your code runs on demand. Think AWS Lambda, Google Cloud Functions.

🐳 CaaS (Container as a Service) → Managed container orchestration. Think AWS Fargate, GKE.

💾 DBaaS (Database as a Service) → Fully managed databases. Think AWS RDS, Firebase.

🔗 BaaS (Backend as a Service) → No need to build a backend! Think Firebase, Supabase.

Final Thoughts – Which Cloud Model Should You Choose?

🔹 Are you a control freak who loves managing infrastructure? → Go for IaaS.

🔹 Are you a developer who just wants to code and deploy? → PaaS is your best friend.

🔹 Do you want a fully managed experience with no headaches? → SaaS is the way.

At the end of the day, cloud computing isn’t just about acronyms—it’s about choosing the right tool for the job.

And now that you know IaaS, PaaS, and SaaS, you can finally explain them to your friends without boring them to death. 🎉

What’s Next?

🚀 Want to try IaaS? Spin up an AWS EC2 instance.

🚀 Want to test PaaS? Deploy a Node.js app on Heroku.

🚀 Want to use SaaS? Just keep using Gmail. 😆

DEV Community: Destiny Obs

Build an Ubuntu WireGuard gateway to access private cloud VMs from your laptop

Summary

Table of contents

What we are building

1. Create the private LAN and router

2. Create the Ubuntu VPN gateway

If DNS is missing

3. Give the gateway a public VPN endpoint

4. Understand the gateway configuration

5. Prepare the laptop and run the installer

6. Update the laptop tunnel

7. Create a private VM and SSH into it

8. Use the same VPN for Windows RDP and other services

When a connection fails

Before using it for a customer

Complete automated gateway script

Running the script: prompts and expected output

Prompt 1: the public endpoint

Prompt 2: the customer LAN

Prompt 3: the WireGuard subnet

Prompt 4: the first device name

Prompt 5: the laptop public key

Automatic installation

Completion output

Laptop configuration printed by the script

Running installation again

Adding and removing devices after installation

Add a device

Display a device’s settings again

Revoke a device

Check status or reapply the gateway firewall

The Complete Beginner's Guide to vpcctl: Building Virtual Networks on Linux

Table of Contents

Introduction: What Problem Are We Solving?

Understanding the Basics

What is a VPC?

What is a Subnet?

What is NAT?

What is Peering?

Real-World Scenario: The Coffee Shop Network

How vpcctl Works Under the Hood

Prerequisites and Installation

System Requirements

Install Steps

Quick Start: Your First VPC

Step 0: One-Time Checks

Step 1: Create the VPC

Step 2: Add Subnets

Step 3: Deploy Test Apps

Step 4: Enable NAT (Internet Access for public)

Step 5: Test Connectivity

Step 6: Show VPC Isolation

Step 7: Peer VPCs (Allow Only Public↔Public)

Step 8: Apply Security Policy

Step 9: Inspect and List

Step 10: Cleanup

Deep Dive: Understanding Each Command

create

add-subnet

deploy-app

stop-app

enable-nat

peer

apply-policy

list / inspect / delete

Architecture Overview

Command Reference

Troubleshooting Common Issues

Issue 1: "Permission denied" or "Operation not permitted"

Issue 2: "Cannot find command: ip"

Issue 3: "Bridge already exists"

Issue 4: Namespace Cannot Access Internet

Issue 5: Subnets Cannot Communicate

Issue 6: "Cannot delete VPC: bridge is busy"

Issue 7: Peered VPCs Cannot Communicate

Issue 8: High CPU Usage from Python HTTP Server

Issue 9: "Address already in use"

Issue 10: Metadata File Corruption

Debugging Tips

Step 4: Install .NET SDK and Hosting Bundle