docs: generate docs for datasource filter feature

ZStack-Robot · ZStack-Robot · commit 996ae9d3d5e9 · 2024-12-26T11:57:24.000+08:00
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,3 +1,5 @@
+# Copyright (c) ZStack.io, Inc.
+
 stages:
   - build
 
diff --git a/docs/data-sources/backupstorages.md b/docs/data-sources/backupstorages.md
@@ -17,6 +17,10 @@ List all backup storages, or query backup storages by exact name match, or query
 data "zstack_backupstorages" "example" {
   #   name  = "backupstorage name"
   #   name_pattern = "image%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    Status = "Connected"
+    State  = "Enabled"
+  }
 }
 
 output "zstack_imagestorages" {
@@ -29,6 +33,7 @@ output "zstack_imagestorages" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter image Storages. For example, to filter by status, use `Status = "Connected"`.
 - `name` (String) Exact name for searching backup storage.
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/clusters.md b/docs/data-sources/clusters.md
@@ -17,6 +17,11 @@ Fetches a list of clusters and their associated attributes.
 data "zstack_clusters" "example" {
   #name = "cluster1"
   #name_pattern = "clu%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State          = "Enabled"
+    HypervisorType = "KVM"
+    Architecture   = "x86_64"
+  }
 }
 
 output "zstack_clusters" {
@@ -29,6 +34,7 @@ output "zstack_clusters" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter Clusters. For example, to filter by CPU Architecture, use `Architecture = "x86_64"`.
 - `name` (String) Exact name for searching Cluster
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/disk_offers.md b/docs/data-sources/disk_offers.md
@@ -17,6 +17,9 @@ Fetches a list of disk offers and their associated attributes from the ZStack en
 data "zstack_disk_offers" "example" {
   name = "smallDiskOffering"
   # name_pattern = "sm%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State = "Enabled"
+  }
 }
 
 output "zstack_disk_offers" {
@@ -29,6 +32,7 @@ output "zstack_disk_offers" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter disk offering. For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for searching  disk offer
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/hosts.md b/docs/data-sources/hosts.md
@@ -17,10 +17,14 @@ Fetches a list of hosts and their associated attributes from the ZStack environm
 data "zstack_images" "example" {
   #  name = "imageName"
   #   name_pattern = "hostname%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = {
+    Status       = "Ready"
+    State        = "Enabled"
+    Platform     = "Linux"
+    Architecture = "x86_64"
+  }
 }
 
-
-
 output "zstack_images" {
   value = data.zstack_images.example
 }
@@ -31,6 +35,7 @@ output "zstack_images" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter hosts. For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for searching hosts
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/images.md b/docs/data-sources/images.md
@@ -17,6 +17,14 @@ Fetches a list of images and their associated attributes from the ZStack environ
 data "zstack_hosts" "example" {
   #  name = "hostname"
   #   name_pattern = "hostname%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State            = "Enabled"
+    Status           = "Connected"
+    HypervisorType   = "KVM"
+    Architecture     = "x86_64"
+    TotalCpuCapacity = "480"
+    ManagementIp     = "172.30.3.4"
+  }
 }
 
 output "zstack_hosts" {
@@ -29,6 +37,7 @@ output "zstack_hosts" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter images. For example, to filter by status, use `Status = "Ready"`.
 - `name` (String) Exact name for searching images
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/instance_offers.md b/docs/data-sources/instance_offers.md
@@ -15,7 +15,11 @@ Fetches a list of instance offers and their associated attributes from the ZStac
 # Copyright (c) ZStack.io, Inc.
 
 data "zstack_instance_offers" "example" {
-
+  # name = "InstanceOffering-1"
+  # name_pattern = "clu%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State = "Enabled"
+  }
 }
 
 output "zstack_instance_offers" {
@@ -28,6 +32,7 @@ output "zstack_instance_offers" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter instance offering. For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for searching  instance offer
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/instances.md b/docs/data-sources/instances.md
@@ -17,6 +17,10 @@ Fetches a list of VM instances and their associated attributes from the ZStack e
 data "zstack_instances" "vminstances" {
   #   name = "name of vm instance"
   #    name_pattern = "virtual machine instances name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State  = "Running"
+    CPUNum = "3"
+  }
 }
 
 
@@ -30,6 +34,7 @@ output "zstack_vminstances" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter instance . For example, to filter by State, use `State = "Running"`.
 - `name` (String) Exact name for searching VM instance
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/l2networks.md b/docs/data-sources/l2networks.md
@@ -16,7 +16,11 @@ Fetches a list of L2 networks and their associated attributes from the ZStack en
 
 data "zstack_l2networks" "networks" {
   #   name = "L2 networks name"
-  #    name_pattern = "L2 networks name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  #   name_pattern = "L2 networks name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = {
+    Vlan = 36
+    Type = "L2VlanNetwork"
+  }
 }
 
 output "zstack_l2networks" {
@@ -29,6 +33,7 @@ output "zstack_l2networks" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter L2 networks . For example, to filter by Vlan, use `Vlan = "2"`.
 - `name` (String) Exact name for searching L2 Network.
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/l3networks.md b/docs/data-sources/l3networks.md
@@ -17,6 +17,10 @@ Fetches a list of L3 networks and their associated attributes from the ZStack en
 data "zstack_l3networks" "networks" {
   #   name = "L3 networks name"
   #    name_pattern = "L3 networks name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = {
+    Category  = "Private"
+    IpVersion = 6
+  }
 }
 
 output "zstack_networks" {
@@ -29,6 +33,7 @@ output "zstack_networks" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter L3 networks . For example, to filter by Category, use `Category = "Private"`.
 - `name` (String) Exact name for searching L3 Network.
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/vips.md b/docs/data-sources/vips.md
@@ -15,7 +15,11 @@ Fetches a list of vips and their associated attributes from the ZStack environme
 # Copyright (c) ZStack.io, Inc.
 
 data "zstack_vips" "test" {
-
+  filter = { # option
+    State  = "Enabled"
+    Ip     = "172.30.9.47"
+    UseFor = "LoadBalancer"
+  }
 }
 
 output "zstack_vips" {
@@ -28,6 +32,7 @@ output "zstack_vips" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter L2 networks . For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for searching VIPs
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/virtual_router_images.md b/docs/data-sources/virtual_router_images.md
@@ -29,6 +29,7 @@ output "zstack_vrimages" {
 
 ### Optional
 
+- `filter` (Map of String) Filter conditions for virtual router images (e.g., state='Enabled', format='qcow2')
 - `name` (String) Exact name for searching virtual router images
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/virtual_router_instances.md b/docs/data-sources/virtual_router_instances.md
@@ -17,6 +17,12 @@ Fetches a list of virtual router instances and their associated attributes from
 data "zstack_virtual_routers" "test" {
   #   name = "name of vm instance"
   #    name_pattern = "virtual router instances name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State          = "Running"
+    Status         = "Connected"
+    HypervisorType = "KVM"
+    Architecture   = "x86_s64"
+  }
 }
 
 
@@ -30,6 +36,7 @@ output "zstack_vrouters" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter virtual router instances . For example, to filter by State, use `State = "Running"`.
 - `name` (String) Exact name for searching virtual router instance
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/virtual_router_offers.md b/docs/data-sources/virtual_router_offers.md
@@ -17,6 +17,10 @@ Fetches a list of virtual router offers and their associated attributes from the
 data "zstack_virtual_router_offers" "test" {
   #   name = "name of virtual router offers"
   #    name_pattern = "virtual router offers name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
+  filter = { # option
+    State  = "Enabled"
+    CpuNum = 2
+  }
 }
 
 output "zstack_offers" {
@@ -29,6 +33,7 @@ output "zstack_offers" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter virtual router offering . For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for searching virtual router offer
 - `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
diff --git a/docs/data-sources/zones.md b/docs/data-sources/zones.md
@@ -29,7 +29,9 @@ output "zstack_zones" {
 
 ### Optional
 
+- `filter` (Map of String) Key-value pairs to filter Zones . For example, to filter by State, use `State = "Enabled"`.
 - `name` (String) Exact name for Searching  zones
+- `name_pattern` (String) Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
 
 ### Read-Only
 
diff --git a/examples/data-sources/backupstorages/data-source.tf b/examples/data-sources/backupstorages/data-source.tf
@@ -3,9 +3,9 @@
 data "zstack_backupstorages" "example" {
   #   name  = "backupstorage name"
   #   name_pattern = "image%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-  filter = {  # option
+  filter = { # option
     Status = "Connected"
-    State = "Enabled"
+    State  = "Enabled"
   }
 }
 
diff --git a/examples/data-sources/clusters/data-source.tf b/examples/data-sources/clusters/data-source.tf
@@ -3,11 +3,11 @@
 data "zstack_clusters" "example" {
   #name = "cluster1"
   #name_pattern = "clu%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-  filter = {  # option
-      State = "Enabled"
-      HypervisorType = "KVM"
-      Architecture = "x86_64"
-   }
+  filter = { # option
+    State          = "Enabled"
+    HypervisorType = "KVM"
+    Architecture   = "x86_64"
+  }
 }
 
 output "zstack_clusters" {
diff --git a/examples/data-sources/disk_offers/data-source.tf b/examples/data-sources/disk_offers/data-source.tf
@@ -3,7 +3,7 @@
 data "zstack_disk_offers" "example" {
   name = "smallDiskOffering"
   # name_pattern = "sm%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-  filter = {  # option
+  filter = { # option
     State = "Enabled"
   }
 }
diff --git a/examples/data-sources/hosts/data-source.tf b/examples/data-sources/hosts/data-source.tf
@@ -3,14 +3,14 @@
 data "zstack_hosts" "example" {
   #  name = "hostname"
   #   name_pattern = "hostname%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-    filter = {  # option
-      State = "Enabled"
-      Status = "Connected"
-      HypervisorType = "KVM"
-      Architecture = "x86_64"
-      TotalCpuCapacity = "480"
-      ManagementIp = "172.30.3.4"      
-   }
+  filter = { # option
+    State            = "Enabled"
+    Status           = "Connected"
+    HypervisorType   = "KVM"
+    Architecture     = "x86_64"
+    TotalCpuCapacity = "480"
+    ManagementIp     = "172.30.3.4"
+  }
 }
 
 output "zstack_hosts" {
diff --git a/examples/data-sources/images/data-source.tf b/examples/data-sources/images/data-source.tf
@@ -4,9 +4,9 @@ data "zstack_images" "example" {
   #  name = "imageName"
   #   name_pattern = "hostname%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
   filter = {
-    Status = "Ready"
-    State = "Enabled"
-    Platform = "Linux"
+    Status       = "Ready"
+    State        = "Enabled"
+    Platform     = "Linux"
     Architecture = "x86_64"
   }
 }
diff --git a/examples/data-sources/instance_offers/data-source.tf b/examples/data-sources/instance_offers/data-source.tf
@@ -3,7 +3,7 @@
 data "zstack_instance_offers" "example" {
   # name = "InstanceOffering-1"
   # name_pattern = "clu%"  # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-  filter = {  # option
+  filter = { # option
     State = "Enabled"
   }
 }
diff --git a/examples/data-sources/instances/data-source.tf b/examples/data-sources/instances/data-source.tf
@@ -3,8 +3,8 @@
 data "zstack_instances" "vminstances" {
   #   name = "name of vm instance"
   #    name_pattern = "virtual machine instances name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-  filter = {  # option
-    State = "Running"
+  filter = { # option
+    State  = "Running"
     CPUNum = "3"
   }
 }
diff --git a/examples/data-sources/l2networks/data-source.tf b/examples/data-sources/l2networks/data-source.tf
@@ -3,10 +3,10 @@
 data "zstack_l2networks" "networks" {
   #   name = "L2 networks name"
   #   name_pattern = "L2 networks name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
-      filter = { 
-        Vlan = 36
-        Type= "L2VlanNetwork"
-    }
+  filter = {
+    Vlan = 36
+    Type = "L2VlanNetwork"
+  }
 }
 
 output "zstack_l2networks" {
diff --git a/examples/data-sources/l3networks/data-source.tf b/examples/data-sources/l3networks/data-source.tf
@@ -4,7 +4,7 @@ data "zstack_l3networks" "networks" {
   #   name = "L3 networks name"
   #    name_pattern = "L3 networks name% Pattern"   # Pattern for fuzzy name search, similar to MySQL LIKE. Use % for multiple characters and _ for exactly one character.
   filter = {
-    Category = "Private"
+    Category  = "Private"
     IpVersion = 6
   }
 }
diff --git a/examples/data-sources/vips/data-source.tf b/examples/data-sources/vips/data-source.tf
diff --git a/examples/data-sources/virtual_router_instances/data-source.tf b/examples/data-sources/virtual_router_instances/data-source.tf
diff --git a/examples/data-sources/virtual_router_offers/data-source.tf b/examples/data-sources/virtual_router_offers/data-source.tf
diff --git a/zstack/utils/filter.go b/zstack/utils/filter.go

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Copyright (c) ZStack.io, Inc.`
	`2`	`+`
`1`	`3`	`stages:`
`2`	`4`	`- build`
`3`	`5`