pulumi-vsphere 4.12.0a1727221820__py3-none-any.whl → 4.12.0a1727848995__py3-none-any.whl

pulumi_vsphere/distributed_virtual_switch.py

@@ -3239,7 +3239,134 @@ class DistributedVirtualSwitch(pulumi.CustomResource):
                  vsan_share_level: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a DistributedVirtualSwitch resource with the given unique name, props, and options.
+        The `DistributedVirtualSwitch` resource can be used to manage vSphere
+        Distributed Switches (VDS).
+
+        An essential component of a distributed, scalable vSphere infrastructure, the
+        VDS provides centralized management and monitoring of the networking
+        configuration for all the hosts that are associated with the switch.
+        In addition to adding distributed port groups
+        (see the `DistributedPortGroup` resource)
+        that can be used as networks for virtual machines, a VDS can be configured to
+        perform advanced high availability, traffic shaping, network monitoring, etc.
+
+        For an overview on vSphere networking concepts, see
+        [this page][ref-vsphere-net-concepts].
+
+        For more information on the VDS, see [this page][ref-vsphere-vds].
+
+        [ref-vsphere-net-concepts]: https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.networking.doc/GUID-2B11DBB8-CB3C-4AFF-8885-EFEA0FC562F4.html
+        [ref-vsphere-vds]: https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.networking.doc/GUID-375B45C7-684C-4C51-BA3C-70E48DFABF04.html
+
+        > **NOTE:** This resource requires vCenter and is not available on
+        direct ESXi host connections.
+
+        ## Example Usage
+
+        The following example below demonstrates a "standard" example of configuring a
+        VDS in a 3-node vSphere datacenter named `dc1`, across 4 NICs with two being
+        used as active, and two being used as passive. Note that the NIC failover order
+        propagates to any port groups configured on this VDS and can be overridden.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        config = pulumi.Config()
+        hosts = config.get_object("hosts")
+        if hosts is None:
+            hosts = [
+                "esxi-01.example.com",
+                "esxi-02.example.com",
+                "esxi-03.example.com",
+            ]
+        network_interfaces = config.get_object("networkInterfaces")
+        if network_interfaces is None:
+            network_interfaces = [
+                "vmnic0",
+                "vmnic1",
+                "vmnic2",
+                "vmnic3",
+            ]
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        host = [vsphere.get_host(name=hosts[__index],
+            datacenter_id=datacenter.id) for __index in range(len(hosts))]
+        vds = vsphere.DistributedVirtualSwitch("vds",
+            name="vds-01",
+            datacenter_id=datacenter.id,
+            uplinks=[
+                "uplink1",
+                "uplink2",
+                "uplink3",
+                "uplink4",
+            ],
+            active_uplinks=[
+                "uplink1",
+                "uplink2",
+            ],
+            standby_uplinks=[
+                "uplink3",
+                "uplink4",
+            ],
+            hosts=[
+                {
+                    "host_system_id": host[0].id,
+                    "devices": [network_interfaces],
+                },
+                {
+                    "host_system_id": host[1].id,
+                    "devices": [network_interfaces],
+                },
+                {
+                    "host_system_id": host[2].id,
+                    "devices": [network_interfaces],
+                },
+            ])
+        ```
+
+        ### Uplink name and count control
+
+        The following abridged example below demonstrates how you can manage the number
+        of uplinks, and the name of the uplinks via the `uplinks` parameter.
+
+        Note that if you change the uplink naming and count after creating the VDS, you
+        may need to explicitly specify `active_uplinks` and `standby_uplinks` as these
+        values are saved to state after creation, regardless of being
+        specified in config, and will drift if not modified, causing errors.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        vds = vsphere.DistributedVirtualSwitch("vds",
+            name="vds-01",
+            datacenter_id=datacenter["id"],
+            uplinks=[
+                "uplink1",
+                "uplink2",
+            ],
+            active_uplinks=["uplink1"],
+            standby_uplinks=["uplink2"])
+        ```
+
+        > **NOTE:** The default uplink names when a VDS is created are `uplink1`
+        through to `uplink4`, however this default is not guaranteed to be stable and
+        you are encouraged to set your own.
+
+        ## Import
+
+        An existing VDS can be imported into this resource via the path
+
+        to the VDS, via the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/distributedVirtualSwitch:DistributedVirtualSwitch vds /dc-01/network/vds-01
+        ```
+
+        The above would import the VDS named `vds-01` that is located 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[Sequence[pulumi.Input[str]]] active_uplinks: List of active uplinks used for load balancing, matching the names of the uplinks assigned in the DVS.
@@ -3365,7 +3492,134 @@ class DistributedVirtualSwitch(pulumi.CustomResource):
                  args: DistributedVirtualSwitchArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a DistributedVirtualSwitch resource with the given unique name, props, and options.
+        The `DistributedVirtualSwitch` resource can be used to manage vSphere
+        Distributed Switches (VDS).
+
+        An essential component of a distributed, scalable vSphere infrastructure, the
+        VDS provides centralized management and monitoring of the networking
+        configuration for all the hosts that are associated with the switch.
+        In addition to adding distributed port groups
+        (see the `DistributedPortGroup` resource)
+        that can be used as networks for virtual machines, a VDS can be configured to
+        perform advanced high availability, traffic shaping, network monitoring, etc.
+
+        For an overview on vSphere networking concepts, see
+        [this page][ref-vsphere-net-concepts].
+
+        For more information on the VDS, see [this page][ref-vsphere-vds].
+
+        [ref-vsphere-net-concepts]: https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.networking.doc/GUID-2B11DBB8-CB3C-4AFF-8885-EFEA0FC562F4.html
+        [ref-vsphere-vds]: https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.networking.doc/GUID-375B45C7-684C-4C51-BA3C-70E48DFABF04.html
+
+        > **NOTE:** This resource requires vCenter and is not available on
+        direct ESXi host connections.
+
+        ## Example Usage
+
+        The following example below demonstrates a "standard" example of configuring a
+        VDS in a 3-node vSphere datacenter named `dc1`, across 4 NICs with two being
+        used as active, and two being used as passive. Note that the NIC failover order
+        propagates to any port groups configured on this VDS and can be overridden.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        config = pulumi.Config()
+        hosts = config.get_object("hosts")
+        if hosts is None:
+            hosts = [
+                "esxi-01.example.com",
+                "esxi-02.example.com",
+                "esxi-03.example.com",
+            ]
+        network_interfaces = config.get_object("networkInterfaces")
+        if network_interfaces is None:
+            network_interfaces = [
+                "vmnic0",
+                "vmnic1",
+                "vmnic2",
+                "vmnic3",
+            ]
+        datacenter = vsphere.get_datacenter(name="dc-01")
+        host = [vsphere.get_host(name=hosts[__index],
+            datacenter_id=datacenter.id) for __index in range(len(hosts))]
+        vds = vsphere.DistributedVirtualSwitch("vds",
+            name="vds-01",
+            datacenter_id=datacenter.id,
+            uplinks=[
+                "uplink1",
+                "uplink2",
+                "uplink3",
+                "uplink4",
+            ],
+            active_uplinks=[
+                "uplink1",
+                "uplink2",
+            ],
+            standby_uplinks=[
+                "uplink3",
+                "uplink4",
+            ],
+            hosts=[
+                {
+                    "host_system_id": host[0].id,
+                    "devices": [network_interfaces],
+                },
+                {
+                    "host_system_id": host[1].id,
+                    "devices": [network_interfaces],
+                },
+                {
+                    "host_system_id": host[2].id,
+                    "devices": [network_interfaces],
+                },
+            ])
+        ```
+
+        ### Uplink name and count control
+
+        The following abridged example below demonstrates how you can manage the number
+        of uplinks, and the name of the uplinks via the `uplinks` parameter.
+
+        Note that if you change the uplink naming and count after creating the VDS, you
+        may need to explicitly specify `active_uplinks` and `standby_uplinks` as these
+        values are saved to state after creation, regardless of being
+        specified in config, and will drift if not modified, causing errors.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        vds = vsphere.DistributedVirtualSwitch("vds",
+            name="vds-01",
+            datacenter_id=datacenter["id"],
+            uplinks=[
+                "uplink1",
+                "uplink2",
+            ],
+            active_uplinks=["uplink1"],
+            standby_uplinks=["uplink2"])
+        ```
+
+        > **NOTE:** The default uplink names when a VDS is created are `uplink1`
+        through to `uplink4`, however this default is not guaranteed to be stable and
+        you are encouraged to set your own.
+
+        ## Import
+
+        An existing VDS can be imported into this resource via the path
+
+        to the VDS, via the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/distributedVirtualSwitch:DistributedVirtualSwitch vds /dc-01/network/vds-01
+        ```
+
+        The above would import the VDS named `vds-01` that is located in the `dc-01`
+
+        datacenter.
+
         :param str resource_name: The name of the resource.
         :param DistributedVirtualSwitchArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/dpm_host_override.py

@@ -200,7 +200,35 @@ class DpmHostOverride(pulumi.CustomResource):
                  host_system_id: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a DpmHostOverride resource with the given unique name, props, and options.
+        The `DpmHostOverride` resource can be used to add a DPM override to a
+        cluster for a particular host. This allows you to control the power management
+        settings for individual hosts in the cluster while leaving any unspecified ones
+        at the default power management settings.
+
+        For more information on DPM within vSphere clusters, see [this
+        page][ref-vsphere-cluster-dpm].
+
+        [ref-vsphere-cluster-dpm]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-resource-management/GUID-5E5E349A-4644-4C9C-B434-1C0243EBDC80.html
+
+        > **NOTE:** This resource requires vCenter and is not available on direct ESXi
+        connections.
+
+        ## Import
+
+        An existing override can be imported into this resource by
+
+        supplying both the path to the cluster, and the path to the host, to `terraform
+
+        import`. If no override exists, an error will be given.  An example is below:
+
+        ```sh
+        $ pulumi import vsphere:index/dpmHostOverride:DpmHostOverride dpm_host_override \\
+        ```
+
+          '{"compute_cluster_path": "/dc1/host/cluster1", \\
+
+          "host_path": "/dc1/host/esxi1"}'
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[str] compute_cluster_id: The managed object reference
@@ -224,7 +252,35 @@ class DpmHostOverride(pulumi.CustomResource):
                  args: DpmHostOverrideArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a DpmHostOverride resource with the given unique name, props, and options.
+        The `DpmHostOverride` resource can be used to add a DPM override to a
+        cluster for a particular host. This allows you to control the power management
+        settings for individual hosts in the cluster while leaving any unspecified ones
+        at the default power management settings.
+
+        For more information on DPM within vSphere clusters, see [this
+        page][ref-vsphere-cluster-dpm].
+
+        [ref-vsphere-cluster-dpm]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-resource-management/GUID-5E5E349A-4644-4C9C-B434-1C0243EBDC80.html
+
+        > **NOTE:** This resource requires vCenter and is not available on direct ESXi
+        connections.
+
+        ## Import
+
+        An existing override can be imported into this resource by
+
+        supplying both the path to the cluster, and the path to the host, to `terraform
+
+        import`. If no override exists, an error will be given.  An example is below:
+
+        ```sh
+        $ pulumi import vsphere:index/dpmHostOverride:DpmHostOverride dpm_host_override \\
+        ```
+
+          '{"compute_cluster_path": "/dc1/host/cluster1", \\
+
+          "host_path": "/dc1/host/esxi1"}'
+
         :param str resource_name: The name of the resource.
         :param DpmHostOverrideArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/drs_vm_override.py

@@ -204,7 +204,37 @@ class DrsVmOverride(pulumi.CustomResource):
                  virtual_machine_id: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a DrsVmOverride resource with the given unique name, props, and options.
+        The `DrsVmOverride` resource can be used to add a DRS override to a
+        cluster for a specific virtual machine. With this resource, one can enable or
+        disable DRS and control the automation level for a single virtual machine
+        without affecting the rest of the cluster.
+
+        For more information on vSphere clusters and DRS, see [this
+        page][ref-vsphere-drs-clusters].
+
+        [ref-vsphere-drs-clusters]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-resource-management/GUID-8ACF3502-5314-469F-8CC9-4A9BD5925BC2.html
+
+        > **NOTE:** This resource requires vCenter and is not available on direct ESXi
+        connections.
+
+        ## Import
+
+        An existing override can be imported into this resource by
+
+        supplying both the path to the cluster, and the path to the virtual machine, to
+
+        `pulumi import`. If no override exists, an error will be given.  An example
+
+        is below:
+
+        ```sh
+        $ pulumi import vsphere:index/drsVmOverride:DrsVmOverride drs_vm_override \\
+        ```
+
+          '{"compute_cluster_path": "/dc1/host/cluster1", \\
+
+          "virtual_machine_path": "/dc1/vm/srv1"}'
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[str] compute_cluster_id: The managed object reference
@@ -229,7 +259,37 @@ class DrsVmOverride(pulumi.CustomResource):
                  args: DrsVmOverrideArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a DrsVmOverride resource with the given unique name, props, and options.
+        The `DrsVmOverride` resource can be used to add a DRS override to a
+        cluster for a specific virtual machine. With this resource, one can enable or
+        disable DRS and control the automation level for a single virtual machine
+        without affecting the rest of the cluster.
+
+        For more information on vSphere clusters and DRS, see [this
+        page][ref-vsphere-drs-clusters].
+
+        [ref-vsphere-drs-clusters]: https://docs.vmware.com/en/VMware-vSphere/8.0/vsphere-resource-management/GUID-8ACF3502-5314-469F-8CC9-4A9BD5925BC2.html
+
+        > **NOTE:** This resource requires vCenter and is not available on direct ESXi
+        connections.
+
+        ## Import
+
+        An existing override can be imported into this resource by
+
+        supplying both the path to the cluster, and the path to the virtual machine, to
+
+        `pulumi import`. If no override exists, an error will be given.  An example
+
+        is below:
+
+        ```sh
+        $ pulumi import vsphere:index/drsVmOverride:DrsVmOverride drs_vm_override \\
+        ```
+
+          '{"compute_cluster_path": "/dc1/host/cluster1", \\
+
+          "virtual_machine_path": "/dc1/vm/srv1"}'
+
         :param str resource_name: The name of the resource.
         :param DrsVmOverrideArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/folder.py

@@ -285,7 +285,74 @@ class Folder(pulumi.CustomResource):
                  type: Optional[pulumi.Input[str]] = None,
                  __props__=None):
         """
-        Create a Folder resource with the given unique name, props, and options.
+        The `Folder` resource can be used to manage vSphere inventory folders.
+        The resource supports creating folders of the 5 major types - datacenter
+        folders, host and cluster folders, virtual machine folders, storage folders,
+        and network folders.
+
+        Paths are always relative to the specific type of folder you are creating.
+        A subfolder is discovered by parsing the relative path specified in `path`, so
+        `foo/bar` will create a folder named `bar` in the parent folder `foo`, as long
+        as that folder exists.
+
+        ## Example Usage
+
+        The basic example below creates a virtual machine folder named
+        `test-folder` in the default datacenter's VM hierarchy.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter()
+        folder = vsphere.Folder("folder",
+            path="test-folder",
+            type="vm",
+            datacenter_id=datacenter.id)
+        ```
+
+        ### Example with subfolders
+
+        The below example builds off of the above by first creating a folder named
+        `test-parent`, and then locating `test-folder` in that
+        folder. To ensure the parent is created first, we create an interpolation
+        dependency off the parent's `path` attribute.
+
+        Note that if you change parents (for example, went from the above basic
+        configuration to this one), your folder will be moved to be under the correct
+        parent.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter()
+        parent = vsphere.Folder("parent",
+            path="test-parent",
+            type="vm",
+            datacenter_id=datacenter.id)
+        folder = vsphere.Folder("folder",
+            path=parent.path.apply(lambda path: f"{path}/test-folder"),
+            type="vm",
+            datacenter_id=datacenter.id)
+        ```
+
+        ## Import
+
+        An existing folder can be imported into this resource via
+
+        its full path, via the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/folder:Folder folder /default-dc/vm/terraform-test-folder
+        ```
+
+        The above command would import the folder from our examples above, the VM
+
+        folder named `terraform-test-folder` located in the datacenter named
+
+        `default-dc`.
+
         :param str resource_name: The name of the resource.
         :param pulumi.ResourceOptions opts: Options for the resource.
         :param pulumi.Input[Mapping[str, pulumi.Input[str]]] custom_attributes: Map of custom attribute ids to attribute
@@ -323,7 +390,74 @@ class Folder(pulumi.CustomResource):
                  args: FolderArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        Create a Folder resource with the given unique name, props, and options.
+        The `Folder` resource can be used to manage vSphere inventory folders.
+        The resource supports creating folders of the 5 major types - datacenter
+        folders, host and cluster folders, virtual machine folders, storage folders,
+        and network folders.
+
+        Paths are always relative to the specific type of folder you are creating.
+        A subfolder is discovered by parsing the relative path specified in `path`, so
+        `foo/bar` will create a folder named `bar` in the parent folder `foo`, as long
+        as that folder exists.
+
+        ## Example Usage
+
+        The basic example below creates a virtual machine folder named
+        `test-folder` in the default datacenter's VM hierarchy.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter()
+        folder = vsphere.Folder("folder",
+            path="test-folder",
+            type="vm",
+            datacenter_id=datacenter.id)
+        ```
+
+        ### Example with subfolders
+
+        The below example builds off of the above by first creating a folder named
+        `test-parent`, and then locating `test-folder` in that
+        folder. To ensure the parent is created first, we create an interpolation
+        dependency off the parent's `path` attribute.
+
+        Note that if you change parents (for example, went from the above basic
+        configuration to this one), your folder will be moved to be under the correct
+        parent.
+
+        ```python
+        import pulumi
+        import pulumi_vsphere as vsphere
+
+        datacenter = vsphere.get_datacenter()
+        parent = vsphere.Folder("parent",
+            path="test-parent",
+            type="vm",
+            datacenter_id=datacenter.id)
+        folder = vsphere.Folder("folder",
+            path=parent.path.apply(lambda path: f"{path}/test-folder"),
+            type="vm",
+            datacenter_id=datacenter.id)
+        ```
+
+        ## Import
+
+        An existing folder can be imported into this resource via
+
+        its full path, via the following command:
+
+        ```sh
+        $ pulumi import vsphere:index/folder:Folder folder /default-dc/vm/terraform-test-folder
+        ```
+
+        The above command would import the folder from our examples above, the VM
+
+        folder named `terraform-test-folder` located in the datacenter named
+
+        `default-dc`.
+
         :param str resource_name: The name of the resource.
         :param FolderArgs args: The arguments to use to populate this resource's properties.
         :param pulumi.ResourceOptions opts: Options for the resource.

pulumi_vsphere/get_compute_cluster_host_group.py

@@ -96,7 +96,7 @@ def get_compute_cluster_host_group(compute_cluster_id: Optional[str] = None,
         compute_cluster_id=cluster.id)
     host_rule = vsphere.ComputeClusterVmHostRule("host_rule",
         compute_cluster_id=cluster.id,
-        name="terraform-host-rule1",
+        name="pulumi-host-rule1",
         vm_group_name="vmgroup-01",
         affinity_host_group_name=host_group.name)
     ```
@@ -144,7 +144,7 @@ def get_compute_cluster_host_group_output(compute_cluster_id: Optional[pulumi.In
         compute_cluster_id=cluster.id)
     host_rule = vsphere.ComputeClusterVmHostRule("host_rule",
         compute_cluster_id=cluster.id,
-        name="terraform-host-rule1",
+        name="pulumi-host-rule1",
         vm_group_name="vmgroup-01",
         affinity_host_group_name=host_group.name)
     ```