2020-08-01 03:09:36 +00:00
---
2022-05-30 00:08:35 +00:00
stage: Systems
2020-12-01 18:09:42 +00:00
group: Distribution
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-08-01 03:09:36 +00:00
---
2021-06-02 21:10:00 +00:00
# Load Balancer for multi-node GitLab **(FREE SELF)**
2020-08-01 03:09:36 +00:00
2021-10-19 18:13:24 +00:00
In a multi-node GitLab configuration, you need a load balancer to route
2020-08-01 03:09:36 +00:00
traffic to the application servers. The specifics on which load balancer to use
or the exact configuration is beyond the scope of GitLab documentation. We hope
that if you're managing HA systems like GitLab you have a load balancer of
choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM,
2022-07-15 12:10:10 +00:00
and Citrix NetScaler. This documentation outlines what ports and protocols
to use with GitLab.
2020-08-01 03:09:36 +00:00
## SSL
2020-11-19 21:09:07 +00:00
How do you want to handle SSL in your multi-node environment? There are several different
2020-08-01 03:09:36 +00:00
options:
- Each application node terminates SSL
2022-02-11 18:18:58 +00:00
- The load balancers terminate SSL and communication is not secure between
the load balancers and the application nodes
- The load balancers terminate SSL and communication is *secure* between the
load balancers and the application nodes
2020-08-01 03:09:36 +00:00
### Application nodes terminate SSL
2022-02-11 18:18:58 +00:00
Configure your load balancers to pass connections on port 443 as 'TCP' rather
2020-11-19 21:09:07 +00:00
than 'HTTP(S)' protocol. This passes the connection to the application nodes
NGINX service untouched. NGINX has the SSL certificate and listen on port 443.
2020-08-01 03:09:36 +00:00
See [NGINX HTTPS documentation ](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https )
for details on managing SSL certificates and configuring NGINX.
2022-02-11 18:18:58 +00:00
### Load Balancers terminate SSL without backend SSL
2020-08-01 03:09:36 +00:00
2022-02-11 18:18:58 +00:00
Configure your load balancers to use the 'HTTP(S)' protocol rather than 'TCP'.
The load balancers is be responsible for managing SSL certificates and
2020-08-01 03:09:36 +00:00
terminating SSL.
2022-07-15 12:10:10 +00:00
Because communication between the load balancers and GitLab isn't secure,
2020-08-01 03:09:36 +00:00
there is some additional configuration needed. See
[NGINX Proxied SSL documentation ](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl )
for details.
2022-02-11 18:18:58 +00:00
### Load Balancers terminate SSL with backend SSL
2020-08-01 03:09:36 +00:00
2022-02-11 18:18:58 +00:00
Configure your load balancers to use the 'HTTP(S)' protocol rather than 'TCP'.
The load balancers is responsible for managing SSL certificates that
2020-11-19 21:09:07 +00:00
end users see.
2020-08-01 03:09:36 +00:00
2022-02-11 18:18:58 +00:00
Traffic is secure between the load balancers and NGINX in this
2022-07-15 12:10:10 +00:00
scenario. There is no need to add configuration for proxied SSL because the
2020-11-19 21:09:07 +00:00
connection is secure all the way. However, configuration must be
2020-08-01 03:09:36 +00:00
added to GitLab to configure SSL certificates. See
[NGINX HTTPS documentation ](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https )
for details on managing SSL certificates and configuring NGINX.
## Ports
### Basic ports
| LB Port | Backend Port | Protocol |
| ------- | ------------ | ------------------------ |
| 80 | 80 | HTTP (*1*) |
| 443 | 443 | TCP or HTTPS (*1*) (*2*) |
| 22 | 22 | TCP |
2021-10-30 18:12:04 +00:00
- (*1*): [Web terminal ](../ci/environments/index.md#web-terminals-deprecated ) support requires
2020-08-01 03:09:36 +00:00
your load balancer to correctly handle WebSocket connections. When using
HTTP or HTTPS proxying, this means your load balancer must be configured
to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the
[web terminal ](integration/terminal.md ) integration guide for
more details.
2020-11-19 21:09:07 +00:00
- (*2*): When using HTTPS protocol for port 443, you must add an SSL
2020-08-01 03:09:36 +00:00
certificate to the load balancers. If you wish to terminate SSL at the
GitLab application server instead, use TCP protocol.
### GitLab Pages Ports
2020-11-19 21:09:07 +00:00
If you're using GitLab Pages with custom domain support you need some
2020-08-01 03:09:36 +00:00
additional port configurations.
GitLab Pages requires a separate virtual IP address. Configure DNS to point the
`pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the
[GitLab Pages documentation ](pages/index.md ) for more information.
| LB Port | Backend Port | Protocol |
| ------- | ------------- | --------- |
| 80 | Varies (*1*) | HTTP |
| 443 | Varies (*1*) | TCP (*2*) |
- (*1*): The backend port for GitLab Pages depends on the
`gitlab_pages['external_http']` and `gitlab_pages['external_https']`
setting. See [GitLab Pages documentation ](pages/index.md ) for more details.
- (*2*): Port 443 for GitLab Pages should always use the TCP protocol. Users can
configure custom domains with custom SSL, which would not be possible
if SSL was terminated at the load balancer.
### Alternate SSH Port
Some organizations have policies against opening SSH port 22. In this case,
it may be helpful to configure an alternate SSH hostname that allows users
2020-11-19 21:09:07 +00:00
to use SSH on port 443. An alternate SSH hostname requires a new virtual IP address
2020-08-01 03:09:36 +00:00
compared to the other GitLab HTTP configuration above.
Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com` .
| LB Port | Backend Port | Protocol |
| ------- | ------------ | -------- |
| 443 | 22 | TCP |
## Readiness check
2020-11-19 21:09:07 +00:00
It is strongly recommend that multi-node deployments configure load balancers to use the [readiness check ](../user/admin_area/monitoring/health_check.md#readiness ) to ensure a node is ready to accept traffic, before routing traffic to it. This is especially important when utilizing Puma, as there is a brief period during a restart where Puma doesn't accept requests.
2020-08-01 03:09:36 +00:00
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X` .
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->