diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/job_logs.md | 2 | ||||
-rw-r--r-- | doc/administration/operations/extra_sidekiq_processes.md | 2 | ||||
-rw-r--r-- | doc/administration/pages/index.md | 2 | ||||
-rw-r--r-- | doc/administration/postgresql/pgbouncer.md | 11 | ||||
-rw-r--r-- | doc/administration/postgresql/replication_and_failover.md | 6 | ||||
-rw-r--r-- | doc/administration/reference_architectures/index.md | 5 | ||||
-rw-r--r-- | doc/install/installation.md | 50 | ||||
-rw-r--r-- | doc/integration/elasticsearch.md | 3 | ||||
-rw-r--r-- | doc/raketasks/backup_restore.md | 33 | ||||
-rw-r--r-- | doc/update/README.md | 2 |
10 files changed, 93 insertions, 23 deletions
diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 7af167de4ad..18dd785705e 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -50,7 +50,7 @@ these steps to move the logs to a new location without losing any data. Jobs in progress are not affected, based on how [data flow](#data-flow) works. ```ruby - sidekiq['experimental_queue_selector'] = true + sidekiq['queue_selector'] = true sidekiq['queue_groups'] = [ "feature_category!=continuous_integration" ] diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index 1f611a50a53..1b7c0edab04 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -114,7 +114,7 @@ you list: > - [Introduced](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/45) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.8. > - [Sidekiq cluster including queue selector moved](https://gitlab.com/groups/gitlab-com/gl-infra/-/epics/181) to GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 12.10. -> - [Marked as supported](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/147) in GitLab [Core](https://about.gitlab.com/pricing/#self-managed) in GitLab 13.6. Renamed from `experimental_queue_selector` to `queue_selector`. +> - [Renamed from `experimental_queue_selector` to `queue_selector`](https://gitlab.com/gitlab-com/gl-infra/scalability/-/issues/147) in GitLab 13.6. In addition to selecting queues by name, as above, the `queue_selector` option allows queue groups to be selected in a more general way using diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index f51c6ec6836..3f0b43607b1 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -501,7 +501,7 @@ the below steps to do a no downtime transfer to a new storage location. 1. Pause Pages deployments by setting the following in `/etc/gitlab/gitlab.rb`: ```ruby - sidekiq['experimental_queue_selector'] = true + sidekiq['queue_selector'] = true sidekiq['queue_groups'] = [ "feature_category!=pages" ] diff --git a/doc/administration/postgresql/pgbouncer.md b/doc/administration/postgresql/pgbouncer.md index f09ac3052f4..951edfeaec2 100644 --- a/doc/administration/postgresql/pgbouncer.md +++ b/doc/administration/postgresql/pgbouncer.md @@ -66,6 +66,12 @@ This content has been moved to a [new location](replication_and_failover.md#conf 1. At this point, your instance should connect to the database through PgBouncer. If you are having issues, see the [Troubleshooting](#troubleshooting) section +## Backups + +Do not backup or restore GitLab through a PgBouncer connection: this will cause a GitLab outage. + +[Read more about this and how to reconfigure backups](../../raketasks/backup_restore.md#backup-and-restore-for-installations-using-pgbouncer). + ## Enable Monitoring > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3786) in GitLab 12.0. @@ -150,7 +156,10 @@ ote_pid | tls ## Procedure for bypassing PgBouncer -Some database changes have to be done directly, and not through PgBouncer. This includes database restores and GitLab upgrades (because of the database migrations). +Some database changes have to be done directly, and not through PgBouncer. + +Read more about the affected tasks: [database restores](../../raketasks/backup_restore.md#backup-and-restore-for-installations-using-pgbouncer) +and [GitLab upgrades](https://docs.gitlab.com/omnibus/update/README.html#use-postgresql-ha). 1. To find the primary node, run the following on a database node: diff --git a/doc/administration/postgresql/replication_and_failover.md b/doc/administration/postgresql/replication_and_failover.md index 53f2e40586a..efc5b5ada81 100644 --- a/doc/administration/postgresql/replication_and_failover.md +++ b/doc/administration/postgresql/replication_and_failover.md @@ -447,6 +447,12 @@ PostgreSQL's `trust_auth_cidr_addresses` in `gitlab.rb` on your database nodes. [PgBouncer error `ERROR: pgbouncer cannot connect to server`](#pgbouncer-error-error-pgbouncer-cannot-connect-to-server) in the Troubleshooting section before proceeding. +### Backups + +Do not backup or restore GitLab through a PgBouncer connection: this will cause a GitLab outage. + +[Read more about this and how to reconfigure backups](../../raketasks/backup_restore.md#backup-and-restore-for-installations-using-pgbouncer). + ### Ensure GitLab is running At this point, your GitLab instance should be up and running. Verify you're able diff --git a/doc/administration/reference_architectures/index.md b/doc/administration/reference_architectures/index.md index 6b04dad9baf..221ee430a51 100644 --- a/doc/administration/reference_architectures/index.md +++ b/doc/administration/reference_architectures/index.md @@ -95,7 +95,6 @@ have more actual perceived uptime for your users. > - Level of complexity: **Low** > - Required domain knowledge: PostgreSQL, GitLab configurations, Git -> - Supported tiers: [GitLab Core, Starter, Premium, and Ultimate](https://about.gitlab.com/pricing/) This solution is appropriate for many teams that have the default GitLab installation. With automatic backups of the GitLab repositories, configuration, and the database, @@ -107,7 +106,6 @@ is the least complex to setup. This provides a point-in-time recovery of a prede > - Level of complexity: **Medium** > - Required domain knowledge: HAProxy, shared storage, distributed systems -> - Supported tiers: [GitLab Starter, Premium, and Ultimate](https://about.gitlab.com/pricing/) This requires separating out GitLab into multiple application nodes with an added [load balancer](../load_balancer.md). The load balancer will distribute traffic @@ -127,7 +125,6 @@ to the default installation: > - Level of complexity: **Medium** > - Required domain knowledge: PostgreSQL, HAProxy, shared storage, distributed systems -> - Supported tiers: [GitLab Starter, Premium, and Ultimate](https://about.gitlab.com/pricing/) GitLab supports [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates). Single GitLab nodes can be updated with only a [few minutes of downtime](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). @@ -138,7 +135,6 @@ As long as at least one of each component is online and capable of handling the > - Level of complexity: **High** > - Required domain knowledge: PgBouncer, Repmgr or Patroni, shared storage, distributed systems -> - Supported tiers: [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/) By adding automatic failover for database systems, you can enable higher uptime with additional database nodes. This extends the default database with @@ -150,7 +146,6 @@ is recommended. > - Level of complexity: **Very High** > - Required domain knowledge: Storage replication -> - Supported tiers: [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/) [GitLab Geo](../geo/index.md) allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational instance diff --git a/doc/install/installation.md b/doc/install/installation.md index 983c7ed577f..49bce16e176 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -271,10 +271,22 @@ sudo adduser --disabled-login --gecos 'GitLab' git NOTE: In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 13.0 and later, we [require PostgreSQL 11+](requirements.md#postgresql-requirements). -1. Install the database packages: +1. Install the database packages. + For Ubuntu 20.04 and later: + + ```shell + sudo apt install -y postgresql postgresql-client libpq-dev postgresql-contrib + ``` + + For Ubuntu 18.04 and earlier, the available PostgreSQL doesn't meet the minimum + version requirement. You need to add PostgreSQL's repository: + ```shell - sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib + wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - + RELEASE=$(lsb_release -cs) echo "deb http://apt.postgresql.org/pub/repos/apt/ ${RELEASE}"-pgdg main | sudo tee /etc/apt/sources.list.d/pgdg.list + sudo apt update + sudo apt -y install postgresql-11 postgresql-client-11 libpq-dev ``` 1. Verify the PostgreSQL version you have is supported by the version of GitLab you're @@ -426,7 +438,7 @@ Clone Enterprise Edition: ```shell # Clone GitLab repository -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b <X-Y-stable> gitlab +sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab.git -b <X-Y-stable-ee> gitlab ``` Make sure to replace `<X-Y-stable>` with the stable branch that matches the @@ -1041,3 +1053,35 @@ On RedHat/CentOS: ```shell sudo yum groupinstall 'Development Tools' ``` + +### Error compiling GitLab assets + +While compiling assets, you might get the following error: + +```plaintext +Killed +error Command failed with exit code 137. +``` + +This happens because when a container runs out of memory, YARN automatically kills it. + +To fix this, first make sure you increase your machine's memory (8GB of memory should be good), +and then run the following commands: + +1. Clean the assets: + + ```shell + sudo -u git -H bundle exec rake gitlab:assets:clean RAILS_ENV=production NODE_ENV=production + ``` + +1. Run the `yarn` command again to ensure any conflicts are resolved: + + ```shell + sudo -u git -H yarn install --production --pure-lockfile + ``` + +1. Recompile assets: + + ```shell + sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + ``` diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 52275649a67..779e461872a 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -311,10 +311,11 @@ used by the GitLab Advanced Search integration. In the **Admin Area > Settings > General > Advanced Search** section, select the **Pause Elasticsearch Indexing** setting, and then save your change. - With this, all updates that should happen on your Elasticsearch index will be buffered and caught up once unpaused. +The indexing will also be automatically paused when the [**Trigger cluster reindexing**](#trigger-the-reindex-via-the-advanced-search-administration) button is used, and unpaused when the reindexing completes or aborts. + ### Setup NOTE: diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 03ffd6bd6ad..53c29f46bfa 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -890,7 +890,7 @@ Restoring repositories: Deleting tmp directories...[DONE] ``` -Next, restore `/home/git/gitlab/.secret` if necessary, as previously mentioned. +Next, restore `/home/git/gitlab/.secret` if necessary, [as previously mentioned](#restore-prerequisites). Restart GitLab: @@ -943,8 +943,16 @@ permissions on your Registry directory. This is a [known issue](https://gitlab.c On GitLab 12.2 or later, you can use `gitlab-backup restore` to avoid this issue. -Next, restore `/etc/gitlab/gitlab-secrets.json` if necessary, as previously -mentioned. +If there's a GitLab version mismatch between your backup tar file and the +installed version of GitLab, the restore command aborts with an error +message. Install the [correct GitLab version](https://packages.gitlab.com/gitlab/), +and then try again. + +NOTE: +There is a known issue with restore not working with `pgbouncer`. [Read more about backup and restore with `pgbouncer`](#backup-and-restore-for-installations-using-pgbouncer). + +Next, restore `/etc/gitlab/gitlab-secrets.json` if necessary, +[as previously mentioned](#restore-prerequisites). Reconfigure, restart and check GitLab: @@ -954,13 +962,13 @@ sudo gitlab-ctl restart sudo gitlab-rake gitlab:check SANITIZE=true ``` -If there's a GitLab version mismatch between your backup tar file and the -installed version of GitLab, the restore command aborts with an error -message. Install the [correct GitLab version](https://packages.gitlab.com/gitlab/), -and then try again. +On GitLab 13.1 and later, check [database values can be decrypted](../administration/raketasks/doctor.md) +especially if `/etc/gitlab/gitlab-secrets.json` was restored, or if a different server is +the target for the restore. -NOTE: -There is a known issue with restore not working with `pgbouncer`. [Read more about backup and restore with `pgbouncer`](#backup-and-restore-for-installations-using-pgbouncer). +```shell +sudo gitlab-rake gitlab:doctor:secrets +``` ### Restore for Docker image and GitLab Helm chart installations @@ -1068,6 +1076,13 @@ following error message is shown: ActiveRecord::StatementInvalid: PG::UndefinedTable ``` +Each time the GitLab backup runs, GitLab will start generating 500 errors and errors about missing +tables will [be logged by PostgreSQL](../administration/logs.md#postgresql-logs): + +```plaintext +ERROR: relation "tablename" does not exist at character 123 +``` + This happens because the task uses `pg_dump`, which [sets a null search path and explicitly includes the schema in every SQL query](https://gitlab.com/gitlab-org/gitlab/-/issues/23211) to address [CVE-2018-1058](https://www.postgresql.org/about/news/postgresql-103-968-9512-9417-and-9322-released-1834/). diff --git a/doc/update/README.md b/doc/update/README.md index 45cac3ec8ca..958beeeb321 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -195,7 +195,7 @@ However, for this to work there are the following requirements: 9.3. - You have to use [post-deployment migrations](../development/post_deployment_migrations.md) (included in - zero downtime update steps below). + [zero downtime update steps below](#steps)). - You are using PostgreSQL. Starting from GitLab 12.1, MySQL is not supported. - Multi-node GitLab instance. Single-node instances may experience brief interruptions [as services restart (Puma in particular)](https://docs.gitlab.com/omnibus/update/README.html#single-node-deployment). |