Add online terminal documentation
This commit is contained in:
parent
7b7781654e
commit
d2212a8b5f
|
@ -34,6 +34,7 @@
|
||||||
- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
|
- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter.
|
||||||
- [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
|
- [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages.
|
||||||
- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
|
- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab.
|
||||||
|
- [Online terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab.
|
||||||
- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
|
- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars.
|
||||||
- [Log system](administration/logs.md) Log system.
|
- [Log system](administration/logs.md) Log system.
|
||||||
- [Environment Variables](administration/environment_variables.md) to configure GitLab.
|
- [Environment Variables](administration/environment_variables.md) to configure GitLab.
|
||||||
|
|
|
@ -11,9 +11,9 @@ you need to use with GitLab.
|
||||||
## Basic ports
|
## Basic ports
|
||||||
|
|
||||||
| LB Port | Backend Port | Protocol |
|
| LB Port | Backend Port | Protocol |
|
||||||
| ------- | ------------ | -------- |
|
| ------- | ------------ | --------------- |
|
||||||
| 80 | 80 | HTTP |
|
| 80 | 80 | HTTP [^1] |
|
||||||
| 443 | 443 | HTTPS [^1] |
|
| 443 | 443 | HTTPS [^1] [^2] |
|
||||||
| 22 | 22 | TCP |
|
| 22 | 22 | TCP |
|
||||||
|
|
||||||
## GitLab Pages Ports
|
## GitLab Pages Ports
|
||||||
|
@ -25,8 +25,8 @@ GitLab Pages requires a separate VIP. Configure DNS to point the
|
||||||
|
|
||||||
| LB Port | Backend Port | Protocol |
|
| LB Port | Backend Port | Protocol |
|
||||||
| ------- | ------------ | -------- |
|
| ------- | ------------ | -------- |
|
||||||
| 80 | Varies [^2] | HTTP |
|
| 80 | Varies [^3] | HTTP |
|
||||||
| 443 | Varies [^2] | TCP [^3] |
|
| 443 | Varies [^3] | TCP [^4] |
|
||||||
|
|
||||||
## Alternate SSH Port
|
## Alternate SSH Port
|
||||||
|
|
||||||
|
@ -50,13 +50,19 @@ Read more on high-availability configuration:
|
||||||
1. [Configure NFS](nfs.md)
|
1. [Configure NFS](nfs.md)
|
||||||
1. [Configure the GitLab application servers](gitlab.md)
|
1. [Configure the GitLab application servers](gitlab.md)
|
||||||
|
|
||||||
[^1]: When using HTTPS protocol for port 443, you will need to add an SSL
|
[^1]: [Terminal support](../../ci/environments.md#terminal-support) 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/terminal.md) 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
|
certificate to the load balancers. If you wish to terminate SSL at the
|
||||||
GitLab application server instead, use TCP protocol.
|
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']`
|
`gitlab_pages['external_http']` and `gitlab_pages['external_https']`
|
||||||
setting. See [GitLab Pages documentation][gitlab-pages] for more details.
|
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
|
configure custom domains with custom SSL, which would not be possible
|
||||||
if SSL was terminated at the load balancer.
|
if SSL was terminated at the load balancer.
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,73 @@
|
||||||
|
# Online terminals
|
||||||
|
|
||||||
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690)
|
||||||
|
in GitLab 8.15. Only project masters and owners can access online terminals.
|
||||||
|
|
||||||
|
With the introduction of the [Kubernetes](../../project_services/kubernetes.md)
|
||||||
|
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](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/terminal.md).
|
||||||
|
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](https://gitlab.com/gitlab-org/gitlab-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/sidekiq.md)
|
||||||
|
* 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/load_balancer.md) 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](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html)
|
||||||
|
* [NGINX](https://www.nginx.com/blog/websocket-nginx/)
|
||||||
|
* [HAProxy](http://blog.haproxy.com/2012/11/07/websockets-load-balancing-with-haproxy/)
|
||||||
|
* [Varnish](https://www.varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html)
|
||||||
|
|
||||||
|
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 `/terminal.ws`
|
||||||
|
(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/8.14-to-8.15.md#nginx-configuration)
|
||||||
|
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,
|
Deployments are created when [jobs] deploy versions of code to environments,
|
||||||
so every environment can have one or more deployments. GitLab keeps track of
|
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
|
your deployments, so you always know what is currently being deployed on your
|
||||||
servers.
|
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
|
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
|
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/cycle_analytics.md).
|
it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
|
||||||
Double the benefit!
|
Double the benefit!
|
||||||
|
|
||||||
|
## Terminal support
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
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/kubernetes.md) 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`!
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
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/koding.md) for online
|
||||||
|
development.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
While this is fine for deploying to some stable environments like staging or
|
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
|
production, what happens for branches? So far we haven't defined anything
|
||||||
regarding deployments for branches other than `master`. Dynamic environments
|
regarding deployments for branches other than `master`. Dynamic environments
|
||||||
|
@ -524,6 +566,7 @@ Below are some links you may find interesting:
|
||||||
[Pipelines]: pipelines.md
|
[Pipelines]: pipelines.md
|
||||||
[jobs]: yaml/README.md#jobs
|
[jobs]: yaml/README.md#jobs
|
||||||
[yaml]: yaml/README.md
|
[yaml]: yaml/README.md
|
||||||
|
[kubernetes-service]: ../project_services/kubernetes.md]
|
||||||
[environments]: #environments
|
[environments]: #environments
|
||||||
[deployments]: #deployments
|
[deployments]: #deployments
|
||||||
[permissions]: ../user/permissions.md
|
[permissions]: ../user/permissions.md
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
After Width: | Height: | Size: 115 KiB |
|
@ -47,3 +47,17 @@ GitLab CI build environment:
|
||||||
- `KUBE_TOKEN`
|
- `KUBE_TOKEN`
|
||||||
- `KUBE_NAMESPACE`
|
- `KUBE_NAMESPACE`
|
||||||
- `KUBE_CA_PEM` - only if a custom CA bundle was specified
|
- `KUBE_CA_PEM` - only if a custom CA bundle was specified
|
||||||
|
|
||||||
|
## Terminal support
|
||||||
|
|
||||||
|
>**NOTE:**
|
||||||
|
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/environments.md#terminal-support)
|
||||||
|
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
|
||||||
|
`app=$CI_ENVIRONMENT_SLUG`.
|
||||||
|
|
|
@ -33,6 +33,7 @@ The following table depicts the various user permission levels in a project.
|
||||||
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
|
| See a container registry | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| See environments | | ✓ | ✓ | ✓ | ✓ |
|
| See environments | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| Create new environments | | | ✓ | ✓ | ✓ |
|
| Create new environments | | | ✓ | ✓ | ✓ |
|
||||||
|
| Use environment terminals | | | | ✓ | ✓ |
|
||||||
| Stop environments | | | ✓ | ✓ | ✓ |
|
| Stop environments | | | ✓ | ✓ | ✓ |
|
||||||
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
|
| See a list of merge requests | | ✓ | ✓ | ✓ | ✓ |
|
||||||
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
|
| Manage/Accept merge requests | | | ✓ | ✓ | ✓ |
|
||||||
|
|
Loading…
Reference in New Issue