pulumi-kafka 3.8.0a1723819820__py3-none-any.whl → 3.13.0a1763619276__py3-none-any.whl

pulumi_kafka/topic.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__ = ['TopicArgs', 'Topic']
@@ -14,16 +19,16 @@ __all__ = ['TopicArgs', 'Topic']
 @pulumi.input_type
 class TopicArgs:
     def __init__(__self__, *,
-                 partitions: pulumi.Input[int],
-                 replication_factor: pulumi.Input[int],
-                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None,
-                 name: Optional[pulumi.Input[str]] = None):
+                 partitions: pulumi.Input[_builtins.int],
+                 replication_factor: pulumi.Input[_builtins.int],
+                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None):
         """
         The set of arguments for constructing a Topic resource.
-        :param pulumi.Input[int] partitions: The number of partitions the topic should have.
-        :param pulumi.Input[int] replication_factor: The number of replicas the topic should have.
-        :param pulumi.Input[Mapping[str, pulumi.Input[str]]] config: A map of string k/v attributes.
-        :param pulumi.Input[str] name: The name of the topic.
+        :param pulumi.Input[_builtins.int] partitions: Number of partitions.
+        :param pulumi.Input[_builtins.int] replication_factor: Number of replicas.
+        :param pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]] config: A map of string k/v attributes.
+        :param pulumi.Input[_builtins.str] name: The name of the topic.
         """
         pulumi.set(__self__, "partitions", partitions)
         pulumi.set(__self__, "replication_factor", replication_factor)
@@ -32,68 +37,68 @@ class TopicArgs:
         if name is not None:
             pulumi.set(__self__, "name", name)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def partitions(self) -> pulumi.Input[int]:
+    def partitions(self) -> pulumi.Input[_builtins.int]:
         """
-        The number of partitions the topic should have.
+        Number of partitions.
         """
         return pulumi.get(self, "partitions")
 
     @partitions.setter
-    def partitions(self, value: pulumi.Input[int]):
+    def partitions(self, value: pulumi.Input[_builtins.int]):
         pulumi.set(self, "partitions", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="replicationFactor")
-    def replication_factor(self) -> pulumi.Input[int]:
+    def replication_factor(self) -> pulumi.Input[_builtins.int]:
         """
-        The number of replicas the topic should have.
+        Number of replicas.
         """
         return pulumi.get(self, "replication_factor")
 
     @replication_factor.setter
-    def replication_factor(self, value: pulumi.Input[int]):
+    def replication_factor(self, value: pulumi.Input[_builtins.int]):
         pulumi.set(self, "replication_factor", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def config(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]:
+    def config(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]]:
         """
         A map of string k/v attributes.
         """
         return pulumi.get(self, "config")
 
     @config.setter
-    def config(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]):
+    def config(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]]):
         pulumi.set(self, "config", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> Optional[pulumi.Input[str]]:
+    def name(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         The name of the topic.
         """
         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 _TopicState:
     def __init__(__self__, *,
-                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None,
-                 name: Optional[pulumi.Input[str]] = None,
-                 partitions: Optional[pulumi.Input[int]] = None,
-                 replication_factor: Optional[pulumi.Input[int]] = None):
+                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None,
+                 partitions: Optional[pulumi.Input[_builtins.int]] = None,
+                 replication_factor: Optional[pulumi.Input[_builtins.int]] = None):
         """
         Input properties used for looking up and filtering Topic resources.
-        :param pulumi.Input[Mapping[str, pulumi.Input[str]]] config: A map of string k/v attributes.
-        :param pulumi.Input[str] name: The name of the topic.
-        :param pulumi.Input[int] partitions: The number of partitions the topic should have.
-        :param pulumi.Input[int] replication_factor: The number of replicas the topic should have.
+        :param pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]] config: A map of string k/v attributes.
+        :param pulumi.Input[_builtins.str] name: The name of the topic.
+        :param pulumi.Input[_builtins.int] partitions: Number of partitions.
+        :param pulumi.Input[_builtins.int] replication_factor: Number of replicas.
         """
         if config is not None:
             pulumi.set(__self__, "config", config)
@@ -104,98 +109,185 @@ class _TopicState:
         if replication_factor is not None:
             pulumi.set(__self__, "replication_factor", replication_factor)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def config(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]:
+    def config(self) -> Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]]:
         """
         A map of string k/v attributes.
         """
         return pulumi.get(self, "config")
 
     @config.setter
-    def config(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]]):
+    def config(self, value: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]]):
         pulumi.set(self, "config", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> Optional[pulumi.Input[str]]:
+    def name(self) -> Optional[pulumi.Input[_builtins.str]]:
         """
         The name of the topic.
         """
         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)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def partitions(self) -> Optional[pulumi.Input[int]]:
+    def partitions(self) -> Optional[pulumi.Input[_builtins.int]]:
         """
-        The number of partitions the topic should have.
+        Number of partitions.
         """
         return pulumi.get(self, "partitions")
 
     @partitions.setter
-    def partitions(self, value: Optional[pulumi.Input[int]]):
+    def partitions(self, value: Optional[pulumi.Input[_builtins.int]]):
         pulumi.set(self, "partitions", value)
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="replicationFactor")
-    def replication_factor(self) -> Optional[pulumi.Input[int]]:
+    def replication_factor(self) -> Optional[pulumi.Input[_builtins.int]]:
         """
-        The number of replicas the topic should have.
+        Number of replicas.
         """
         return pulumi.get(self, "replication_factor")
 
     @replication_factor.setter
-    def replication_factor(self, value: Optional[pulumi.Input[int]]):
+    def replication_factor(self, value: Optional[pulumi.Input[_builtins.int]]):
         pulumi.set(self, "replication_factor", value)
 
 
+@pulumi.type_token("kafka:index/topic:Topic")
 class Topic(pulumi.CustomResource):
     @overload
     def __init__(__self__,
                  resource_name: str,
                  opts: Optional[pulumi.ResourceOptions] = None,
-                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None,
-                 name: Optional[pulumi.Input[str]] = None,
-                 partitions: Optional[pulumi.Input[int]] = None,
-                 replication_factor: Optional[pulumi.Input[int]] = None,
+                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None,
+                 partitions: Optional[pulumi.Input[_builtins.int]] = None,
+                 replication_factor: Optional[pulumi.Input[_builtins.int]] = None,
                  __props__=None):
         """
-        A resource for managing Kafka topics. Increases partition count without destroying the topic.
+        The `Topic` resource manages Apache Kafka topics, including their partition count, replication factor, and various configuration parameters. This resource supports non-destructive partition count increases.
 
         ## Example Usage
 
+        ### Basic Topic
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        example = kafka.Topic("example",
+            name="example-topic",
+            replication_factor=3,
+            partitions=10)
+        ```
+
+        ### Topic with Common Configurations
+
         ```python
         import pulumi
         import pulumi_kafka as kafka
 
         logs = kafka.Topic("logs",
-            name="systemd_logs",
-            replication_factor=2,
+            name="application-logs",
+            replication_factor=3,
+            partitions=50,
+            config={
+                "retention.ms": "604800000",
+                "segment.ms": "86400000",
+                "cleanup.policy": "delete",
+                "compression.type": "gzip",
+            })
+        ```
+
+        ### Compacted Topic for Event Sourcing
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        events = kafka.Topic("events",
+            name="user-events",
+            replication_factor=3,
             partitions=100,
             config={
-                "segment.ms": "20000",
                 "cleanup.policy": "compact",
+                "retention.ms": "-1",
+                "min.compaction.lag.ms": "3600000",
+                "delete.retention.ms": "86400000",
+                "compression.type": "lz4",
+                "segment.bytes": "1073741824",
             })
         ```
 
+        ### High-Throughput Topic
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        metrics = kafka.Topic("metrics",
+            name="system-metrics",
+            replication_factor=2,
+            partitions=200,
+            config={
+                "retention.ms": "86400000",
+                "segment.ms": "3600000",
+                "compression.type": "lz4",
+                "max.message.bytes": "1048576",
+                "min.insync.replicas": "2",
+                "unclean.leader.election.enable": "false",
+            })
+        ```
+
+        ## Configuration Parameters
+
+        The `config` map supports all Kafka topic-level configurations. Common configurations include:
+
+        ### Retention Settings
+        - `retention.ms` - How long to retain messages (in milliseconds). Default: 604800000 (7 days)
+        - `retention.bytes` - Maximum size of the log before deleting old segments. Default: -1 (no limit)
+        - `segment.ms` - Time after which a log segment should be rotated. Default: 604800000 (7 days)
+        - `segment.bytes` - Maximum size of a single log segment file. Default: 1073741824 (1GB)
+
+        ### Cleanup and Compaction
+        - `cleanup.policy` - Either "delete" or "compact" or both "compact,delete". Default: "delete"
+        - `min.compaction.lag.ms` - Minimum time a message will remain uncompacted. Default: 0
+        - `delete.retention.ms` - How long to retain delete tombstone markers for compacted topics. Default: 86400000 (1 day)
+
+        ### Compression
+        - `compression.type` - Compression codec: "uncompressed", "zstd", "lz4", "snappy", "gzip", "producer". Default: "producer"
+
+        ### Replication and Durability
+        - `min.insync.replicas` - Minimum number of replicas that must acknowledge a write. Default: 1
+        - `unclean.leader.election.enable` - Whether to allow replicas not in ISR to be elected leader. Default: false
+
+        ### Message Size
+        - `max.message.bytes` - Maximum size of a message. Default: 1048588 (~1MB)
+        - `message.timestamp.type` - Whether to use CreateTime or LogAppendTime. Default: "CreateTime"
+
+        For a complete list of configurations, refer to the [Kafka documentation](https://kafka.apache.org/documentation/#topicconfigs).
+
+        > **Note:** Increasing the partition count is supported without recreating the topic. However, decreasing partitions requires topic recreation.
+
         ## Import
 
-        Topics can be imported using their ARN, e.g.
+        Existing Kafka topics can be imported using the topic name:
 
         ```sh
-        $ pulumi import kafka:index/topic:Topic logs systemd_logs
+        $ pulumi import kafka:index/topic:Topic example example-topic
         ```
 
         :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]]] config: A map of string k/v attributes.
-        :param pulumi.Input[str] name: The name of the topic.
-        :param pulumi.Input[int] partitions: The number of partitions the topic should have.
-        :param pulumi.Input[int] replication_factor: The number of replicas the topic should have.
+        :param pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]] config: A map of string k/v attributes.
+        :param pulumi.Input[_builtins.str] name: The name of the topic.
+        :param pulumi.Input[_builtins.int] partitions: Number of partitions.
+        :param pulumi.Input[_builtins.int] replication_factor: Number of replicas.
         """
         ...
     @overload
@@ -204,30 +296,116 @@ class Topic(pulumi.CustomResource):
                  args: TopicArgs,
                  opts: Optional[pulumi.ResourceOptions] = None):
         """
-        A resource for managing Kafka topics. Increases partition count without destroying the topic.
+        The `Topic` resource manages Apache Kafka topics, including their partition count, replication factor, and various configuration parameters. This resource supports non-destructive partition count increases.
 
         ## Example Usage
 
+        ### Basic Topic
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        example = kafka.Topic("example",
+            name="example-topic",
+            replication_factor=3,
+            partitions=10)
+        ```
+
+        ### Topic with Common Configurations
+
         ```python
         import pulumi
         import pulumi_kafka as kafka
 
         logs = kafka.Topic("logs",
-            name="systemd_logs",
-            replication_factor=2,
+            name="application-logs",
+            replication_factor=3,
+            partitions=50,
+            config={
+                "retention.ms": "604800000",
+                "segment.ms": "86400000",
+                "cleanup.policy": "delete",
+                "compression.type": "gzip",
+            })
+        ```
+
+        ### Compacted Topic for Event Sourcing
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        events = kafka.Topic("events",
+            name="user-events",
+            replication_factor=3,
             partitions=100,
             config={
-                "segment.ms": "20000",
                 "cleanup.policy": "compact",
+                "retention.ms": "-1",
+                "min.compaction.lag.ms": "3600000",
+                "delete.retention.ms": "86400000",
+                "compression.type": "lz4",
+                "segment.bytes": "1073741824",
             })
         ```
 
+        ### High-Throughput Topic
+
+        ```python
+        import pulumi
+        import pulumi_kafka as kafka
+
+        metrics = kafka.Topic("metrics",
+            name="system-metrics",
+            replication_factor=2,
+            partitions=200,
+            config={
+                "retention.ms": "86400000",
+                "segment.ms": "3600000",
+                "compression.type": "lz4",
+                "max.message.bytes": "1048576",
+                "min.insync.replicas": "2",
+                "unclean.leader.election.enable": "false",
+            })
+        ```
+
+        ## Configuration Parameters
+
+        The `config` map supports all Kafka topic-level configurations. Common configurations include:
+
+        ### Retention Settings
+        - `retention.ms` - How long to retain messages (in milliseconds). Default: 604800000 (7 days)
+        - `retention.bytes` - Maximum size of the log before deleting old segments. Default: -1 (no limit)
+        - `segment.ms` - Time after which a log segment should be rotated. Default: 604800000 (7 days)
+        - `segment.bytes` - Maximum size of a single log segment file. Default: 1073741824 (1GB)
+
+        ### Cleanup and Compaction
+        - `cleanup.policy` - Either "delete" or "compact" or both "compact,delete". Default: "delete"
+        - `min.compaction.lag.ms` - Minimum time a message will remain uncompacted. Default: 0
+        - `delete.retention.ms` - How long to retain delete tombstone markers for compacted topics. Default: 86400000 (1 day)
+
+        ### Compression
+        - `compression.type` - Compression codec: "uncompressed", "zstd", "lz4", "snappy", "gzip", "producer". Default: "producer"
+
+        ### Replication and Durability
+        - `min.insync.replicas` - Minimum number of replicas that must acknowledge a write. Default: 1
+        - `unclean.leader.election.enable` - Whether to allow replicas not in ISR to be elected leader. Default: false
+
+        ### Message Size
+        - `max.message.bytes` - Maximum size of a message. Default: 1048588 (~1MB)
+        - `message.timestamp.type` - Whether to use CreateTime or LogAppendTime. Default: "CreateTime"
+
+        For a complete list of configurations, refer to the [Kafka documentation](https://kafka.apache.org/documentation/#topicconfigs).
+
+        > **Note:** Increasing the partition count is supported without recreating the topic. However, decreasing partitions requires topic recreation.
+
         ## Import
 
-        Topics can be imported using their ARN, e.g.
+        Existing Kafka topics can be imported using the topic name:
 
         ```sh
-        $ pulumi import kafka:index/topic:Topic logs systemd_logs
+        $ pulumi import kafka:index/topic:Topic example example-topic
         ```
 
         :param str resource_name: The name of the resource.
@@ -245,10 +423,10 @@ class Topic(pulumi.CustomResource):
     def _internal_init(__self__,
                  resource_name: str,
                  opts: Optional[pulumi.ResourceOptions] = None,
-                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None,
-                 name: Optional[pulumi.Input[str]] = None,
-                 partitions: Optional[pulumi.Input[int]] = None,
-                 replication_factor: Optional[pulumi.Input[int]] = None,
+                 config: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]] = None,
+                 name: Optional[pulumi.Input[_builtins.str]] = None,
+                 partitions: Optional[pulumi.Input[_builtins.int]] = None,
+                 replication_factor: Optional[pulumi.Input[_builtins.int]] = None,
                  __props__=None):
         opts = pulumi.ResourceOptions.merge(_utilities.get_resource_opts_defaults(), opts)
         if not isinstance(opts, pulumi.ResourceOptions):
@@ -276,10 +454,10 @@ class Topic(pulumi.CustomResource):
     def get(resource_name: str,
             id: pulumi.Input[str],
             opts: Optional[pulumi.ResourceOptions] = None,
-            config: Optional[pulumi.Input[Mapping[str, pulumi.Input[str]]]] = None,
-            name: Optional[pulumi.Input[str]] = None,
-            partitions: Optional[pulumi.Input[int]] = None,
-            replication_factor: Optional[pulumi.Input[int]] = None) -> 'Topic':
+            config: Optional[pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]]] = None,
+            name: Optional[pulumi.Input[_builtins.str]] = None,
+            partitions: Optional[pulumi.Input[_builtins.int]] = None,
+            replication_factor: Optional[pulumi.Input[_builtins.int]] = None) -> 'Topic':
         """
         Get an existing Topic resource's state with the given name, id, and optional extra
         properties used to qualify the lookup.
@@ -287,10 +465,10 @@ class Topic(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[Mapping[str, pulumi.Input[str]]] config: A map of string k/v attributes.
-        :param pulumi.Input[str] name: The name of the topic.
-        :param pulumi.Input[int] partitions: The number of partitions the topic should have.
-        :param pulumi.Input[int] replication_factor: The number of replicas the topic should have.
+        :param pulumi.Input[Mapping[str, pulumi.Input[_builtins.str]]] config: A map of string k/v attributes.
+        :param pulumi.Input[_builtins.str] name: The name of the topic.
+        :param pulumi.Input[_builtins.int] partitions: Number of partitions.
+        :param pulumi.Input[_builtins.int] replication_factor: Number of replicas.
         """
         opts = pulumi.ResourceOptions.merge(opts, pulumi.ResourceOptions(id=id))
 
@@ -302,35 +480,35 @@ class Topic(pulumi.CustomResource):
         __props__.__dict__["replication_factor"] = replication_factor
         return Topic(resource_name, opts=opts, __props__=__props__)
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def config(self) -> pulumi.Output[Optional[Mapping[str, str]]]:
+    def config(self) -> pulumi.Output[Optional[Mapping[str, _builtins.str]]]:
         """
         A map of string k/v attributes.
         """
         return pulumi.get(self, "config")
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def name(self) -> pulumi.Output[str]:
+    def name(self) -> pulumi.Output[_builtins.str]:
         """
         The name of the topic.
         """
         return pulumi.get(self, "name")
 
-    @property
+    @_builtins.property
     @pulumi.getter
-    def partitions(self) -> pulumi.Output[int]:
+    def partitions(self) -> pulumi.Output[_builtins.int]:
         """
-        The number of partitions the topic should have.
+        Number of partitions.
         """
         return pulumi.get(self, "partitions")
 
-    @property
+    @_builtins.property
     @pulumi.getter(name="replicationFactor")
-    def replication_factor(self) -> pulumi.Output[int]:
+    def replication_factor(self) -> pulumi.Output[_builtins.int]:
         """
-        The number of replicas the topic should have.
+        Number of replicas.
         """
         return pulumi.get(self, "replication_factor")