pulumi-vsphere 4.10.0a1709017641__py3-none-any.whl → 4.17.0a1763710194__py3-none-any.whl

pulumi_vsphere/tag.py

@@ -1,12 +1,17 @@
 # coding=utf-8
-# *** WARNING: this file was generated by the Pulumi Terraform Bridge (tfgen) Tool. ***
+# *** WARNING: this file was generated by pulumi-language-python. ***
 # *** Do not edit by hand unless you're certain you know what you are doing! ***
 
-import copy
+import builtins as _builtins
 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']
@@ -14,15 +19,15 @@ __all__ = ['TagArgs', 'Tag']
 @pulumi.input_type
 class TagArgs:
     def __init__(__self__, *,
-                 category_id: pulumi.Input[str],
-                 description: Optional[pulumi.Input[str]] = None,
-                 name: Optional[pulumi.Input[str]] = None):
+                 category_id: pulumi.Input[_builtins.str],
+                 description: Optional[pulumi.Input[_builtins.str]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None):
         """
         The set of arguments for constructing a Tag resource.
-        :param pulumi.Input[str] category_id: The unique identifier of the parent category in
+        :param pulumi.Input[_builtins.str] category_id: The unique identifier of the parent category in
                which this tag will be created. Forces a new resource if changed.
-        :param pulumi.Input[str] description: A description for the tag.
-        :param pulumi.Input[str] name: The display name of the tag. The name must be unique
+        :param pulumi.Input[_builtins.str] description: A description for the tag.
+        :param pulumi.Input[_builtins.str] name: The display name of the tag. The name must be unique
                within its category.
         """
         pulumi.set(__self__, "category_id", category_id)
@@ -31,9 +36,9 @@ class TagArgs:
         if name is not None:
             pulumi.set(__self__, "name", name)
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="categoryId")
-    def category_id(self) -> pulumi.Input[str]:
+    def category_id(self) -> pulumi.Input[_builtins.str]:
         """
         The unique identifier of the parent category in
         which this tag will be created. Forces a new resource if changed.
@@ -41,24 +46,24 @@ class TagArgs:
         return pulumi.get(self, "category_id")
 
     @category_id.setter
-    def category_id(self, value: pulumi.Input[str]):
+    def category_id(self, value: pulumi.Input[_builtins.str]):
         pulumi.set(self, "category_id", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def description(self) -> Optional[pulumi.Input[str]]:
+    def description(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         A description for the tag.
         """
         return pulumi.get(self, "description")
 
     @description.setter
-    def description(self, value: Optional[pulumi.Input[str]]):
+    def description(self, value: Optional[pulumi.Input[_builtins.str]]):
         pulumi.set(self, "description", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> Optional[pulumi.Input[str]]:
+    def name(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         The display name of the tag. The name must be unique
         within its category.
@@ -66,22 +71,22 @@ class TagArgs:
         return pulumi.get(self, "name")
 
     @name.setter
-    def name(self, value: Optional[pulumi.Input[str]]):
+    def name(self, value: Optional[pulumi.Input[_builtins.str]]):
         pulumi.set(self, "name", value)
 
 
 @pulumi.input_type
 class _TagState:
     def __init__(__self__, *,
-                 category_id: Optional[pulumi.Input[str]] = None,
-                 description: Optional[pulumi.Input[str]] = None,
-                 name: Optional[pulumi.Input[str]] = None):
+                 category_id: Optional[pulumi.Input[_builtins.str]] = None,
+                 description: Optional[pulumi.Input[_builtins.str]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None):
         """
         Input properties used for looking up and filtering Tag resources.
-        :param pulumi.Input[str] category_id: The unique identifier of the parent category in
+        :param pulumi.Input[_builtins.str] category_id: The unique identifier of the parent category in
                which this tag will be created. Forces a new resource if changed.
-        :param pulumi.Input[str] description: A description for the tag.
-        :param pulumi.Input[str] name: The display name of the tag. The name must be unique
+        :param pulumi.Input[_builtins.str] description: A description for the tag.
+        :param pulumi.Input[_builtins.str] name: The display name of the tag. The name must be unique
                within its category.
         """
         if category_id is not None:
@@ -91,9 +96,9 @@ class _TagState:
         if name is not None:
             pulumi.set(__self__, "name", name)
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="categoryId")
-    def category_id(self) -> Optional[pulumi.Input[str]]:
+    def category_id(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         The unique identifier of the parent category in
         which this tag will be created. Forces a new resource if changed.
@@ -101,24 +106,24 @@ class _TagState:
         return pulumi.get(self, "category_id")
 
     @category_id.setter
-    def category_id(self, value: Optional[pulumi.Input[str]]):
+    def category_id(self, value: Optional[pulumi.Input[_builtins.str]]):
         pulumi.set(self, "category_id", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def description(self) -> Optional[pulumi.Input[str]]:
+    def description(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         A description for the tag.
         """
         return pulumi.get(self, "description")
 
     @description.setter
-    def description(self, value: Optional[pulumi.Input[str]]):
+    def description(self, value: Optional[pulumi.Input[_builtins.str]]):
         pulumi.set(self, "description", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> Optional[pulumi.Input[str]]:
+    def name(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         The display name of the tag. The name must be unique
         within its category.
@@ -126,27 +131,106 @@ class _TagState:
         return pulumi.get(self, "name")
 
     @name.setter
-    def name(self, value: Optional[pulumi.Input[str]]):
+    def name(self, value: Optional[pulumi.Input[_builtins.str]]):
         pulumi.set(self, "name", value)
 
 
+@pulumi.type_token("vsphere:index/tag:Tag")
 class Tag(pulumi.CustomResource):
     @overload
     def __init__(__self__,
                  resource_name: str,
                  opts: Optional[pulumi.ResourceOptions] = None,
-                 category_id: Optional[pulumi.Input[str]] = None,
-                 description: Optional[pulumi.Input[str]] = None,
-                 name: Optional[pulumi.Input[str]] = None,
+                 category_id: Optional[pulumi.Input[_builtins.str]] = None,
+                 description: Optional[pulumi.Input[_builtins.str]] = None,
+                 name: Optional[pulumi.Input[_builtins.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://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-tags-and-attributes.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:
+
+        [docs-import]: https://developer.hashicorp.com/terraform/cli/import
+
+        ```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
+        :param pulumi.Input[_builtins.str] category_id: The unique identifier of the parent category in
                which this tag will be created. Forces a new resource if changed.
-        :param pulumi.Input[str] description: A description for the tag.
-        :param pulumi.Input[str] name: The display name of the tag. The name must be unique
+        :param pulumi.Input[_builtins.str] description: A description for the tag.
+        :param pulumi.Input[_builtins.str] name: The display name of the tag. The name must be unique
                within its category.
         """
         ...
@@ -156,7 +240,85 @@ 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://techdocs.broadcom.com/us/en/vmware-cis/vsphere/vsphere/8-0/vsphere-tags-and-attributes.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:
+
+        [docs-import]: https://developer.hashicorp.com/terraform/cli/import
+
+        ```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.
@@ -172,9 +334,9 @@ class Tag(pulumi.CustomResource):
     def _internal_init(__self__,
                  resource_name: str,
                  opts: Optional[pulumi.ResourceOptions] = None,
-                 category_id: Optional[pulumi.Input[str]] = None,
-                 description: Optional[pulumi.Input[str]] = None,
-                 name: Optional[pulumi.Input[str]] = None,
+                 category_id: Optional[pulumi.Input[_builtins.str]] = None,
+                 description: Optional[pulumi.Input[_builtins.str]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None,
                  __props__=None):
         opts = pulumi.ResourceOptions.merge(_utilities.get_resource_opts_defaults(), opts)
         if not isinstance(opts, pulumi.ResourceOptions):
@@ -199,9 +361,9 @@ class Tag(pulumi.CustomResource):
     def get(resource_name: str,
             id: pulumi.Input[str],
             opts: Optional[pulumi.ResourceOptions] = None,
-            category_id: Optional[pulumi.Input[str]] = None,
-            description: Optional[pulumi.Input[str]] = None,
-            name: Optional[pulumi.Input[str]] = None) -> 'Tag':
+            category_id: Optional[pulumi.Input[_builtins.str]] = None,
+            description: Optional[pulumi.Input[_builtins.str]] = None,
+            name: Optional[pulumi.Input[_builtins.str]] = None) -> 'Tag':
         """
         Get an existing Tag resource's state with the given name, id, and optional extra
         properties used to qualify the lookup.
@@ -209,10 +371,10 @@ class Tag(pulumi.CustomResource):
         :param str resource_name: The unique name of the resulting resource.
         :param pulumi.Input[str] id: The unique provider ID of the resource to lookup.
         :param pulumi.ResourceOptions opts: Options for the resource.
-        :param pulumi.Input[str] category_id: The unique identifier of the parent category in
+        :param pulumi.Input[_builtins.str] category_id: The unique identifier of the parent category in
                which this tag will be created. Forces a new resource if changed.
-        :param pulumi.Input[str] description: A description for the tag.
-        :param pulumi.Input[str] name: The display name of the tag. The name must be unique
+        :param pulumi.Input[_builtins.str] description: A description for the tag.
+        :param pulumi.Input[_builtins.str] name: The display name of the tag. The name must be unique
                within its category.
         """
         opts = pulumi.ResourceOptions.merge(opts, pulumi.ResourceOptions(id=id))
@@ -224,26 +386,26 @@ class Tag(pulumi.CustomResource):
         __props__.__dict__["name"] = name
         return Tag(resource_name, opts=opts, __props__=__props__)
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="categoryId")
-    def category_id(self) -> pulumi.Output[str]:
+    def category_id(self) -> pulumi.Output[_builtins.str]:
         """
         The unique identifier of the parent category in
         which this tag will be created. Forces a new resource if changed.
         """
         return pulumi.get(self, "category_id")
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def description(self) -> pulumi.Output[Optional[str]]:
+    def description(self) -> pulumi.Output[Optional[_builtins.str]]:
         """
         A description for the tag.
         """
         return pulumi.get(self, "description")
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> pulumi.Output[str]:
+    def name(self) -> pulumi.Output[_builtins.str]:
         """
         The display name of the tag. The name must be unique
         within its category.