Container Management - FreshPerf/PVE4J GitHub Wiki

Container Management

This guide covers LXC container management using PVE4J.

Table of Contents

Listing Containers

List Containers on a Specific Node

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcIndex;
import java.util.List;

try {
    List<PveLxcIndex> containers = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .getIndex()
            .execute();
    
    for (PveLxcIndex container : containers) {
        System.out.printf("VMID: %d, Name: %s, Status: %s%n",
                container.getVmid(), container.getName(), container.getStatus());
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

List All Containers in Cluster

import fr.freshperf.pve4j.entities.cluster.resources.PveClusterResources;
import java.util.List;

try {
    List<PveClusterResources> resources = proxmox.getCluster()
            .getResources()
            .execute();
    
    for (PveClusterResources resource : resources) {
        if ("lxc".equals(resource.getType())) {
            System.out.printf("VMID: %d, Name: %s, Node: %s, Status: %s%n",
                    resource.getVmid(), resource.getName(), 
                    resource.getNode(), resource.getStatus());
        }
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Container Information

Get Container Status

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcStatus;

try {
    PveLxcStatus status = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getStatus()
            .execute();
    
    System.out.println("Status: " + status.getStatus());
    System.out.println("CPU Usage: " + status.getCpu());
    System.out.println("Memory: " + status.getMem() + " / " + status.getMaxmem());
    System.out.println("Swap: " + status.getSwap() + " / " + status.getMaxswap());
    System.out.println("Disk: " + status.getDisk() + " / " + status.getMaxdisk());
    System.out.println("Uptime: " + status.getUptime() + " seconds");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Get Container Configuration

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcConfig;

try {
    PveLxcConfig config = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getConfig()
            .execute();
    
    System.out.println("Hostname: " + config.getHostname());
    System.out.println("Memory: " + config.getMemory());
    System.out.println("Swap: " + config.getSwap());
    System.out.println("Cores: " + config.getCores());
    System.out.println("Rootfs: " + config.getRootfs());
    System.out.println("OS Type: " + config.getOstype());
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Get Pending Configuration Changes

try {
    List<PveLxcPendingChange> pending = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getPending()
            .execute();
    
    for (PveLxcPendingChange change : pending) {
        System.out.println("Pending: " + change);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Creating Containers

Create a Container

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcCreateOptions;

try {
    PveLxcCreateOptions options = PveLxcCreateOptions.builder()
            .ostemplate("local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst")
            .hostname("my-container")
            .memory(1024)
            .swap(512)
            .cores(2)
            .rootfs("local-lvm:8")
            .password("secure-password")
            .unprivileged(true)
            .onboot(true)
            .start(true)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .create(200, options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Create with SSH Keys and Networking

try {
    PveLxcCreateOptions options = PveLxcCreateOptions.builder()
            .ostemplate("local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst")
            .hostname("ssh-container")
            .memory(512)
            .cores(1)
            .rootfs("local-lvm:4")
            .sshPublicKeys("ssh-rsa AAAA... user@host")
            .nameserver("8.8.8.8")
            .searchdomain("example.com")
            .unprivileged(true)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .create(201, options)
            .waitForCompletion(proxmox)
            .execute();
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Lifecycle Operations

Start a Container

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .start()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container started!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Stop a Container (Hard)

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .stop()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container stopped!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Shutdown a Container (Graceful)

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .shutdown()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container shutdown!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Reboot / Suspend / Resume

// Reboot
container.reboot().waitForCompletion(proxmox).execute();

// Suspend
container.suspend().waitForCompletion(proxmox).execute();

// Resume
container.resume().waitForCompletion(proxmox).execute();

Delete a Container

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .delete()
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container deleted!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Container Configuration

Update Configuration

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcConfigUpdateOptions;

try {
    PveLxcConfigUpdateOptions options = PveLxcConfigUpdateOptions.builder()
            .memory(2048)
            .swap(1024)
            .cores(4)
            .build();
    
    proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .updateConfig(options)
            .execute();
    
    System.out.println("Container configuration updated!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Cloning Containers

Simple Clone

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .cloneContainer(201)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container cloned!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Clone with Options

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcCloneOptions;

try {
    PveLxcCloneOptions options = PveLxcCloneOptions.builder()
            .hostname("cloned-container")
            .storage("local-lvm")
            .full(true)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .cloneContainer(201, options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container cloned with options!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Migration

Migrate a Container

try {
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .migrate("pve-node-02")
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container migrated!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Migrate with Options

import fr.freshperf.pve4j.entities.nodes.node.lxc.PveLxcMigrateOptions;

try {
    PveLxcMigrateOptions options = PveLxcMigrateOptions.builder()
            .online(true)
            .targetStorage("local-lvm")
            .restart(true)
            .timeout(120)
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .migrate("pve-node-02", options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Container migrated with options!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Templates

Convert a Container to Template

try {
    proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .template()
            .execute();
    
    System.out.println("Container converted to template!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Snapshots

List Snapshots

try {
    List<PveLxcSnapshot> snapshots = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getSnapshots()
            .list()
            .execute();
    
    for (PveLxcSnapshot snapshot : snapshots) {
        System.out.println("Snapshot: " + snapshot.getName());
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Create a Snapshot

import fr.freshperf.pve4j.entities.nodes.node.lxc.snapshot.PveLxcSnapshotCreateOptions;

try {
    PveLxcSnapshotCreateOptions options = PveLxcSnapshotCreateOptions.builder()
            .description("Before upgrade")
            .build();
    
    PveTask task = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getSnapshots()
            .create("pre-upgrade", options)
            .waitForCompletion(proxmox)
            .execute();
    
    System.out.println("Snapshot created!");
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Rollback / Delete / Update a Snapshot

var snapItem = proxmox.getNodes()
        .get("pve-node-01")
        .getLxc()
        .get(200)
        .getSnapshots()
        .get("pre-upgrade");

// Get snapshot configuration
PveLxcSnapshotConfig config = snapItem.getConfig().execute();

// Rollback
snapItem.rollback().waitForCompletion(proxmox).execute();

// Update description
snapItem.update(PveLxcSnapshotUpdateOptions.builder()
        .description("Updated description")
        .build()).execute();

// Delete
snapItem.delete().waitForCompletion(proxmox).execute();

Network Interfaces

Get Container Network Interfaces

try {
    List<PveLxcInterface> interfaces = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getInterfaces()
            .execute();
    
    for (PveLxcInterface iface : interfaces) {
        System.out.println("Interface: " + iface);
    }
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Feature Availability

Check if a Feature is Available

try {
    PveLxcFeatureAvailability feature = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getFeature("snapshot")  // "snapshot", "clone", or "copy"
            .execute();
    
    System.out.println("Feature available: " + feature);
    
    // Check with a specific snapshot
    PveLxcFeatureAvailability cloneFeature = proxmox.getNodes()
            .get("pve-node-01")
            .getLxc()
            .get(200)
            .getFeature("clone", "my-snapshot")
            .execute();
} catch (ProxmoxAPIError | InterruptedException e) {
    e.printStackTrace();
}

Working with Multiple Containers

Start Multiple Containers

import java.util.Arrays;
import java.util.List;

List<Integer> containerIds = Arrays.asList(200, 201, 202, 203);

for (int ctid : containerIds) {
    try {
        proxmox.getNodes()
                .get("pve-node-01")
                .getLxc()
                .get(ctid)
                .start()
                .waitForCompletion(proxmox)
                .execute();
        
        System.out.println("Container " + ctid + " started");
        
    } catch (ProxmoxAPIError | InterruptedException e) {
        System.err.println("Failed to start container " + ctid + ": " + e.getMessage());
    }
}

Common Use Cases

Automated Container Management

public class ContainerManager {
    private final Proxmox proxmox;
    private final String nodeName;
    
    public ContainerManager(Proxmox proxmox, String nodeName) {
        this.proxmox = proxmox;
        this.nodeName = nodeName;
    }
    
    public void ensureRunning(int ctid) throws ProxmoxAPIError, InterruptedException {
        PveLxcStatus status = proxmox.getNodes()
                .get(nodeName)
                .getLxc()
                .get(ctid)
                .getStatus()
                .execute();
        
        if (!"running".equals(status.getStatus())) {
            proxmox.getNodes()
                    .get(nodeName)
                    .getLxc()
                    .get(ctid)
                    .start()
                    .waitForCompletion(proxmox)
                    .execute();
            
            System.out.println("Container " + ctid + " started");
        }
    }
    
    public void ensureStopped(int ctid) throws ProxmoxAPIError, InterruptedException {
        PveLxcStatus status = proxmox.getNodes()
                .get(nodeName)
                .getLxc()
                .get(ctid)
                .getStatus()
                .execute();
        
        if ("running".equals(status.getStatus())) {
            proxmox.getNodes()
                    .get(nodeName)
                    .getLxc()
                    .get(ctid)
                    .shutdown()
                    .waitForCompletion(proxmox)
                    .execute();
            
            System.out.println("Container " + ctid + " shutdown initiated");
        }
    }
}

Container Health Check

public boolean isContainerHealthy(int ctid) {
    try {
        PveLxcStatus status = proxmox.getNodes()
                .get("pve-node-01")
                .getLxc()
                .get(ctid)
                .getStatus()
                .execute();
        
        boolean isRunning = "running".equals(status.getStatus());
        boolean memoryOk = (double) status.getMem() / status.getMaxmem() < 0.9;
        boolean diskOk = (double) status.getDisk() / status.getMaxdisk() < 0.9;
        
        return isRunning && memoryOk && diskOk;
    } catch (Exception e) {
        return false;
    }
}

Next Steps

⚠️ **GitHub.com Fallback** ⚠️