What is a Network/VPC?

A Virtual Private Cloud (VPC) is an isolated network environment in the cloud where you deploy your resources. Think of it as your own private data center in the cloud - completely isolated from other users' networks.

Key Benefits:

• Network Isolation - Your resources are completely isolated from other accounts
• Security Control - Define your own firewall rules and access policies
• Custom IP Ranges - Choose your own IP address ranges
• Multi-Region - Deploy networks in different regions for global reach

CIDR Notation Explained

CIDR (Classless Inter-Domain Routing) is a method for allocating IP addresses. When you see 10.0.0.0/16, it means:

• 10.0.0.0 - The base IP address
• /16 - The network prefix (first 16 bits are fixed)

Common CIDR Ranges

Public vs Private Subnets

Within your VPC, you create subnets - smaller networks that divide your IP space. Subnets come in two types:

Public Subnets

Purpose: Internet-accessible resources

Use For:

• Load balancers (ALB, NLB)
• NAT Gateways
• Bastion hosts
• Public-facing web servers

How It Works: Has a route to an Internet Gateway (IGW)

Private Subnets

Purpose: Internal resources with no direct internet access

Use For:

• Application servers
• Kubernetes worker nodes
• Databases
• Internal services

How It Works: Internet access via NAT Gateway in public subnet

VPC: 10.0.0.0/16
│
├── Public Subnet 1: 10.0.1.0/24 (AZ: us-east-1a)
│   └── Load Balancer, NAT Gateway
│
├── Public Subnet 2: 10.0.2.0/24 (AZ: us-east-1b)
│   └── Load Balancer, NAT Gateway
│
├── Private Subnet 1: 10.0.11.0/24 (AZ: us-east-1a)
│   └── Kubernetes Nodes, Applications
│
└── Private Subnet 2: 10.0.12.0/24 (AZ: us-east-1b)
    └── Kubernetes Nodes, Applications

Creating a Network

Step 1: Navigate to Networks

1. Go to Account → Networks
2. Click "+ Create Network"

Step 2: Choose Provider

Select your cloud provider (AWS, GCP, Azure)

Make sure you've already added the provider credentials in Providers.

Step 3: Define CIDR Range

Options:

• Predefined: Choose from dropdown (10.0.0.0/16, 10.10.0.0/16, etc.)
• Custom: Enter your own CIDR block

Requirements:

• Must be RFC1918 compliant (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
• Must not overlap with existing networks
• Recommended: /16 for production, /20 for staging, /24 for dev

Step 4: Choose NAT Gateway Strategy

Select how NAT Gateways will be deployed for internet access:

Step 5: Select Availability Zone Configuration

Choose how many availability zones to use:

Step 6: Configure Subnets (if Automatic mode)

Public Subnets:

• Minimum: 1 subnet
• Maximum: 5 subnets
• Example: 10.0.1.0/24, 10.0.2.0/24
• Used for: Load balancers, NAT Gateways, bastion hosts

Private Subnets:

• Minimum: 1 subnet
• Maximum: 5 subnets
• Example: 10.0.11.0/24, 10.0.12.0/24
• Used for: Kubernetes nodes, application servers, databases

Step 5: Select Region

Choose AWS region:

• us-east-1 (N. Virginia)
• us-west-2 (Oregon)
• eu-west-1 (Ireland)
• ap-southeast-1 (Singapore)
• ... and more

Step 6: Review and Create

Review your configuration and click "Create Network"

Creation Time: 5-10 minutes

Importing Existing VPCs

Already have a VPC in AWS? You can import it into SeaGit to manage it alongside your Kubernetes clusters without recreating your infrastructure.

When to Import vs Create New

Import Methods

SeaGit supports three flexible methods to identify your VPC and subnets:

1. Import by Resource IDs (Recommended)

Best for: Precise control, known resource IDs

How it works: Directly reference AWS resource IDs

VPC ID: vpc-0a1b2c3d4e5f6g7h8
Public Subnets: subnet-abc123, subnet-def456
Private Subnets: subnet-xyz789, subnet-uvw012

Steps:

1. Go to AWS Console → VPC Dashboard
2. Copy your VPC ID (starts with vpc-)
3. Copy subnet IDs from the Subnets section
4. Paste into SeaGit import form

2. Import by VPC Name

Best for: Named VPCs, easier identification

How it works: SeaGit searches for VPC by its Name tag

VPC Name: production-vpc
Public Subnets: subnet-abc123, subnet-def456  
Private Subnets: subnet-xyz789, subnet-uvw012

Requirements:

• VPC must have a Name tag in AWS
• Name must be unique in the region

3. Import by CIDR Block

Best for: When you know the IP range

How it works: SeaGit finds VPC by CIDR range

VPC CIDR: 10.0.0.0/16
Public Subnets: subnet-abc123, subnet-def456
Private Subnets: subnet-xyz789, subnet-uvw012

Requirements:

• CIDR must be unique in the region
• Must match exactly (e.g., 10.0.0.0/16, not 10.0.0.0/20)

Subnet Import Methods

For each subnet type (public and private), you can choose how to identify them:

Option A: By Subnet IDs (Recommended)

Direct reference using AWS subnet IDs

Public: subnet-0a1b2c3d, subnet-1e2f3g4h
Private: subnet-5i6j7k8l, subnet-9m0n1o2p

Option B: By CIDR Blocks

Identify subnets by their IP ranges

Public: 10.0.1.0/24, 10.0.2.0/24
Private: 10.0.11.0/24, 10.0.12.0/24

Option C: By AWS Tags

Best for: Large VPCs with many subnets, consistent tagging strategy

How it works: SeaGit finds all subnets with a specific tag

Tag: Type = public  (finds all public subnets)
Tag: Type = private (finds all private subnets)

Prerequisites:

• Your subnets must be tagged in AWS: Type = public or Type = private
• Use consistent tagging across all subnets

# Tag your AWS subnets:
aws ec2 create-tags \
  --resources subnet-abc123 subnet-def456 \
  --tags Key=Type,Value=public

aws ec2 create-tags \
  --resources subnet-xyz789 subnet-uvw012 \
  --tags Key=Type,Value=private

Step-by-Step Import Process

1. Navigate to Networks page
   Account → Networks → Click "Import Network" button
2. Select Provider and Region
   Choose the AWS account and region where your VPC exists
3. Choose VPC Import Method
   Select: By ID, By Name, or By CIDR
4. Enter VPC Identifier
   Depending on method: vpc-xxx, "production-vpc", or 10.0.0.0/16
5. Configure Public Subnets
   Choose import method (IDs, CIDRs, or Tags) and provide values
6. Configure Private Subnets
   Choose import method (IDs, CIDRs, or Tags) and provide values
7. Review and Import
   Click "Import Network" - Process takes 2-5 minutes

What Happens During Import

When you import a VPC, SeaGit performs the following validation and discovery:

1. VPC Discovery - Verifies VPC exists in the specified region
2. Subnet Discovery - Finds subnets based on your chosen method
3. Resource Validation - Checks that subnets belong to the VPC
4. Metadata Extraction - Reads CIDR blocks, availability zones, route tables
5. State Import - Creates Terraform state to manage resources
6. Network Registration - Adds network to SeaGit for cluster deployment

Import Examples

Example 1: Import by IDs (Simple)

Provider: AWS Production Account
Region: us-east-1

VPC Import Method: By ID
VPC ID: vpc-0a1b2c3d4e5f6g7h8

Public Subnets Method: By IDs
Public Subnet IDs: subnet-pub1, subnet-pub2

Private Subnets Method: By IDs  
Private Subnet IDs: subnet-priv1, subnet-priv2, subnet-priv3

Example 2: Import by Tags (Scalable)

Provider: AWS Production Account
Region: eu-west-1

VPC Import Method: By Name
VPC Name: production-vpc

Public Subnets Method: By AWS Tag
Tag Value: public
(SeaGit will find all subnets tagged with Type=public)

Private Subnets Method: By AWS Tag
Tag Value: private
(SeaGit will find all subnets tagged with Type=private)

Example 3: Mixed Import Methods

Provider: AWS Staging Account
Region: us-west-2

VPC Import Method: By CIDR
VPC CIDR: 10.20.0.0/16

Public Subnets Method: By CIDRs
Public Subnet CIDRs: 10.20.1.0/24, 10.20.2.0/24

Private Subnets Method: By IDs
Private Subnet IDs: subnet-abc, subnet-def, subnet-ghi

Post-Import Verification

After import completes, verify the following:

• Network Status: Check that network shows "Active" status
• CIDR Blocks: Verify VPC and subnet CIDRs are correct
• Availability Zones: Ensure subnets are in expected AZs
• Subnet Count: Confirm all public/private subnets were discovered
• Cluster Compatibility: Test deploying a cluster to the imported network

Troubleshooting Import Issues

"VPC Not Found" Error

Causes:

• VPC ID is incorrect or doesn't exist in the region
• VPC is in a different AWS account than the selected provider
• Wrong region selected
• VPC Name tag doesn't match (case-sensitive when using name import)

Solution:

# Verify VPC exists in AWS
aws ec2 describe-vpcs --region us-east-1 --vpc-ids vpc-xxx

# List all VPCs in region
aws ec2 describe-vpcs --region us-east-1

"Subnet Not in VPC" Error

Cause: Specified subnet belongs to a different VPC

Solution:

# Check which VPC a subnet belongs to
aws ec2 describe-subnets --subnet-ids subnet-xxx \
  --query 'Subnets[0].VpcId'

# List all subnets in a VPC
aws ec2 describe-subnets \
  --filters "Name=vpc-id,Values=vpc-xxx"

"No Subnets Found with Tag" Error

Causes:

• Subnets aren't tagged with specified Type value
• Tag key is not exactly "Type" (case-sensitive)
• Tag value doesn't match (e.g., "Public" vs "public")

Solution:

# Check existing tags on subnets
aws ec2 describe-subnets --subnet-ids subnet-xxx \
  --query 'Subnets[0].Tags'

# Tag subnets correctly
aws ec2 create-tags \
  --resources subnet-xxx \
  --tags Key=Type,Value=public

"Permission Denied" Error

Cause: Provider credentials lack necessary IAM permissions

Required Permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeRouteTables",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeNatGateways",
        "ec2:DescribeTags"
      ],
      "Resource": "*"
    }
  ]
}

Multi-AZ (Availability Zone) Deployments

Availability Zones are physically separate data centers within a region. Deploying across multiple AZs provides:

Benefits

• High Availability - If one AZ fails, your app keeps running
• Fault Tolerance - Protection against data center outages
• Better SLA - AWS guarantees 99.99% uptime for multi-AZ

Best Practices

• Minimum 2 AZs - Deploy at least 2 public and 2 private subnets
• Balance Load - Distribute traffic across AZs
• Data Replication - Ensure data is replicated across AZs

Network Security

Security Groups

Virtual firewalls that control inbound and outbound traffic

• Stateful - Return traffic is automatically allowed
• Instance-level - Applied to individual resources
• Default Deny - Everything blocked unless explicitly allowed

Network ACLs (Access Control Lists)

Additional security layer at subnet level

• Stateless - Must explicitly allow both inbound and outbound
• Subnet-level - Applied to entire subnet
• Rule Numbers - Rules evaluated in order (lowest first)

Best Practices

• Use security groups as primary firewall
• Use NACLs for additional subnet-level protection
• Follow principle of least privilege
• Regularly audit security rules

Cost Considerations

NAT Gateway Costs

Pricing: ~$0.045/hour + $0.045/GB data processed

Monthly Cost: ~$32/month per NAT Gateway (plus data transfer)

Cost Saving Tips:

• Single NAT Gateway for Dev - Use one NAT Gateway instead of per-AZ
• NAT Instances for Low Traffic - Use EC2 NAT instances (cheaper but less reliable)
• VPC Endpoints - Use VPC endpoints for AWS services to avoid NAT costs

Data Transfer Costs

• Within VPC: Free
• Between AZs: $0.01/GB
• To Internet: $0.09/GB (first 10TB)
• Between Regions: $0.02/GB

VPC Peering Costs

Same Region: $0.01/GB

Cross Region: $0.02/GB

Troubleshooting

"CIDR Block Overlaps" Error

Symptoms: Cannot create network, error about overlapping CIDR

Cause: New network CIDR overlaps with existing network

Solution:

1. Check existing networks in your account
2. Choose a different CIDR range
3. Example: If 10.0.0.0/16 exists, try 10.1.0.0/16 or 10.10.0.0/16

"Subnet Not in CIDR Range" Error

Symptoms: Subnet creation fails

Cause: Subnet CIDR is outside VPC CIDR

Solution:

• VPC: 10.0.0.0/16 allows subnets from 10.0.0.0 to 10.0.255.255
• 10.1.1.0/24 would be invalid (outside range)
• 10.0.1.0/24 would be valid (inside range)

Cannot Connect to Resources

Symptoms: Cannot access resources in VPC

Common Causes:

1. No Internet Gateway - Public subnets need IGW
2. No NAT Gateway - Private subnets need NAT for outbound
3. Wrong Route Table - Subnets not associated with correct route table
4. Security Group Rules - Firewall blocking traffic

Solution:

# Check route tables
aws ec2 describe-route-tables --filters "Name=vpc-id,Values=vpc-xxx"

# Check security groups
aws ec2 describe-security-groups --filters "Name=vpc-id,Values=vpc-xxx"

# Check NAT gateways
aws ec2 describe-nat-gateways --filter "Name=vpc-id,Values=vpc-xxx"

"IP Address Exhaustion" Issue

Symptoms: Cannot launch new instances, "no available IPs"

Cause: All IPs in subnet are used

Solution:

1. Add additional subnets to VPC
2. Delete unused resources to free IPs
3. Or create new VPC with larger CIDR (/16 instead of /24)

API Reference

List Networks

GET /accounts/{accountId}/networks?active={0|1}&orgid={orgId}

Query Parameters:

• active: Filter by status (1 = active, 0 = all)
• orgid: Filter by organization

Create Network

POST /accounts/{accountId}/networks
Content-Type: application/json

{
  "name": "production-vpc",
  "provider_id": "507f1f77bcf86cd799439011",
  "region": "us-east-1",
  "cidr": "10.0.0.0/16",
  "public_subnets": ["10.0.1.0/24", "10.0.2.0/24"],
  "private_subnets": ["10.0.11.0/24", "10.0.12.0/24"]
}

Get Network Details

GET /accounts/{accountId}/networks/{networkId}

Update Network

PUT /accounts/{accountId}/networks/{networkId}
Content-Type: application/json

{
  "name": "production-vpc-updated"
}

Delete Network

DELETE /accounts/{accountId}/networks/{networkId}

Note: Cannot delete networks in use by clusters