1# Network Isolation
2
3Isolate applications in separate Docker networks for enhanced security.
4
5## Configuration
6
7```toml
8[network_isolation]
9enabled = true
10network_prefix = "gordon"
11dns_suffix = ".internal"
12```
13
14## Options
15
16| Option | Type | Default | Description |
17|--------|------|---------|-------------|
18| `enabled` | bool | `false` | Enable per-app network isolation |
19| `network_prefix` | string | `"gordon"` | Prefix for created networks |
20| `dns_suffix` | string | `".internal"` | DNS suffix for service discovery |
21
22## How It Works
23
24When network isolation is enabled, each application gets its own Docker network:
25
26```
27[network_isolation]
28enabled = true
29network_prefix = "gordon"
30
31[routes]
32"app.mydomain.com" = "myapp:latest"
33"api.mydomain.com" = "myapi:latest"
34```
35
36Creates two isolated networks:
37- `gordon-app-mydomain-com`
38- `gordon-api-mydomain-com`
39
40## Network Naming
41
42Networks are named: `{prefix}-{domain-with-dashes}`
43
44| Domain | Network Name |
45|--------|--------------|
46| `app.mydomain.com` | `gordon-app-mydomain-com` |
47| `api.company.io` | `gordon-api-company-io` |
48| `staging.app.dev` | `gordon-staging-app-dev` |
49
50## Security Benefits
51
52### Without Network Isolation
53
54All containers can potentially communicate:
55
56```
57┌──────────────────────────────────────────────┐
58│ Default Bridge Network                        │
59│                                              │
60│  App A ←──────→ App B ←──────→ App C        │
61│    ↕              ↕              ↕           │
62│  DB A ←──────→ DB B ←──────→ DB C           │
63│                                              │
64└──────────────────────────────────────────────┘
65```
66
67### With Network Isolation
68
69Each app is isolated with its dependencies:
70
71```
72┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
73│ gordon-app-a    │  │ gordon-app-b    │  │ gordon-app-c    │
74│                 │  │                 │  │                 │
75│  App A ←→ DB A │  │  App B ←→ DB B │  │  App C ←→ DB C │
76│                 │  │                 │  │                 │
77└─────────────────┘  └─────────────────┘  └─────────────────┘
78        ↑                   ↑                   ↑
79        └───────── No direct communication ─────┘
80```
81
82## Service Discovery
83
84Within an isolated network, services are discoverable by name:
85
86```toml
87[network_isolation]
88enabled = true
89
90[attachments]
91"app.mydomain.com" = ["postgres:latest", "redis:latest"]
92```
93
94Your application connects using simple hostnames:
95
96```python
97# These work within the isolated network
98db = connect("postgresql://postgres:5432/mydb")
99cache = connect("redis://redis:6379")
100```
101
102## DNS Resolution
103
104The `dns_suffix` option adds a suffix for internal DNS resolution:
105
106```toml
107[network_isolation]
108dns_suffix = ".internal"
109```
110
111Services can be accessed as:
112- `postgres` (short form)
113- `postgres.internal` (with suffix)
114
115## Examples
116
117### Basic Isolation
118
119```toml
120[network_isolation]
121enabled = true
122
123[routes]
124"app.mydomain.com" = "myapp:latest"
125"api.mydomain.com" = "myapi:latest"
126
127[attachments]
128"app.mydomain.com" = ["app-postgres:latest"]
129"api.mydomain.com" = ["api-postgres:latest"]
130```
131
132Each app gets its own network with its own database.
133
134### Production Configuration
135
136```toml
137[network_isolation]
138enabled = true
139network_prefix = "prod"
140dns_suffix = ".internal"
141
142[routes]
143"app.company.com" = "company-app:v2.1.0"
144"api.company.com" = "company-api:v1.5.0"
145"admin.company.com" = "admin-panel:v1.0.0"
146```
147
148Creates networks:
149- `prod-app-company-com`
150- `prod-api-company-com`
151- `prod-admin-company-com`
152
153### Shared Services with Network Groups
154
155When apps need to communicate, use network groups:
156
157```toml
158[network_isolation]
159enabled = true
160
161[network_groups]
162"backend" = ["app.mydomain.com", "api.mydomain.com"]
163
164[attachments]
165"backend" = ["shared-postgres:latest", "shared-redis:latest"]
166```
167
168Both apps share the `gordon-backend` network.
169
170## Inspecting Networks
171
172View created networks:
173
174```bash
175docker network ls | grep gordon
176# gordon-app-mydomain-com
177# gordon-api-mydomain-com
178# gordon-backend
179```
180
181Inspect a network:
182
183```bash
184docker network inspect gordon-app-mydomain-com
185```
186
187## Related
188
189- [Network Groups](./network-groups.md)
190- [Attachments](./attachments.md)
191- [Configuration Overview](./index.md)