diff options
Diffstat (limited to 'doc/administration')
| -rw-r--r-- | doc/administration/gitaly/index.md | 6 | ||||
| -rw-r--r-- | doc/administration/high_availability/nfs.md | 9 | ||||
| -rw-r--r-- | doc/administration/img/circuitbreaker_config.png | bin | 29130 -> 0 bytes | |||
| -rw-r--r-- | doc/administration/img/failing_storage.png | bin | 16291 -> 0 bytes | |||
| -rw-r--r-- | doc/administration/index.md | 3 | ||||
| -rw-r--r-- | doc/administration/integration/koding.md | 246 | ||||
| -rw-r--r-- | doc/administration/integration/plantuml.md | 4 | ||||
| -rw-r--r-- | doc/administration/job_artifacts.md | 3 | ||||
| -rw-r--r-- | doc/administration/monitoring/prometheus/gitlab_metrics.md | 3 | ||||
| -rw-r--r-- | doc/administration/operations/filesystem_benchmarking.md | 55 | ||||
| -rw-r--r-- | doc/administration/operations/index.md | 4 | ||||
| -rw-r--r-- | doc/administration/repository_storage_paths.md | 49 |
12 files changed, 72 insertions, 310 deletions
diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index b5e2b5448f7..e1b2a0a24eb 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -25,15 +25,13 @@ gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` To change a Gitaly setting in installations from source you can edit -`/home/git/gitaly/config.toml`. +`/home/git/gitaly/config.toml`. Changes will be applied when you run +`service gitlab restart`. ```toml prometheus_listen_addr = "localhost:9236" ``` -Changes to `/home/git/gitaly/config.toml` are applied when you run `service -gitlab restart`. - ## Client-side GRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 95e2caf0cad..040c9ecae55 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -3,6 +3,11 @@ You can view information and options set for each of the mounted NFS file systems by running `nfsstat -m` and `cat /etc/fstab`. +NOTE: **Note:** Filesystem performance has a big impact on overall GitLab +performance, especially for actions that read or write to Git repositories. See +[Filesystem Performance Benchmarking](../operations/filesystem_benchmarking.md) +for steps to test filesystem performance. + ## NFS Server features ### Required features @@ -87,7 +92,7 @@ Mount `/gitlab-nfs` then use the following Omnibus configuration to move each data location to a subdirectory: ```ruby -git_data_dirs({"default" => "/gitlab-nfs/gitlab-data/git-data"}) +git_data_dirs({"default" => { "path" => "/gitlab-nfs/gitlab-data/git-data"} }) user['home'] = '/gitlab-nfs/gitlab-data/home' gitlab_rails['uploads_directory'] = '/gitlab-nfs/gitlab-data/uploads' gitlab_rails['shared_path'] = '/gitlab-nfs/gitlab-data/shared' @@ -133,7 +138,7 @@ following are the 5 locations need to be shared: | Location | Description | Default configuration | | -------- | ----------- | --------------------- | -| `/var/opt/gitlab/git-data` | Git repository data. This will account for a large portion of your data | `git_data_dirs({"default" => "/var/opt/gitlab/git-data"})` +| `/var/opt/gitlab/git-data` | Git repository data. This will account for a large portion of your data | `git_data_dirs({"default" => { "path" => "/var/opt/gitlab/git-data"} })` | `/var/opt/gitlab/.ssh` | SSH `authorized_keys` file and keys used to import repositories from some other Git services | `user['home'] = '/var/opt/gitlab/'` | `/var/opt/gitlab/gitlab-rails/uploads` | User uploaded attachments | `gitlab_rails['uploads_directory'] = '/var/opt/gitlab/gitlab-rails/uploads'` | `/var/opt/gitlab/gitlab-rails/shared` | Build artifacts, GitLab Pages, LFS objects, temp files, etc. If you're using LFS this may also account for a large portion of your data | `gitlab_rails['shared_path'] = '/var/opt/gitlab/gitlab-rails/shared'` diff --git a/doc/administration/img/circuitbreaker_config.png b/doc/administration/img/circuitbreaker_config.png Binary files differdeleted file mode 100644 index 20233276055..00000000000 --- a/doc/administration/img/circuitbreaker_config.png +++ /dev/null diff --git a/doc/administration/img/failing_storage.png b/doc/administration/img/failing_storage.png Binary files differdeleted file mode 100644 index 652d7dcb5d7..00000000000 --- a/doc/administration/img/failing_storage.png +++ /dev/null diff --git a/doc/administration/index.md b/doc/administration/index.md index d713247983b..8e6fa9563c7 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -118,10 +118,9 @@ created in snippets, wikis, and repos. ## Continuous Integration settings - [Enable/disable GitLab CI/CD](../ci/enable_or_disable_ci.md#site-wide-admin-setting): Enable or disable GitLab CI/CD for your instance. -- [GitLab CI/CD admin settings](../user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration time. +- [GitLab CI/CD admin settings](../user/admin_area/settings/continuous_integration.md): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time. - [Job artifacts](job_artifacts.md): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully). - [Job traces](job_traces.md): Information about the job traces (logs). -- [Artifacts size and expiration](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size): Define maximum artifacts limits and expiration date. - [Register Shared and specific Runners](../ci/runners/README.md#registering-a-shared-runner): Learn how to register and configure Shared and specific Runners to your own instance. - [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for Shared Runners. - [Enable/disable Auto DevOps](../topics/autodevops/index.md#enabling-auto-devops): Enable or disable Auto DevOps for your instance. diff --git a/doc/administration/integration/koding.md b/doc/administration/integration/koding.md deleted file mode 100644 index def0add0061..00000000000 --- a/doc/administration/integration/koding.md +++ /dev/null @@ -1,246 +0,0 @@ -# Koding & GitLab - -> **Notes:** -> - **As of GitLab 10.0, the Koding integration is deprecated and will be removed -> in a future version. The option to configure it is removed from GitLab's admin -> area.** -> - [Introduced][ce-5909] in GitLab 8.11. - -This document will guide you through installing and configuring Koding with -GitLab. - -First of all, to be able to use Koding and GitLab together you will need public -access to your server. This allows you to use single sign-on from GitLab to -Koding and using vms from cloud providers like AWS. Koding has a registry for -VMs, called Kontrol and it runs on the same server as Koding itself, VMs from -cloud providers register themselves to Kontrol via the agent that we put into -provisioned VMs. This agent is called Klient and it provides Koding to access -and manage the target machine. - -Kontrol and Klient are based on another technology called -[Kite](https://github.com/koding/kite), that we have written at Koding. Which is a -microservice framework that allows you to develop microservices easily. - -## Requirements - -### Hardware - -Minimum requirements are; - - - 2 cores CPU - - 3G RAM - - 10G Storage - -If you plan to use AWS to install Koding it is recommended that you use at -least a `c3.xlarge` instance. - -### Software - - - [Git](https://git-scm.com) - - [Docker](https://www.docker.com) - - [docker-compose](https://www.docker.com/products/docker-compose) - -Koding can run on most of the UNIX based operating systems, since it's shipped -as containerized with Docker support, it can work on any operating system that -supports Docker. - -Required services are: - -- **PostgreSQL** - Kontrol and Service DB provider -- **MongoDB** - Main DB provider the application -- **Redis** - In memory DB used by both application and services -- **RabbitMQ** - Message Queue for both application and services - -which are also provided as a Docker container by Koding. - - -## Getting Started with Development Versions - - -### Koding - -You can run `docker-compose` environment for developing koding by -executing commands in the following snippet. - -```bash -git clone https://github.com/koding/koding.git -cd koding -docker-compose -f docker-compose-init.yml run init -docker-compose up -``` - -This should start koding on `localhost:8090`. - -By default there is no team exists in Koding DB. You'll need to create a team -called `gitlab` which is the default team name for GitLab integration in the -configuration. To make things in order it's recommended to create the `gitlab` -team first thing after setting up Koding. - - -### GitLab - -To install GitLab to your environment for development purposes it's recommended -to use GitLab Development Kit which you can get it from -[here](https://gitlab.com/gitlab-org/gitlab-development-kit). - -After all those steps, gitlab should be running on `localhost:3000` - - -## Integration - -Integration includes following components; - - - Single Sign On with OAuth from GitLab to Koding - - System Hook integration for handling GitLab events on Koding - (`project_created`, `user_joined` etc.) - - Service endpoints for importing/executing stacks from GitLab to Koding - (`Run/Try on IDE (Koding)` buttons on GitLab Projects, Issues, MRs) - -As it's pointed out before, you will need public access to this machine that -you've installed Koding and GitLab on. Better to use a domain but a static IP -is also fine. - -For IP based installation you can use [nip.io](https://nip.io) service which is -free and provides DNS resolution to IP based requests like following; - - - 127.0.0.1.nip.io -> resolves to 127.0.0.1 - - foo.bar.baz.127.0.0.1.nip.io -> resolves to 127.0.0.1 - - and so on... - -As Koding needs subdomains for team names; `foo.127.0.0.1.nip.io` requests for -a running koding instance on `127.0.0.1` server will be handled as `foo` team -requests. - - -### GitLab Side - -You need to enable Koding integration from Settings under Admin Area. To do -that login with an Admin account and do followings; - -- open [http://127.0.0.1:3000/admin/application_settings](http://127.0.0.1:3000/admin/application_settings) -- scroll to bottom of the page until Koding section -- check `Enable Koding` checkbox -- provide GitLab team page for running Koding instance as `Koding URL`* - * For `Koding URL` you need to provide the gitlab integration enabled team on -your Koding installation. Team called `gitlab` has integration on Koding out -of the box, so if you didn't change anything your team on Koding should be -`gitlab`. - -So, if your Koding is running on `http://1.2.3.4.nip.io:8090` your URL needs -to be `http://gitlab.1.2.3.4.nip.io:8090`. You need to provide the same host -with your Koding installation here. - - -#### Registering Koding for OAuth integration - -We need `Application ID` and `Secret` to enable login to Koding via GitLab -feature and to do that you need to register running Koding as a new application -to your running GitLab application. Follow -[these](http://docs.gitlab.com/ce/integration/oauth_provider.html) steps to -enable this integration. - -Redirect URI should be `http://gitlab.127.0.0.1:8090/-/oauth/gitlab/callback` -which again you need to _replace `127.0.0.1` with your instance public IP._ - -Take a copy of `Application ID` and `Secret` that is generated by the GitLab -application, we will need those on _Koding Part_ of this guide. - - -#### Registering system hooks to Koding (optional) - -Koding can take actions based on the events generated by GitLab application. -This feature is still in progress and only following events are processed by -Koding at the moment; - - - user_create - - user_destroy - -All system events are handled but not implemented on Koding side. - -To enable this feature you need to provide a `URL` and a `Secret Token` to your -GitLab application. Open your admin area on your GitLab app from -[http://127.0.0.1:3000/admin/hooks](http://127.0.0.1:3000/admin/hooks) -and provide `URL` as `http://gitlab.127.0.0.1:8090/-/api/gitlab` which is the -endpoint to handle GitLab events on Koding side. Provide a `Secret Token` and -keep a copy of it, we will need it on _Koding Part_ of this guide. - -_(replace `127.0.0.1` with your instance public IP)_ - - -### Koding Part - -If you followed the steps in GitLab part we should have followings to enable -Koding part integrations; - - - `Application ID` and `Secret` for OAuth integration - - `Secret Token` for system hook integration - - Public address of running GitLab instance - - -#### Start Koding with GitLab URL - -Now we need to configure Koding with all this information to get things ready. -If it's already running please stop koding first. - -##### From command-line - -Replace followings with the ones you got from GitLab part of this guide; - -```bash -cd koding -docker-compose run \ - --service-ports backend \ - /opt/koding/scripts/bootstrap-container build \ - --host=**YOUR_IP**.nip.io \ - --gitlabHost=**GITLAB_IP** \ - --gitlabPort=**GITLAB_PORT** \ - --gitlabToken=**SECRET_TOKEN** \ - --gitlabAppId=**APPLICATION_ID** \ - --gitlabAppSecret=**SECRET** -``` - -##### By updating configuration - -Alternatively you can update `gitlab` section on -`config/credentials.default.coffee` like following; - -``` -gitlab = - host: '**GITLAB_IP**' - port: '**GITLAB_PORT**' - applicationId: '**APPLICATION_ID**' - applicationSecret: '**SECRET**' - team: 'gitlab' - redirectUri: '' - systemHookToken: '**SECRET_TOKEN**' - hooksEnabled: yes -``` - -and start by only providing the `host`; - -```bash -cd koding -docker-compose run \ - --service-ports backend \ - /opt/koding/scripts/bootstrap-container build \ - --host=**YOUR_IP**.nip.io \ -``` - -#### Enable Single Sign On - -Once you restarted your Koding and logged in with your username and password -you need to activate oauth authentication for your user. To do that - - - Navigate to Dashboard on Koding from; - `http://gitlab.**YOUR_IP**.nip.io:8090/Home/my-account` - - Scroll down to Integrations section - - Click on toggle to turn On integration in GitLab integration section - -This will redirect you to your GitLab instance and will ask your permission ( -if you are not logged in to GitLab at this point you will be redirected after -login) once you accept you will be redirected to your Koding instance. - -From now on you can login by using `SIGN IN WITH GITLAB` button on your Login -screen in your Koding instance. - -[ce-5909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5909 diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 293036f2f4b..b61c5409a56 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -80,10 +80,10 @@ our AsciiDoc snippets, wikis and repos using delimited blocks: ``` [plantuml, format="png", id="myDiagram", width="200px"] - -- + ---- Bob->Alice : hello Alice -> Bob : Go Away - -- + ---- ``` - **reStructuredText** diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 757865ea2c5..2feac1fd3b0 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -98,7 +98,7 @@ _The artifacts are stored by default in If you don't want to use the local disk where GitLab is installed to store the artifacts, you can use an object storage like AWS S3 instead. This configuration relies on valid AWS credentials to be configured already. -Use an [Object storage option][os] like AWS S3 to store job artifacts. +Use an object storage option like AWS S3 to store job artifacts. ### Object Storage Settings @@ -315,4 +315,3 @@ memory and disk I/O. [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository" -[os]: https://docs.gitlab.com/administration/job_artifacts.html#using-object-storage diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 7bc92ae77ee..c6fd7ef7360 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -45,9 +45,6 @@ The following metrics are available: | redis_ping_success | Gauge | 9.4 | Whether or not the last redis ping succeeded | | redis_ping_latency_seconds | Gauge | 9.4 | Round trip time of the redis ping | | user_session_logins_total | Counter | 9.4 | Counter of how many users have logged in | -| filesystem_circuitbreaker_latency_seconds | Gauge | 9.5 | Time spent validating if a storage is accessible | -| filesystem_circuitbreaker | Gauge | 9.5 | Whether or not the circuit for a certain shard is broken or not | -| circuitbreaker_storage_check_duration_seconds | Histogram | 10.3 | Time a single storage probe took | | failed_login_captcha_total | Gauge | 11.0 | Counter of failed CAPTCHA attempts during login | | successful_login_captcha_total | Gauge | 11.0 | Counter of successful CAPTCHA attempts during login | diff --git a/doc/administration/operations/filesystem_benchmarking.md b/doc/administration/operations/filesystem_benchmarking.md new file mode 100644 index 00000000000..44018e966e0 --- /dev/null +++ b/doc/administration/operations/filesystem_benchmarking.md @@ -0,0 +1,55 @@ +# Filesystem Performance Benchmarking + +Filesystem performance has a big impact on overall GitLab performance, +especially for actions that read or write to Git repositories. This information +will help benchmark filesystem performance against known good and bad real-world +systems. + +Normally when talking about filesystem performance the biggest concern is +with Network Filesystems (NFS). However, even some local disks can have slow +IO. The information on this page can be used for either scenario. + +## Write Performance + +The following one-line command is a quick benchmark for filesystem write +performance. This will write 1,000 small files to the directory in which it is +executed. + +1. Change into the root of the appropriate + [repository storage path](../repository_storage_paths.md). +1. Create a temporary directory for the test so it's easy to remove the files later: + + ```sh + mkdir test; cd test + ``` +1. Run the command: + + ```sh + time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + ``` +1. Remove the test files: + + ```sh + cd ../; rm -rf test + ``` + +The output of the `time for ...` command will look similar to the following. The +important metric is the `real` time. + +```sh +$ time for i in {0..1000}; do echo 'test' > "test${i}.txt"; done + +real 0m0.116s +user 0m0.025s +sys 0m0.091s +``` + +From experience with multiple customers, the following are ranges that indicate +whether your filesystem performance is satisfactory or less than ideal: + +| Rating | Benchmark result | +|:----------|:------------------------| +| Best | Less than 10 seconds | +| OK | 10-18 seconds | +| Poor | 18-25 seconds | +| Very poor | Greater than 25 seconds | diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index dea98cb8197..a16fc7ae74f 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -16,3 +16,7 @@ to restart Sidekiq. indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). +- [Filesystem Performance Benchmarking](filesystem_benchmarking.md): Filesystem +performance can have a big impact on GitLab performance, especially for actions +that read or write Git repositories. This information will help benchmark +filesystem performance against known good and bad real-world systems. diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 7ea7ed48850..c03f23a8931 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -97,55 +97,6 @@ be stored via the **Application Settings** in the Admin area. Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be randomly placed on one of the selected paths. -## Handling failing repository storage - -> [Introduced][ce-11449] in GitLab 9.5. - -When GitLab detects access to the repositories storage fails repeatedly, it can -gracefully prevent attempts to access the storage. This might be useful when -the repositories are stored somewhere on the network. - -This can be configured from the admin interface: - - - -**Number of access attempts**: The number of attempts GitLab will make to access a -storage when probing a shard. - -**Number of failures before backing off**: The number of failures after which -GitLab will start temporarily disabling access to a storage shard on a host. - -**Maximum git storage failures:** The number of failures of after which GitLab will -completely prevent access to the storage. The number of failures can be reset in -the admin interface: `https://gitlab.example.com/admin/health_check` or using the -[api](../api/repository_storage_health.md) to allow access to the storage again. - -**Seconds to wait after a storage failure:** When access to a storage fails. GitLab -will prevent access to the storage for the time specified here. This allows the -filesystem to recover. - -**Seconds before reseting failure information:** The time in seconds GitLab will -keep failure information. When no failures occur during this time, information about the -mount is reset. - -**Seconds to wait for a storage access attempt:** The time in seconds GitLab will -try to access storage. After this time a timeout error will be raised. - -To enable the circuitbreaker for repository storage you can flip the feature flag from a rails console: - -``` -Feature.enable('git_storage_circuit_breaker') -``` - -Alternatively it can be enabled by setting `true` in the `GIT_STORAGE_CIRCUIT_BREAKER` environment variable. -This approach would be used when enabling the circuit breaker on a single host. - -When storage failures occur, this will be visible in the admin interface like this: - - - -To allow access to all storages, click the `Reset git storage health information` button. - [ce-4578]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4578 [restart-gitlab]: restart_gitlab.md#installations-from-source [reconfigure-gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure |
