diff options
Diffstat (limited to 'doc/install')
| -rw-r--r-- | doc/install/README.md | 8 | ||||
| -rw-r--r-- | doc/install/digitaloceandocker.md | 5 | ||||
| -rw-r--r-- | doc/install/google_cloud_platform/index.md | 4 | ||||
| -rw-r--r-- | doc/install/installation.md | 40 | ||||
| -rw-r--r-- | doc/install/kubernetes/gitlab_chart.md | 436 | ||||
| -rw-r--r-- | doc/install/kubernetes/gitlab_runner_chart.md | 175 | ||||
| -rw-r--r-- | doc/install/kubernetes/index.md | 46 | ||||
| -rw-r--r-- | doc/install/requirements.md | 19 |
8 files changed, 713 insertions, 20 deletions
diff --git a/doc/install/README.md b/doc/install/README.md index d35709266e4..bc831a37735 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -18,10 +18,10 @@ the hardware requirements. Useful for unsupported systems like *BSD. For an overview of the directory structure, read the [structure documentation](structure.md). - [Docker](https://docs.gitlab.com/omnibus/docker/) - Install GitLab using Docker. -- [Installation on Google Cloud Platform](google_cloud_platform/index.md) - Install - GitLab on Google Cloud Platform using our official image. -- [Digital Ocean and Docker](digitaloceandocker.md) - Install GitLab quickly - on DigitalOcean using Docker. +- [Installing in Kubernetes](kubernetes/index.md) - Install GitLab into a Kubernetes + Cluster using our official Helm Chart Repository. +- Testing only! [DigitalOcean and Docker Machine](digitaloceandocker.md) - + Quickly test any version of GitLab on DigitalOcean using Docker Machine. ## Database diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 820060a489b..8efc0530b8a 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,4 +1,7 @@ -# Digital Ocean and Docker +# Digital Ocean and Docker Machine test environment + +## Warning. This guide is for quickly testing different versions of GitLab and +## not recommended for ease of future upgrades or keeping the data you create. ## Initial setup diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 26506111548..35220119e9b 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -2,6 +2,10 @@  +>**Important note:** +GitLab has no official images in Google Cloud Platform yet. This guide serves +as a template for when the GitLab VM will be available. + The fastest way to get started on [Google Cloud Platform (GCP)][gcp] is through the [Google Cloud Launcher][launcher] program. diff --git a/doc/install/installation.md b/doc/install/installation.md index a2248a38435..5bba405f159 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -109,14 +109,19 @@ Then select 'Internet Site' and press enter to confirm the hostname. ## 2. Ruby -**Note:** The current supported Ruby version is 2.3.x. GitLab 9.0 dropped support -for Ruby 2.1.x. +The Ruby interpreter is required to run GitLab. + +**Note:** The current supported Ruby (MRI) version is 2.3.x. GitLab 9.0 dropped +support for Ruby 2.1.x. The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab in production, frequently leads to hard to diagnose problems. For example, GitLab Shell is called from OpenSSH, and having a version manager can prevent pushing and pulling over SSH. Version managers are not supported and we strongly -advise everyone to follow the instructions below to use a system Ruby. +advise everyone to follow the instructions below to use a system Ruby. + +Linux distributions generally have older versions of Ruby available, so these +instructions are designed to install Ruby from the official source code. Remove the old Ruby 1.8 if present: @@ -132,7 +137,7 @@ Download Ruby and compile it: make sudo make install -Install the Bundler Gem: +Then install the Bundler Gem: sudo gem install bundler --no-ri --no-rdoc @@ -289,9 +294,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 9-0-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 9-2-stable gitlab -**Note:** You can change `9-0-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `9-2-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -423,6 +428,11 @@ which is the recommended location. sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production +You can specify a different Git repository by providing it as an extra paramter: + + sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production + + ### Initialize Database and Activate Advanced Features sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production @@ -459,20 +469,26 @@ Make GitLab start on boot: ### Install Gitaly -As of GitLab 9.0 Gitaly is an **optional** component. Its -configuration is expected to change in GitLab 9.1. It is OK to wait -with setting up Gitaly until you upgrade to GitLab 9.1 or later. +As of GitLab 9.1 Gitaly is an **optional** component. Its +configuration is still changing regularly. It is OK to wait +with setting up Gitaly until you upgrade to GitLab 9.2 or later. # Fetch Gitaly source with Git and compile with Go sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly]" RAILS_ENV=production +You can specify a different Git repository by providing it as an extra paramter: + + sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,https://example.com/gitaly.git]" RAILS_ENV=production + +Next, make sure gitaly configured: + # Restrict Gitaly socket access sudo chmod 0700 /home/git/gitlab/tmp/sockets/private sudo chown git /home/git/gitlab/tmp/sockets/private - # Configure Gitaly - echo 'GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket' | \ - sudo -u git tee -a /home/git/gitaly/env + # If you are using non-default settings you need to update config.toml + cd /home/git/gitaly + sudo -u git -H editor config.toml # Enable Gitaly in the init script echo 'gitaly_enabled=true' | sudo tee -a /etc/default/gitlab diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md new file mode 100644 index 00000000000..2d7edbe16e4 --- /dev/null +++ b/doc/install/kubernetes/gitlab_chart.md @@ -0,0 +1,436 @@ +# GitLab Helm Chart + +The `gitlab` Helm chart deploys GitLab into your Kubernetes cluster. + +This chart includes the following: + +- Deployment using the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce) or [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee) container image +- ConfigMap containing the `gitlab.rb` contents that configure [Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options) +- Persistent Volume Claims for Data, Config, Logs, and Registry Storage +- A Kubernetes service +- Optional Redis deployment using the [Redis Chart](https://github.com/kubernetes/charts/tree/master/stable/redis) (defaults to enabled) +- Optional PostgreSQL deployment using the [PostgreSQL Chart](https://github.com/kubernetes/charts/tree/master/stable/postgresql) (defaults to enabled) +- Optional Ingress (defaults to disabled) + +## Prerequisites + +- _At least_ 3 GB of RAM available on your cluster, in chunks of 1 GB +- Kubernetes 1.4+ with Beta APIs enabled +- [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure +- The ability to point a DNS entry or URL at your GitLab install +- The `kubectl` CLI installed locally and authenticated for the cluster +- The Helm Client installed locally +- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init` +- The GitLab Helm Repo [added to your Helm Client](index.md#add-the-gitlab-helm-repository) + +## Configuring GitLab + +Create a `values.yaml` file for your GitLab configuration. See the +[Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md) +for information on how your values file will override the defaults. + +The default configuration can always be [found in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab/values.yaml), in the chart repository. + +### Required configuration + +In order for GitLab to function, your config file **must** specify the following: + +- An `externalUrl` that GitLab will be reachable at. + +### Choosing GitLab Edition + +The Helm chart defaults to installing GitLab CE. This can be controlled by setting the `edition` variable in your values. + +Setting `edition` to GitLab Enterprise Edition (EE) in your `values.yaml` + +```yaml +edition: EE + +externalUrl: 'http://gitlab.example.com' +``` + +### Choosing a different GitLab release version + +The version of GitLab installed is based on the `edition` setting (see [section](#choosing-gitlab-edition) above), and +the value of the corresponding helm setting: `ceImage` or `eeImage`. + +```yaml +## GitLab Edition +## ref: https://about.gitlab.com/products/ +## - CE - Community Edition +## - EE - Enterprise Edition - (requires license issued by GitLab Inc) +## +edition: CE + +## GitLab CE image +## ref: https://hub.docker.com/r/gitlab/gitlab-ce/tags/ +## +ceImage: gitlab/gitlab-ce:9.1.2-ce.0 + +## GitLab EE image +## ref: https://hub.docker.com/r/gitlab/gitlab-ee/tags/ +## +eeImage: gitlab/gitlab-ee:9.1.2-ee.0 +``` + +The different images can be found in the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce/tags/) and [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee/tags/) +repositories on Docker Hub + +> **Note:** +There is no guarantee that other release versions of GitLab, other than what are +used by default in the chart, will be supported by a chart install. + + +### Custom Omnibus GitLab configuration + +In addition to the configuration options provided for GitLab in the Helm Chart, you can also pass any custom configuration +that is valid for the [Omnibus GitLab Configuration](https://docs.gitlab.com/omnibus/settings/configuration.html). + +The setting to pass these values in is `omnibusConfigRuby`. It accepts any valid +Ruby code that could used in the Omnibus `/etc/gitlab/gitlab.rb` file. In +Kubernetes, the contents will be stored in a ConfigMap. + +Example setting: + +```yaml +omnibusConfigRuby: | + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; +``` + +### Persistent storage + +By default, persistent storage is enabled for GitLab and the charts it depends +on (Redis and PostgreSQL). + +Components can have their claim size set from your `values.yaml`, and each +component allows you to optionally configure the `storageClass` variable so you +can take advantage of faster drives on your cloud provider. + +Basic configuration: + +```yaml +## Enable persistence using Persistent Volume Claims +## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/ +## ref: https://docs.gitlab.com/ce/install/requirements.html#storage +## +persistence: + ## This volume persists generated configuration files, keys, and certs. + ## + gitlabEtc: + enabled: true + size: 1Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + accessMode: ReadWriteOnce + ## This volume is used to store git data and other project files. + ## ref: https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory + ## + gitlabData: + enabled: true + size: 10Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + accessMode: ReadWriteOnce + gitlabRegistry: + enabled: true + size: 10Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + + postgresql: + persistence: + # storageClass: + size: 10Gi + ## Configuration values for the Redis dependency. + ## ref: https://github.com/kubernetes/charts/blob/master/stable/redis/README.md + ## + redis: + persistence: + # storageClass: + size: 10Gi +``` + +>**Note:** +You can make use of faster SSD drives by adding a [StorageClass] to your cluster +and using the `storageClass` setting in the above config to the name of +your new storage class. + +### Routing + +By default, the GitLab chart uses a service type of `LoadBalancer` which will +result in the GitLab service being exposed externally using your cloud provider's +load balancer. + +This field is configurable in your `values.yml` by setting the top-level +`serviceType` field. See the [Service documentation][kube-srv] for more +information on the possible values. + +#### Ingress routing + +Optionally, you can enable the Chart's ingress for use by an ingress controller +deployed in your cluster. + +To enable the ingress, edit its section in your `values.yaml`: + +```yaml +ingress: + ## If true, gitlab Ingress will be created + ## + enabled: true + + ## gitlab Ingress hostnames + ## Must be provided if Ingress is enabled + ## + hosts: + - gitlab.example.com + + ## gitlab Ingress annotations + ## + annotations: + kubernetes.io/ingress.class: nginx +``` + +You must also provide the list of hosts that the ingress will use. In order for +you ingress controller to work with the GitLab Ingress, you will need to specify +its class in an annotation. + +>**Note:** +The Ingress alone doesn't expose GitLab externally. You need to have a Ingress controller setup to do that. +Setting up an Ingress controller can be as simple as installing the `nginx-ingress` helm chart. But be sure +to read the [documentation](https://github.com/kubernetes/charts/blob/master/stable/nginx-ingress/README.md) + +### External database + +You can configure the GitLab Helm chart to connect to an external PostgreSQL +database. + +>**Note:** +This is currently our recommended approach for a Production setup. + +To use an external database, in your `values.yaml`, disable the included +PostgreSQL dependency, then configure access to your database: + +```yaml +dbHost: "<reachable postgres hostname>" +dbPassword: "<password for the user with access to the db>" +dbUsername: "<user with read/write access to the database>" +dbDatabase: "<database name on postgres to connect to for GitLab>" + +postgresql: + # Sets whether the PostgreSQL helm chart is used as a dependency + enabled: false +``` + +Be sure to check the GitLab documentation on how to +[configure the external database](../requirements.md#postgresql-requirements) + +You can also configure the chart to use an external Redis server, but this is +not required for basic production use: + +```yaml +dbHost: "<reachable redis hostname>" +dbPassword: "<password>" + +redis: + # Sets whether the Redis helm chart is used as a dependency + enabled: false +``` + +### Sending email + +By default, the GitLab container will not be able to send email from your cluster. +In order to send email, you should configure SMTP settings in the +`omnibusConfigRuby` section, as per the [GitLab Omnibus documentation](https://docs.gitlab.com/omnibus/settings/smtp.html). + +>**Note:** +Some cloud providers restrict emails being sent out on SMTP, so you will have +to use a SMTP service that is supported by your provider. See this +[Google Cloud Platform page](https://cloud.google.com/compute/docs/tutorials/sending-mail/) +as and example. + +Here is an example configuration for Mailgun SMTP support: + +```yaml +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + # SMTP settings + gitlab_rails['smtp_enable'] = true + gitlab_rails['smtp_address'] = "smtp.mailgun.org" + gitlab_rails['smtp_port'] = 2525 # High port needed for Google Cloud + gitlab_rails['smtp_authentication'] = "plain" + gitlab_rails['smtp_enable_starttls_auto'] = false + gitlab_rails['smtp_user_name'] = "postmaster@mg.your-mail-domain" + gitlab_rails['smtp_password'] = "you-password" + gitlab_rails['smtp_domain'] = "mg.your-mail-domain" +``` + +### HTTPS configuration + +To setup HTTPS access to your GitLab server, first you need to configure the +chart to use the [ingress](#ingress-routing). + +GitLab's config should be updated to support [proxied SSL](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl). + +In addition to having a Ingress Controller deployed and the basic ingress +settings configured, you will also need to specify in the ingress settings +which hosts to use HTTPS for. + +Make sure `externalUrl` now includes `https://` instead of `http://` in its +value, and update the `omnibusConfigRuby` section: + +```yaml +externalUrl: 'https://gitlab.example.com' + +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + # These are the settings needed to support proxied SSL + nginx['listen_port'] = 80 + nginx['listen_https'] = false + nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support + + hosts: + - gitlab.example.com + + ## gitlab Ingress TLS configuration + ## Secrets must be created in the namespace, and is not done for you in this chart + ## + tls: + - secretName: gitlab-tls + hosts: + - gitlab.example.com +``` + +You will need to create the named secret in your cluster, specifying the private +and public certificate pair using the format outlined in the +[ingress documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). + +Alternatively, you can use the `kubernetes.io/tls-acme` annotation, and install +the `kube-lego` chart to your cluster to have Let's Encrypt issue your +certificate. See the [kube-lego documentation](https://github.com/kubernetes/charts/blob/master/stable/kube-lego/README.md) +for more information. + +### Enabling the GitLab Container Registry + +The GitLab Registry is disabled by default but can be enabled by providing an +external URL for it in the configuration. In order for the Registry to be easily +used by GitLab CI and your Kubernetes cluster, you will need to set it up with +a TLS certificate, so these examples will include the ingress settings for that +as well. See the [HTTPS Configuration section](#https-configuration) +for more explanation on some of these settings. + +Example config: + +```yaml +externalUrl: 'https://gitlab.example.com' + +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + registry_external_url 'https://registry.example.com'; + + # These are the settings needed to support proxied SSL + nginx['listen_port'] = 80 + nginx['listen_https'] = false + nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + registry_nginx['listen_port'] = 80 + registry_nginx['listen_https'] = false + registry_nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support + + hosts: + - gitlab.example.com + - registry.example.com + + ## gitlab Ingress TLS configuration + ## Secrets must be created in the namespace, and is not done for you in this chart + ## + tls: + - secretName: gitlab-tls + hosts: + - gitlab.example.com + - registry.example.com +``` + +## Installing GitLab using the Helm Chart + +Once you [have configured](#configuration) GitLab in your `values.yml` file, +run the following: + +```bash +helm install --namespace <NAMESPACE> --name gitlab -f <CONFIG_VALUES_FILE> gitlab/gitlab +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where you want to install GitLab. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom + configuration. See the [Configuration](#configuration) section to create it. + +## Updating GitLab using the Helm Chart + +Once your GitLab Chart is installed, configuration changes and chart updates +should we done using `helm upgrade` + +```bash +helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom + [configuration] (#configuration). +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab`. + +## Uninstalling GitLab using the Helm Chart + +To uninstall the GitLab Chart, run the following: + +```bash +helm delete --namespace <NAMESPACE> <RELEASE-NAME> +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed. +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab`. + +[kube-srv]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types +[storageclass]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#storageclasses diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md new file mode 100644 index 00000000000..dbd9ae3f70c --- /dev/null +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -0,0 +1,175 @@ +# GitLab Runner Helm Chart + +The `gitlab-runner` Helm chart deploys a GitLab Runner instance into your +Kubernetes cluster. + +This chart configures the Runner to: + +- Run using the GitLab Runner [Kubernetes executor](https://docs.gitlab.com/runner/install/kubernetes.html) +- For each new job it receives from [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), it will provision a + new pod within the specified namespace to run it. + +## Prerequisites + +- Your GitLab Server's API is reachable from the cluster +- Kubernetes 1.4+ with Beta APIs enabled +- The `kubectl` CLI installed locally and authenticated for the cluster +- The Helm Client installed locally +- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init` +- The GitLab Helm Repo added to your Helm Client. See [Adding GitLab Helm Repo](index.md#add-the-gitlab-helm-repository) + +## Configuring GitLab Runner using the Helm Chart + +Create a `values.yaml` file for your GitLab Runner configuration. See [Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md) +for information on how your values file will override the defaults. + +The default configuration can always be found in the [values.yaml](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository. + +### Required configuration + +In order for GitLab Runner to function, your config file **must** specify the following: + + - `gitlabURL` - the GitLab Server URL (with protocol) to register the runner against + - `runnerRegistrationToken` - The Registration Token for adding new Runners to the GitLab Server. This must be + retrieved from your GitLab Instance. See the [GitLab Runner Documentation](../../ci/runners/README.md#creating-and-registering-a-runner) for more information. + +### Other configuration + +The rest of the configuration is [documented in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository. + +Here is a snippet of the important settings: + +```yaml +## The GitLab Server URL (with protocol) that want to register the runner against +## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register +## +gitlabURL: http://gitlab.your-domain.com/ + +## The Registration Token for adding new Runners to the GitLab Server. This must +## be retreived from your GitLab Instance. +## ref: https://docs.gitlab.com/ce/ci/runners/README.html#creating-and-registering-a-runner +## +runnerRegistrationToken: "" + +## Configure the maximum number of concurrent jobs +## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section +## +concurrent: 10 + +## Defines in seconds how often to check GitLab for a new builds +## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section +## +checkInterval: 30 + +## Configuration for the Pods that that the runner launches for each new job +## +runners: + ## Default container image to use for builds when none is specified + ## + image: ubuntu:16.04 + + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind + ## + privileged: false + + ## Namespace to run Kubernetes jobs in (defaults to 'default') + ## + # namespace: + + ## Build Container specific configuration + ## + builds: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + + ## Service Container specific configuration + ## + services: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + + ## Helper Container specific configuration + ## + helpers: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + +``` + +### Running Docker-in-Docker containers with GitLab Runners + +See [Running Privileged Containers for the Runners](#running-privileged-containers-for-the-runners) for how to enable it, +and the [GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds) on running dind. + +### Running privileged containers for the Runners + +You can tell the GitLab Runner to run using privileged containers. You may need +this enabled if you need to use the Docker executable within your GitLab CI jobs. + +This comes with several risks that you can read about in the +[GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds). + +If you are okay with the risks, and your GitLab CI Runner instance is registered +against a specific project in GitLab that you trust the CI jobs of, you can +enable privileged mode in `values.yaml`: + +```yaml +runners: + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind + ## + privileged: true +``` + +## Installing GitLab Runner using the Helm Chart + +Once you [have configured](#configuration) GitLab Runner in your `values.yml` file, +run the following: + +```bash +helm install --namepace <NAMEPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner +``` + +- `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the + [Configuration](#configuration) section to create it. + +## Updating GitLab Runner using the Helm Chart + +Once your GitLab Runner Chart is installed, configuration changes and chart updates should we done using `helm upgrade` + +```bash +helm upgrade --namepace <NAMEPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner +``` + +Where: +- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the + [Configuration](#configuration) section to create it. +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab-runner`. + +## Uninstalling GitLab Runner using the Helm Chart + +To uninstall the GitLab Runner Chart, run the following: + +```bash +helm delete --namespace <NAMESPACE> <RELEASE-NAME> +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab-runner`. diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md new file mode 100644 index 00000000000..cae5837a12b --- /dev/null +++ b/doc/install/kubernetes/index.md @@ -0,0 +1,46 @@ +# Installing GitLab in Kubernetes +> Officially supported cloud providers are Google Container Service and Azure Container Service. +> Officially supported schedulers are Kubernetes and Terraform. + +The easiest method to deploy GitLab in [Kubernetes](https://kubernetes.io/) is +to take advantage of the official GitLab Helm charts. [Helm] is a package +management tool for Kubernetes, allowing apps to be easily managed via their +Charts. A [Chart] is a detailed description of the application including how it +should be deployed, upgraded, and configured. + +The GitLab Helm repository is located at https://charts.gitlab.io. +You can report any issues related to GitLab's Helm Charts at +https://gitlab.com/charts/charts.gitlab.io/issues. +Contributions and improvements are also very welcome. + +## Prerequisites + +To use the charts, the Helm tool must be installed and initialized. The best +place to start is by reviewing the [Helm Quick Start Guide][helm-quick]. + +## Add the GitLab Helm repository + +Once Helm has been installed, the GitLab chart repository must be added: + +```bash +helm repo add gitlab https://charts.gitlab.io +``` + +After adding the repository, Helm must be re-initialized: + +```bash +helm init +``` + +## Using the GitLab Helm Charts + +GitLab makes available two Helm Charts, one for the GitLab server and another +for the Runner. More detailed information on installing and configuring each +Chart can be found below: + +- [Install GitLab](gitlab_chart.md) +- [Install GitLab Runner](gitlab_runner_chart.md) + +[chart]: https://github.com/kubernetes/charts +[helm-quick]: https://github.com/kubernetes/helm/blob/master/docs/quickstart.md +[helm]: https://github.com/kubernetes/helm/blob/master/README.md diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 7b586138f42..2e456557d77 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -122,13 +122,26 @@ To change the Unicorn workers when you have the Omnibus package please see [the We currently support the following databases: -- PostgreSQL (recommended) +- PostgreSQL - MySQL/MariaDB -If you want to run the database separately, expect a size of about 1 MB per user. +We _highly_ recommend the use of PostgreSQL instead of MySQL/MariaDB as not all +features of GitLab may work with MySQL/MariaDB. For example, MySQL does not have +the right features to support nested groups in an efficient manner; see +<https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> for more information +about this. Existing users using GitLab with MySQL/MariaDB are advised to +migrate to PostgreSQL instead. + +The server running the database should have _at least_ 5-10 GB of storage +available, though the exact requirements depend on the size of the GitLab +installation (e.g. the number of users, projects, etc). ### PostgreSQL Requirements +As of GitLab 9.0, PostgreSQL 9.2 or newer is required, and earlier versions are +not supported. We highly recommend users to use at least PostgreSQL 9.6 as this +is the PostgreSQL version used for development and testing. + Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every GitLab database. This extension can be enabled (using a PostgreSQL super user) by running the following query for every database: @@ -162,4 +175,4 @@ about it, check the [Prometheus documentation](../administration/monitoring/prom We support the current and the previous major release of Firefox, Chrome/Chromium, Safari and Microsoft browsers (Microsoft Edge and Internet Explorer 11). -Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version.
\ No newline at end of file +Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version. |