Commit d2212a8b authored by Nick Thomas's avatar Nick Thomas

Add online terminal documentation

parent 7b778165
......@@ -34,6 +34,7 @@
- [Integration](integration/ How to integrate with systems such as JIRA, Redmine, Twitter.
- [Issue closing pattern](administration/ Customize how to close an issue from commit messages.
- [Koding](administration/integration/ Set up Koding to use with GitLab.
- [Online terminals](administration/integration/ Provide terminal access to environments from within GitLab.
- [Libravatar](customization/ Use Libravatar instead of Gravatar for user avatars.
- [Log system](administration/ Log system.
- [Environment Variables](administration/ to configure GitLab.
......@@ -10,11 +10,11 @@ you need to use with GitLab.
## Basic ports
| LB Port | Backend Port | Protocol |
| ------- | ------------ | -------- |
| 80 | 80 | HTTP |
| 443 | 443 | HTTPS [^1] |
| 22 | 22 | TCP |
| LB Port | Backend Port | Protocol |
| ------- | ------------ | --------------- |
| 80 | 80 | HTTP [^1] |
| 443 | 443 | HTTPS [^1] [^2] |
| 22 | 22 | TCP |
## GitLab Pages Ports
......@@ -25,8 +25,8 @@ GitLab Pages requires a separate VIP. Configure DNS to point the
| LB Port | Backend Port | Protocol |
| ------- | ------------ | -------- |
| 80 | Varies [^2] | HTTP |
| 443 | Varies [^2] | TCP [^3] |
| 80 | Varies [^3] | HTTP |
| 443 | Varies [^3] | TCP [^4] |
## Alternate SSH Port
......@@ -50,13 +50,19 @@ Read more on high-availability configuration:
1. [Configure NFS](
1. [Configure the GitLab application servers](
[^1]: When using HTTPS protocol for port 443, you will need to add an SSL
[^1]: [Terminal support](../../ci/ requires
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
[online terminal](../integration/ integration guide for
more details.
[^2]: When using HTTPS protocol for port 443, you will need to add an SSL
certificate to the load balancers. If you wish to terminate SSL at the
GitLab application server instead, use TCP protocol.
[^2]: The backend port for GitLab Pages depends on the
[^3]: The backend port for GitLab Pages depends on the
`gitlab_pages['external_http']` and `gitlab_pages['external_https']`
setting. See [GitLab Pages documentation][gitlab-pages] for more details.
[^3]: Port 443 for GitLab Pages should always use the TCP protocol. Users can
[^4]: 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.
# Online terminals
> [Introduced](
in GitLab 8.15. Only project masters and owners can access online terminals.
With the introduction of the [Kubernetes](../../project_services/
project service, GitLab gained the ability to store and use credentials for a
Kubernetes cluster. One of the things it uses these credentials for is providing
access to [online terminals](../../ci/environments.html#online-terminals)
for environments.
## How it works
A detailed overview of the architecture of online terminals and how they work
can be found in [this document](
In brief:
* GitLab relies on the user to provide their own Kubernetes credentials, and to
appropriately label the pods they create when deploying.
* When a user navigates to the terminal page for an environment, they are served
a JavaScript application that opens a WebSocket connection back to GitLab.
* The WebSocket is handled in [Workhorse](,
rather than the Rails application server.
* Workhorse queries Rails for connection details and user permissions; Rails
queries Kubernetes for them in the background, using [Sidekiq](../troubleshooting/
* Workhorse acts as a proxy server between the user's browser and the Kubernetes
API, passing WebSocket frames between the two.
* Workhorse regularly polls Rails, terminating the WebSocket connection if the
user no longer has permission to access the terminal, or if the connection
details have changed.
## Enabling and disabling terminal support
As online terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers
through to the next one in the chain. If you installed Gitlab using Omnibus, or
from source, starting with GitLab 8.15, this should be done by the default
configuration, so there's no need for you to do anything.
However, if you run a [load balancer](../high_availability/ in
front of GitLab, you may need to make some changes to your configuration. These
guides document the necessary steps for a selection of popular reverse proxies:
* [Apache](
* [NGINX](
* [HAProxy](
* [Varnish](
Workhorse won't let WebSocket requests through to non-WebSocket endpoints, so
it's safe to enable support for these headers globally. If you'd rather had a
narrower set of rules, you can restrict it to URLs ending with `/`
(although this may still have a few false positives).
If you installed from source, or have made any configuration changes to your
Omnibus installation before upgrading to 8.15, you may need to make some
changes to your configuration. See the [8.14 to 8.15 upgrade](../../update/
document for more details.
If you'd like to disable online terminal support in GitLab, just stop passing
the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse
proxy in the chain. For most users, this will be the NGINX server bundled with
Omnibus Gitlab, in which case, you need to:
* Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file
* Ensure the whole block is uncommented, and then comment out or remove the
`Connection` and `Upgrade` lines.
For your own load balancer, just reverse the configuration changes recommended
by the above guides.
When these headers are not passed through, Workhorse will return a
`400 Bad Request` response to users attempting to use an online terminal. In
turn, they will receive a `Connection failed` message.
......@@ -25,7 +25,9 @@ Environments are like tags for your CI jobs, describing where code gets deployed
Deployments are created when [jobs] deploy versions of code to environments,
so every environment can have one or more deployments. GitLab keeps track of
your deployments, so you always know what is currently being deployed on your
servers. If you have a deployment service such as [Kubernetes][kubernetes-service]
enabled for your project, you can use it to assist with your deployments, and
can even access a terminal for your environment from within GitLab!
To better understand how environments and deployments work, let's consider an
example. We assume that you have already created a project in GitLab and set up
......@@ -233,6 +235,46 @@ Remember that if your environment's name is `production` (all lowercase), then
it will get recorded in [Cycle Analytics](../user/project/
Double the benefit!
## Terminal support
Terminal support was added in GitLab 8.15 and is only available to project
masters and owners.
If you deploy to your environments with the help of a deployment service (e.g.,
the [Kubernetes](../project_services/ service), GitLab can open
a terminal session to your environment! This is a very powerful feature that
allows you to debug issues without leaving the comfort of your web browser. To
enable it, just follow the instructions given in the service documentation.
Once enabled, your environments will gain a "terminal" button:
![Terminal button on environment index](img/environments_terminal_button_on_index.png)
You can also access the terminal button from the page for a specific environment:
![Terminal button for an environment](img/environments_terminal_button_on_show.png)
Wherever you find it, clicking the button will take you to a separate page to
establish the terminal session:
![Terminal page](img/environments_terminal_page.png)
This works just like any other terminal - you'll be in the container created
by your deployment, so you can run shell commands and get responses in real
time, check the logs, try out configuration or code tweaks, etc. You can open
multiple terminals to the same environment - they each get their own shell
session - and even a multiplexer like `screen` or `tmux`!
Container-based deployments often lack basic tools (like an editor), and may
be stopped or restarted at any time. If this happens, you will lose all your
changes! Treat this as a debugging tool, not a comprehensive online IDE. You
can use [Koding](../administration/integration/ for online
While this is fine for deploying to some stable environments like staging or
production, what happens for branches? So far we haven't defined anything
regarding deployments for branches other than `master`. Dynamic environments
......@@ -524,6 +566,7 @@ Below are some links you may find interesting:
[jobs]: yaml/
[yaml]: yaml/
[kubernetes-service]: ../project_services/]
[environments]: #environments
[deployments]: #deployments
[permissions]: ../user/
......@@ -47,3 +47,17 @@ GitLab CI build environment:
- `KUBE_CA_PEM` - only if a custom CA bundle was specified
## Terminal support
Added in GitLab 8.15. You must be the project owner or have `master` permissions
to use terminals. Support is currently limited to the first container in the
first pod of your environment.
When enabled, the Kubernetes service adds online [terminal support](../ci/
to your environments. This is based on the `exec` functionality found in
Docker and Kubernetes, so you get a new shell session within your existing
containers. To use this integration, you should deploy to Kubernetes using
the deployment variables above, ensuring any pods you create are labelled with
......@@ -33,6 +33,7 @@ The following table depicts the various user permission levels in a project.
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
| See environments | | ✓ | ✓ | ✓ | ✓ |
| Create new environments | | | ✓ | ✓ | ✓ |
| Use environment terminals | | | | ✓ | ✓ |
| Stop environments | | | ✓ | ✓ | ✓ |
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment