You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/r/is_lb_pool.html.markdown
+92-37Lines changed: 92 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,10 +8,11 @@ description: |-
8
8
---
9
9
10
10
# ibm_is_lb_pool
11
-
Create, update, or delete a VPC load balancer pool. For more information, about load balancer pool, see [working with pool](https://cloud.ibm.com/docs/vpc?topic=vpc-nlb-pools).
11
+
Create, update, or delete a VPC load balancer pool. For more information about load balancer pools, see [working with pools](https://cloud.ibm.com/docs/vpc?topic=vpc-nlb-pools).
12
12
13
13
**Note:**
14
-
VPC infrastructure services are a regional specific based endpoint, by default targets to `us-south`. Please make sure to target right region in the provider block as shown in the `provider.tf` file, if VPC service is created in region other than `us-south`.
14
+
VPC infrastructure services use region-specific endpoints. By default, the Terraform provider targets the `us-south` region.
15
+
If your VPC resources are provisioned in a different region, update the region attribute in the provider block accordingly. You can find an example configuration in the provider.tf file section.
### Load balancer pool without session persistence (Route Mode Compatible)
123
+
124
+
For route mode load balancers or when session persistence isn't required, omit the session persistence parameters entirely:
125
+
126
+
```terraform
127
+
resource "ibm_is_lb_pool" "route_mode_example" {
128
+
name = "route-mode-pool"
129
+
lb = ibm_is_lb.route_mode.id
130
+
algorithm = "round_robin"
131
+
protocol = "tcp"
132
+
health_delay = 60
133
+
health_retries = 5
134
+
health_timeout = 30
135
+
health_type = "tcp"
136
+
# No session_persistence_type specified - required for route mode
137
+
}
138
+
```
139
+
140
+
### Load balancer pool with failsafe policy
141
+
142
+
Configure failsafe behavior when all pool members become unhealthy:
143
+
144
+
```terraform
145
+
resource "ibm_is_lb_pool" "with_failsafe" {
146
+
name = "failsafe-pool"
147
+
lb = ibm_is_lb.example.id
148
+
algorithm = "least_connections"
149
+
protocol = "https"
150
+
health_delay = 30
151
+
health_retries = 3
152
+
health_timeout = 15
153
+
health_type = "https"
154
+
155
+
failsafe_policy {
156
+
action = "forward"
157
+
target {
158
+
id = ibm_is_lb_pool.backup_pool.pool_id
159
+
}
160
+
}
161
+
}
162
+
```
163
+
113
164
## Timeouts
114
165
The `ibm_is_lb_pool` resource provides the following [Timeouts](https://www.terraform.io/docs/language/resources/syntax.html) configuration options:
115
166
116
-
-**create** - (Default 10 minutes) Used for creating Instance.
117
-
-**update** - (Default 10 minutes) Used for updating Instance.
118
-
-**delete** - (Default 10 minutes) Used for deleting Instance.
167
+
-**create** - (Default 10 minutes) Used for creating the load balancer pool.
168
+
-**update** - (Default 10 minutes) Used for updating the load balancer pool.
169
+
-**delete** - (Default 10 minutes) Used for deleting the load balancer pool.
119
170
120
171
121
172
## Argument reference
122
173
Review the argument references that you can specify for your resource.
123
174
124
-
-`algorithm` - (Required, String) The load-balancing algorithm. Supported values are `round_robin`, `weighted_round_robin`, or `least_connections`.
125
-
-`failsafe_policy` - (Optional, List) The failsafe policy to use for this pool. If unspecified, the default failsafe policy action from the profile will be used.
175
+
-`algorithm` - (Required, String) The load-balancing algorithm. Supported values are `round_robin`, `weighted_round_robin`, or `least_connections`. Choose `least_connections` for workloads with varying response times.
176
+
-`failsafe_policy` - (Optional, List) The failsafe policy defines behavior when all pool members are unhealthy. If unspecified, the default failsafe policy from the load balancer profile applies.
126
177
Nested schema for **failsafe_policy**:
127
-
- `action` - (Optional, String) A load balancer failsafe policy action:- `forward`: Forwards requests to the `target` pool.- `fail`: Rejects requests with an HTTP `503` status code.The enumerated values for this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
128
-
- `target` - (Optional, List) If `action` is `forward`, the target pool to forward to.If `action` is `fail`, this property will be absent.The targets supported by this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
178
+
- `action` - (Optional, String) Failsafe policy action: `forward` (routes requests to target pool) or `fail` (rejects requests with HTTP 503). The enumerated values for this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
179
+
- `target` - (Optional, List) Target pool for `forward` action. Not applicable when action is `fail`. The targets supported by this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
129
180
Nested schema for **target**:
130
-
- `href` - (Optional, String) The URL for this load balancer pool. Mutually exclusive with `id`. On update, specify "null" to remove an existing failsafe target pool.
131
-
- `id` - (Optional, String) The unique identifier for this load balancer pool. Mutually exclusive with `href`. On update, specify "null" to remove an existing failsafe target pool.
132
-
-`health_delay`- (Required, Integer) The health check interval in seconds. Interval must be greater than `timeout` value.
133
-
-`health_retries`- (Required, Integer) The health check max retries.
134
-
-`health_timeout`- (Required, Integer) The health check timeout in seconds.
135
-
-`health_type` - (Required, String) The pool protocol. Enumeration type: `http`, `https`, `tcp` are supported.
136
-
-`health_monitor_url` - (Optional, String) The health check URL. This option is applicable only to the HTTP `health-type`.
137
-
-`health_monitor_port` - (Optional, Integer) The health check port number. Specify `0` to remove an existing health check port.
138
-
-`lb` - (Required, Forces new resource, String) The load balancer unique identifier.
139
-
-`name` - (Required, String) The name of the pool.
140
-
-`protocol` - (Required, String) The pool protocol. Enumeration type: `http`, `https`, `tcp`, `udp` are supported.
141
-
-`proxy_protocol` - (Optional, String) The proxy protocol setting for the pool that is supported by the load balancers in the application family. Valid values are `disabled`, `v1`, and `v2`. Default value is `disabled`.
-`session_persistence_app_cookie_name` - (Optional, String) Session persistence app cookie name. This is applicable only to app_cookie type.
181
+
- `href` - (Optional, String) The URL for the target load balancer pool. Mutually exclusive with `id`. Specify "null" during update to remove an existing failsafe target pool.
182
+
- `id` - (Optional, String) The unique identifier for the target load balancer pool. Mutually exclusive with `href`. Specify "null" during update to remove an existing failsafe target pool.
183
+
-`health_delay`- (Required, Integer) Health check interval in seconds. Must be greater than the `health_timeout` value. Recommended range: 30-300 seconds.
184
+
-`health_retries`- (Required, Integer) Maximum number of health check retries before marking a member unhealthy. Recommended range: 2-10.
185
+
-`health_timeout`- (Required, Integer) Health check timeout in seconds. Must be less than `health_delay`. Recommended range: 5-60 seconds.
186
+
-`health_type` - (Required, String) The health check protocol. Supported values: `http`, `https`, `tcp`. Should typically match the pool protocol for optimal compatibility.
187
+
-`health_monitor_url` - (Optional, String) The health check URL path (e.g., `/health`, `/status`). Only applicable for `http` and `https` health check types. Defaults to `/` if not specified.
188
+
-`health_monitor_port` - (Optional, Integer) Custom health check port number. Specify `0` to remove an existing custom health check port and use the member's port. If not specified, uses the same port as the pool member.
189
+
-`lb` - (Required, Forces new resource, String) The unique identifier of the load balancer. Changing this forces recreation of the resource.
190
+
-`name` - (Required, String) The name of the pool. Must be unique within the load balancer and follow standard naming conventions.
191
+
-`protocol` - (Required, String) The pool protocol for traffic forwarding. Supported values: `http`, `https`, `tcp`, `udp`. Choose based on your application requirements.
192
+
-`proxy_protocol` - (Optional, String) Proxy protocol setting for preserving client connection information. Supported values: `disabled` (default), `v1`, `v2`. Only supported by application load balancers, not network load balancers.
193
+
-`session_persistence_type` - (Optional, String) Session persistence method to ensure client requests are routed to the same backend server. Supported values: `source_ip`, `app_cookie`, `http_cookie`. **Important notes:**
194
+
- Omit this parameter entirely when no session persistence is needed
195
+
- Must be omitted for route mode load balancers
196
+
- To remove session persistence from an existing pool, remove this parameter from your configuration and apply
197
+
- Cannot be used with UDP protocol
198
+
-`session_persistence_app_cookie_name` - (Optional, String) Name of the application cookie used for session persistence. Required and only applicable when `session_persistence_type = "app_cookie"`. Common examples include `JSESSIONID`, `PHPSESSID`, or custom application cookies.
144
199
145
200
## Attribute reference
146
201
In addition to all argument reference list, you can access the following attribute reference after your resource is created.
147
202
148
203
-`id` - (String) The unique identifier of the load balancer pool. The ID is composed of `<lb_id>/<pool_id>`.
149
-
-`failsafe_policy` - (List) The failsafe policy to use for this pool.If unspecified, the default failsafe policy action from the profile will be used.
204
+
-`failsafe_policy` - (List) The configured failsafe policy for this pool.If unspecified, the default failsafe policy action from the profile is used.
150
205
Nested schema for **failsafe_policy**:
151
-
- `healthy_member_threshold_count` - (Integer) The healthy member count at which the failsafe policy action will be triggered. At present, this is always `0`, but may be modifiable in the future. The minimum value is `0`.
152
-
- `target` - (List) If `action` is `forward`, the target pool to forward to.If `action` is `fail`, this property will be absent.The targets supported by this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
206
+
- `healthy_member_threshold_count` - (Integer) The healthy member count threshold that triggers the failsafe policy action. Currently always `0`, but may be configurable in future versions. The minimum value is `0`.
207
+
- `target` - (List) Target pool configuration when `action` is `forward`. Not present when `action` is `fail`. The targets supported by this property may[expand](https://cloud.ibm.com/apidocs/vpc#property-value-expansion) in the future.
153
208
Nested schema for **target**:
154
-
- `deleted` - (List) If present, this property indicates the referenced resource has been deleted, and providessome supplementary information.
209
+
- `deleted` - (List) Indicates if the referenced target resource has been deleted, with supplementary information.
155
210
Nested schema for **deleted**:
156
211
- `more_info` - (String) Link to documentation about deleted resources.
157
212
- `href` - (String) The URL for this load balancer pool.
158
213
- `id` - (String) The unique identifier for this load balancer pool.
159
214
- `name` - (String) The name for this load balancer pool. The name is unique across all pools for the load balancer.
160
-
-`provisioning_status` - (String) The status of load balancer pool.
161
-
-`pool_id` - (String) ID of the load balancer pool.
162
-
-`related_crn` - (String) The CRN of the load balancer resource.
163
-
-`session_persistence_http_cookie_name` - (String) HTTP cookie name for session persistence. Only applicable for http_cookie session persistence type.
215
+
-`provisioning_status` - (String) The current provisioning status of the load balancer pool. Possible values: `create_pending`, `active`, `delete_pending`, `failed`, `maintenance_pending`, `update_pending`.
216
+
-`pool_id` - (String) The unique identifier of the load balancer pool (without the load balancer prefix).
217
+
-`related_crn` - (String) The Cloud Resource Name (CRN) of the associated load balancer resource.
218
+
-`session_persistence_http_cookie_name` - (String) The HTTP cookie name used for session persistence. Only present when `session_persistence_type = "http_cookie"`. This is system-generated and read-only.
164
219
165
220
## Import
166
-
The `ibm_is_lb_pool` resource can be imported by using the load balancer ID and pool ID.
221
+
The `ibm_is_lb_pool` resource can be imported using the load balancer ID and pool ID separated by a forward slash.
0 commit comments