1. Packages
  2. Proxmox Virtual Environment (Proxmox VE)
  3. API Docs
  4. Oci
  5. Image
Proxmox Virtual Environment (Proxmox VE) v7.11.0 published on Saturday, Dec 13, 2025 by Daniel Muehlbachler-Pietrzykowski
Schema (JSON)
muhlba91/pulumi-proxmoxve

proxmoxve.Oci.Image

proxmoxve logo
Proxmox Virtual Environment (Proxmox VE) v7.11.0 published on Saturday, Dec 13, 2025 by Daniel Muehlbachler-Pietrzykowski
Schema (JSON)
muhlba91/pulumi-proxmoxve

    Manages OCI images pulled from OCI registries using PVE oci-registry-pull API. Pulls OCI container images and stores them as tar files in Proxmox VE datastores.

    Example Usage

    import * as pulumi from "@pulumi/pulumi";
import * as proxmoxve from "@muhlba91/pulumi-proxmoxve";

const ubuntuLatest = new proxmoxve.oci.Image("ubuntu_latest", {
    nodeName: "pve",
    datastoreId: "local",
    reference: "docker.io/library/ubuntu:latest",
});
const nginx = new proxmoxve.oci.Image("nginx", {
    nodeName: "pve",
    datastoreId: "local",
    reference: "docker.io/library/nginx:alpine",
    fileName: "custom_image_name.tar",
});
const debian = new proxmoxve.oci.Image("debian", {
    nodeName: "pve",
    datastoreId: "local",
    reference: "docker.io/library/debian:bookworm",
    uploadTimeout: 900,
    overwrite: false,
    overwriteUnmanaged: true,
});

    import pulumi
import pulumi_proxmoxve as proxmoxve

ubuntu_latest = proxmoxve.oci.Image("ubuntu_latest",
    node_name="pve",
    datastore_id="local",
    reference="docker.io/library/ubuntu:latest")
nginx = proxmoxve.oci.Image("nginx",
    node_name="pve",
    datastore_id="local",
    reference="docker.io/library/nginx:alpine",
    file_name="custom_image_name.tar")
debian = proxmoxve.oci.Image("debian",
    node_name="pve",
    datastore_id="local",
    reference="docker.io/library/debian:bookworm",
    upload_timeout=900,
    overwrite=False,
    overwrite_unmanaged=True)

    package main

import (
	"github.com/muhlba91/pulumi-proxmoxve/sdk/v7/go/proxmoxve/oci"
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		_, err := oci.NewImage(ctx, "ubuntu_latest", &oci.ImageArgs{
			NodeName:    pulumi.String("pve"),
			DatastoreId: pulumi.String("local"),
			Reference:   pulumi.String("docker.io/library/ubuntu:latest"),
		})
		if err != nil {
			return err
		}
		_, err = oci.NewImage(ctx, "nginx", &oci.ImageArgs{
			NodeName:    pulumi.String("pve"),
			DatastoreId: pulumi.String("local"),
			Reference:   pulumi.String("docker.io/library/nginx:alpine"),
			FileName:    pulumi.String("custom_image_name.tar"),
		})
		if err != nil {
			return err
		}
		_, err = oci.NewImage(ctx, "debian", &oci.ImageArgs{
			NodeName:           pulumi.String("pve"),
			DatastoreId:        pulumi.String("local"),
			Reference:          pulumi.String("docker.io/library/debian:bookworm"),
			UploadTimeout:      pulumi.Int(900),
			Overwrite:          pulumi.Bool(false),
			OverwriteUnmanaged: pulumi.Bool(true),
		})
		if err != nil {
			return err
		}
		return nil
	})
}

    using System.Collections.Generic;
using System.Linq;
using Pulumi;
using ProxmoxVE = Pulumi.ProxmoxVE;

return await Deployment.RunAsync(() => 
{
    var ubuntuLatest = new ProxmoxVE.Oci.Image("ubuntu_latest", new()
    {
        NodeName = "pve",
        DatastoreId = "local",
        Reference = "docker.io/library/ubuntu:latest",
    });

    var nginx = new ProxmoxVE.Oci.Image("nginx", new()
    {
        NodeName = "pve",
        DatastoreId = "local",
        Reference = "docker.io/library/nginx:alpine",
        FileName = "custom_image_name.tar",
    });

    var debian = new ProxmoxVE.Oci.Image("debian", new()
    {
        NodeName = "pve",
        DatastoreId = "local",
        Reference = "docker.io/library/debian:bookworm",
        UploadTimeout = 900,
        Overwrite = false,
        OverwriteUnmanaged = true,
    });

});

    package generated_program;

import com.pulumi.Context;
import com.pulumi.Pulumi;
import com.pulumi.core.Output;
import io.muehlbachler.pulumi.proxmoxve.Oci.Image;
import io.muehlbachler.pulumi.proxmoxve.Oci.ImageArgs;
import java.util.List;
import java.util.ArrayList;
import java.util.Map;
import java.io.File;
import java.nio.file.Files;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        Pulumi.run(App::stack);
    }

    public static void stack(Context ctx) {
        var ubuntuLatest = new Image("ubuntuLatest", ImageArgs.builder()
            .nodeName("pve")
            .datastoreId("local")
            .reference("docker.io/library/ubuntu:latest")
            .build());

        var nginx = new Image("nginx", ImageArgs.builder()
            .nodeName("pve")
            .datastoreId("local")
            .reference("docker.io/library/nginx:alpine")
            .fileName("custom_image_name.tar")
            .build());

        var debian = new Image("debian", ImageArgs.builder()
            .nodeName("pve")
            .datastoreId("local")
            .reference("docker.io/library/debian:bookworm")
            .uploadTimeout(900)
            .overwrite(false)
            .overwriteUnmanaged(true)
            .build());

    }
}

    resources:
  ubuntuLatest:
    type: proxmoxve:Oci:Image
    name: ubuntu_latest
    properties:
      nodeName: pve
      datastoreId: local
      reference: docker.io/library/ubuntu:latest
  nginx:
    type: proxmoxve:Oci:Image
    properties:
      nodeName: pve
      datastoreId: local
      reference: docker.io/library/nginx:alpine
      fileName: custom_image_name.tar
  debian:
    type: proxmoxve:Oci:Image
    properties:
      nodeName: pve
      datastoreId: local
      reference: docker.io/library/debian:bookworm
      uploadTimeout: 900
      overwrite: false
      overwriteUnmanaged: true

    Create Image Resource

    Resources are created with functions called constructors. To learn more about declaring and configuring resources, see Resources.

    Constructor syntax

    new Image(name: string, args: ImageArgs, opts?: CustomResourceOptions);
    @overload
def Image(resource_name: str,
          args: ImageArgs,
          opts: Optional[ResourceOptions] = None)

@overload
def Image(resource_name: str,
          opts: Optional[ResourceOptions] = None,
          datastore_id: Optional[str] = None,
          node_name: Optional[str] = None,
          reference: Optional[str] = None,
          file_name: Optional[str] = None,
          overwrite: Optional[bool] = None,
          overwrite_unmanaged: Optional[bool] = None,
          upload_timeout: Optional[int] = None)
    func NewImage(ctx *Context, name string, args ImageArgs, opts ...ResourceOption) (*Image, error)
    public Image(string name, ImageArgs args, CustomResourceOptions? opts = null)
    public Image(String name, ImageArgs args)
public Image(String name, ImageArgs args, CustomResourceOptions options)

    type: proxmoxve:Oci:Image
properties: # The arguments to resource properties.
options: # Bag of options to control resource's behavior.

    Parameters

    name string
    The unique name of the resource.
    args ImageArgs
    The arguments to resource properties.
    opts CustomResourceOptions
    Bag of options to control resource's behavior.
    resource_name str
    The unique name of the resource.
    args ImageArgs
    The arguments to resource properties.
    opts ResourceOptions
    Bag of options to control resource's behavior.
    ctx Context
    Context object for the current deployment.
    name string
    The unique name of the resource.
    args ImageArgs
    The arguments to resource properties.
    opts ResourceOption
    Bag of options to control resource's behavior.
    name string
    The unique name of the resource.
    args ImageArgs
    The arguments to resource properties.
    opts CustomResourceOptions
    Bag of options to control resource's behavior.
    name String
    The unique name of the resource.
    args ImageArgs
    The arguments to resource properties.
    options CustomResourceOptions
    Bag of options to control resource's behavior.

    Constructor example

    The following reference example uses placeholder values for all input properties.

    var imageResource = new ProxmoxVE.Oci.Image("imageResource", new()
{
    DatastoreId = "string",
    NodeName = "string",
    Reference = "string",
    FileName = "string",
    Overwrite = false,
    OverwriteUnmanaged = false,
    UploadTimeout = 0,
});

    example, err := oci.NewImage(ctx, "imageResource", &oci.ImageArgs{
	DatastoreId:        pulumi.String("string"),
	NodeName:           pulumi.String("string"),
	Reference:          pulumi.String("string"),
	FileName:           pulumi.String("string"),
	Overwrite:          pulumi.Bool(false),
	OverwriteUnmanaged: pulumi.Bool(false),
	UploadTimeout:      pulumi.Int(0),
})

    var imageResource = new Image("imageResource", ImageArgs.builder()
    .datastoreId("string")
    .nodeName("string")
    .reference("string")
    .fileName("string")
    .overwrite(false)
    .overwriteUnmanaged(false)
    .uploadTimeout(0)
    .build());

    image_resource = proxmoxve.oci.Image("imageResource",
    datastore_id="string",
    node_name="string",
    reference="string",
    file_name="string",
    overwrite=False,
    overwrite_unmanaged=False,
    upload_timeout=0)

    const imageResource = new proxmoxve.oci.Image("imageResource", {
    datastoreId: "string",
    nodeName: "string",
    reference: "string",
    fileName: "string",
    overwrite: false,
    overwriteUnmanaged: false,
    uploadTimeout: 0,
});

    type: proxmoxve:Oci:Image
properties:
    datastoreId: string
    fileName: string
    nodeName: string
    overwrite: false
    overwriteUnmanaged: false
    reference: string
    uploadTimeout: 0

    Image Resource Properties

    To learn more about resource properties and how to use them, see Inputs and Outputs in the Architecture and Concepts docs.

    Inputs

    In Python, inputs that are objects can be passed either as argument classes or as dictionary literals.

    The Image resource accepts the following input properties:

    DatastoreId string
    The identifier for the target datastore.
    NodeName string
    The node name.
    Reference string
    The reference to the OCI image.
    FileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    Overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    OverwriteUnmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    UploadTimeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    DatastoreId string
    The identifier for the target datastore.
    NodeName string
    The node name.
    Reference string
    The reference to the OCI image.
    FileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    Overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    OverwriteUnmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    UploadTimeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId String
    The identifier for the target datastore.
    nodeName String
    The node name.
    reference String
    The reference to the OCI image.
    fileName String
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    overwrite Boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged Boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    uploadTimeout Integer
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId string
    The identifier for the target datastore.
    nodeName string
    The node name.
    reference string
    The reference to the OCI image.
    fileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    overwrite boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    uploadTimeout number
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastore_id str
    The identifier for the target datastore.
    node_name str
    The node name.
    reference str
    The reference to the OCI image.
    file_name str
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwrite_unmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    upload_timeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId String
    The identifier for the target datastore.
    nodeName String
    The node name.
    reference String
    The reference to the OCI image.
    fileName String
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    overwrite Boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged Boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    uploadTimeout Number
    The OCI image pull timeout in seconds. Default is 600 (10min).

    Outputs

    All input properties are implicitly available as output properties. Additionally, the Image resource produces the following output properties:

    Id string
    The provider-assigned unique ID for this managed resource.
    Size int
    The image size in PVE.
    Id string
    The provider-assigned unique ID for this managed resource.
    Size int
    The image size in PVE.
    id String
    The provider-assigned unique ID for this managed resource.
    size Integer
    The image size in PVE.
    id string
    The provider-assigned unique ID for this managed resource.
    size number
    The image size in PVE.
    id str
    The provider-assigned unique ID for this managed resource.
    size int
    The image size in PVE.
    id String
    The provider-assigned unique ID for this managed resource.
    size Number
    The image size in PVE.

    Look up Existing Image Resource

    Get an existing Image resource’s state with the given name, ID, and optional extra properties used to qualify the lookup.

    public static get(name: string, id: Input<ID>, state?: ImageState, opts?: CustomResourceOptions): Image
    @staticmethod
def get(resource_name: str,
        id: str,
        opts: Optional[ResourceOptions] = None,
        datastore_id: Optional[str] = None,
        file_name: Optional[str] = None,
        node_name: Optional[str] = None,
        overwrite: Optional[bool] = None,
        overwrite_unmanaged: Optional[bool] = None,
        reference: Optional[str] = None,
        size: Optional[int] = None,
        upload_timeout: Optional[int] = None) -> Image
    func GetImage(ctx *Context, name string, id IDInput, state *ImageState, opts ...ResourceOption) (*Image, error)
    public static Image Get(string name, Input<string> id, ImageState? state, CustomResourceOptions? opts = null)
    public static Image get(String name, Output<String> id, ImageState state, CustomResourceOptions options)
    resources:  _:    type: proxmoxve:Oci:Image    get:      id: ${id}
    name
    The unique name of the resulting resource.
    id
    The unique provider ID of the resource to lookup.
    state
    Any extra arguments used during the lookup.
    opts
    A bag of options that control this resource's behavior.
    resource_name
    The unique name of the resulting resource.
    id
    The unique provider ID of the resource to lookup.
    name
    The unique name of the resulting resource.
    id
    The unique provider ID of the resource to lookup.
    state
    Any extra arguments used during the lookup.
    opts
    A bag of options that control this resource's behavior.
    name
    The unique name of the resulting resource.
    id
    The unique provider ID of the resource to lookup.
    state
    Any extra arguments used during the lookup.
    opts
    A bag of options that control this resource's behavior.
    name
    The unique name of the resulting resource.
    id
    The unique provider ID of the resource to lookup.
    state
    Any extra arguments used during the lookup.
    opts
    A bag of options that control this resource's behavior.
    The following state arguments are supported:
    DatastoreId string
    The identifier for the target datastore.
    FileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    NodeName string
    The node name.
    Overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    OverwriteUnmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    Reference string
    The reference to the OCI image.
    Size int
    The image size in PVE.
    UploadTimeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    DatastoreId string
    The identifier for the target datastore.
    FileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    NodeName string
    The node name.
    Overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    OverwriteUnmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    Reference string
    The reference to the OCI image.
    Size int
    The image size in PVE.
    UploadTimeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId String
    The identifier for the target datastore.
    fileName String
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    nodeName String
    The node name.
    overwrite Boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged Boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    reference String
    The reference to the OCI image.
    size Integer
    The image size in PVE.
    uploadTimeout Integer
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId string
    The identifier for the target datastore.
    fileName string
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    nodeName string
    The node name.
    overwrite boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    reference string
    The reference to the OCI image.
    size number
    The image size in PVE.
    uploadTimeout number
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastore_id str
    The identifier for the target datastore.
    file_name str
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    node_name str
    The node name.
    overwrite bool
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwrite_unmanaged bool
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    reference str
    The reference to the OCI image.
    size int
    The image size in PVE.
    upload_timeout int
    The OCI image pull timeout in seconds. Default is 600 (10min).
    datastoreId String
    The identifier for the target datastore.
    fileName String
    The file name for the pulled OCI image. If not provided, it will be generated automatically. The file will be stored as a .tar file.
    nodeName String
    The node name.
    overwrite Boolean
    By default true. If true and the OCI image size has changed in the datastore, it will be replaced. If false, there will be no check.
    overwriteUnmanaged Boolean
    If true and an OCI image with the same name already exists in the datastore, it will be deleted and the new image will be pulled. If false and the image already exists, an error will be returned.
    reference String
    The reference to the OCI image.
    size Number
    The image size in PVE.
    uploadTimeout Number
    The OCI image pull timeout in seconds. Default is 600 (10min).

    Package Details

    Repository
    proxmoxve muhlba91/pulumi-proxmoxve
    License
    Apache-2.0
    Notes
    This Pulumi package is based on the proxmox Terraform Provider.
    proxmoxve logo
    Proxmox Virtual Environment (Proxmox VE) v7.11.0 published on Saturday, Dec 13, 2025 by Daniel Muehlbachler-Pietrzykowski
    Schema (JSON)
    muhlba91/pulumi-proxmoxve
      Meet Neo: Your AI Platform Teammate