1---
2stage: Enablement
3group: Distribution
4info: 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
5type: reference
6---
7
8# Load Balancer for multi-node GitLab **(FREE SELF)**
9
10In a multi-node GitLab configuration, you need a load balancer to route
11traffic to the application servers. The specifics on which load balancer to use
12or the exact configuration is beyond the scope of GitLab documentation. We hope
13that if you're managing HA systems like GitLab you have a load balancer of
14choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM,
15and Citrix Net Scaler. This documentation outlines what ports and protocols
16you need to use with GitLab.
17
18## SSL
19
20How do you want to handle SSL in your multi-node environment? There are several different
21options:
22
23- Each application node terminates SSL
24- The load balancer(s) terminate SSL and communication is not secure between
25  the load balancer(s) and the application nodes
26- The load balancer(s) terminate SSL and communication is *secure* between the
27  load balancer(s) and the application nodes
28
29### Application nodes terminate SSL
30
31Configure your load balancer(s) to pass connections on port 443 as 'TCP' rather
32than 'HTTP(S)' protocol. This passes the connection to the application nodes
33NGINX service untouched. NGINX has the SSL certificate and listen on port 443.
34
35See [NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
36for details on managing SSL certificates and configuring NGINX.
37
38### Load Balancer(s) terminate SSL without backend SSL
39
40Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'.
41The load balancer(s) is be responsible for managing SSL certificates and
42terminating SSL.
43
44Since communication between the load balancer(s) and GitLab isn't secure,
45there is some additional configuration needed. See
46[NGINX Proxied SSL documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl)
47for details.
48
49### Load Balancer(s) terminate SSL with backend SSL
50
51Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'.
52The load balancer(s) is responsible for managing SSL certificates that
53end users see.
54
55Traffic is secure between the load balancer(s) and NGINX in this
56scenario. There is no need to add configuration for proxied SSL since the
57connection is secure all the way. However, configuration must be
58added to GitLab to configure SSL certificates. See
59[NGINX HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
60for details on managing SSL certificates and configuring NGINX.
61
62## Ports
63
64### Basic ports
65
66| LB Port | Backend Port | Protocol                 |
67| ------- | ------------ | ------------------------ |
68| 80      | 80           | HTTP (*1*)               |
69| 443     | 443          | TCP or HTTPS (*1*) (*2*) |
70| 22      | 22           | TCP                      |
71
72- (*1*): [Web terminal](../ci/environments/index.md#web-terminals-deprecated) support requires
73  your load balancer to correctly handle WebSocket connections. When using
74  HTTP or HTTPS proxying, this means your load balancer must be configured
75  to pass through the `Connection` and `Upgrade` hop-by-hop headers. See the
76  [web terminal](integration/terminal.md) integration guide for
77  more details.
78- (*2*): When using HTTPS protocol for port 443, you must add an SSL
79  certificate to the load balancers. If you wish to terminate SSL at the
80  GitLab application server instead, use TCP protocol.
81
82### GitLab Pages Ports
83
84If you're using GitLab Pages with custom domain support you need some
85additional port configurations.
86GitLab Pages requires a separate virtual IP address. Configure DNS to point the
87`pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the
88[GitLab Pages documentation](pages/index.md) for more information.
89
90| LB Port | Backend Port  | Protocol  |
91| ------- | ------------- | --------- |
92| 80      | Varies (*1*)  | HTTP      |
93| 443     | Varies (*1*)  | TCP (*2*) |
94
95- (*1*): The backend port for GitLab Pages depends on the
96  `gitlab_pages['external_http']` and `gitlab_pages['external_https']`
97  setting. See [GitLab Pages documentation](pages/index.md) for more details.
98- (*2*): Port 443 for GitLab Pages should always use the TCP protocol. Users can
99  configure custom domains with custom SSL, which would not be possible
100  if SSL was terminated at the load balancer.
101
102### Alternate SSH Port
103
104Some organizations have policies against opening SSH port 22. In this case,
105it may be helpful to configure an alternate SSH hostname that allows users
106to use SSH on port 443. An alternate SSH hostname requires a new virtual IP address
107compared to the other GitLab HTTP configuration above.
108
109Configure DNS for an alternate SSH hostname such as `altssh.gitlab.example.com`.
110
111| LB Port | Backend Port | Protocol |
112| ------- | ------------ | -------- |
113| 443     | 22           | TCP      |
114
115## Readiness check
116
117It 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.
118
119<!-- ## Troubleshooting
120
121Include any troubleshooting steps that you can foresee. If you know beforehand what issues
122one might have when setting this up, or when something is changed, or on upgrading, it's
123important to describe those, too. Think of things that may go wrong and include them here.
124This is important to minimize requests for support, and to avoid doc comments with
125questions that you know someone might ask.
126
127Each scenario can be a third-level heading, e.g. `### Getting error message X`.
128If you have none to add when creating a doc, leave this section in place
129but commented out to help encourage others to add to it in the future. -->
130