Merge 'feat/add-http-proxy' into 'main'

feat: add HTTP proxy support

See merge request: !92

Author: sdk-liuzhaoliang

README.md

@@ -142,6 +142,61 @@ $ export VOLCENGINE_PROFILE="your_profile"
 $ export VOLCENGINE_FILE_PATH="your_file_path" # if empty, default path is ~/.volcengine
 ```
 
+## Authenticated Cloud Control proxy
+
+Use `proxy_url` together with `proxy_authorization` when Cloud Control API requests must pass through an authenticated HTTP proxy. `proxy_authorization` is the complete value of the `Proxy-Authorization` header and is marked sensitive. For HTTP proxies, keep credentials out of `proxy_url` and use this attribute instead. `proxy_authorization` supports HTTP and HTTPS proxy URLs; SOCKS5 and SOCKS5H URLs remain available without this attribute.
+
+For a ZTI proxy, configure the same values used by curl:
+
+```shell
+PSM="<your-psm>"
+PROXY="<your-proxy-domain>"
+AUTH_TOKEN=$(echo -n "ZTI_$PSM:$(cat "$SEC_TOKEN_PATH")" | base64 -w0)
+
+export VOLCENGINE_PROXY_URL="http://${PROXY}:8080"
+export VOLCENGINE_PROXY_AUTHORIZATION="Basic ${AUTH_TOKEN}"
+```
+
+The equivalent Terraform configuration is:
+
+```hcl
+variable "proxy_authorization" {
+  type      = string
+  sensitive = true
+}
+
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+}
+```
+
+Standard `no_proxy` rules identify destinations that connect directly instead of using `proxy_url`:
+
+```hcl
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+  no_proxy            = "localhost,127.0.0.1,.internal.example.com"
+}
+```
+
+To use the proxy only for specified destinations, configure the inverse allowlist with `proxy_include_domains`:
+
+```hcl
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+  proxy_include_domains = [
+    "cloudcontrol.cn-beijing.volcengineapi.com",
+  ]
+}
+```
+
+Replace `cn-beijing` with the configured region, or list the host from `endpoints.cloudcontrolapi` when using a custom endpoint. A domain without a leading dot matches the domain and its subdomains; a leading dot matches subdomains only. IP addresses, CIDR ranges, optional ports, and `*` follow standard `NO_PROXY` matching. `no_proxy` and `proxy_include_domains` cannot be configured together.
+
+The equivalent environment variables are `VOLCENGINE_NO_PROXY` (with `NO_PROXY` and `no_proxy` as fallbacks) and comma-separated `VOLCENGINE_PROXY_INCLUDE_DOMAINS`. Explicit provider attributes take precedence over the environment variables. These settings apply to Cloud Control API traffic; STS calls made by `assume_role` use a separate client.
+
 <!-- schema generated by tfplugindocs -->
 
 ## Schema
@@ -156,7 +211,10 @@ $ export VOLCENGINE_FILE_PATH="your_file_path" # if empty, default path is ~/.vo
 - `customer_headers` (String) CUSTOMER HEADERS for Volcengine Provider. The customer_headers field uses commas (,) to separate multiple headers, and colons (:) to separate each header key from its corresponding value.
 - `disable_ssl` (Boolean) Disable SSL for Volcengine Provider
 - `endpoints` (Attributes) An `endpoints` block (documented below). Only one `endpoints` block may be in the configuration. (see [below for nested schema](#nestedatt--endpoints))
-- `proxy_url` (String) PROXY URL for Volcengine Provider
+- `no_proxy` (String) Comma-separated hosts, domain suffixes, IP addresses, or CIDR ranges that bypass proxy_url. It follows standard NO_PROXY matching and can be sourced from VOLCENGINE_NO_PROXY, NO_PROXY, or no_proxy.
+- `proxy_authorization` (String, Sensitive) Value of the Proxy-Authorization header for Cloud Control API proxy requests, for example `Basic <token>`. It can also be sourced from the `VOLCENGINE_PROXY_AUTHORIZATION` environment variable.
+- `proxy_include_domains` (Set of String) Hosts, domain suffixes, IP addresses, or CIDR ranges that use proxy_url while all other destinations connect directly. It can be sourced as a comma-separated list from VOLCENGINE_PROXY_INCLUDE_DOMAINS and cannot be combined with no_proxy.
+- `proxy_url` (String) HTTP, HTTPS, SOCKS5, or SOCKS5H proxy URL for Cloud Control API requests. It can also be sourced from the `VOLCENGINE_PROXY_URL` environment variable.
 - `region` (String) The Region for Volcengine Provider. It must be provided, but it can also be sourced from the `VOLCENGINE_REGION` environment variable
 
 

docs/index.md

@@ -137,6 +137,61 @@ $ export VOLCENGINE_PROFILE="your_profile"
 $ export VOLCENGINE_FILE_PATH="your_file_path" # if empty, default path is ~/.volcengine
 ```
 
+## Authenticated Cloud Control proxy
+
+Use `proxy_url` together with `proxy_authorization` when Cloud Control API requests must pass through an authenticated HTTP proxy. `proxy_authorization` is the complete value of the `Proxy-Authorization` header and is marked sensitive. For HTTP proxies, keep credentials out of `proxy_url` and use this attribute instead. `proxy_authorization` supports HTTP and HTTPS proxy URLs; SOCKS5 and SOCKS5H URLs remain available without this attribute.
+
+For a ZTI proxy, configure the same values used by curl:
+
+```shell
+PSM="<your-psm>"
+PROXY="<your-proxy-domain>"
+AUTH_TOKEN=$(echo -n "ZTI_$PSM:$(cat "$SEC_TOKEN_PATH")" | base64 -w0)
+
+export VOLCENGINE_PROXY_URL="http://${PROXY}:8080"
+export VOLCENGINE_PROXY_AUTHORIZATION="Basic ${AUTH_TOKEN}"
+```
+
+The equivalent Terraform configuration is:
+
+```hcl
+variable "proxy_authorization" {
+  type      = string
+  sensitive = true
+}
+
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+}
+```
+
+Standard `no_proxy` rules identify destinations that connect directly instead of using `proxy_url`:
+
+```hcl
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+  no_proxy            = "localhost,127.0.0.1,.internal.example.com"
+}
+```
+
+To use the proxy only for specified destinations, configure the inverse allowlist with `proxy_include_domains`:
+
+```hcl
+provider "volcenginecc" {
+  proxy_url           = "http://<your-proxy-domain>:8080"
+  proxy_authorization = var.proxy_authorization
+  proxy_include_domains = [
+    "cloudcontrol.cn-beijing.volcengineapi.com",
+  ]
+}
+```
+
+Replace `cn-beijing` with the configured region, or list the host from `endpoints.cloudcontrolapi` when using a custom endpoint. A domain without a leading dot matches the domain and its subdomains; a leading dot matches subdomains only. IP addresses, CIDR ranges, optional ports, and `*` follow standard `NO_PROXY` matching. `no_proxy` and `proxy_include_domains` cannot be configured together.
+
+The equivalent environment variables are `VOLCENGINE_NO_PROXY` (with `NO_PROXY` and `no_proxy` as fallbacks) and comma-separated `VOLCENGINE_PROXY_INCLUDE_DOMAINS`. Explicit provider attributes take precedence over the environment variables. These settings apply to Cloud Control API traffic; STS calls made by `assume_role` use a separate client.
+
 <!-- schema generated by tfplugindocs -->
 
 ## Schema
@@ -152,7 +207,10 @@ $ export VOLCENGINE_FILE_PATH="your_file_path" # if empty, default path is ~/.vo
 - `customer_headers` (String) CUSTOMER HEADERS for Volcengine Provider. The customer_headers field uses commas (,) to separate multiple headers, and colons (:) to separate each header key from its corresponding value.
 - `disable_ssl` (Boolean) Disable SSL for Volcengine Provider
 - `endpoints` (Attributes) An `endpoints` block (documented below). Only one `endpoints` block may be in the configuration. (see [below for nested schema](#nestedatt--endpoints))
-- `proxy_url` (String) PROXY URL for Volcengine Provider
+- `no_proxy` (String) Comma-separated hosts, domain suffixes, IP addresses, or CIDR ranges that bypass proxy_url. It follows standard NO_PROXY matching and can be sourced from VOLCENGINE_NO_PROXY, NO_PROXY, or no_proxy.
+- `proxy_authorization` (String, Sensitive) Value of the Proxy-Authorization header for Cloud Control API proxy requests, for example `Basic <token>`. It can also be sourced from the `VOLCENGINE_PROXY_AUTHORIZATION` environment variable.
+- `proxy_include_domains` (Set of String) Hosts, domain suffixes, IP addresses, or CIDR ranges that use proxy_url while all other destinations connect directly. It can be sourced as a comma-separated list from VOLCENGINE_PROXY_INCLUDE_DOMAINS and cannot be combined with no_proxy.
+- `proxy_url` (String) HTTP, HTTPS, SOCKS5, or SOCKS5H proxy URL for Cloud Control API requests. It can also be sourced from the `VOLCENGINE_PROXY_URL` environment variable.
 - `region` (String) The Region for Volcengine Provider. It must be provided, but it can also be sourced from the `VOLCENGINE_REGION` environment variable
 
 
@@ -185,4 +243,4 @@ The current version has a known issue when modifying the SetNestedAttribute and
 | Parameter Type | Impact | Recommendation | Example |
 |---|---|---|---|
 | `SetNestedAttribute` | If `SetNestedAttribute` is not fully defined, creating new resources may fail. Even when it is fully defined, modifying existing items in the Set may cause the following issues: errors that prevent the update; or no explicit error, but non-target items being incorrectly updated. There is also a certain probability that re-running `terraform apply` will fail. | 1. All attributes under `SetNestedAttribute` must be fully defined.<br>2. If there are multiple items under a `SetNestedAttribute`, try to avoid operating on them through Terraform. | 1. [`volcenginecc_alb_listener`: `domain_extensions`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/resources/alb_listener)<br>2. [`volcenginecc_alb_rule`: `rule_action`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/resources/alb_rule) |
-| `ListNestedAttribute` | When it contains read-only attributes, it has no impact on creating new resources or modifying existing ones. However, when changing resource data, inserting or deleting items in the middle of the list can lead to data being misaligned, causing incorrect updates to non-target items. | 1. All attributes under `ListNestedAttribute` must be fully defined.<br>2. If there are multiple items under a `ListNestedAttribute`, try to avoid operating on them through Terraform.<br>3. If changes are necessary, only add or delete items at the end of the `ListNestedAttribute`. | 1. [`volcenginecc_rdspostgresql_db_endpoint`: `addresses`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/rdspostgresql_db_endpoint)<br>2. [`volcenginecc_ecs_instance`: `secondary_network_interfaces`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/ecs_instance) |
+| `ListNestedAttribute` | When it contains read-only attributes, it has no impact on creating new resources or modifying existing ones. However, when changing resource data, inserting or deleting items in the middle of the list can lead to data being misaligned, causing incorrect updates to non-target items. | 1. All attributes under `ListNestedAttribute` must be fully defined.<br>2. If there are multiple items under a `ListNestedAttribute`, try to avoid operating on them through Terraform.<br>3. If changes are necessary, only add or delete items at the end of the `ListNestedAttribute`. | 1. [`volcenginecc_rdspostgresql_db_endpoint`: `addresses`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/rdspostgresql_db_endpoint)<br>2. [`volcenginecc_ecs_instance`: `secondary_network_interfaces`](https://registry.terraform.io/providers/volcengine/volcenginecc/latest/docs/ecs_instance) |

go.mod

@@ -19,6 +19,7 @@ require (
 	github.com/test-go/testify v1.1.4
 	github.com/volcengine/volcengine-go-sdk v1.2.36
 	github.com/xeipuuv/gojsonschema v1.2.0
+	golang.org/x/net v0.52.0
 	golang.org/x/text v0.36.0
 )
 
@@ -80,7 +81,6 @@ require (
 	github.com/zclconf/go-cty v1.18.1 // indirect
 	golang.org/x/crypto v0.49.0 // indirect
 	golang.org/x/mod v0.35.0 // indirect
-	golang.org/x/net v0.52.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
 	golang.org/x/sys v0.43.0 // indirect
 	golang.org/x/tools v0.43.0 // indirect

internal/common/common.go

@@ -2,5 +2,5 @@ package common
 
 const (
 	TerraformProviderName    = "terraform-provider-volcenginecc"
-	TerraformProviderVersion = "0.0.62"
+	TerraformProviderVersion = "0.0.63"
 )