Configuration Reference

This document provides comprehensive details on the Subnetter configuration schema, explaining all available options and their purposes.

Configuration Schema

The configuration file must follow this schema:

interface Config {
  /**
   * The base CIDR block to allocate subnets from
   * @example "10.0.0.0/8"
   */
  baseCidr: string;

  /**
   * Optional prefix lengths for different levels of the hierarchy
   */
  prefixLengths?: {
    account?: number;
    region?: number;
    az?: number;
  };

  /**
   * List of cloud providers to support
   * @example ["aws", "azure", "gcp"]
   */
  cloudProviders: string[];

  /**
   * Account configurations
   */
  accounts: Account[];

  /**
   * Default subnet types with their prefix lengths
   * @example { "Public": 24, "Private": 23, "Database": 25 }
   */
  subnetTypes: Record<string, number>;

  /**
   * Optional allocation strategy configuration
   */
  allocation?: {
    /**
     * Whether to use strict validation rules for CIDR allocations
     * @default true
     */
    strictValidation?: boolean;

    /**
     * Whether to allow automatic expansion of the base CIDR if needed
     * @default false
     */
    autoExpand?: boolean;
  };
}

interface Account {
  /**
   * Name of the account
   * @example "production"
   */
  name: string;

  /**
   * Cloud-specific configurations
   */
  clouds: Record<string, CloudConfig>;
}

interface CloudConfig {
  /**
   * Optional base CIDR for this cloud provider within the account
   * If not provided, it will be auto-allocated from the account's allocation
   * @example "10.0.0.0/16"
   */
  baseCidr?: string;

  /**
   * List of regions to create subnets in
   * @example ["us-east-1", "eu-west-1"]
   */
  regions: string[];

  /**
   * Optional list of specific availability zones to use
   * If not provided, defaults will be used based on the cloud provider
   * @example ["us-east-1a", "us-east-1b", "us-east-1c"]
   */
  availabilityZones?: Record<string, string[]>;

  /**
   * Optional subnet types specific to this cloud provider
   * If not provided, the global subnetTypes will be used
   * @example { "Public": 24, "Private": 23, "Database": 25 }
   */
  subnetTypes?: Record<string, number>;
}

Required Fields

The following fields are required in all configurations:

baseCidr: The top-level IPv4 CIDR block from which all subnets will be allocated
cloudProviders: Array of cloud provider names (e.g., “aws”, “azure”, “gcp”)
accounts: Array of account configurations
subnetTypes: Object mapping subnet type names to their prefix lengths

Optional Fields

These fields can be omitted, and defaults will be used:

prefixLengths: Customize the hierarchy levels for CIDR allocation
- Default is based on the base CIDR and number of accounts/regions

Configuration Example

Here’s an example of a complete configuration file:

{
  "baseCidr": "10.0.0.0/8",
  "prefixLengths": {
    "account": 16,
    "region": 20,
    "az": 24
  },
  "cloudProviders": ["aws", "azure", "gcp"],
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "regions": ["us-east-1", "us-west-2", "eu-west-1"],
          "availabilityZones": {
            "us-east-1": ["us-east-1a", "us-east-1b", "us-east-1c"]
          }
        },
        "azure": {
          "regions": ["eastus", "westus2", "westeurope"]
        }
      }
    },
    {
      "name": "staging",
      "clouds": {
        "aws": {
          "regions": ["us-east-1", "eu-west-1"]
        }
      }
    }
  ],
  "subnetTypes": {
    "Public": 24,
    "Private": 23,
    "Database": 25,
    "Management": 26
  }
}

Configuration Best Practices

When creating your configuration file, consider these recommended practices:

Start with a large CIDR block (e.g., /8 or /12) to accommodate future growth
Use consistent prefix lengths across environments to simplify management
Plan for multi-cloud operations even if you only use one provider initially
Map subnet types to workload requirements by allocating larger blocks to applications requiring more IPs
Document your addressing scheme for reference by network and cloud teams
Store configurations in version control to track changes over time

Cloud-Specific Considerations

AWS

Region format: Use AWS region codes like “us-east-1”, “eu-west-1”
AZ format: Use AWS AZ codes like “us-east-1a”, “us-east-1b”
VPC limits: Default maximum of 5 VPCs per region (can be increased via AWS support)
Subnet considerations: AWS reserves the first 4 and last IP of each subnet

Azure

Region format: Use Azure region names like “eastus”, “westeurope”
AZ format: Azure AZs are represented as numbers (1, 2, 3)
VNET limits: Up to 1000 VNets per subscription
Subnet considerations: Azure reserves the first 4 and last IP of each subnet

GCP

Region format: Use GCP region codes like “us-central1”, “europe-west1”
Zone format: Use GCP zone codes like “us-central1-a”, “us-central1-b”
VPC limits: Up to 15 VPC networks per project
Subnet considerations: GCP reserves the first 2 and last 2 IPs of each subnet

File Format Support

Subnetter supports both JSON and YAML formats for configuration files:

YAML Example:

baseCidr: 10.0.0.0/8
cloudProviders:
  - aws
  - azure
accounts:
  - name: production
    clouds:
      aws:
        regions:
          - us-east-1
          - us-west-2
# ...rest of configuration

JSON Example:

{
  "baseCidr": "10.0.0.0/8",
  "cloudProviders": ["aws", "azure"],
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "regions": ["us-east-1", "us-west-2"]
        }
      }
    }
  ]
  // ...rest of configuration
}

Advanced Configuration Options

Allocation Strategy Control

Subnetter uses a sophisticated allocation strategy to ensure that CIDR blocks are optimally distributed without overlaps. You can influence how this allocation works through several configuration options:

interface Config {
  // ... other fields ...

  /**
   * Optional allocation strategy configuration
   */
  allocation?: {
    /**
     * Whether to use strict validation rules for CIDR allocations
     * @default true
     */
    strictValidation?: boolean;

    /**
     * Whether to allow automatic expansion of the base CIDR if needed
     * @default false
     */
    autoExpand?: boolean;
  };
}

Account-Level CIDR Overrides

For greater control over specific sections of your IP address space, you can override the automatically allocated CIDR blocks at the account level. This is particularly useful when you’re migrating existing infrastructure into Subnetter:

{
  "baseCidr": "10.0.0.0/8",
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "provider": "aws",
          "baseCidr": "10.1.0.0/16",  // Override the auto-allocated CIDR
          "regions": ["us-east-1", "us-west-2"]
        }
      }
    }
  ]
}

The allocation algorithm will respect these overrides while ensuring that no overlaps occur with other accounts or providers.

Cloud Provider-Specific Overrides

You can also provide cloud provider-specific CIDR blocks to segment your IP space by provider:

{
  "baseCidr": "10.0.0.0/8",
  "accounts": [
    {
      "name": "development",
      "clouds": {
        "aws": {
          "provider": "aws",
          "baseCidr": "10.0.0.0/16",
          "regions": ["us-east-1"]
        },
        "azure": {
          "provider": "azure",
          "baseCidr": "172.16.0.0/16",  // Completely different address space
          "regions": ["eastus"]
        }
      }
    }
  ]
}

This allows you to use separate address spaces for different cloud providers if needed.

Hierarchical Allocation Process

The allocation process follows a hierarchical structure:

Base CIDR → Starting point (e.g., 10.0.0.0/8)
Account Level → Each account gets a portion (typically /16)
Region Level → Each region gets a portion of the account’s allocation (typically /20)
Availability Zone Level → Each AZ gets a portion of the region’s allocation (typically /24)
Subnet Level → Each subnet type gets a portion of the AZ’s allocation (defined in subnetTypes)

The prefix lengths at each level are configurable through the prefixLengths option:

{
  "baseCidr": "10.0.0.0/8",
  "prefixLengths": {
    "account": 16,  // Each account gets a /16
    "region": 20,   // Each region gets a /20
    "az": 24        // Each AZ gets a /24
  },
  // ... rest of config
}

Subnet Type Configuration

Subnet types define the different kinds of subnets you want to create and their respective sizes:

{
  // ... other config
  "subnetTypes": {
    "Public": 26,    // Public subnets get a /26 (62 usable IPs)
    "Private": 24,   // Private subnets get a /24 (254 usable IPs)
    "Database": 27,  // Database subnets get a /27 (30 usable IPs)
    "Management": 28 // Management subnets get a /28 (14 usable IPs)
  }
}

The larger the prefix number, the smaller the subnet. For example, a /24 subnet (256 IPs) is larger than a /26 subnet (64 IPs).

Configuration Validation

Subnetter performs extensive validation on your configuration file to ensure it will produce valid allocations:

CIDR Format Validation: Ensures all CIDR blocks are in valid format (e.g., 10.0.0.0/8)
Prefix Length Validation: Confirms prefix lengths are appropriate for each level
Overlap Detection: Checks that manual CIDR overrides don’t overlap
Space Verification: Confirms there’s enough IP space for all requested subnets

If validation fails, Subnetter will provide detailed error messages to help you fix the issues.

Example Configurations

Basic Single-Cloud Configuration

{
  "baseCidr": "10.0.0.0/8",
  "prefixLengths": {
    "account": 16,
    "region": 20,
    "az": 24
  },
  "cloudProviders": ["aws"],
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "provider": "aws",
          "regions": ["us-east-1", "us-west-2"]
        }
      }
    }
  ],
  "subnetTypes": {
    "Public": 26,
    "Private": 24,
    "Database": 27
  }
}

Advanced Multi-Cloud Configuration with Overrides

{
  "baseCidr": "10.0.0.0/8",
  "prefixLengths": {
    "account": 16,
    "region": 20,
    "az": 24
  },
  "cloudProviders": ["aws", "azure", "gcp"],
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "provider": "aws",
          "baseCidr": "10.100.0.0/16",
          "regions": ["us-east-1", "us-west-2", "eu-west-1"]
        },
        "azure": {
          "provider": "azure",
          "baseCidr": "10.200.0.0/16",
          "regions": ["eastus", "westeurope"]
        },
        "gcp": {
          "provider": "gcp",
          "baseCidr": "10.300.0.0/16",
          "regions": ["us-central1", "europe-west1"]
        }
      }
    },
    {
      "name": "development",
      "clouds": {
        "aws": {
          "provider": "aws",
          "regions": ["us-east-1"]
        },
        "azure": {
          "provider": "azure",
          "regions": ["eastus"]
        }
      }
    }
  ],
  "subnetTypes": {
    "Public": 26,
    "Private": 24,
    "Database": 27,
    "Management": 28
  }
}

Configuration with Variable Subnet Sizing

{
  "baseCidr": "10.0.0.0/8",
  "prefixLengths": {
    "account": 16,
    "region": 20,
    "az": 24
  },
  "cloudProviders": ["aws"],
  "accounts": [
    {
      "name": "production",
      "clouds": {
        "aws": {
          "provider": "aws",
          "regions": ["us-east-1"],
          "subnetTypes": {
            "LoadBalancer": 26,
            "WebTier": 25,
            "AppTier": 24,
            "DatabaseTier": 27,
            "Management": 28
          }
        }
      }
    }
  ],
  "subnetTypes": {
    "Public": 26,
    "Private": 24
  }
}

In this example, the account-specific subnet types will override the global subnet types for the “production” account’s AWS resources.

Cloud Providers

Each cloud provider defined in your configuration has specific attributes:

{
  "cloudProviders": {
    "aws": {
      "regions": ["us-east-1", "us-west-2"],
      "azCount": 3
    },
    "gcp": {
      "regions": ["us-central1", "europe-west3"],
      "azCount": 3
    },
    "azure": {
      "regions": ["eastus", "westeurope"],
      "azCount": 3
    }
  }
}

regions: Array of region identifiers for the cloud provider
azCount: Number of availability zones to use within each region (optional)

Availability Zone Naming

Subnetter uses cloud-provider specific naming conventions for availability zones:

AWS

AWS availability zones follow the pattern region + letter (e.g., us-east-1a). Subnetter supports region-specific AZ naming patterns:

Most regions use sequential letters (a, b, c, …)
Some regions like us-west-1 use non-sequential letters (a, c)
Regions like ap-northeast-1 have specific patterns (a, c, d)

The system respects these region-specific patterns when generating AZ names. For example, requesting 3 AZs in ap-northeast-1 will generate ap-northeast-1a, ap-northeast-1c, and ap-northeast-1d.

Azure

Azure availability zones use numbers (1, 2, 3) and are named as region-number (e.g., eastus-1).

Not all Azure regions support availability zones. Subnetter validates that regions like eastus, westeurope, and centralus support AZs, while others like brazilsoutheast do not. A warning is logged when using AZs in unsupported regions.

GCP

GCP zones follow the pattern region + letter (e.g., us-central1-a). Subnetter supports region-specific zone patterns:

Most regions use sequential letters (a, b, c, …)
Some regions like us-east1 use non-sequential letters (b, c, d)
Regions like europe-west1 have specific patterns (b, c, d)

The system respects these patterns when generating zone names. For example, requesting 3 zones in us-east1 will generate us-east1-b, us-east1-c, and us-east1-d.

Configuration Reference

Configuration Schema

Required Fields

Optional Fields

Configuration Example

Configuration Best Practices

Cloud-Specific Considerations

AWS

Azure

GCP

File Format Support

See Also

Advanced Configuration Options

Allocation Strategy Control

Account-Level CIDR Overrides

Cloud Provider-Specific Overrides

Hierarchical Allocation Process

Subnet Type Configuration

Configuration Validation

Example Configurations

Basic Single-Cloud Configuration

Advanced Multi-Cloud Configuration with Overrides

Configuration with Variable Subnet Sizing

Cloud Providers

Availability Zone Naming

AWS

Azure

GCP