pulumi-vsphere 4.10.0a1710245029__py3-none-any.whl → 4.13.0a1736836157__py3-none-any.whl

pulumi_vsphere/tag.py

@@ -4,9 +4,14 @@
 
 import copy
 import warnings
+import sys
 import pulumi
 import pulumi.runtime
 from typing import Any, Mapping, Optional, Sequence, Union, overload
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict, TypeAlias
+else:
+    from typing_extensions import NotRequired, TypedDict, TypeAlias
 from . import _utilities
 
 __all__ = ['TagArgs', 'Tag']
@@ -140,7 +145,83 @@ class Tag(pulumi.CustomResource):
                  name: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a Tag resource with the given unique name, props, and options.
+        The `Tag` resource can be used to create and manage tags, which allow
+        you to attach metadata to objects in the vSphere inventory to make these
+        objects more sortable and searchable.
+
+        For more information about tags, click [here][ext-tags-general].
+
+        [ext-tags-general]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html
+
+        ## Example Usage
+
+        This example creates a tag named `test-tag`. This tag is assigned the
+        `test-category` category, which was created by the
+        `TagCategory` resource. The resulting
+        tag can be assigned to VMs and datastores only, and can be the only value in
+        the category that can be assigned, as per the restrictions defined by the
+        category.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            cardinality="SINGLE",
+            description="Managed by Pulumi",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        tag = vsphere.Tag("tag",
+            name="test-tag",
+            category_id=category.id,
+            description="Managed by Pulumi")
+        ```
+
+        ### Using Tags in a Supported Resource
+
+        Tags can be applied to vSphere resources via the `tags` argument
+        in any supported resource.
+
+        The following example builds on the above example by creating a
+        `VirtualMachine` and applying the
+        created tag to it:
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            cardinality="SINGLE",
+            description="Managed by Pulumi",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        tag = vsphere.Tag("tag",
+            name="test-tag",
+            category_id=category.id,
+            description="Managed by Pulumi")
+        web = vsphere.VirtualMachine("web", tags=[tag.id])
+        ```
+
+        ## Import
+
+        An existing tag can be imported into this resource by supplying
+
+        both the tag's category name and the name of the tag as a JSON string to
+
+        `pulumi import`, as per the example below:
+
+        ```sh
+        $ pulumi import vsphere:index/tag:Tag tag \\
+        ```
+
+          '{"category_name": "pulumi-test-category", "tag_name": "pulumi-test-tag"}'
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[str] category_id: The unique identifier of the parent category in
@@ -156,7 +237,83 @@ class Tag(pulumi.CustomResource):
                  args: TagArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a Tag resource with the given unique name, props, and options.
+        The `Tag` resource can be used to create and manage tags, which allow
+        you to attach metadata to objects in the vSphere inventory to make these
+        objects more sortable and searchable.
+
+        For more information about tags, click [here][ext-tags-general].
+
+        [ext-tags-general]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html
+
+        ## Example Usage
+
+        This example creates a tag named `test-tag`. This tag is assigned the
+        `test-category` category, which was created by the
+        `TagCategory` resource. The resulting
+        tag can be assigned to VMs and datastores only, and can be the only value in
+        the category that can be assigned, as per the restrictions defined by the
+        category.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            cardinality="SINGLE",
+            description="Managed by Pulumi",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        tag = vsphere.Tag("tag",
+            name="test-tag",
+            category_id=category.id,
+            description="Managed by Pulumi")
+        ```
+
+        ### Using Tags in a Supported Resource
+
+        Tags can be applied to vSphere resources via the `tags` argument
+        in any supported resource.
+
+        The following example builds on the above example by creating a
+        `VirtualMachine` and applying the
+        created tag to it:
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            cardinality="SINGLE",
+            description="Managed by Pulumi",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        tag = vsphere.Tag("tag",
+            name="test-tag",
+            category_id=category.id,
+            description="Managed by Pulumi")
+        web = vsphere.VirtualMachine("web", tags=[tag.id])
+        ```
+
+        ## Import
+
+        An existing tag can be imported into this resource by supplying
+
+        both the tag's category name and the name of the tag as a JSON string to
+
+        `pulumi import`, as per the example below:
+
+        ```sh
+        $ pulumi import vsphere:index/tag:Tag tag \\
+        ```
+
+          '{"category_name": "pulumi-test-category", "tag_name": "pulumi-test-tag"}'
+
         :param str resource_name: The name of the resource.
         :param TagArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/tag_category.py

@@ -4,9 +4,14 @@
 
 import copy
 import warnings
+import sys
 import pulumi
 import pulumi.runtime
 from typing import Any, Mapping, Optional, Sequence, Union, overload
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict, TypeAlias
+else:
+    from typing_extensions import NotRequired, TypedDict, TypeAlias
 from . import _utilities
 
 __all__ = ['TagCategoryArgs', 'TagCategory']
@@ -196,7 +201,45 @@ class TagCategory(pulumi.CustomResource):
                  name: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a TagCategory resource with the given unique name, props, and options.
+        The `TagCategory` resource can be used to create and manage tag
+        categories, which determine how tags are grouped together and applied to
+        specific objects.
+
+        For more information about tags, click [here][ext-tags-general].
+
+        [ext-tags-general]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html
+
+        ## Example Usage
+
+        This example creates a tag category named `test-category`, with
+        single cardinality (meaning that only one tag in this category can be assigned
+        to an object at any given time). Tags in this category can only be assigned to
+        VMs and datastores.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            description="Managed by Pulumi",
+            cardinality="SINGLE",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        ```
+
+        ## Import
+
+        An existing tag category can be imported into this resource via
+
+        its name, using the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/tagCategory:TagCategory category terraform-test-category
+        ```
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[Sequence[pulumi.Input[str]]] associable_types: A list object types that this category is
@@ -219,7 +262,45 @@ class TagCategory(pulumi.CustomResource):
                  args: TagCategoryArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a TagCategory resource with the given unique name, props, and options.
+        The `TagCategory` resource can be used to create and manage tag
+        categories, which determine how tags are grouped together and applied to
+        specific objects.
+
+        For more information about tags, click [here][ext-tags-general].
+
+        [ext-tags-general]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vcenter-esxi-management/GUID-E8E854DD-AA97-4E0C-8419-CE84F93C4058.html
+
+        ## Example Usage
+
+        This example creates a tag category named `test-category`, with
+        single cardinality (meaning that only one tag in this category can be assigned
+        to an object at any given time). Tags in this category can only be assigned to
+        VMs and datastores.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        category = vsphere.TagCategory("category",
+            name="test-category",
+            description="Managed by Pulumi",
+            cardinality="SINGLE",
+            associable_types=[
+                "VirtualMachine",
+                "Datastore",
+            ])
+        ```
+
+        ## Import
+
+        An existing tag category can be imported into this resource via
+
+        its name, using the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/tagCategory:TagCategory category terraform-test-category
+        ```
+
         :param str resource_name: The name of the resource.
         :param TagCategoryArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/vapp_container.py

@@ -4,9 +4,14 @@
 
 import copy
 import warnings
+import sys
 import pulumi
 import pulumi.runtime
 from typing import Any, Mapping, Optional, Sequence, Union, overload
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict, TypeAlias
+else:
+    from typing_extensions import NotRequired, TypedDict, TypeAlias
 from . import _utilities
 
 __all__ = ['VappContainerArgs', 'VappContainer']
@@ -640,7 +645,85 @@ class VappContainer(pulumi.CustomResource):
                  tags: Optional[pulumi.Input[Sequence[pulumi.Input[str]]]] = None,
                  __props__=None):
         """
-        Create a VappContainer resource with the given unique name, props, and options.
+        The `VappContainer` resource can be used to create and manage
+        vApps.
+
+        For more information on vSphere vApps, see the VMware vSphere [product documentation][ref-vsphere-vapp].
+
+        [ref-vsphere-vapp]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-E6E9D2A9-D358-4996-9BC7-F8D9D9645290.html
+
+        ## Basic Example
+
+        The example below sets up a vSphere vApp container in a compute cluster which uses
+        the default settings for CPU and memory reservations, shares, and limits. The compute cluster
+        needs to already exist in vSphere.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        compute_cluster = vsphere.get_compute_cluster(name="cluster-01",
+            datacenter_id=datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-01",
+            parent_resource_pool_id=compute_cluster.resource_pool_id)
+        ```
+
+        ### Example with a Virtual Machine
+
+        The example below builds off the basic example, but includes a virtual machine
+        in the new vApp container. To accomplish this, the `resource_pool_id` of the
+        virtual machine is set to the `id` of the vApp container.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        compute_cluster = vsphere.get_compute_cluster(name="cluster-01",
+            datacenter_id=datacenter.id)
+        datastore = vsphere.get_datastore(name="datastore-01",
+            datacenter_id=datacenter.id)
+        network = vsphere.get_network(name="VM Network",
+            datacenter_id=datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-01",
+            parent_resource_pool_id=compute_cluster.resource_pool_id)
+        vm = vsphere.VirtualMachine("vm",
+            name="foo",
+            resource_pool_id=vapp_container_vsphere_vapp_container["id"],
+            datastore_id=datastore.id,
+            num_cpus=1,
+            memory=1024,
+            guest_id="ubuntu64Guest",
+            network_interfaces=[{
+                "network_id": network.id,
+            }],
+            disks=[{
+                "label": "disk0",
+                "size": 20,
+            }])
+        ```
+
+        ## Import
+
+        An existing vApp container can be imported into this resource via
+
+        the path to the vApp container, using the following command:
+
+        Example:
+
+        ```sh
+        $ pulumi import vsphere:index/vappContainer:VappContainer vapp_container /dc-01/host/cluster-01/Resources/resource-pool-01/vapp-01
+        ```
+
+        The example above would import the vApp container named `vapp-01` that is
+
+        located in the resource pool `resource-pool-01` that is part of the host cluster
+
+        `cluster-01` in the `dc-01` datacenter.
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[bool] cpu_expandable: Determines if the reservation on a vApp
@@ -694,7 +777,85 @@ class VappContainer(pulumi.CustomResource):
                  args: VappContainerArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a VappContainer resource with the given unique name, props, and options.
+        The `VappContainer` resource can be used to create and manage
+        vApps.
+
+        For more information on vSphere vApps, see the VMware vSphere [product documentation][ref-vsphere-vapp].
+
+        [ref-vsphere-vapp]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-E6E9D2A9-D358-4996-9BC7-F8D9D9645290.html
+
+        ## Basic Example
+
+        The example below sets up a vSphere vApp container in a compute cluster which uses
+        the default settings for CPU and memory reservations, shares, and limits. The compute cluster
+        needs to already exist in vSphere.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        compute_cluster = vsphere.get_compute_cluster(name="cluster-01",
+            datacenter_id=datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-01",
+            parent_resource_pool_id=compute_cluster.resource_pool_id)
+        ```
+
+        ### Example with a Virtual Machine
+
+        The example below builds off the basic example, but includes a virtual machine
+        in the new vApp container. To accomplish this, the `resource_pool_id` of the
+        virtual machine is set to the `id` of the vApp container.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        compute_cluster = vsphere.get_compute_cluster(name="cluster-01",
+            datacenter_id=datacenter.id)
+        datastore = vsphere.get_datastore(name="datastore-01",
+            datacenter_id=datacenter.id)
+        network = vsphere.get_network(name="VM Network",
+            datacenter_id=datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-01",
+            parent_resource_pool_id=compute_cluster.resource_pool_id)
+        vm = vsphere.VirtualMachine("vm",
+            name="foo",
+            resource_pool_id=vapp_container_vsphere_vapp_container["id"],
+            datastore_id=datastore.id,
+            num_cpus=1,
+            memory=1024,
+            guest_id="ubuntu64Guest",
+            network_interfaces=[{
+                "network_id": network.id,
+            }],
+            disks=[{
+                "label": "disk0",
+                "size": 20,
+            }])
+        ```
+
+        ## Import
+
+        An existing vApp container can be imported into this resource via
+
+        the path to the vApp container, using the following command:
+
+        Example:
+
+        ```sh
+        $ pulumi import vsphere:index/vappContainer:VappContainer vapp_container /dc-01/host/cluster-01/Resources/resource-pool-01/vapp-01
+        ```
+
+        The example above would import the vApp container named `vapp-01` that is
+
+        located in the resource pool `resource-pool-01` that is part of the host cluster
+
+        `cluster-01` in the `dc-01` datacenter.
+
         :param str resource_name: The name of the resource.
         :param VappContainerArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/vapp_entity.py

@@ -4,9 +4,14 @@
 
 import copy
 import warnings
+import sys
 import pulumi
 import pulumi.runtime
 from typing import Any, Mapping, Optional, Sequence, Union, overload
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict, TypeAlias
+else:
+    from typing_extensions import NotRequired, TypedDict, TypeAlias
 from . import _utilities
 
 __all__ = ['VappEntityArgs', 'VappEntity']
@@ -406,7 +411,77 @@ class VappEntity(pulumi.CustomResource):
                  wait_for_guest: Optional[pulumi.Input[bool]] = None,
                  __props__=None):
         """
-        Create a VappEntity resource with the given unique name, props, and options.
+        The `VappEntity` resource can be used to describe the behavior of an
+        entity (virtual machine or sub-vApp container) in a vApp container.
+
+        For more information on vSphere vApps, see [this
+        page][ref-vsphere-vapp].
+
+        [ref-vsphere-vapp]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-2A95EBB8-1779-40FA-B4FB-4D0845750879.html
+
+        ## Example Usage
+
+        The basic example below sets up a vApp container and a virtual machine in a
+        compute cluster and then creates a vApp entity to change the virtual machine's
+        power on behavior in the vApp container.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        config = pulumi.Config()
+        datacenter = config.get("datacenter")
+        if datacenter is None:
+            datacenter = "dc-01"
+        cluster = config.get("cluster")
+        if cluster is None:
+            cluster = "cluster-01"
+        datacenter_get_datacenter = vsphere.get_datacenter(name=datacenter)
+        compute_cluster = vsphere.get_compute_cluster(name=cluster,
+            datacenter_id=datacenter_get_datacenter.id)
+        network = vsphere.get_network(name="network1",
+            datacenter_id=datacenter_get_datacenter.id)
+        datastore = vsphere.get_datastore(name="datastore1",
+            datacenter_id=datacenter_get_datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-container-test",
+            parent_resource_pool_id=compute_cluster.id)
+        vm = vsphere.VirtualMachine("vm",
+            name="virtual-machine-test",
+            resource_pool_id=vapp_container.id,
+            datastore_id=datastore.id,
+            num_cpus=2,
+            memory=1024,
+            guest_id="ubuntu64Guest",
+            disks=[{
+                "label": "disk0",
+                "size": 1,
+            }],
+            network_interfaces=[{
+                "network_id": network.id,
+            }])
+        vapp_entity = vsphere.VappEntity("vapp_entity",
+            target_id=vm.moid,
+            container_id=vapp_container.id,
+            start_action="none")
+        ```
+
+        ## Import
+
+        An existing vApp entity can be imported into this resource via
+
+        the ID of the vApp Entity.
+
+        ```sh
+        $ pulumi import vsphere:index/vappEntity:VappEntity vapp_entity vm-123:res-456
+        ```
+
+        The above would import the vApp entity that governs the behavior of the virtual
+
+        machine with a [managed object ID][docs-about-morefs] of vm-123 in the vApp
+
+        container with the [managed object ID][docs-about-morefs] res-456.
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[str] container_id: Managed object ID of the vApp
@@ -438,7 +513,77 @@ class VappEntity(pulumi.CustomResource):
                  args: VappEntityArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a VappEntity resource with the given unique name, props, and options.
+        The `VappEntity` resource can be used to describe the behavior of an
+        entity (virtual machine or sub-vApp container) in a vApp container.
+
+        For more information on vSphere vApps, see [this
+        page][ref-vsphere-vapp].
+
+        [ref-vsphere-vapp]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-vm-administration/GUID-2A95EBB8-1779-40FA-B4FB-4D0845750879.html
+
+        ## Example Usage
+
+        The basic example below sets up a vApp container and a virtual machine in a
+        compute cluster and then creates a vApp entity to change the virtual machine's
+        power on behavior in the vApp container.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        config = pulumi.Config()
+        datacenter = config.get("datacenter")
+        if datacenter is None:
+            datacenter = "dc-01"
+        cluster = config.get("cluster")
+        if cluster is None:
+            cluster = "cluster-01"
+        datacenter_get_datacenter = vsphere.get_datacenter(name=datacenter)
+        compute_cluster = vsphere.get_compute_cluster(name=cluster,
+            datacenter_id=datacenter_get_datacenter.id)
+        network = vsphere.get_network(name="network1",
+            datacenter_id=datacenter_get_datacenter.id)
+        datastore = vsphere.get_datastore(name="datastore1",
+            datacenter_id=datacenter_get_datacenter.id)
+        vapp_container = vsphere.VappContainer("vapp_container",
+            name="vapp-container-test",
+            parent_resource_pool_id=compute_cluster.id)
+        vm = vsphere.VirtualMachine("vm",
+            name="virtual-machine-test",
+            resource_pool_id=vapp_container.id,
+            datastore_id=datastore.id,
+            num_cpus=2,
+            memory=1024,
+            guest_id="ubuntu64Guest",
+            disks=[{
+                "label": "disk0",
+                "size": 1,
+            }],
+            network_interfaces=[{
+                "network_id": network.id,
+            }])
+        vapp_entity = vsphere.VappEntity("vapp_entity",
+            target_id=vm.moid,
+            container_id=vapp_container.id,
+            start_action="none")
+        ```
+
+        ## Import
+
+        An existing vApp entity can be imported into this resource via
+
+        the ID of the vApp Entity.
+
+        ```sh
+        $ pulumi import vsphere:index/vappEntity:VappEntity vapp_entity vm-123:res-456
+        ```
+
+        The above would import the vApp entity that governs the behavior of the virtual
+
+        machine with a [managed object ID][docs-about-morefs] of vm-123 in the vApp
+
+        container with the [managed object ID][docs-about-morefs] res-456.
+
         :param str resource_name: The name of the resource.
         :param VappEntityArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.