File: //snap/google-cloud-cli/current/help/man/man1/gcloud_compute_backend-services_update-backend.1
.TH "GCLOUD_COMPUTE_BACKEND\-SERVICES_UPDATE\-BACKEND" 1
.SH "NAME"
.HP
gcloud compute backend\-services update\-backend \- update an existing backend of a load balancer or Traffic Director
.SH "SYNOPSIS"
.HP
\f5gcloud compute backend\-services update\-backend\fR \fIBACKEND_SERVICE_NAME\fR ([\fB\-\-instance\-group\fR=\fIINSTANCE_GROUP\fR\ :\ \fB\-\-instance\-group\-region\fR=\fIINSTANCE_GROUP_REGION\fR\ |\ \fB\-\-instance\-group\-zone\fR=\fIINSTANCE_GROUP_ZONE\fR]\ |\ [\fB\-\-network\-endpoint\-group\fR=\fINETWORK_ENDPOINT_GROUP\fR\ :\ \fB\-\-network\-endpoint\-group\-zone\fR=\fINETWORK_ENDPOINT_GROUP_ZONE\fR]) [\fB\-\-balancing\-mode\fR=\fIBALANCING_MODE\fR] [\fB\-\-capacity\-scaler\fR=\fICAPACITY_SCALER\fR] [\fB\-\-description\fR=\fIDESCRIPTION\fR] [\fB\-\-failover\fR] [\fB\-\-max\-utilization\fR=\fIMAX_UTILIZATION\fR] [\fB\-\-preference\fR=\fIPREFERENCE\fR] [\fB\-\-clear\-custom\-metrics\fR\ |\ \fB\-\-custom\-metrics\fR=[\fICUSTOM_METRICS\fR,...]\ |\ \fB\-\-custom\-metrics\-file\fR=[\fICUSTOM_METRICS\fR,...]] [\fB\-\-global\fR\ |\ \fB\-\-region\fR=\fIREGION\fR] [\fB\-\-max\-connections\fR=\fIMAX_CONNECTIONS\fR\ |\ \fB\-\-max\-connections\-per\-endpoint\fR=\fIMAX_CONNECTIONS_PER_ENDPOINT\fR\ |\ \fB\-\-max\-connections\-per\-instance\fR=\fIMAX_CONNECTIONS_PER_INSTANCE\fR\ |\ \fB\-\-max\-rate\fR=\fIMAX_RATE\fR\ |\ \fB\-\-max\-rate\-per\-endpoint\fR=\fIMAX_RATE_PER_ENDPOINT\fR\ |\ \fB\-\-max\-rate\-per\-instance\fR=\fIMAX_RATE_PER_INSTANCE\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR]
.SH "DESCRIPTION"
\fBgcloud compute backend\-services update\-backend\fR updates attributes of a
backend that is already associated with a backend service. Configurable
attributes depend on the load balancing scheme and the type of backend (instance
group, zonal NEG, serverless NEG, or internet NEG). For more information, see
traffic distribution
(https://cloud.google.com/load\-balancing/docs/backend\-service#traffic_distribution).
and the Failover for Internal TCP/UDP Load Balancing overview
(https://cloud.google.com/load\-balancing/docs/internal/failover\-overview).
To add, remove, or swap backends, use the \f5gcloud compute backend\-services
remove\-backend\fR and \f5gcloud compute backend\-services add\-backend\fR
commands.
.SH "POSITIONAL ARGUMENTS"
.RS 2m
.TP 2m
\fIBACKEND_SERVICE_NAME\fR
Name of the backend service to operate on.
.RE
.sp
.SH "REQUIRED FLAGS"
.RS 2m
.TP 2m
Exactly one of these must be specified:
.RS 2m
.TP 2m
Instance Group
.RS 2m
.TP 2m
\fB\-\-instance\-group\fR=\fIINSTANCE_GROUP\fR
Name of the instance group to update in the backend service. For details on
valid instance names, refer to the criteria documented under the field 'name'
at: https://cloud.google.com/compute/docs/reference/rest/v1/instances
This flag argument must be specified if any of the other arguments in this group
are specified.
.TP 2m
At most one of these can be specified:
.RS 2m
.TP 2m
\fB\-\-instance\-group\-region\fR=\fIINSTANCE_GROUP_REGION\fR
Region of the instance group to update in the backend service. If not specified,
you might be prompted to select a region (interactive mode only).
To avoid prompting when this flag is omitted, you can set the
\f5\fIcompute/region\fR\fR property:
.RS 2m
$ gcloud config set compute/region REGION
.RE
A list of regions can be fetched by running:
.RS 2m
$ gcloud compute regions list
.RE
To unset the property, run:
.RS 2m
$ gcloud config unset compute/region
.RE
Alternatively, the region can be stored in the environment variable
\f5\fICLOUDSDK_COMPUTE_REGION\fR\fR.
.TP 2m
\fB\-\-instance\-group\-zone\fR=\fIINSTANCE_GROUP_ZONE\fR
Zone of the instance group to update in the backend service. If not specified
and the \f5\fIcompute/zone\fR\fR property isn't set, you might be prompted to
select a zone (interactive mode only).
To avoid prompting when this flag is omitted, you can set the
\f5\fIcompute/zone\fR\fR property:
.RS 2m
$ gcloud config set compute/zone ZONE
.RE
A list of zones can be fetched by running:
.RS 2m
$ gcloud compute zones list
.RE
To unset the property, run:
.RS 2m
$ gcloud config unset compute/zone
.RE
Alternatively, the zone can be stored in the environment variable
\f5\fICLOUDSDK_COMPUTE_ZONE\fR\fR.
.RE
.RE
.sp
.TP 2m
Network Endpoint Group
.RS 2m
.TP 2m
\fB\-\-network\-endpoint\-group\fR=\fINETWORK_ENDPOINT_GROUP\fR
Name of the network endpoint group to update in the backend service.
This flag argument must be specified if any of the other arguments in this group
are specified.
.TP 2m
\fB\-\-network\-endpoint\-group\-zone\fR=\fINETWORK_ENDPOINT_GROUP_ZONE\fR
Zone of the network endpoint group to update in the backend service. If not
specified and the \f5\fIcompute/zone\fR\fR property isn't set, you might be
prompted to select a zone (interactive mode only).
To avoid prompting when this flag is omitted, you can set the
\f5\fIcompute/zone\fR\fR property:
.RS 2m
$ gcloud config set compute/zone ZONE
.RE
A list of zones can be fetched by running:
.RS 2m
$ gcloud compute zones list
.RE
To unset the property, run:
.RS 2m
$ gcloud config unset compute/zone
.RE
Alternatively, the zone can be stored in the environment variable
\f5\fICLOUDSDK_COMPUTE_ZONE\fR\fR.
.RE
.RE
.RE
.sp
.SH "OPTIONAL FLAGS"
.RS 2m
.TP 2m
\fB\-\-balancing\-mode\fR=\fIBALANCING_MODE\fR
Defines how to measure whether a backend can handle additional traffic or is
fully loaded. For more information, see
https://cloud.google.com/load\-balancing/docs/backend\-service#balancing\-mode.
\fIBALANCING_MODE\fR must be one of:
.RS 2m
.TP 2m
\fBCONNECTION\fR
Available if the backend service's load balancing scheme is either
\f5INTERNAL\fR or \f5EXTERNAL\fR. Available if the backend service's protocol is
one of \f5SSL\fR, \f5TCP\fR, or \f5UDP\fR.
Spreads load based on how many concurrent connections the backend can handle.
For backend services with \-\-load\-balancing\-scheme \f5EXTERNAL\fR, you must
specify exactly one of these additional parameters: \f5\-\-max\-connections\fR,
\f5\-\-max\-connections\-per\-instance\fR, or
\f5\-\-max\-connections\-per\-endpoint\fR.
For backend services where \f5\-\-load\-balancing\-scheme\fR is \f5INTERNAL\fR,
you must omit all of these parameters.
.TP 2m
\fBCUSTOM_METRICS\fR
Spreads load based on custom defined and reported metrics.
.TP 2m
\fBRATE\fR
Available if the backend service's load balancing scheme is
\f5INTERNAL_MANAGED\fR, \f5INTERNAL_SELF_MANAGED\fR, or \f5EXTERNAL\fR.
Available if the backend service's protocol is one of HTTP, HTTPS, or HTTP/2.
Spreads load based on how many HTTP requests per second (RPS) the backend can
handle.
You must specify exactly one of these additional parameters:
\f5\-\-max\-rate\fR, \f5\-\-max\-rate\-per\-instance\fR, or
\f5\-\-max\-rate\-per\-endpoint\fR.
.TP 2m
\fBUTILIZATION\fR
Available if the backend service's load balancing scheme is
\f5INTERNAL_MANAGED\fR, \f5INTERNAL_SELF_MANAGED\fR, or \f5EXTERNAL\fR.
Available only for managed or unmanaged instance group backends.
Spreads load based on the backend utilization of instances in a backend instance
group.
The following additional parameters may be specified:
\f5\-\-max\-utilization\fR, \f5\-\-max\-rate\fR,
\f5\-\-max\-rate\-per\-instance\fR, \f5\-\-max\-connections\fR,
\f5\-\-max\-connections\-per\-instance\fR. For valid combinations, see
\f5\-\-max\-utilization\fR.
.RE
.sp
.TP 2m
\fB\-\-capacity\-scaler\fR=\fICAPACITY_SCALER\fR
Scales down the target capacity (max utilization, max rate, or max connections)
without changing the target capacity. For usage guidelines and examples, see
Capacity scaler
(https://cloud.google.com/load\-balancing/docs/backend\-service#capacity_scaler).
.TP 2m
\fB\-\-description\fR=\fIDESCRIPTION\fR
An optional, textual description for the backend.
.TP 2m
\fB\-\-failover\fR
Designates whether this is a failover backend. More than one failover backend
can be configured for a given BackendService. Not compatible with the \-\-global
flag
.TP 2m
\fB\-\-max\-utilization\fR=\fIMAX_UTILIZATION\fR
Defines the maximum target for average utilization of the backend instance
group. Supported values are \f50.0\fR (0%) through \f51.0\fR (100%). This is an
optional parameter for the \f5UTILIZATION\fR balancing mode.
You can use this parameter with other parameters for defining target capacity.
For usage guidelines, see Balancing mode combinations
(https://cloud.google.com/load\-balancing/docs/backend\-service#balancing\-mode\-combos).
.TP 2m
\fB\-\-preference\fR=\fIPREFERENCE\fR
This parameter specifies whether a backend should be fully utilized before
sending traffic to backends with the default preference. This parameter cannot
be used with regional managed instance groups and when the endpoint type of an
attached network endpoint group is INTERNET_IP_PORT, INTERNET_FQDN_PORT, or
SERVERLESS. \fIPREFERENCE\fR must be one of:
.RS 2m
.TP 2m
\fBDEFAULT\fR
This is the default setting. If the designated preferred backends don't have
enough capacity, backends in the default category are used. Traffic is
distributed between default backends based on the load balancing algorithm used.
.TP 2m
\fBPREFERRED\fR
Backends with this preference setting are used up to their capacity limits
first, while optimizing overall network latency.
.RE
.sp
.TP 2m
At most one of these can be specified:
.RS 2m
.TP 2m
\fB\-\-clear\-custom\-metrics\fR
Clears current list of CUSTOM_METRICS.
.TP 2m
\fB\-\-custom\-metrics\fR=[\fICUSTOM_METRICS\fR,...]
List of custom metrics that are used for CUSTOM_METRICS balancing mode and
WEIGHTED_ROUND_ROBIN locality load balancing policy.
Example:
.RS 2m
$ gcloud compute backend\-services update\-backend \e
\-\-custom\-metrics='name=my\-signal,maxUtilization=0.8,dryRun=true'
$ gcloud compute backend\-services update\-backend \e
\-\-custom\-metrics='name=my\-signal,maxUtilization=0.8,dryRun=true'\e
\-\-custom\-metrics='name=my\-signal2,maxUtilization=0.2'
$ gcloud compute backend\-services update\-backend \e
\-\-custom\-metrics='[{"name" : "my\-signal", "maxUtilization" :
0.8, "dryRun" : true}, {"name" : "my\-signal2", "maxUtilization" :
0.1}]'
.RE
Sets \f5custom_metrics\fR value.
.RS 2m
.TP 2m
\fBdryRun\fR
Sets \f5dryRun\fR value.
.TP 2m
\fBmaxUtilization\fR
Sets \f5maxUtilization\fR value.
.TP 2m
\fBname\fR
Required, sets \f5name\fR value.
.RE
.sp
\fBShorthand Example:\fR
.RS 2m
\-\-custom\-metrics=dryRun=boolean,maxUtilization=float,name=string \-\-custom\-metrics=dryRun=boolean,maxUtilization=float,name=string
.RE
\fBJSON Example:\fR
.RS 2m
\-\-custom\-metrics='[{"dryRun": boolean, "maxUtilization": float, "name": "string"}]'
.RE
\fBFile Example:\fR
.RS 2m
\-\-custom\-metrics=path_to_file.(yaml|json)
.RE
.TP 2m
\fB\-\-custom\-metrics\-file\fR=[\fICUSTOM_METRICS\fR,...]
File path to json file with custom metrics that are used for CUSTOM_METRICS
balancing mode and WEIGHTED_ROUND_ROBIN locality load balancing policy.
Example:
.RS 2m
$ gcloud compute backend\-services update\-backend \e
\-\-custom\-metrics\-file='customMetric.json'
.RE
Sets \f5custom_metrics_file\fR value.
.RS 2m
.TP 2m
\fBdryRun\fR
Sets \f5dryRun\fR value.
.TP 2m
\fBmaxUtilization\fR
Sets \f5maxUtilization\fR value.
.TP 2m
\fBname\fR
Required, sets \f5name\fR value.
.RE
.sp
\fBShorthand Example:\fR
.RS 2m
\-\-custom\-metrics\-file=dryRun=boolean,maxUtilization=float,name=string \-\-custom\-metrics\-file=dryRun=boolean,maxUtilization=float,name=string
.RE
\fBJSON Example:\fR
.RS 2m
\-\-custom\-metrics\-file='[{"dryRun": boolean, "maxUtilization": float, "name": "string"}]'
.RE
\fBFile Example:\fR
.RS 2m
\-\-custom\-metrics\-file=path_to_file.(yaml|json)
.RE
.RE
.sp
.TP 2m
At most one of these can be specified:
.RS 2m
.TP 2m
\fB\-\-global\fR
If set, the backend service is global.
.TP 2m
\fB\-\-region\fR=\fIREGION\fR
Region of the backend service to operate on. Overrides the default
\fBcompute/region\fR property value for this command invocation.
.RE
.sp
.TP 2m
At most one of these can be specified:
.RS 2m
.TP 2m
\fB\-\-max\-connections\fR=\fIMAX_CONNECTIONS\fR
Maximum concurrent connections that the backend can handle. Valid for network
endpoint group and instance group backends (except for regional managed instance
groups).
.TP 2m
\fB\-\-max\-connections\-per\-endpoint\fR=\fIMAX_CONNECTIONS_PER_ENDPOINT\fR
Only valid for network endpoint group backends. Defines a maximum number of
connections per endpoint if all endpoints are healthy. When one or more
endpoints are unhealthy, an effective maximum average number of connections per
healthy endpoint is calculated by multiplying \f5MAX_CONNECTIONS_PER_ENDPOINT\fR
by the number of endpoints in the network endpoint group, and then dividing by
the number of healthy endpoints.
.TP 2m
\fB\-\-max\-connections\-per\-instance\fR=\fIMAX_CONNECTIONS_PER_INSTANCE\fR
Only valid for instance group backends. Defines a maximum number of concurrent
connections per instance if all instances in the instance group are healthy.
When one or more instances are unhealthy, an effective average maximum number of
connections per healthy instance is calculated by multiplying
\f5MAX_CONNECTIONS_PER_INSTANCE\fR by the number of instances in the instance
group, and then dividing by the number of healthy instances.
.TP 2m
\fB\-\-max\-rate\fR=\fIMAX_RATE\fR
Maximum number of HTTP requests per second (RPS) that the backend can handle.
Valid for network endpoint group and instance group backends (except for
regional managed instance groups). Must not be defined if the backend is a
managed instance group using load balancing\-based autoscaling.
.TP 2m
\fB\-\-max\-rate\-per\-endpoint\fR=\fIMAX_RATE_PER_ENDPOINT\fR
Only valid for network endpoint group backends. Defines a maximum number of HTTP
requests per second (RPS) per endpoint if all endpoints are healthy. When one or
more endpoints are unhealthy, an effective maximum rate per healthy endpoint is
calculated by multiplying \f5MAX_RATE_PER_ENDPOINT\fR by the number of endpoints
in the network endpoint group, and then dividing by the number of healthy
endpoints.
.TP 2m
\fB\-\-max\-rate\-per\-instance\fR=\fIMAX_RATE_PER_INSTANCE\fR
Only valid for instance group backends. Defines a maximum number of HTTP
requests per second (RPS) per instance if all instances in the instance group
are healthy. When one or more instances are unhealthy, an effective maximum RPS
per healthy instance is calculated by multiplying \f5MAX_RATE_PER_INSTANCE\fR by
the number of instances in the instance group, and then dividing by the number
of healthy instances. This parameter is compatible with managed instance group
backends that use autoscaling based on load balancing.
.RE
.RE
.sp
.SH "GCLOUD WIDE FLAGS"
These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.
Run \fB$ gcloud help\fR for details.
.SH "NOTES"
These variants are also available:
.RS 2m
$ gcloud alpha compute backend\-services update\-backend
.RE
.RS 2m
$ gcloud beta compute backend\-services update\-backend
.RE