Skip to content

Modern Docker Management, Designed for Everyone

feat: add optional IP range to network creation (#3959)

Kyle Mendell38d3ed8c19fa
diff --git a/frontend/messages/en.json b/frontend/messages/en.json
index 85be4e3af..87f9dc58e 100644
--- a/frontend/messages/en.json
+++ b/frontend/messages/en.json
@@ -2310,6 +2310,7 @@
"network_enable_ipam_label": "Enable IPAM Configuration",
"network_subnet_description": "Network subnet in CIDR notation",
"network_gateway_description": "Gateway IP address for the network",
+ "network_ip_range_description": "Range used for automatic IP allocation, in CIDR notation. Must be within the subnet.",
"network_driver_options_placeholder": "parent=eth0\ncom.docker.network.bridge.name=docker0",
"network_driver_options_description": "Enter driver-specific options as key=value pairs (e.g., parent=eth0 for macvlan), one per line",
"network_interface": "Network interface",
@@ -3201,6 +3202,7 @@
"nav_expand_user_card": "Expand user card",
"network_example_subnet": "e.g., 172.20.0.0/16",
"network_example_gateway": "e.g., 172.20.0.1",
+ "network_example_ip_range": "e.g., 172.20.1.0/24",
"env_edge_agent_desc": "Edge agent - connects outbound to manager",
"env_remote_docker_host": "Remote Docker Host",
"sidebar_toggle_submenu": "Toggle submenu",
diff --git a/frontend/src/lib/components/sheets/create-network-sheet.svelte b/frontend/src/lib/components/sheets/create-network-sheet.svelte
index 1f3febdfb..be12e60a7 100644
--- a/frontend/src/lib/components/sheets/create-network-sheet.svelte
+++ b/frontend/src/lib/components/sheets/create-network-sheet.svelte
@@ -7,7 +7,7 @@
import { Label } from '#lib/components/ui/label/index.js';
import { Input } from '#lib/components/ui/input/index.js';
import { Textarea } from '#lib/components/ui/textarea/index.js';
- import type { NetworkCreateOptions } from '#lib/types/docker.js';
+ import type { IPAMConfig, NetworkCreateOptions } from '#lib/types/docker.js';
import { z } from 'zod/v4';
import { createForm, preventDefault } from '#lib/utils/settings.svelte.js';
@@ -41,6 +41,7 @@
driverOptions: z.string().optional().default(''),
enableIpam: z.boolean().default(false),
subnet: z.string().optional().default(''),
+ ipRange: z.string().optional().default(''),
gateway: z.string().optional().default('')
});
@@ -53,6 +54,7 @@
driverOptions: '',
enableIpam: false,
subnet: '',
+ ipRange: '',
gateway: ''
});
@@ -98,12 +100,15 @@
};
// Add IPAM configuration if enabled
- if (data.enableIpam && (data.subnet?.trim() || data.gateway?.trim())) {
- const ipamConfig: { subnet?: string; gateway?: string } = {};
+ if (data.enableIpam && (data.subnet?.trim() || data.ipRange?.trim() || data.gateway?.trim())) {
+ const ipamConfig: IPAMConfig = {};
if (data.subnet?.trim()) {
ipamConfig.subnet = data.subnet.trim();
}
+ if (data.ipRange?.trim()) {
+ ipamConfig.ipRange = data.ipRange.trim();
+ }
if (data.gateway?.trim()) {
ipamConfig.gateway = data.gateway.trim();
}
@@ -131,6 +136,7 @@
inputs.driverOptions.value = '';
inputs.enableIpam.value = false;
inputs.subnet.value = '';
+ inputs.ipRange.value = '';
inputs.gateway.value = '';
labels = [{ key: '', value: '' }];
}
@@ -285,6 +291,22 @@
<p class="text-xs text-muted-foreground">{m.network_subnet_description()}</p>
</div>
+ <div class="space-y-2">
+ <Label for="ip-range" class="text-sm font-medium">{m.networks_ipam_iprange_label()}</Label>
+ <Input
+ id="ip-range"
+ type="text"
+ placeholder={m.network_example_ip_range()}
+ disabled={isLoading}
+ bind:value={inputs.ipRange.value}
+ class={inputs.ipRange.error ? 'border-destructive' : ''}
+ />
+ {#if inputs.ipRange.error}
+ <p class="text-xs text-destructive">{inputs.ipRange.error}</p>
+ {/if}
+ <p class="text-xs text-muted-foreground">{m.network_ip_range_description()}</p>
+ </div>
+
<div class="space-y-2">
<Label for="gateway" class="text-sm font-medium">{m.common_gateway()}</Label>
<Input
@@ -313,6 +335,7 @@
{#snippet footer()}
<SheetFooterActions
bind:open
+ onCancel={() => handleOpenChange(false)}
cancelDisabled={isLoading}
submitDisabled={isLoading}
submitLoading={isLoading}
diff --git a/frontend/src/routes/(app)/networks/+page.svelte b/frontend/src/routes/(app)/networks/+page.svelte
index ecef6bb4e..0c17f6a9a 100644
--- a/frontend/src/routes/(app)/networks/+page.svelte
+++ b/frontend/src/routes/(app)/networks/+page.svelte
@@ -15,6 +15,8 @@
import { ResourcePageLayout, type ActionButton, type StatCardConfig } from '#lib/layouts/index.js';
import { createMutation, createQuery, useQueryClient } from '@tanstack/svelte-query';
import { activityToastOptions, extractActivityId } from '#lib/utils/activity-toast.js';
+ import { extractApiErrorMessage } from '#lib/utils/api.js';
+ import { tryCatch } from '#lib/utils/try-catch.js';
let { data } = $props();
const queryClient = useQueryClient();
@@ -53,8 +55,10 @@
pageState.isCreateDialogOpen = false;
}
},
- onError: (_error, variables) => {
- toast.error(m.common_create_failed({ resource: `${m.resource_network()} "${variables.name}"` }));
+ onError: (error, variables) => {
+ toast.error(m.common_create_failed({ resource: `${m.resource_network()} "${variables.name}"` }), {
+ description: extractApiErrorMessage(error)
+ });
}
}));
@@ -64,7 +68,7 @@
});
async function handleCreate(name: string, options: NetworkCreateOptions) {
- await createNetworkMutation.mutateAsync({ name, options, requestedEnvId: pageState.envId });
+ await tryCatch(createNetworkMutation.mutateAsync({ name, options, requestedEnvId: pageState.envId }));
}
async function loadNetworks(options = pageState.requestOptions, requestedEnvId = pageState.envId) {
diff --git a/tests/spec/network.spec.ts b/tests/spec/network.spec.ts
index b59bd15a5..a9601a5e0 100644
--- a/tests/spec/network.spec.ts
+++ b/tests/spec/network.spec.ts
@@ -1,4 +1,4 @@
-import { test, expect, type Page } from '../fixtures/test.fixture';
+import { test, expect, type Locator, type Page } from '../fixtures/test.fixture';
import { fetchNetworksCountsWithRetry } from '../utils/fetch.util';
import authUtil from '../utils/auth.util';
@@ -21,14 +21,17 @@ test.beforeEach(async ({ page }) => {
await navigateToNetworks(page);
});
-async function createNetworkViaUI(page: Page, networkName: string) {
+async function openCreateNetworkDialog(page: Page, networkName: string) {
await page.getByRole('button', { name: 'Create Network' }).first().click();
const dialog = page.getByRole('dialog');
await expect(dialog).toBeVisible();
await expect(dialog.getByRole('heading', { name: 'Create New Network' })).toBeVisible();
await dialog.getByLabel('Network Name *').fill(networkName);
+ return dialog;
+}
- const createRequest = page.waitForResponse(
+function waitForCreateNetworkResponse(page: Page) {
+ return page.waitForResponse(
(response) => {
const request = response.request();
if (request.method() !== 'POST') return false;
@@ -36,6 +39,22 @@ async function createNetworkViaUI(page: Page, networkName: string) {
},
{ timeout: 15000 }
);
+}
+
+async function fillIpam(
+ dialog: Locator,
+ values: { subnet?: string; ipRange?: string; gateway?: string }
+) {
+ await dialog.getByRole('button', { name: 'IPAM Configuration' }).click();
+ await dialog.getByLabel('Enable IPAM Configuration').check();
+ if (values.subnet !== undefined) await dialog.getByLabel('Subnet').fill(values.subnet);
+ if (values.ipRange !== undefined) await dialog.getByLabel('IP Range').fill(values.ipRange);
+ if (values.gateway !== undefined) await dialog.getByLabel('Gateway').fill(values.gateway);
+}
+
+async function createNetworkViaUI(page: Page, networkName: string) {
+ const dialog = await openCreateNetworkDialog(page, networkName);
+ const createRequest = waitForCreateNetworkResponse(page);
await dialog.getByRole('button', { name: 'Create Network' }).click();
const createResponse = await createRequest;
@@ -203,6 +222,118 @@ test.describe('Networks Page', () => {
await expect(removeBtn).toBeDisabled();
});
+ test('creates a network with a subnet, IP range, and gateway', async ({ page }) => {
+ const networkName = `e2e-iprange-network-${Date.now()}`;
+ const subnet = '172.28.0.0/16';
+ const ipRange = '172.28.5.0/24';
+ const gateway = '172.28.0.1';
+ try {
+ await openCreateNetworkDialog(page, networkName);
+ const dialog = page.getByRole('dialog');
+ await fillIpam(dialog, { subnet, ipRange, gateway });
+
+ const createRequest = waitForCreateNetworkResponse(page);
+ await dialog.getByRole('button', { name: 'Create Network' }).click();
+ const createResponse = await createRequest;
+ expect(createResponse.ok()).toBe(true);
+ expect(createResponse.request().postDataJSON()).toMatchObject({
+ name: networkName,
+ options: { ipam: { driver: 'default', config: [{ subnet, ipRange, gateway }] } }
+ });
+ await expect(dialog).toBeHidden();
+
+ const inspect = await page.request.get(
+ `/api/environments/0/networks/${encodeURIComponent(networkName)}`
+ );
+ expect(inspect.ok()).toBe(true);
+ const inspected = await inspect.json();
+ expect(inspected.data.ipam.config[0]).toMatchObject({ subnet, ipRange, gateway });
+
+ await page.goto(`/networks/${encodeURIComponent(networkName)}`);
+ await expect(page.getByRole('heading', { level: 1, name: networkName })).toBeVisible();
+ await expect(page.getByText(ipRange, { exact: true })).toBeVisible();
+ } finally {
+ await removeNetworkViaApi(page, networkName);
+ }
+ });
+
+ test('omits blank IP range, drops IPAM when disabled, and resets on close', async ({ page }) => {
+ const blankRangeName = `e2e-blank-range-${Date.now()}`;
+ const disabledIpamName = `e2e-ipam-off-${Date.now()}`;
+ try {
+ await openCreateNetworkDialog(page, blankRangeName);
+ const dialog = page.getByRole('dialog');
+ await fillIpam(dialog, { subnet: '172.29.0.0/16', ipRange: ' ' });
+
+ let createRequest = waitForCreateNetworkResponse(page);
+ await dialog.getByRole('button', { name: 'Create Network' }).click();
+ let createResponse = await createRequest;
+ expect(createResponse.ok()).toBe(true);
+ const blankBody = createResponse.request().postDataJSON();
+ expect(blankBody.options.ipam.config[0]).toEqual({ subnet: '172.29.0.0/16' });
+ await expect(dialog).toBeHidden();
+
+ await openCreateNetworkDialog(page, disabledIpamName);
+ await fillIpam(dialog, { subnet: '172.30.0.0/16', ipRange: '172.30.1.0/24' });
+ await dialog.getByLabel('Enable IPAM Configuration').uncheck();
+ await expect(dialog.getByLabel('IP Range')).toBeHidden();
+
+ createRequest = waitForCreateNetworkResponse(page);
+ await dialog.getByRole('button', { name: 'Create Network' }).click();
+ createResponse = await createRequest;
+ expect(createResponse.ok()).toBe(true);
+ expect(createResponse.request().postDataJSON().options.ipam).toBeUndefined();
+ await expect(dialog).toBeHidden();
+
+ await openCreateNetworkDialog(page, 'e2e-reset-check');
+ await fillIpam(dialog, { ipRange: '172.31.1.0/24' });
+ await dialog.getByRole('button', { name: 'Cancel' }).click();
+ await expect(dialog).toBeHidden();
+
+ await page.getByRole('button', { name: 'Create Network' }).first().click();
+ await expect(dialog).toBeVisible();
+ await expect(dialog.getByLabel('Enable IPAM Configuration')).toBeHidden();
+ await dialog.getByRole('button', { name: 'IPAM Configuration' }).click();
+ await expect(dialog.getByLabel('Enable IPAM Configuration')).not.toBeChecked();
+ await dialog.getByLabel('Enable IPAM Configuration').check();
+ await expect(dialog.getByLabel('IP Range')).toHaveValue('');
+ } finally {
+ await removeNetworkViaApi(page, blankRangeName);
+ await removeNetworkViaApi(page, disabledIpamName);
+ }
+ });
+
+ test('shows an actionable error for an invalid or out-of-subnet IP range', async ({ page }) => {
+ const networkName = `e2e-bad-cidr-${Date.now()}`;
+ const toast = page
+ .getByRole('region', { name: 'Notifications alt+T', exact: true })
+ .getByRole('listitem');
+ try {
+ await openCreateNetworkDialog(page, networkName);
+ const dialog = page.getByRole('dialog');
+ await fillIpam(dialog, { subnet: '172.32.0.0/16', ipRange: 'not-a-cidr' });
+
+ let createRequest = waitForCreateNetworkResponse(page);
+ await dialog.getByRole('button', { name: 'Create Network' }).click();
+ expect((await createRequest).ok()).toBe(false);
+ await expect(toast.filter({ hasText: 'not-a-cidr' })).toContainText('Failed to create');
+ await expect(dialog).toBeVisible();
+ await expect(dialog.getByLabel('IP Range')).toHaveValue('not-a-cidr');
+
+ await dialog.getByLabel('IP Range').fill('10.99.0.0/24');
+ createRequest = waitForCreateNetworkResponse(page);
+ await dialog.getByRole('button', { name: 'Create Network' }).click();
+ expect((await createRequest).ok()).toBe(false);
+ await expect(toast.filter({ hasText: "doesn't contain ip-range" })).toContainText(
+ '10.99.0.0/24'
+ );
+ await expect(dialog).toBeVisible();
+ await expect(dialog.getByLabel('Network Name *')).toHaveValue(networkName);
+ } finally {
+ await removeNetworkViaApi(page, networkName);
+ }
+ });
+
test('Details page shows usage badge', async ({ page }) => {
const networkName = `e2e-badge-network-${Date.now()}`;
try {