### VM Operations API

Source: https://context7.com/zstackio/zstack/llms.txt

APIs for starting, stopping, and migrating virtual machine instances.

```APIDOC
## VM Operations API

This section details the ZStack API operations for managing Virtual Machines (VMs), including starting, stopping, and migrating instances.

### Start VM Instance

Starts a specified VM instance.

### Method

POST

### Endpoint

`/zstack/api/v1/vm-instances/{uuid}/start`

### Parameters

#### Path Parameters

- **uuid** (string) - Required - The UUID of the VM instance to start.

### Request Example

```java
APIStartVmInstanceMsg startMsg = new APIStartVmInstanceMsg();
startMsg.setUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
APIStartVmInstanceEvent startEvt = (APIStartVmInstanceEvent) cloudBus.call(startMsg);
```

### Stop VM Instance

Stops a specified VM instance. Supports both graceful and cold shutdown.

### Method

POST

### Endpoint

`/zstack/api/v1/vm-instances/{uuid}/stop`

### Parameters

#### Path Parameters

- **uuid** (string) - Required - The UUID of the VM instance to stop.

#### Query Parameters

- **type** (string) - Optional - The shutdown type. Can be "grace" (default) or "cold" (force shutdown).

### Request Example

```java
APIStopVmInstanceMsg stopMsg = new APIStopVmInstanceMsg();
stopMsg.setUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
stopMsg.setType("grace"); // or "cold" for force shutdown
APIStopVmInstanceEvent stopEvt = (APIStopVmInstanceEvent) cloudBus.call(stopMsg);
```

### Migrate VM Instance

Migrates a VM instance to a specified target host.

### Method

POST

### Endpoint

`/zstack/api/v1/vm-instances/{vmInstanceUuid}/migrate`

### Parameters

#### Path Parameters

- **vmInstanceUuid** (string) - Required - The UUID of the VM instance to migrate.

#### Request Body

- **hostUuid** (string) - Required - The UUID of the target host to migrate the VM to.

### Request Example

```java
APIMigrateVmMsg migrateMsg = new APIMigrateVmMsg();
migrateMsg.setVmInstanceUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
migrateMsg.setHostUuid("target-host-uuid-1234567890abcdef");
APIMigrateVmEvent migrateEvt = (APIMigrateVmEvent) cloudBus.call(migrateMsg);

if (!migrateEvt.isSuccess()) {
    System.err.println("Migration failed: " + migrateEvt.getError());
}
```
```

--------------------------------

### Manage Virtual Machine Power States with ZStack API

Source: https://context7.com/zstackio/zstack/llms.txt

Provides examples of controlling virtual machine power states such as starting, stopping, and rebooting using the ZStack REST API. The stop operation supports a 'grace' type for a clean shutdown. Migration to a specific host is also demonstrated.

```bash
# Start VM
curl -X PUT http://localhost:8080/zstack/api/v1/vm-instances/8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f/actions \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <access-token>" \
  -d '{"startVmInstance": {}}'

# Stop VM
curl -X PUT http://localhost:8080/zstack/api/v1/vm-instances/8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f/actions \
  -H "Content-Type: application/json" \
  -d '{"stopVmInstance": {"type": "grace"}}'

# Reboot VM
curl -X PUT http://localhost:8080/zstack/api/v1/vm-instances/8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f/actions \
  -H "Content-Type: application/json" \
  -d '{"rebootVmInstance": {}}'

# Migrate VM to another host
curl -X PUT http://localhost:8080/zstack/api/v1/vm-instances/8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f/actions \
  -H "Content-Type: application/json" \
  -d '{ \
    "migrateVm": { \
      "hostUuid": "target-host-uuid-1234567890abcdef" \
    } \
  }'
```

--------------------------------

### EIP Management (Java)

Source: https://context7.com/zstackio/zstack/llms.txt

Java SDK examples for creating, detaching, and attaching EIPs. It demonstrates the lifecycle management of an EIP.

```java
# Java SDK Example
APICreateEipMsg createMsg = new APICreateEipMsg();
createMsg.setName("eip-for-webserver");
createMsg.setVipUuid("vip-uuid-1234567890abcdef");
createMsg.setVmNicUuid("vm-nic-uuid-1234567890");

APICreateEipEvent createEvt = (APICreateEipEvent) cloudBus.call(createMsg);
String eipUuid = createEvt.getInventory().getUuid();

// Detach EIP
APIDetachEipMsg detachMsg = new APIDetachEipMsg();
detachMsg.setUuid(eipUuid);
cloudBus.call(detachMsg);

// Attach to different NIC
APIAttachEipMsg attachMsg = new APIAttachEipMsg();
attachMsg.setEipUuid(eipUuid);
attachMsg.setVmNicUuid("another-vm-nic-uuid");
cloudBus.call(attachMsg);
```

--------------------------------

### Build and Execute VM Creation Workflow Chain in Java

Source: https://context7.com/zstackio/zstack/llms.txt

This Java code demonstrates how to build and execute a complex workflow chain for creating a virtual machine using the ZStack workflow engine. It chains together multiple flows, including host allocation, storage allocation, network allocation, VM creation on hypervisor, and VM start. Error handling and success handlers are also configured. Dependencies include FlowChainBuilder, various Flow implementations (AllocateHostFlow, etc.), FlowDoneHandler, and FlowErrorHandler.

```java
public void createVmWithWorkflow(VmInstanceSpec spec) {
    FlowChain chain = FlowChainBuilder.newSimpleFlowChain();
    chain.setName("create-vm-workflow");

    chain.then(new AllocateHostFlow())
         .then(new AllocatePrimaryStorageFlow())
         .then(new AllocateVolumeFlow())
         .then(new AllocateNetworkFlow())
         .then(new CreateVmOnHypervisorFlow())
         .then(new StartVmFlow())
         .done(new FlowDoneHandler(null) {
             @Override
             public void handle(Map data) {
                 VmInstanceSpec resultSpec = (VmInstanceSpec) data.get(VmInstanceConstant.Params.VmInstanceSpec.toString());
                 logger.info("VM created successfully: " + resultSpec.getVmInventory().getUuid());
                 // Send success reply
             }
         })
         .error(new FlowErrorHandler(null) {
             @Override
             public void handle(ErrorCode errCode, Map data) {
                 logger.error("VM creation failed: " + errCode);
                 // Automatic rollback will be triggered
                 // Send error reply
             }
         })
         .start();
}
```

--------------------------------

### Add NFS Primary Storage (Java)

Source: https://context7.com/zstackio/zstack/llms.txt

Java SDK example for adding NFS primary storage and attaching it to a cluster. It also demonstrates querying capacity.

```java
// Java SDK Example
APIAddNfsPrimaryStorageMsg addMsg = new APIAddNfsPrimaryStorageMsg();
addMsg.setName("nfs-primary-1");
addMsg.setUrl("192.168.10.50:/export/primary");
addMsg.setZoneUuid("zone-uuid-1234567890");

APIAddNfsPrimaryStorageEvent addEvt = (APIAddNfsPrimaryStorageEvent) cloudBus.call(addMsg);
String psUuid = addEvt.getInventory().getUuid();

// Attach to cluster
APIAttachPrimaryStorageToClusterMsg attachMsg = new APIAttachPrimaryStorageToClusterMsg();
attachMsg.setPrimaryStorageUuid(psUuid);
attachMsg.setClusterUuid("cluster-uuid-1234567890");
cloudBus.call(attachMsg);

// Query capacity
APIGetPrimaryStorageCapacityMsg capacityMsg = new APIGetPrimaryStorageCapacityMsg();
capacityMsg.setPrimaryStorageUuids(Arrays.asList(psUuid));
APIGetPrimaryStorageCapacityReply capacityReply = (APIGetPrimaryStorageCapacityReply) cloudBus.call(capacityMsg);
System.out.println("Available: " + capacityReply.getAvailableCapacity());
```

--------------------------------

### REST API: Query VMs with Advanced Filtering

Source: https://context7.com/zstackio/zstack/llms.txt

This example shows how to query VM instances using the ZStack REST API with advanced filtering capabilities. It supports complex conditions, field selection, and pagination. Authentication is required via an OAuth token.

```Bash
# Query VMs by network IP
curl -X GET "http://localhost:8080/zstack/api/v1/vm-instances?q=vmNics.eip.guestIp=16.16.16.16" \
  -H "Authorization: OAuth <access-token>"

# Query hosts with specific conditions and field selection
curl -X GET "http://localhost:8080/zstack/api/v1/hosts?q=hypervisorType=KVM,vmInstance.state=Running,vmInstance.allVolumes.size>=549755813888000&fields=name,uuid,managementIp&start=0&limit=10" \
  -H "Authorization: OAuth <access-token>"

# Query VMs in specific zone with resource details
curl -X GET "http://localhost:8080/zstack/api/v1/vm-instances?q=zone.name=west-coast,state=Running,vmNics.l3Network.name=production-network" \
  -H "Authorization: OAuth <access-token>"

# Complex query with multiple conditions
curl -X GET "http://localhost:8080/zstack/api/v1/vm-instances?q=name~=%test%,cpuNum>=4,memorySize>=8589934592,createDate>2024-01-01" \
  -H "Authorization: OAuth <access-token>"
```

--------------------------------

### Java SDK: VM Instance Operations

Source: https://context7.com/zstackio/zstack/llms.txt

This snippet demonstrates how to start, stop, and migrate VM instances using the ZStack Java SDK. It requires the cloudBus to be available and uses specific API messages for each operation. The stop operation supports graceful or cold shutdown.

```Java
APIStartVmInstanceMsg startMsg = new APIStartVmInstanceMsg();
startMsg.setUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
APIStartVmInstanceEvent startEvt = (APIStartVmInstanceEvent) cloudBus.call(startMsg);

APIStopVmInstanceMsg stopMsg = new APIStopVmInstanceMsg();
stopMsg.setUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
stopMsg.setType("grace"); // or "cold" for force shutdown
APIStopVmInstanceEvent stopEvt = (APIStopVmInstanceEvent) cloudBus.call(stopMsg);

APIMigrateVmMsg migrateMsg = new APIMigrateVmMsg();
migrateMsg.setVmInstanceUuid("8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f");
migrateMsg.setHostUuid("target-host-uuid-1234567890abcdef");
APIMigrateVmEvent migrateEvt = (APIMigrateVmEvent) cloudBus.call(migrateMsg);

if (!migrateEvt.isSuccess()) {
    System.err.println("Migration failed: " + migrateEvt.getError());
}
```

--------------------------------

### REST API: Create L3 Network

Source: https://context7.com/zstackio/zstack/llms.txt

This example demonstrates how to create a new L3 network using the ZStack REST API. It requires specifying network details such as name, description, L2 network UUID, and category. Authentication is required via an OAuth token.

```Bash
# Create L3 Network
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <access-token>" \
  -d '{
    "params": {
      "name": "GuestNetwork",
      "description": "Production guest network",
      "type": "L3BasicNetwork",
      "l2NetworkUuid": "2f5e0755584d41dabb73c7dcbee2fe29",
      "category": "Private",
      "ipVersion": 4
    }
  }'
```

--------------------------------

### REST API: Add IP Range to L3 Network

Source: https://context7.com/zstackio/zstack/llms.txt

This example shows how to add an IP range to an existing L3 network using the ZStack REST API. It requires the L3 network UUID and defines the start IP, end IP, netmask, and gateway for the range.

```Bash
# Add IP Range to L3 Network
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/ip-ranges \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "name": "IPRange1",
      "startIp": "192.168.1.10",
      "endIp": "192.168.1.100",
      "netmask": "255.255.255.0",
      "gateway": "192.168.1.1"
    }
  }'
```

--------------------------------

### Create Virtual Machine with ZStack API

Source: https://context7.com/zstackio/zstack/llms.txt

Demonstrates creating a new virtual machine instance using the ZStack REST API and Java SDK. Requires specifying instance offerings, image, network, and optional volumes. The API returns detailed inventory of the created VM.

```bash
# REST API Request
curl -X POST http://localhost:8080/zstack/api/v1/vm-instances \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <access-token>" \
  -d '{
    "params": {
      "name": "TestVm",
      "instanceOfferingUuid": "1618154b462a48749ca9b114cf4a2979",
      "imageUuid": "99a5eea648954ef7be2b8ede8f34fe26",
      "l3NetworkUuids": [
        "c4f6a370f80443798cc460ee07d56ff1",
        "f5fbd96e0df745bdb7bc4f4c19febe65"
      ],
      "type": "UserVm",
      "dataDiskOfferingUuids": ["d8f5e5a1234567890abcdef123456789"],
      "description": "Production web server",
      "defaultL3NetworkUuid": "c4f6a370f80443798cc460ee07d56ff1",
      "zoneUuid": "a7b4c6d8e9f0a1b2c3d4e5f6a7b8c9d0",
      "strategy": "InstantStart"
    }
  }'

# Expected Response
{
  "inventory": {
    "uuid": "8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f",
    "name": "TestVm",
    "state": "Running",
    "vmNics": [
      {
        "uuid": "nic-uuid-1",
        "l3NetworkUuid": "c4f6a370f80443798cc460ee07d56ff1",
        "ip": "192.168.1.10",
        "mac": "fa:16:3e:12:34:56"
      }
    ],
    "allVolumes": [
      {
        "uuid": "vol-uuid-1",
        "type": "Root",
        "size": 10737418240,
        "deviceId": 0
      }
    ],
    "hypervisorType": "KVM",
    "instanceOfferingUuid": "1618154b462a48749ca9b114cf4a2979",
    "imageUuid": "99a5eea648954ef7be2b8ede8f34fe26",
    "hostUuid": "host-uuid-allocated",
    "createDate": "2024-12-01T10:30:00Z"
  }
}
```

```java
APICreateVmInstanceMsg msg = new APICreateVmInstanceMsg();
msg.setName("TestVm");
msg.setInstanceOfferingUuid("1618154b462a48749ca9b114cf4a2979");
msg.setImageUuid("99a5eea648954ef7be2b8ede8f34fe26");
msg.setL3NetworkUuids(Arrays.asList("c4f6a370f80443798cc460ee07d56ff1"));
msg.setType("UserVm");
msg.setDefaultL3NetworkUuid("c4f6a370f80443798cc460ee07d56ff1");

APICreateVmInstanceEvent evt = (APICreateVmInstanceEvent) cloudBus.call(msg);
if (evt.isSuccess()) {
    VmInstanceInventory vm = evt.getInventory();
    System.out.println("VM created: " + vm.getUuid());
}
```

--------------------------------

### POST /zstack/api/v1/vm-instances

Source: https://context7.com/zstackio/zstack/llms.txt

Creates a new virtual machine instance with specified resources.

```APIDOC
## POST /zstack/api/v1/vm-instances

### Description
Creates a new virtual machine instance with specified resources including compute offerings, network interfaces, and storage volumes.

### Method
POST

### Endpoint
/zstack/api/v1/vm-instances

### Parameters
#### Request Body
- **params** (object) - Required - Contains parameters for VM creation.
  - **name** (string) - Required - The name of the virtual machine.
  - **instanceOfferingUuid** (string) - Required - UUID of the instance offering.
  - **imageUuid** (string) - Required - UUID of the image to use for the VM.
  - **l3NetworkUuids** (array of strings) - Required - List of L3 network UUIDs for the VM.
  - **type** (string) - Required - Type of the VM (e.g., "UserVm").
  - **dataDiskOfferingUuids** (array of strings) - Optional - UUIDs of data disk offerings.
  - **description** (string) - Optional - A description for the VM.
  - **defaultL3NetworkUuid** (string) - Optional - UUID of the default L3 network.
  - **zoneUuid** (string) - Optional - UUID of the zone where the VM will be created.
  - **strategy** (string) - Optional - VM creation strategy (e.g., "InstantStart").

### Request Example
```json
{
  "params": {
    "name": "TestVm",
    "instanceOfferingUuid": "1618154b462a48749ca9b114cf4a2979",
    "imageUuid": "99a5eea648954ef7be2b8ede8f34fe26",
    "l3NetworkUuids": [
      "c4f6a370f80443798cc460ee07d56ff1",
      "f5fbd96e0df745bdb7bc4f4c19febe65"
    ],
    "type": "UserVm",
    "dataDiskOfferingUuids": ["d8f5e5a1234567890abcdef123456789"],
    "description": "Production web server",
    "defaultL3NetworkUuid": "c4f6a370f80443798cc460ee07d56ff1",
    "zoneUuid": "a7b4c6d8e9f0a1b2c3d4e5f6a7b8c9d0",
    "strategy": "InstantStart"
  }
}
```

### Response
#### Success Response (200)
- **inventory** (object) - Details of the created VM instance.
  - **uuid** (string) - The UUID of the VM.
  - **name** (string) - The name of the VM.
  - **state** (string) - The current state of the VM (e.g., "Running").
  - **vmNics** (array of objects) - Network interfaces of the VM.
    - **uuid** (string) - UUID of the VM NIC.
    - **l3NetworkUuid** (string) - UUID of the L3 network.
    - **ip** (string) - IP address of the NIC.
    - **mac** (string) - MAC address of the NIC.
  - **allVolumes** (array of objects) - All volumes attached to the VM.
    - **uuid** (string) - UUID of the volume.
    - **type** (string) - Type of the volume (e.g., "Root").
    - **size** (integer) - Size of the volume in bytes.
    - **deviceId** (integer) - Device ID of the volume.
  - **hypervisorType** (string) - The type of hypervisor used.
  - **instanceOfferingUuid** (string) - UUID of the instance offering.
  - **imageUuid** (string) - UUID of the image.
  - **hostUuid** (string) - UUID of the host where the VM is running.
  - **createDate** (string) - Timestamp of VM creation.

#### Response Example
```json
{
  "inventory": {
    "uuid": "8c7d3e5f9a0b1c2d3e4f5a6b7c8d9e0f",
    "name": "TestVm",
    "state": "Running",
    "vmNics": [
      {
        "uuid": "nic-uuid-1",
        "l3NetworkUuid": "c4f6a370f80443798cc460ee07d56ff1",
        "ip": "192.168.1.10",
        "mac": "fa:16:3e:12:34:56"
      }
    ],
    "allVolumes": [
      {
        "uuid": "vol-uuid-1",
        "type": "Root",
        "size": 10737418240,
        "deviceId": 0
      }
    ],
    "hypervisorType": "KVM",
    "instanceOfferingUuid": "1618154b462a48749ca9b114cf4a2979",
    "imageUuid": "99a5eea648954ef7be2b8ede8f34fe26",
    "hostUuid": "host-uuid-allocated",
    "createDate": "2024-12-01T10:30:00Z"
  }
}
```
```

--------------------------------

### REST API: Add DNS to L3 Network

Source: https://context7.com/zstackio/zstack/llms.txt

This example demonstrates how to add a DNS server to an existing L3 network using the ZStack REST API. It requires the L3 network UUID and the IP address of the DNS server.

```Bash
# Add DNS to L3 Network
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/dns \
  -H "Content-Type: application/json" \
  -d '{
    "dns": "8.8.8.8"
  }'
```

--------------------------------

### VM Creation Extension Point - Java

Source: https://context7.com/zstackio/zstack/llms.txt

Implements `VmInstanceCreateExtensionPoint` to hook into VM creation lifecycle. It allows pre-validation, custom logic before creation, and post-creation actions like sending notifications. Dependencies include `CloudBus` and `DatabaseFacade`. It takes `VmInstanceInventory` as input and can throw `VmInstanceException`.

```java
// VM Creation Extension Point
@Component
public class CustomVmCreationExtension implements VmInstanceCreateExtensionPoint {
    @Autowired
    private CloudBus bus;

    @Autowired
    private DatabaseFacade dbf;

    @Override
    public void preCreateVmInstance(VmInstanceInventory inv) throws VmInstanceException {
        // Custom validation before VM creation
        if (inv.getCpuNum() > 32) {
            throw new VmInstanceException("CPU count exceeds maximum allowed: 32");
        }

        // Add custom tags
        SystemTagCreator creator = SystemTagCreator.createNonInherent(
            inv.getUuid(),
            "custom::validated::true"
        );
        creator.create();

        logger.info("Pre-create validation passed for VM: " + inv.getName());
    }

    @Override
    public void beforeCreateVmInstance(VmInstanceInventory inv) {
        // Custom logic before VM is actually created
        logger.info("Creating VM with custom configuration: " + inv.getName());
    }

    @Override
    public void afterCreateVmInstance(VmInstanceInventory inv) {
        // Post-creation actions
        logger.info("VM created, applying custom post-creation steps: " + inv.getUuid());

        // Send notification to external system
        NotificationMessage notification = new NotificationMessage();
        notification.setResourceType("VmInstance");
        notification.setResourceUuid(inv.getUuid());
        notification.setAction("Created");
        bus.send(notification);
    }
}
```

--------------------------------

### Java SDK: Query VM Instances with Filters

Source: https://context7.com/zstackio/zstack/llms.txt

This Java SDK snippet demonstrates how to query VM instances with specific conditions, select desired fields, and apply pagination. It utilizes the APIQueryVmInstanceMsg and expects a reply containing a list of VmInstanceInventory objects.

```Java
APIQueryVmInstanceMsg query = new APIQueryVmInstanceMsg();
query.setConditions(Arrays.asList(
    "vmNics.eip.guestIp=16.16.16.16",
    "state=Running",
    "zone.name=west-coast"
));
query.setFields(Arrays.asList("name", "uuid", "state", "vmNics"));
query.setStart(0);
query.setLimit(100);

APIQueryVmInstanceReply reply = (APIQueryVmInstanceReply) cloudBus.call(query);
List<VmInstanceInventory> vms = reply.getInventories();
```

--------------------------------

### Create and Revert Volume Snapshot using Java SDK

Source: https://context7.com/zstackio/zstack/llms.txt

Demonstrates the ZStack Java SDK usage for creating a volume snapshot and reverting a volume from an existing snapshot. It involves constructing the relevant API message objects and processing their responses.

```Java
APICreateVolumeSnapshotMsg createMsg = new APICreateVolumeSnapshotMsg();
createMsg.setVolumeUuid("volume-uuid-1234567890");
createMsg.setName("snapshot-before-upgrade");
createMsg.setDescription("Backup before system upgrade");

APICreateVolumeSnapshotEvent createEvt = (APICreateVolumeSnapshotEvent) cloudBus.call(createMsg);
String snapshotUuid = createEvt.getInventory().getUuid();

// Revert volume from snapshot
APIRevertVolumeFromSnapshotMsg revertMsg = new APIRevertVolumeFromSnapshotMsg();
revertMsg.setUuid(snapshotUuid);
APIRevertVolumeFromSnapshotEvent revertEvt = (APIRevertVolumeFromSnapshotEvent) cloudBus.call(revertMsg);

if (revertEvt.isSuccess()) {
    System.out.println("Volume reverted successfully");
}
```

--------------------------------

### REST API: Attach Network Service to L3 Network

Source: https://context7.com/zstackio/zstack/llms.txt

This example shows how to attach network services (e.g., DHCP, DNS, SNAT, EIP) to an L3 network using the ZStack REST API. It requires the L3 network UUID and the UUID of the virtual router provider for each service.

```Bash
# Attach Network Service to L3 Network
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/network-services \
  -H "Content-Type: application/json" \
  -d '{
    "networkServices": {
      "DHCP": ["virtual-router-provider-uuid"],
      "DNS": ["virtual-router-provider-uuid"],
      "SNAT": ["virtual-router-provider-uuid"],
      "EIP": ["virtual-router-provider-uuid"]
    }
  }'
```

--------------------------------

### L3 Network Creation and Management

Source: https://context7.com/zstackio/zstack/llms.txt

APIs for creating and managing L3 networks, including IP ranges, DNS, and network services.

```APIDOC
## L3 Network Creation and Management

Create and manage logical networks with IP address ranges, DNS, and network services.

### Create L3 Network

Creates a new L3 network.

### Method

POST

### Endpoint

`/zstack/api/v1/l3-networks`

### Parameters

#### Request Body

- **params** (object) - Required - Contains the parameters for creating the L3 network.
  - **name** (string) - Required - The name of the L3 network.
  - **description** (string) - Optional - A description for the L3 network.
  - **type** (string) - Required - The type of L3 network (e.g., "L3BasicNetwork").
  - **l2NetworkUuid** (string) - Required - The UUID of the associated L2 network.
  - **category** (string) - Optional - The category of the network (e.g., "Private").
  - **ipVersion** (integer) - Optional - The IP version (4 or 6).

### Request Example

```bash
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <access-token>" \
  -d '{
    "params": {
      "name": "GuestNetwork",
      "description": "Production guest network",
      "type": "L3BasicNetwork",
      "l2NetworkUuid": "2f5e0755584d41dabb73c7dcbee2fe29",
      "category": "Private",
      "ipVersion": 4
    }
  }'
```

### Add IP Range to L3 Network

Adds an IP range to an existing L3 network.

### Method

POST

### Endpoint

`/zstack/api/v1/l3-networks/{l3-network-uuid}/ip-ranges`

### Parameters

#### Path Parameters

- **l3-network-uuid** (string) - Required - The UUID of the L3 network.

#### Request Body

- **params** (object) - Required - Contains the parameters for the IP range.
  - **name** (string) - Required - The name of the IP range.
  - **startIp** (string) - Required - The starting IP address of the range.
  - **endIp** (string) - Required - The ending IP address of the range.
  - **netmask** (string) - Required - The netmask for the IP range.
  - **gateway** (string) - Required - The gateway for the IP range.

### Request Example

```bash
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/ip-ranges \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "name": "IPRange1",
      "startIp": "192.168.1.10",
      "endIp": "192.168.1.100",
      "netmask": "255.255.255.0",
      "gateway": "192.168.1.1"
    }
  }'
```

### Add DNS to L3 Network

Adds a DNS server to an L3 network.

### Method

POST

### Endpoint

`/zstack/api/v1/l3-networks/{l3-network-uuid}/dns`

### Parameters

#### Path Parameters

- **l3-network-uuid** (string) - Required - The UUID of the L3 network.

#### Request Body

- **dns** (string) - Required - The IP address of the DNS server.

### Request Example

```bash
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/dns \
  -H "Content-Type: application/json" \
  -d '{
    "dns": "8.8.8.8"
  }'
```

### Attach Network Service to L3 Network

Attaches a network service to an L3 network.

### Method

POST

### Endpoint

`/zstack/api/v1/l3-networks/{l3-network-uuid}/network-services`

### Parameters

#### Path Parameters

- **l3-network-uuid** (string) - Required - The UUID of the L3 network.

#### Request Body

- **networkServices** (object) - Required - An object mapping network service types to provider UUIDs.
  - **DHCP** (array of strings) - Optional - List of provider UUIDs for DHCP service.
  - **DNS** (array of strings) - Optional - List of provider UUIDs for DNS service.
  - **SNAT** (array of strings) - Optional - List of provider UUIDs for SNAT service.
  - **EIP** (array of strings) - Optional - List of provider UUIDs for EIP service.

### Request Example

```bash
curl -X POST http://localhost:8080/zstack/api/v1/l3-networks/l3-network-uuid/network-services \
  -H "Content-Type: application/json" \
  -d '{
    "networkServices": {
      "DHCP": ["virtual-router-provider-uuid"],
      "DNS": ["virtual-router-provider-uuid"],
      "SNAT": ["virtual-router-provider-uuid"],
      "EIP": ["virtual-router-provider-uuid"]
    }
  }'
```
```

--------------------------------

### Create Security Group and Add Rules (Java SDK)

Source: https://context7.com/zstackio/zstack/llms.txt

Demonstrates creating a security group and adding ingress rules using the ZStack Java SDK. It utilizes the CloudBus for asynchronous communication.

```java
APICreateSecurityGroupMsg createMsg = new APICreateSecurityGroupMsg();
createMsg.setName("web-server-sg");
createMsg.setDescription("Security group for web servers");

APICreateSecurityGroupEvent createEvt = (APICreateSecurityGroupEvent) cloudBus.call(createMsg);
String sgUuid = createEvt.getInventory().getUuid();

// Add rules
APIAddSecurityGroupRuleMsg addRuleMsg = new APIAddSecurityGroupRuleMsg();
addRuleMsg.setSecurityGroupUuid(sgUuid);

SecurityGroupRuleAO rule1 = new SecurityGroupRuleAO();
rule1.setType("Ingress");
rule1.setProtocol("TCP");
rule1.setStartPort(80);
rule1.setEndPort(80);
rule1.setAllowedCidr("0.0.0.0/0");

SecurityGroupRuleAO rule2 = new SecurityGroupRuleAO();
rule2.setType("Ingress");
rule2.setProtocol("TCP");
rule2.setStartPort(443);
rule2.setEndPort(443);
rule2.setAllowedCidr("0.0.0.0/0");

addRuleMsg.setRules(Arrays.asList(rule1, rule2));
cloudBus.call(addRuleMsg);
```

--------------------------------

### Create L3 Network and Add IP Range using Java SDK

Source: https://context7.com/zstackio/zstack/llms.txt

Demonstrates how to create a basic L3 network and subsequently add an IP range to it using the ZStack Java SDK. This involves constructing API messages for network creation and IP range addition, then submitting them via the cloud bus.

```Java
APICreateL3NetworkMsg msg = new APICreateL3NetworkMsg();
msg.setName("GuestNetwork");
msg.setDescription("Production guest network");
msg.setType("L3BasicNetwork");
msg.setL2NetworkUuid("2f5e0755584d41dabb73c7dcbee2fe29");
msg.setCategory("Private");
msg.setIpVersion(4);

APICreateL3NetworkEvent evt = (APICreateL3NetworkEvent) cloudBus.call(msg);
String l3Uuid = evt.getInventory().getUuid();

// Add IP range
APIAddIpRangeMsg ipRangeMsg = new APIAddIpRangeMsg();
ipRangeMsg.setL3NetworkUuid(l3Uuid);
ipRangeMsg.setName("IPRange1");
ipRangeMsg.setStartIp("192.168.1.10");
ipRangeMsg.setEndIp("192.168.1.100");
ipRangeMsg.setNetmask("255.255.255.0");
ipRangeMsg.setGateway("192.168.1.1");
cloudBus.call(ipRangeMsg);
```

--------------------------------

### Manage Backup Storage using Java SDK

Source: https://context7.com/zstackio/zstack/llms.txt

Illustrates how to add and update SFTP backup storage configurations using the ZStack Java SDK. This involves creating message objects for adding and updating backup storage and sending them through the cloud bus.

```Java
APIAddSftpBackupStorageMsg addMsg = new APIAddSftpBackupStorageMsg();
addMsg.setName("backup-sftp-1");
addMsg.setUrl("/backup");
addMsg.setHostname("192.168.10.100");
addMsg.setUsername("root");
addMsg.setPassword("password");
addMsg.setSshPort(22);

APIAddSftpBackupStorageEvent addEvt = (APIAddSftpBackupStorageEvent) cloudBus.call(addMsg);
String bsUuid = addEvt.getInventory().getUuid();

// Update backup storage
APIUpdateBackupStorageMsg updateMsg = new APIUpdateBackupStorageMsg();
updateMsg.setUuid(bsUuid);
updateMsg.setName("backup-sftp-updated");
updateMsg.setDescription("Updated backup storage");
cloudBus.call(updateMsg);
```

--------------------------------

### Create EIP (Bash)

Source: https://context7.com/zstackio/zstack/llms.txt

Creates an Elastic IP (EIP) and associates it with a VIP and VM NIC. Requires name, VIP UUID, and VM NIC UUID. Authentication may be needed.

```bash
# Create EIP
curl -X POST http://localhost:8080/zstack/api/v1/eips \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <access-token>" \
  -d '{
    "params": {
      "name": "eip-for-webserver",
      "vipUuid": "vip-uuid-1234567890abcdef",
      "vmNicUuid": "vm-nic-uuid-1234567890"
    }
  }'
```

--------------------------------

### Network Service Extension - Java

Source: https://context7.com/zstackio/zstack/llms.txt

Implements `NetworkServiceExtensionPoint` to apply and release custom network services, such as firewall rules. It defines a `NetworkServiceType` and includes methods for applying and cleaning up network configurations based on VM specifications. Dependencies include `VmInstanceSpec` and `HostInventory`.

```java
// Network Service Extension
@Component
public class CustomNetworkServiceExtension implements NetworkServiceExtensionPoint {
    @Override
    public NetworkServiceType getNetworkServiceType() {
        return new NetworkServiceType("CustomFirewall");
    }

    @Override
    public void applyNetworkService(VmInstanceSpec spec, Map<String, Object> data) {
        // Apply custom network service
        String vmUuid = spec.getVmInventory().getUuid();
        logger.info("Applying custom firewall rules for VM: " + vmUuid);

        // Custom firewall rule application logic
        List<String> rules = getCustomFirewallRules(vmUuid);
        applyFirewallRules(spec.getDestHost(), vmUuid, rules);
    }

    @Override
    public void releaseNetworkService(VmInstanceSpec spec, Map<String, Object> data) {
        // Clean up custom network service
        String vmUuid = spec.getVmInventory().getUuid();
        logger.info("Removing custom firewall rules for VM: " + vmUuid);
        removeFirewallRules(spec.getDestHost(), vmUuid);
    }

    private List<String> getCustomFirewallRules(String vmUuid) {
        // Retrieve rules from database or configuration
        return Arrays.asList(
            "ACCEPT tcp 80",
            "ACCEPT tcp 443",
            "DROP all"
        );
    }

    private void applyFirewallRules(HostInventory host, String vmUuid, List<String> rules) {
        // Apply rules to hypervisor
    }

    private void removeFirewallRules(HostInventory host, String vmUuid) {
        // Remove rules from hypervisor
    }
}
```

--------------------------------

### Primary Storage Management API

Source: https://context7.com/zstackio/zstack/llms.txt

APIs for managing primary storage backends, including adding NFS and local storage, attaching to clusters, querying capacity, and updating configurations.

```APIDOC
## Add NFS Primary Storage

### Description
Adds a new NFS primary storage backend to the ZStack environment.

### Method
POST

### Endpoint
/zstack/api/v1/primary-storage/nfs

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for adding NFS primary storage.
  - **name** (string) - Required - The name of the primary storage.
  - **url** (string) - Required - The NFS share URL (e.g., '192.168.10.50:/export/primary').
  - **zoneUuid** (string) - Required - The UUID of the zone where the primary storage will be located.
  - **type** (string) - Required - Must be 'NFS'.

### Request Example
```json
{
  "params": {
    "name": "nfs-primary-1",
    "url": "192.168.10.50:/export/primary",
    "zoneUuid": "zone-uuid-1234567890",
    "type": "NFS"
  }
}
```

## Add Local Primary Storage

### Description
Adds a new local primary storage backend to the ZStack environment.

### Method
POST

### Endpoint
/zstack/api/v1/primary-storage/local

### Parameters
#### Request Body
- **params** (object) - Required - Parameters for adding local primary storage.
  - **name** (string) - Required - The name of the primary storage.
  - **url** (string) - Required - The local path for the storage (e.g., '/local_ps').
  - **zoneUuid** (string) - Required - The UUID of the zone where the primary storage will be located.
  - **type** (string) - Required - Must be 'LocalStorage'.

### Request Example
```json
{
  "params": {
    "name": "local-primary-1",
    "url": "/local_ps",
    "zoneUuid": "zone-uuid-1234567890",
    "type": "LocalStorage"
  }
}
```

## Attach Primary Storage to Cluster

### Description
Attaches an existing primary storage to a specific cluster.

### Method
POST

### Endpoint
/zstack/api/v1/clusters/{clusterUuid}/primary-storage/{primaryStorageUuid}

### Parameters
#### Path Parameters
- **clusterUuid** (string) - Required - The UUID of the cluster.
- **primaryStorageUuid** (string) - Required - The UUID of the primary storage.

## Query Primary Storage Capacity

### Description
Retrieves the capacity information for a given primary storage.

### Method
GET

### Endpoint
/zstack/api/v1/primary-storage/{primaryStorageUuid}/capacity

### Parameters
#### Path Parameters
- **primaryStorageUuid** (string) - Required - The UUID of the primary storage.

#### Query Parameters
- **Authorization** (string) - Optional - OAuth access token.

### Response
#### Success Response (200)
- **totalCapacity** (long) - Total storage capacity in bytes.
- **availableCapacity** (long) - Available storage capacity in bytes.
- **totalPhysicalCapacity** (long) - Total physical storage capacity in bytes.
- **availablePhysicalCapacity** (long) - Available physical storage capacity in bytes.
- **systemUsedCapacity** (long) - Capacity used by the system in bytes.

### Response Example
```json
{
  "totalCapacity": 10995116277760,
  "availableCapacity": 8796093022208,
  "totalPhysicalCapacity": 10995116277760,
  "availablePhysicalCapacity": 8796093022208,
  "systemUsedCapacity": 1099511627776
}
```

## Update Primary Storage Configuration

### Description
Updates the configuration of an existing primary storage, such as name or description. Note: This endpoint is for general updates, specific actions like over-provisioning ratio might have dedicated endpoints.

### Method
PUT

### Endpoint
/zstack/api/v1/primary-storage/{primaryStorageUuid}/actions

### Parameters
#### Path Parameters
- **primaryStorageUuid** (string) - Required - The UUID of the primary storage to update.

#### Request Body
- **updatePrimaryStorage** (object) - Required - The update payload.
  - **name** (string) - Optional - The new name for the primary storage.
  - **description** (string) - Optional - The new description for the primary storage.

### Request Example
```json
{
  "updatePrimaryStorage": {
    "name": "nfs-primary-updated",
    "description": "Updated NFS storage"
  }
}
```
```