docs/reference-manual/src/main/asciidoc/create-http-lb-ref.adoc

type=page
status=published
title=create-http-lb-ref
next=create-http-listener.html
prev=create-http-lb-config.html
~~~~~~

= create-http-lb-ref

[[create-http-lb-ref-1]][[GSRFM00029]][[create-http-lb-ref]]

== create-http-lb-ref

Adds an existing cluster or server instance to an existing load balancer
configuration or load balancer

[[sthref259]]

=== Synopsis

[source]
----
asadmin [asadmin-options] create-http-lb-ref [--help]
--config config_name | --lbname load_balancer_name
[--lbpolicy round-robin] [--lbpolicymodule lb_policy_module]
[--healthcheckerurl url] [--healthcheckerinterval 10]
[--healthcheckertimeout 10] [--lbenableallinstances=true]
[--lbenableallapplications=true] [--lbweight instance=weight[:instance=weight]*]
target
----

[[sthref260]]

=== Description

Use the `create-http-lb-ref` subcommand to:

* Add an existing cluster or server instance to an existing load
balancer configuration or load balancer. The load balancer forwards the
requests to the clustered and standalone instances it references.
* Set the load balancing policy to round-robin, weighted round-robin, or
to a user-defined policy.
* Configure a health checker for the load balancer. Any health checker
settings defined here apply only to the target. If you do not create a
health checker with this subcommand, use `create-http-health-checker`.
* Enable all instances in the target cluster for load balancing, or use
`enable-http-lb-server` to enable them individually.
* Enable all applications deployed to the target for load balancing, or
use `enable-http-lb-application` to enable them individually.


[NOTE]
====
This subcommand is only applicable to {productName}. This
subcommand is not applicable to {productName}.
====


[[sthref261]]

=== Options

asadmin-options::
  Options for the `asadmin` utility. For information about these
  options, see the link:asadmin.html#asadmin-1m[`asadmin`(1M)] help page.
`--help`::
`-?`::
  Displays the help text for the subcommand.
`--config`::
  Specifies which load balancer configuration to which to add clusters
  and server instances. Specify either a load balancer configuration or
  a load balancer. Specifying both results in an error.
`--lbname`::
  Specifies the load balancer to which to add clusters and server
  instances. Specify either a load balancer configuration or a load
  balancer. Specifying both results in an error.
`--lbpolicy`::
  The policy the load balancer follows. Valid values are `round-robin`,
  `weighted-round-robin`, and `user-defined`. If you choose
  user-defined, specify a load balancer policy module with the
  `lbpolicymodule` option. If you choose `weighted-round-robin` assign
  weights to the server instances using the `configure-lb-weight`
  subcommand. The default is `round-robin`.
`--lbpolicymodule`::
  If your load balancer policy is `user-defined`, use this option to
  specify the full path and name of the shared library of your load
  balancing policy module. The shared library needs to be in a location
  accessible by the web server.
`--healthcheckerurl`::
  The URL to ping to determine whether the instance is healthy.
`--healthcheckerinterval`::
  The interval in seconds the health checker waits between checks of an
  unhealthy instance to see whether it has become healthy. The default
  value is 30 seconds. A value of 0 disables the health checker.
`--healthcheckertimeout`::
  The interval in seconds the health checker waits to receive a response
  from an instance. If the health checker has not received a response in
  this interval, the instance is considered unhealthy. The default is
  10.
`--lbenableallinstances`::
  Enables all instances in the target cluster for load balancing. If the
  target is a server instance, enables that instance for load balancing.
  The default value is true.
`--lbenableallapplications`::
  Enables all applications deployed to the target cluster or instance
  for load balancing. The default value is true.
`--lbweight`::
  The name of the instance and the weight you are assigning it. The
  weight must be an integer. The pairs of instances and weights are
  separated by colons. For example `instance1=1:instance2=4` means that
  for every five requests, one goes to instance1 and four go to
  instance2. A weight of 1 is the default.

[[sthref262]]

=== Operands

target::
  Specifies which cluster or instance to add to the load balancer. Valid
  values are:
+
  * cluster_name- Specifies that requests for this cluster will be
  handled by the load balancer.
  * stand-alone_instance_name- Specifies that requests for this
  standalone instance will be handled by the load balancer.

[[sthref263]]

=== Examples

[[GSRFM480]][[sthref264]]

==== Example 1   Adding a Cluster Reference to a Load Balancer Configuration

This example adds a reference to a cluster named `cluster2` to a load
balancer configuration named `mylbconfig`.

[source]
----
asadmin> create-http-lb-ref --config mylbconfig cluster2

Command create-http-lb-ref executed successfully.
----

[[GSRFM481]][[sthref265]]

==== Example 2   Adding a Cluster Reference to a Load Balancer

This example adds a reference to a cluster named `cluster2` to a load
balancer named `mylb`.

[source]
----
asadmin> create-http-lb-ref --lbname mylb cluster2

Command create-http-lb-ref executed successfully.
----

[[GSRFM482]][[sthref266]]

==== Example 3   Configuring a Health Checker and Load Balancer Policy

This example configures a health checker and load balancing policy, and
enables the load balancer for instances and applications.

[source]
----
asadmin> create-http-lb-ref --config mylbconfig --lbpolicy weighted-round-robin
--healthcheckerinterval 40 --healthcheckertimeout 20
--lbenableallinstances=true --lbenableallapplications=true cluster2

Command create-http-lb-ref executed successfully.
----

[[GSRFM483]][[sthref267]]

==== Example 4   Setting a User-Defined Load Balancing Policy

This example sets a user-defined load balancing policy.

[source]
----
asadmin> create-http-lb-ref --lbpolicy user-defined --lbpolicymodule /user/modules/module.so
--config mylbconfig cluster2

Command create-http-lb-ref executed successfully.
----

[[sthref268]]

=== Exit Status

0::
  subcommand executed successfully
1::
  error in executing the subcommand

[[sthref269]]

=== See Also

link:asadmin.html#asadmin-1m[`asadmin`(1M)]

link:configure-lb-weight.html#configure-lb-weight-1[`configure-lb-weight`(1)],
link:create-http-health-checker.html#create-http-health-checker-1[`create-http-health-checker`(1)],
link:delete-http-lb-ref.html#delete-http-lb-ref-1[`delete-http-lb-ref`(1)],
link:enable-http-lb-application.html#enable-http-lb-application-1[`enable-http-lb-application`(1)],
link:enable-http-lb-server.html#enable-http-lb-server-1[`enable-http-lb-server`(1)],
link:list-http-lb-configs.html#list-http-lb-configs-1[`list-http-lb-configs`(1)],
link:list-http-lbs.html#list-http-lbs-1[`list-http-lbs`(1)]