0
# Cloud Management
1

2
Cloud infrastructure management including cloud accounts, resource types, networks, and services. Provides comprehensive modeling of cloud provider resources with hierarchical organization and integration with IPAM systems.
3

4
## Capabilities
5

6
### Cloud Account Management
7

8
Manage cloud provider accounts with authentication and configuration.
9

10
```python { .api }
11
class CloudAccount:
12
    """
13
    Cloud provider account management.
14
    
15
    Attributes:
16
        name (str): The name of the cloud account (unique, max 255 chars)
17
        description (str, optional): Description of the account (max 255 chars)
18
        account_number (str): The account identifier (max 255 chars)
19
        provider (ForeignKey): Cloud provider (dcim.Manufacturer)
20
        secrets_group (ForeignKey, optional): Associated secrets group (extras.SecretsGroup)
21
    """
22
    
23
    @property
24
    def display(self):
25
        """Returns formatted string: {provider}: {name} - {account_number}"""
26
```
27

28
### Cloud Resource Type Management
29

30
Define and manage cloud resource types with schema validation.
31

32
```python { .api }
33
class CloudResourceType:
34
    """
35
    Cloud resource type definitions with JSON schema validation.
36
    
37
    Attributes:
38
        name (str): Type of cloud objects (unique, max 255 chars)
39
        description (str, optional): Description of the resource type (max 255 chars)
40
        provider (ForeignKey): Cloud provider (dcim.Manufacturer)
41
        config_schema (JSONField, optional): JSON schema for validation
42
        content_types (ManyToManyField): Applicable model types
43
    """
44
    
45
    @property
46
    def display(self):
47
        """Returns formatted string: {provider}: {name}"""
48

49
class CloudResourceTypeMixin:
50
    """
51
    Abstract mixin for models that use CloudResourceType.
52
    
53
    Attributes:
54
        cloud_resource_type (ForeignKey): Associated resource type
55
        extra_config (JSONField, optional): Additional configuration data
56
    """
57
    
58
    def clean(self):
59
        """Validates extra_config against cloud_resource_type.config_schema using JSON Schema Draft 7."""
60
```
61

62
### Cloud Network Management
63

64
Hierarchical cloud network management with IPAM integration.
65

66
```python { .api }
67
class CloudNetwork:
68
    """
69
    Cloud network management with hierarchical organization.
70
    
71
    Inherits: CloudResourceTypeMixin, PrimaryModel
72
    
73
    Attributes:
74
        name (str): Network name (unique, max 255 chars)
75
        description (str, optional): Network description (max 255 chars)
76
        cloud_account (ForeignKey): Associated cloud account
77
        parent (ForeignKey, optional): Parent network (max 2 levels deep)
78
        prefixes (ManyToManyField): Associated IPAM prefixes (through CloudNetworkPrefixAssignment)
79
    """
80
    
81
    def clean(self):
82
        """
83
        Validates network hierarchy:
84
        - Parent cannot have a parent (no grandparent relationships)
85
        - Cannot be its own parent
86
        """
87

88
class CloudNetworkPrefixAssignment:
89
    """
90
    Through model for CloudNetwork ↔ Prefix relationship.
91
    
92
    Attributes:
93
        cloud_network (ForeignKey): Associated cloud network
94
        prefix (ForeignKey): Associated IPAM prefix
95
    """
96
```
97

98
### Cloud Service Management
99

100
Cloud service management with network associations.
101

102
```python { .api }
103
class CloudService:
104
    """
105
    Cloud service management with network associations.
106
    
107
    Inherits: CloudResourceTypeMixin, PrimaryModel
108
    
109
    Attributes:
110
        name (str): Service name (unique, max 255 chars)
111
        description (str, optional): Service description (max 255 chars)
112
        cloud_account (ForeignKey, optional): Associated cloud account
113
        cloud_networks (ManyToManyField): Associated networks (through CloudServiceNetworkAssignment)
114
    """
115

116
class CloudServiceNetworkAssignment:
117
    """
118
    Through model for CloudService ↔ CloudNetwork relationship.
119
    
120
    Attributes:
121
        cloud_network (ForeignKey): Associated cloud network
122
        cloud_service (ForeignKey): Associated cloud service
123
    """
124
```
125

126
### API Serializers
127

128
REST API serializers for cloud resources.
129

130
```python { .api }
131
class CloudAccountSerializer:
132
    """Serializer for CloudAccount with tagging support."""
133

134
class CloudResourceTypeSerializer:
135
    """Serializer for CloudResourceType with ContentType fields."""
136

137
class CloudNetworkSerializer:
138
    """Serializer for CloudNetwork with tagging and hierarchical support."""
139

140
class CloudNetworkPrefixAssignmentSerializer:
141
    """Serializer for CloudNetwork-Prefix associations."""
142

143
class CloudServiceSerializer:
144
    """Serializer for CloudService with tagging support."""
145

146
class CloudServiceNetworkAssignmentSerializer:
147
    """Serializer for CloudService-Network associations."""
148
```
149

150
### API ViewSets
151

152
REST API viewsets for cloud resource management.
153

154
```python { .api }
155
class CloudAccountViewSet:
156
    """ViewSet for CloudAccount CRUD operations with filtering."""
157

158
class CloudResourceTypeViewSet:
159
    """ViewSet for CloudResourceType CRUD operations with filtering."""
160

161
class CloudNetworkViewSet:
162
    """ViewSet for CloudNetwork CRUD operations with filtering."""
163

164
class CloudNetworkPrefixAssignmentViewSet:
165
    """ViewSet for CloudNetwork-Prefix assignment operations."""
166

167
class CloudServiceViewSet:
168
    """ViewSet for CloudService CRUD operations with filtering."""
169

170
class CloudServiceNetworkAssignmentViewSet:
171
    """ViewSet for CloudService-Network assignment operations."""
172
```
173

174
## Usage Examples
175

176
### Basic Cloud Account Setup
177

178
```python
179
from nautobot.cloud.models import CloudAccount, CloudResourceType
180
from nautobot.dcim.models import Manufacturer
181
from nautobot.extras.models import Status
182

183
# Create a cloud provider
184
aws = Manufacturer.objects.create(name="AWS")
185

186
# Create a cloud account
187
account = CloudAccount.objects.create(
188
    name="Production AWS Account",
189
    description="Main production AWS environment",
190
    account_number="123456789012",
191
    provider=aws
192
)
193

194
# Create resource types for this provider
195
vpc_type = CloudResourceType.objects.create(
196
    name="VPC",
197
    description="Virtual Private Cloud",
198
    provider=aws,
199
    config_schema={
200
        "type": "object",
201
        "properties": {
202
            "region": {"type": "string"},
203
            "cidr_block": {"type": "string"}
204
        },
205
        "required": ["region", "cidr_block"]
206
    }
207
)
208
```
209

210
### Hierarchical Network Management
211

212
```python
213
from nautobot.cloud.models import CloudNetwork
214
from nautobot.ipam.models import Prefix, Namespace
215

216
# Create a parent network (VPC)
217
namespace = Namespace.objects.get(name="Global")
218
prefix = Prefix.objects.create(
219
    prefix="10.0.0.0/16",
220
    namespace=namespace,
221
    status=Status.objects.get(name="Active")
222
)
223

224
vpc = CloudNetwork.objects.create(
225
    name="prod-vpc-01",
226
    description="Production VPC",
227
    cloud_account=account,
228
    cloud_resource_type=vpc_type,
229
    extra_config={
230
        "region": "us-east-1",
231
        "cidr_block": "10.0.0.0/16"
232
    }
233
)
234

235
# Associate prefix with the network
236
from nautobot.cloud.models import CloudNetworkPrefixAssignment
237
CloudNetworkPrefixAssignment.objects.create(
238
    cloud_network=vpc,
239
    prefix=prefix
240
)
241

242
# Create a subnet (child network)
243
subnet_prefix = Prefix.objects.create(
244
    prefix="10.0.1.0/24",
245
    namespace=namespace,
246
    status=Status.objects.get(name="Active"),
247
    parent=prefix
248
)
249

250
subnet = CloudNetwork.objects.create(
251
    name="prod-subnet-01",
252
    description="Production subnet 1",
253
    cloud_account=account,
254
    parent=vpc,
255
    cloud_resource_type=CloudResourceType.objects.create(
256
        name="Subnet",
257
        provider=aws
258
    )
259
)
260

261
CloudNetworkPrefixAssignment.objects.create(
262
    cloud_network=subnet,
263
    prefix=subnet_prefix
264
)
265
```
266

267
### Cloud Service Configuration
268

269
```python
270
from nautobot.cloud.models import CloudService, CloudServiceNetworkAssignment
271

272
# Create a cloud service
273
rds_type = CloudResourceType.objects.create(
274
    name="RDS Database",
275
    description="Relational Database Service",
276
    provider=aws,
277
    config_schema={
278
        "type": "object",
279
        "properties": {
280
            "engine": {"type": "string"},
281
            "instance_class": {"type": "string"},
282
            "allocated_storage": {"type": "integer"}
283
        },
284
        "required": ["engine", "instance_class"]
285
    }
286
)
287

288
database = CloudService.objects.create(
289
    name="prod-db-01",
290
    description="Production database server",
291
    cloud_account=account,
292
    cloud_resource_type=rds_type,
293
    extra_config={
294
        "engine": "postgresql",
295
        "instance_class": "db.t3.medium",
296
        "allocated_storage": 100
297
    }
298
)
299

300
# Associate service with networks
301
CloudServiceNetworkAssignment.objects.create(
302
    cloud_service=database,
303
    cloud_network=subnet
304
)
305
```
306

307
### API Usage
308

309
```python
310
from nautobot.cloud.api.serializers import CloudAccountSerializer, CloudNetworkSerializer
311
from nautobot.cloud.api.views import CloudAccountViewSet
312

313
# Serialize cloud account data
314
serializer = CloudAccountSerializer(account)
315
data = serializer.data
316

317
# Query cloud networks via API
318
networks = CloudNetwork.objects.filter(cloud_account=account)
319
network_serializer = CloudNetworkSerializer(networks, many=True)
320
network_data = network_serializer.data
321
```
322

323
### Filtering and Search
324

325
```python
326
from nautobot.cloud.filters import CloudNetworkFilterSet
327

328
# Filter networks by provider
329
aws_networks = CloudNetwork.objects.filter(
330
    cloud_account__provider__name="AWS"
331
)
332

333
# Search across multiple fields
334
search_results = CloudNetwork.objects.filter(
335
    name__icontains="prod"
336
).filter(
337
    description__icontains="vpc"
338
)
339

340
# Filter by resource type
341
vpc_networks = CloudNetwork.objects.filter(
342
    cloud_resource_type__name="VPC"
343
)
344
```
345

346
## API Endpoints
347

348
The cloud module exposes the following REST API endpoints:
349

350
- `/api/cloud/cloud-accounts/` - Cloud account management
351
- `/api/cloud/cloud-networks/` - Network management
352
- `/api/cloud/cloud-network-prefix-assignments/` - Network-prefix associations
353
- `/api/cloud/cloud-resource-types/` - Resource type definitions
354
- `/api/cloud/cloud-services/` - Service management
355
- `/api/cloud/cloud-service-network-assignments/` - Service-network associations
356

357
## Error Handling
358

359
Common validation patterns for cloud resources:
360

361
```python
362
from django.core.exceptions import ValidationError
363
from nautobot.cloud.models import CloudNetwork
364

365
try:
366
    # Attempt to create invalid hierarchy (3 levels deep)
367
    grandchild = CloudNetwork.objects.create(
368
        name="invalid-network",
369
        cloud_account=account,
370
        parent=subnet  # subnet already has a parent (vpc)
371
    )
372
except ValidationError as e:
373
    # Handle hierarchy validation error
374
    print(f"Validation error: {e}")
375

376
try:
377
    # Invalid JSON schema validation
378
    network = CloudNetwork(
379
        name="test-network",
380
        cloud_account=account,
381
        cloud_resource_type=vpc_type,
382
        extra_config={
383
            "region": "us-east-1"
384
            # Missing required "cidr_block" field
385
        }
386
    )
387
    network.full_clean()
388
except ValidationError as e:
389
    # Handle schema validation error
390
    print(f"Schema validation error: {e}")
391
```