add_upstream
The `add_upstream` directive allows the configuration of upstreams by adding predefined upstream servers, including optional parameters for customization.
Description
The add_upstream directive is part of the NGINX Combined Upstreams module and is utilized within an upstream block to incorporate additional upstream servers defined by their existing configurations. Its primary function is to extend the current upstream's server pool by referencing other upstream configurations, with the first parameter being mandatory to specify the upstream to be added. It facilitates a way to reuse upstream definitions while maintaining their attributes, such as weights and fail counts.
In addition to the required upstream name, the directive accepts optional arguments. The backup parameter can be appended to designate all added upstream servers as backup servers, ensuring they are only used when regular servers are unavailable. The weight=N parameter allows you to modify the initial weights of the servers from the referenced upstream by applying a multiplicative factor, effectively enabling fine-tuned load balancing across multiple upstreams. This feature can be particularly useful for scaling services by leveraging pre-defined upstream configurations without full replication of configurations across multiple upstream directives.
Overall, the add_upstream directive enhances the modularity and manageability of NGINX configurations, allowing administrators to build complex upstream architectures without redundancy in configuration code.
Config Example
upstream combined {
add_upstream upstream1; # Add upstream 1
add_upstream upstream2 weight=2; # Add upstream 2 with weight factor
server some_another_server; # Additional server if needed
add_upstream upstream3 backup; # Add upstream 3 as a backup
}Ensure the referenced upstream is defined before using it in add_upstream.
Using weight and backup together can lead to confusion if not properly documented in the configuration.
Overly complex upstream definitions can hinder performance and make debugging difficult. Consider simplifying where possible.