feat(cls): add timezone parameter to cls_cos_shipper resource

Author: iac-agent

.changelog/4159.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/tencentcloud_cls_cos_shipper: add timezone parameter support
+```

go.mod

@@ -45,8 +45,8 @@ require (
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/ckafka v1.3.16
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/clb v1.3.52
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cloudaudit v1.0.1033
-	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.58
-	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.102
+	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.103
+	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.103
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/config v1.3.80
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm v1.3.69
 	github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cwp v1.3.30

go.sum

@@ -875,8 +875,8 @@ github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/clb v1.3.52 h1:t3/KRe8e
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/clb v1.3.52/go.mod h1:llHcTUrqshNqR3ZHhrooFogFcoXh6Er8SnkHfGpdK04=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cloudaudit v1.0.1033 h1:dIr+MVsZeUBiKZELfJh5HRJdI+BI6lCp5pv/2oXekuk=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cloudaudit v1.0.1033/go.mod h1:7oFlNimGSTHFy6JV7W/IZKuJWr+NUjCnGLTvb9MWNrY=
-github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.58 h1:pTW5RzN6Lx887sHK+KVNX7mG9YfRS3XA3gPGAEId+Fk=
-github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.58/go.mod h1:SHM5qxbY3qzCz2pSoXwE13xV2qRNXGkBskNiSgn5KfU=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.103 h1:6uJoaCafWAOMd9mp6u5WfyZIwYyLqvEmx7DNmmLCyYU=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls v1.3.103/go.mod h1:+9DZIuORfHQJ3Oz0I8IYOSwoYiRL7dwyeKmEGuYwl5o=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.0.414/go.mod h1:7sCQWVkxcsR38nffDW057DRGk8mUjK1Ing/EFOK8s8Y=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.0.486/go.mod h1:7sCQWVkxcsR38nffDW057DRGk8mUjK1Ing/EFOK8s8Y=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.0.533/go.mod h1:7sCQWVkxcsR38nffDW057DRGk8mUjK1Ing/EFOK8s8Y=
@@ -957,8 +957,11 @@ github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.89/go.mod h
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.90/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.94/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.95/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
-github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.102 h1:3n7BpLOPnE9Rv3Y9Jxgl/XaQX3GzktO+dEaAbtVbjSk=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.98/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.101/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.102/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.103 h1:W1dpZ/Q6+DjUpiAUSmIHuFn7rAvetlSqzQCtf0tKEEA=
+github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common v1.3.103/go.mod h1:r5r4xbfxSaeR04b166HGsBa/R4U3SueirEUpXGuw+Q0=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/config v1.3.80 h1:chnsNBeJn3MieFLki4hpbzoml5NiTvLVzOTqYRVxQho=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/config v1.3.80/go.mod h1:B/ezGtlvDhZlleNM+2QdvZccrUi+J+fN6vMnDDsZnuM=
 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/controlcenter v1.1.51 h1:pGwrfCBBCt1u+EDHwfNj9NLQpvk5MVKVMcsE7SvwqM4=

openspec/changes/archive/2026-05-28-add-cls-cos-shipper-timezone/.openspec.yaml

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-05-28
+status: applied

openspec/changes/archive/2026-05-28-add-cls-cos-shipper-timezone/design.md

@@ -0,0 +1,34 @@
+## Context
+
+The `tencentcloud_cls_cos_shipper` resource manages CLS (Cloud Log Service) log shipping rules to COS (Cloud Object Storage). The resource currently supports parameters like `topic_id`, `bucket`, `prefix`, `shipper_name`, `interval`, `max_size`, `filter_rules`, `partition`, `compress`, `content`, `filename_mode`, `start_time`, `end_time`, and `storage_type`.
+
+The cloud API already supports a `TimeZone` parameter in `CreateShipperRequest`, `ModifyShipperRequest`, and returns it in `ShipperInfo` (via `DescribeShippers`). However, the Terraform resource does not yet expose this parameter.
+
+The resource file is at `tencentcloud/services/cls/resource_tc_cls_cos_shipper.go` and follows the standard CRUD pattern with retry logic.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `time_zone` as an Optional string parameter to the `tencentcloud_cls_cos_shipper` resource schema
+- Wire the parameter into Create, Read, and Update methods
+- Maintain backward compatibility (existing configurations without `time_zone` continue to work)
+
+**Non-Goals:**
+- Adding other missing parameters (e.g., `DSLFilter`, `RoleArn`, `ExternalId`)
+- Changing existing parameter behavior
+- Modifying the service layer (`service_tencentcloud_cls.go`)
+
+## Decisions
+
+1. **Schema field type**: Use `schema.TypeString` with `Optional: true` and `Computed: true`. The field is optional on create/update, and the API may return a default value on read.
+
+2. **No validation function**: The API accepts a wide range of GMT/UTC timezone formats. Rather than maintaining a large validation list in Terraform, we rely on the API to validate the input and return appropriate errors.
+
+3. **Update support**: The `time_zone` field is updatable via `ModifyShipper` API, so it will be handled in the Update method with `d.HasChange("time_zone")` pattern, consistent with other string fields like `storage_type`.
+
+4. **Read support**: Read from `ShipperInfo.TimeZone` in the Read method with nil check before setting, consistent with existing patterns like `storage_type`.
+
+## Risks / Trade-offs
+
+- [Risk] API timezone format validation may change → Mitigation: Rely on API-side validation; no client-side validation needed.
+- [Trade-off] No client-side validation means users get API errors instead of Terraform plan-time errors → Acceptable since the timezone list is extensive and may be updated server-side.

openspec/changes/archive/2026-05-28-add-cls-cos-shipper-timezone/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+The `tencentcloud_cls_cos_shipper` resource currently does not support the `TimeZone` parameter, which is used to generate time variables in the file path when shipping logs to COS. Users need this parameter to control the timezone used in COS file path generation, ensuring logs are organized according to their preferred timezone.
+
+## What Changes
+
+- Add a new optional `time_zone` parameter to the `tencentcloud_cls_cos_shipper` resource
+- The parameter maps to `TimeZone` in the CLS cloud API (CreateShipper, ModifyShipper, DescribeShippers)
+- The parameter accepts GMT/UTC timezone format strings (e.g., "GMT+08:00", "UTC+08:00")
+- The parameter is used in Create, Update, and Read operations
+
+## Capabilities
+
+### New Capabilities
+- `cls-cos-shipper-timezone`: Add `time_zone` parameter support to the CLS COS shipper resource for controlling timezone in COS file path generation
+
+### Modified Capabilities
+
+## Impact
+
+- `tencentcloud/services/cls/resource_tc_cls_cos_shipper.go`: Add `time_zone` schema field and wire it into Create, Read, Update methods
+- `tencentcloud/services/cls/resource_tc_cls_cos_shipper_test.go`: Add unit test cases for the new parameter
+- `tencentcloud/services/cls/resource_tc_cls_cos_shipper.md`: Update example usage documentation
+- Cloud API SDK: Uses existing `TimeZone` field in `CreateShipperRequest`, `ModifyShipperRequest`, and `ShipperInfo` structs from `github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cls/v20201016`

openspec/changes/archive/2026-05-28-add-cls-cos-shipper-timezone/specs/cls-cos-shipper-timezone/spec.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Support time_zone parameter in CLS COS shipper resource
+
+The `tencentcloud_cls_cos_shipper` resource SHALL support an optional `time_zone` parameter that maps to the `TimeZone` field in the CLS cloud API. This parameter is used to generate time variables in the file path when shipping logs to COS.
+
+The parameter SHALL be:
+- Type: string
+- Optional: true
+- Computed: true
+- Description: "The timezone used to generate time variables in the COS file path. Supports GMT/UTC timezone formats (e.g., GMT+08:00, UTC+08:00)."
+
+#### Scenario: Create shipper with time_zone specified
+
+- **WHEN** user creates a `tencentcloud_cls_cos_shipper` resource with `time_zone = "GMT+08:00"`
+- **THEN** the `CreateShipper` API request SHALL include `TimeZone` set to `"GMT+08:00"`
+- **AND** the resource state SHALL store the `time_zone` value after successful creation
+
+#### Scenario: Create shipper without time_zone specified
+
+- **WHEN** user creates a `tencentcloud_cls_cos_shipper` resource without specifying `time_zone`
+- **THEN** the `CreateShipper` API request SHALL NOT include `TimeZone` parameter
+- **AND** the resource state SHALL read back whatever value the API returns for `TimeZone` in the Read method
+
+#### Scenario: Read shipper with time_zone
+
+- **WHEN** the resource Read method is called
+- **AND** the `ShipperInfo.TimeZone` field in the `DescribeShippers` response is not nil
+- **THEN** the resource state SHALL set `time_zone` to the value of `ShipperInfo.TimeZone`
+
+#### Scenario: Read shipper without time_zone
+
+- **WHEN** the resource Read method is called
+- **AND** the `ShipperInfo.TimeZone` field in the `DescribeShippers` response is nil
+- **THEN** the resource state SHALL NOT set `time_zone` (skip the `d.Set` call)
+
+#### Scenario: Update shipper time_zone
+
+- **WHEN** user updates the `time_zone` field of an existing `tencentcloud_cls_cos_shipper` resource
+- **THEN** the `ModifyShipper` API request SHALL include `TimeZone` set to the new value
+- **AND** the resource state SHALL reflect the updated value after successful modification
+
+#### Scenario: Import existing shipper with time_zone
+
+- **WHEN** user imports an existing CLS COS shipper resource
+- **THEN** the Read method SHALL correctly populate the `time_zone` field from the API response

openspec/changes/archive/2026-05-28-add-cls-cos-shipper-timezone/tasks.md

@@ -0,0 +1,17 @@
+## 1. Schema Definition
+
+- [x] 1.1 Add `time_zone` field to the resource schema in `tencentcloud/services/cls/resource_tc_cls_cos_shipper.go` as an Optional, Computed string field with appropriate description
+
+## 2. CRUD Implementation
+
+- [x] 2.1 Add `time_zone` handling in the Create method (`resourceTencentCloudClsCosShipperCreate`): read from ResourceData and set `request.TimeZone`
+- [x] 2.2 Add `time_zone` handling in the Read method (`resourceTencentCloudClsCosShipperRead`): read from `ShipperInfo.TimeZone` with nil check and set to state
+- [x] 2.3 Add `time_zone` handling in the Update method (`resourceTencentCloudClsCosShipperUpdate`): handle `d.HasChange("time_zone")` and set `request.TimeZone`
+
+## 3. Unit Tests
+
+- [x] 3.1 Add unit test cases in `tencentcloud/services/cls/resource_tc_cls_cos_shipper_test.go` using gomonkey to mock cloud API calls, verifying the `time_zone` parameter is correctly handled in Create, Read, and Update operations
+
+## 4. Documentation
+
+- [x] 4.1 Update `tencentcloud/services/cls/resource_tc_cls_cos_shipper.md` to include `time_zone` parameter in the example usage

openspec/specs/cls-cos-shipper-timezone/spec.md

@@ -0,0 +1,46 @@
+## ADDED Requirements
+
+### Requirement: Support time_zone parameter in CLS COS shipper resource
+
+The `tencentcloud_cls_cos_shipper` resource SHALL support an optional `time_zone` parameter that maps to the `TimeZone` field in the CLS cloud API. This parameter is used to generate time variables in the file path when shipping logs to COS.
+
+The parameter SHALL be:
+- Type: string
+- Optional: true
+- Computed: true
+- Description: "The timezone used to generate time variables in the COS file path. Supports GMT/UTC timezone formats (e.g., GMT+08:00, UTC+08:00)."
+
+#### Scenario: Create shipper with time_zone specified
+
+- **WHEN** user creates a `tencentcloud_cls_cos_shipper` resource with `time_zone = "GMT+08:00"`
+- **THEN** the `CreateShipper` API request SHALL include `TimeZone` set to `"GMT+08:00"`
+- **AND** the resource state SHALL store the `time_zone` value after successful creation
+
+#### Scenario: Create shipper without time_zone specified
+
+- **WHEN** user creates a `tencentcloud_cls_cos_shipper` resource without specifying `time_zone`
+- **THEN** the `CreateShipper` API request SHALL NOT include `TimeZone` parameter
+- **AND** the resource state SHALL read back whatever value the API returns for `TimeZone` in the Read method
+
+#### Scenario: Read shipper with time_zone
+
+- **WHEN** the resource Read method is called
+- **AND** the `ShipperInfo.TimeZone` field in the `DescribeShippers` response is not nil
+- **THEN** the resource state SHALL set `time_zone` to the value of `ShipperInfo.TimeZone`
+
+#### Scenario: Read shipper without time_zone
+
+- **WHEN** the resource Read method is called
+- **AND** the `ShipperInfo.TimeZone` field in the `DescribeShippers` response is nil
+- **THEN** the resource state SHALL NOT set `time_zone` (skip the `d.Set` call)
+
+#### Scenario: Update shipper time_zone
+
+- **WHEN** user updates the `time_zone` field of an existing `tencentcloud_cls_cos_shipper` resource
+- **THEN** the `ModifyShipper` API request SHALL include `TimeZone` set to the new value
+- **AND** the resource state SHALL reflect the updated value after successful modification
+
+#### Scenario: Import existing shipper with time_zone
+
+- **WHEN** user imports an existing CLS COS shipper resource
+- **THEN** the Read method SHALL correctly populate the `time_zone` field from the API response

tencentcloud/services/cls/resource_tc_cls_cos_shipper.go

@@ -228,6 +228,12 @@ func ResourceTencentCloudClsCosShipper() *schema.Resource {
 				Optional:    true,
 				Description: "COS bucket storage type. support: STANDARD_IA, ARCHIVE, DEEP_ARCHIVE, STANDARD, MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING.",
 			},
+			"time_zone": {
+				Type:        schema.TypeString,
+				Optional:    true,
+				Computed:    true,
+				Description: "Timezone used to generate the time variable in the COS file path when shipping logs. Supports GMT and UTC timezone formats, e.g., `GMT+08:00`, `UTC+08:00`.",
+			},
 		},
 	}
 }
@@ -388,6 +394,10 @@ func resourceTencentCloudClsCosShipperCreate(d *schema.ResourceData, meta interf
 		request.StorageType = helper.String(v.(string))
 	}
 
+	if v, ok := d.GetOk("time_zone"); ok {
+		request.TimeZone = helper.String(v.(string))
+	}
+
 	err := resource.Retry(tccommon.WriteRetryTimeout, func() *resource.RetryError {
 		result, e := meta.(tccommon.ProviderMeta).GetAPIV3Conn().UseClsClient().CreateShipper(request)
 		if e != nil {
@@ -534,6 +544,10 @@ func resourceTencentCloudClsCosShipperRead(d *schema.ResourceData, meta interfac
 		_ = d.Set("storage_type", shipper.StorageType)
 	}
 
+	if shipper.TimeZone != nil {
+		_ = d.Set("time_zone", shipper.TimeZone)
+	}
+
 	return nil
 }
 
@@ -708,6 +722,12 @@ func resourceTencentCloudClsCosShipperUpdate(d *schema.ResourceData, meta interf
 		}
 	}
 
+	if d.HasChange("time_zone") {
+		if v, ok := d.GetOk("time_zone"); ok {
+			request.TimeZone = helper.String(v.(string))
+		}
+	}
+
 	err := resource.Retry(tccommon.WriteRetryTimeout, func() *resource.RetryError {
 		result, e := meta.(tccommon.ProviderMeta).GetAPIV3Conn().UseClsClient().ModifyShipper(request)
 		if e != nil {