Skip to content

G
gitlab-ce
Commit 3b267450 authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Redirect Kubernetes installation to the charts docs 

With the advent of the new chart docs, we should deprecate the old ones
and redirect them to the new ones.
parent 0f04d4b2
Hide whitespace changes
Inline Side-by-side
Showing with 46 additions and 931 deletions
doc/administration/git_protocol.md
View file @ 3b267450
......@@ -31,7 +31,7 @@ From the client side, `git` `v2.18.0` or newer must be installed.
From the server side, if we want to configure SSH we need to set the `sshd`
server to accept the `GIT_PROTOCOL` environment.
In installations using [GitLab Helm Charts](../install/kubernetes/gitlab_chart.md)
In installations using [GitLab Helm Charts](https://docs.gitlab.com/charts/)
and [All-in-one docker image](https://docs.gitlab.com/omnibus/docker/), the SSH
service is already configured to accept the `GIT_PROTOCOL` environment and users
need not do anything more.
......
doc/install/README.md
View file @ 3b267450
......@@ -55,9 +55,9 @@ need to be aware of:
- It can be more expensive for smaller installations. The default installation
requires more resources than a single node Omnibus deployment, as most services
are deployed in a redundant fashion.
- There are some feature [limitations to be aware of](kubernetes/gitlab_chart.md#limitations).
- There are some feature [limitations to be aware of](https://docs.gitlab.com/charts/#limitations).
[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](kubernetes/index.md)
[**> Install GitLab on Kubernetes using the GitLab Helm charts.**](https://docs.gitlab.com/charts/)
## Installing GitLab with Docker
......
doc/install/kubernetes/gitlab_chart.md
View file @ 3b267450
# GitLab Helm Chart
---
redirect_to: https://docs.gitlab.com/charts/
---
This is the official way to install GitLab on a cloud native environment.
NOTE: **Kubernetes experience required:**
Our Helm charts are recommended for those who are familiar with Kubernetes.
If you're not sure if Kubernetes is for you, our
[Omnibus GitLab packages](../README.md#installing-gitlab-using-the-omnibus-gitlab-package-recommended)
are mature, scalable, support [high availability](../../administration/high_availability/README.md)
and are used today on GitLab.com.
It is not necessary to have GitLab installed on Kubernetes in order to use [GitLab Kubernetes integration](https://docs.gitlab.com/ee/user/project/clusters/index.html).
## Introduction
The `gitlab` chart is the best way to operate GitLab on Kubernetes. This chart
contains all the required components to get started, and can scale to large deployments.
The default deployment includes:
- Core GitLab components: Unicorn, Shell, Workhorse, Registry, Sidekiq, and Gitaly
- Optional dependencies: Postgres, Redis, Minio
- An auto-scaling, unprivileged [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor
- Automatically provisioned SSL via [Let's Encrypt](https://letsencrypt.org/).
## Limitations
Some features of GitLab are not currently available:
- [GitLab Pages](https://gitlab.com/charts/gitlab/issues/37)
- [GitLab Geo](https://gitlab.com/charts/gitlab/issues/8)
- [No in-cluster HA database](https://gitlab.com/charts/gitlab/issues/48)
- MySQL will not be supported, as support is [deprecated within GitLab](https://docs.gitlab.com/omnibus/settings/database.html#using-a-mysql-database-management-server-enterprise-edition-only)
## Installing GitLab using the Helm Chart
The `gitlab` chart includes all required dependencies, and takes a few minutes
to deploy.
TIP: **Tip:**
For production deployments, we strongly recommend using the
[detailed installation instructions](https://gitlab.com/charts/gitlab/blob/master/doc/installation/index.md)
utilizing [external Postgres, Redis, and object storage](https://gitlab.com/charts/gitlab/tree/master/doc/advanced) services.
### Requirements
In order to deploy GitLab on Kubernetes, the following are required:
1. `helm` and `kubectl` [installed on your computer](preparation/tools_installation.md).
1. A Kubernetes cluster, version 1.8 or higher. 6vCPU and 16GB of RAM is recommended.
- [Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
- [Google GKE](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-container-cluster)
- [IBM IKS](https://console.bluemix.net/docs/tutorials/scalable-webapp-kubernetes.html#create_kube_cluster)
- [Microsoft AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal)
1. A [wildcard DNS entry and external IP address](preparation/networking.md)
1. [Authenticate and connect](preparation/connect.md) to the cluster
1. Configure and initialize [Helm Tiller](preparation/tiller.md).
### Deployment of GitLab to Kubernetes
To deploy GitLab, the following three parameters are required:
- `global.hosts.domain`: the [base domain](preparation/networking.md) of the
wildcard host entry. For example, `example.com` if the wild card entry is
`*.example.com`.
- `global.hosts.externalIP`: the [external IP](preparation/networking.md) which
the wildcard DNS resolves to.
- `certmanager-issuer.email`: the email address to use when requesting new SSL
certificates from Let's Encrypt.
NOTE: **Note:**
For deployments to Amazon EKS, there are
[additional configuration requirements](preparation/eks.md). A full list of
configuration options is [also available](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md).
Once you have all of your configuration options collected, you can get any
dependencies and run helm. In this example, the helm release is named "gitlab":
```sh
helm repo add gitlab https://charts.gitlab.io/
helm repo update
helm upgrade --install gitlab gitlab/gitlab \
--timeout 600 \
--set global.hosts.domain=example.com \
--set global.hosts.externalIP=10.10.10.10 \
--set certmanager-issuer.email=email@example.com
```
### Monitoring the Deployment
This will output the list of resources installed once the deployment finishes,
which may take 5-10 minutes.
The status of the deployment can be checked by running `helm status gitlab`
which can also be done while the deployment is taking place if you run the
command in another terminal.
### Initial login
You can access the GitLab instance by visiting the domain name beginning with
`gitlab.` followed by the domain specified during installation. From the example
above, the URL would be `https://gitlab.example.com`.
If you manually created the secret for initial root password, you
can use that to sign in as `root` user. If not, GitLab automatically
created a random password for `root` user. This can be extracted by the
following command (replace `<name>` by name of the release - which is `gitlab`
if you used the command above):
```sh
kubectl get secret <name>-gitlab-initial-root-password -ojsonpath={.data.password} | base64 --decode ; echo
```
### Outgoing email
By default outgoing email is disabled. To enable it, provide details for your SMTP server
using the `global.smtp` and `global.email` settings. You can find details for these settings in the
[command line options](https://gitlab.com/charts/gitlab/blob/master/doc/installation/command-line-options.md#email-configuration).
If your SMTP server requires authentication make sure to read the section on providing
your password in the [secrets documentation](https://gitlab.com/charts/gitlab/blob/master/doc/installation/secrets.md#smtp-password).
You can disable authentication settings with `--set global.smtp.authentication=""`.
If your Kubernetes cluster is on GKE, be aware that SMTP port [25 is blocked](https://cloud.google.com/compute/docs/tutorials/sending-mail/#using_standard_email_ports).
### Deploying the Community Edition
To deploy the Community Edition, include these options in your `helm install` command:
```sh
--set gitlab.migrations.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-rails-ce
--set gitlab.sidekiq.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-sidekiq-ce
--set gitlab.unicorn.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-unicorn-ce
--set gitlab.unicorn.workhorse.image=registry.gitlab.com/gitlab-org/build/cng/gitlab-workhorse-ce
--set gitlab.task-runner.image.repository=registry.gitlab.com/gitlab-org/build/cng/gitlab-task-runner-ce
```
## Updating GitLab using the Helm Chart
Once your GitLab Chart is installed, configuration changes and chart updates
should be done using `helm upgrade`:
```sh
helm repo update
helm upgrade --reuse-values gitlab gitlab/gitlab
```
## Uninstalling GitLab using the Helm Chart
To uninstall the GitLab Chart, run the following:
```sh
helm delete 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
This document was moved to [another location](https://docs.gitlab.com/charts/).
doc/install/kubernetes/gitlab_omnibus.md
View file @ 3b267450
# GitLab-Omnibus Helm Chart
---
redirect_to: https://docs.gitlab.com/charts/
---
CAUTION: **Caution:**
This chart is **deprecated**. We recommend using the [`gitlab` chart](gitlab_chart.md)
instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8).
For more information on available GitLab Helm Charts, see [Installing GitLab on Kubernetes](index.md).
- This GitLab-Omnibus chart has been tested on Google Kubernetes Engine and Azure Container Service.
- This work is based partially on: <https://github.com/lwolf/kubernetes-gitlab/>. GitLab would like to thank Sergey Nuzhdin for his work.
## Introduction
This chart provides an easy way to get started with GitLab, provisioning an
installation with nearly all functionality enabled. SSL is automatically
provisioned via [Let's Encrypt](https://letsencrypt.org/).
This Helm chart is suited for small to medium deployments and is **deprecated**
and replaced by the [cloud native GitLab chart](https://gitlab.com/charts/helm.gitlab.io/blob/master/README.md).
Due to the significant architectural changes, migrating will require backing up
data out of this instance and importing it into the new deployment.
The deployment includes:
- A [GitLab Omnibus](https://docs.gitlab.com/omnibus/) Pod, including Mattermost, Container Registry, and Prometheus
- An auto-scaling [GitLab Runner](https://docs.gitlab.com/runner/) using the Kubernetes executor
- [Redis](https://github.com/kubernetes/charts/tree/master/stable/redis)
- [PostgreSQL](https://github.com/kubernetes/charts/tree/master/stable/postgresql)
- [NGINX Ingress](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress)
- Persistent Volume Claims for Data, Registry, Postgres, and Redis
## Limitations
[High Availability](../../administration/high_availability/README.md) and
[Geo](https://docs.gitlab.com/ee/administration/geo/replication/index.html) are not supported.
## Requirements
- _At least_ 4 GB of RAM available on your cluster. 41GB of storage and 2 CPU are also required.
- Kubernetes 1.4+ with Beta APIs enabled
- [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure
- A [wildcard DNS entry](#networking-requirements), which resolves to the external IP address
- The `kubectl` CLI installed locally and authenticated for the cluster
- The [Helm client](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md) installed locally on your machine
### Networking requirements
This chart configures a GitLab server and Kubernetes cluster which can support
dynamic [Review Apps](../../ci/review_apps/index.md), as well as services like
the integrated [Container Registry](../../user/project/container_registry.md)
and [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/).
To support the GitLab services and dynamic environments, a wildcard DNS entry
is required which resolves to the [load balancer](#load-balancer-ip) or
[external IP](#external-ip-recommended). Configuration of the DNS entry will depend upon
the DNS service being used.
#### External IP (recommended)
To provision an external IP on GCP and Azure, simply request a new address from
the Networking section. Ensure that the region matches the region your container
cluster is created in. It is important that the IP is not assigned at this point
in time. It will be automatically assigned once the Helm chart is installed,
and assigned to the Load Balancer.
Now that an external IP address has been allocated, ensure that the wildcard
DNS entry you would like to use resolves to this IP. Please consult the
documentation for your DNS service for more information on creating DNS records.
Finally, set the `baseIP` setting to this IP address when
[deploying GitLab](#configuring-and-installing-gitlab).
#### Load Balancer IP
If you do not specify a `baseIP`, an IP will be assigned to the Load Balancer or
Ingress. You can retrieve this IP by running the following command *after* deploying GitLab:
```sh
kubectl get svc -w --namespace nginx-ingress nginx
```
The IP address will be displayed in the `EXTERNAL-IP` field, and should be used
to configure the Wildcard DNS entry. For more information on creating a wildcard
DNS entry, consult the documentation for the DNS server you are using.
For production deployments of GitLab, we strongly recommend using a
[external IP](#external-ip-recommended).
## Configuring and Installing GitLab
For most installations, two parameters are required:
- `baseDomain`: the [base domain](#networking-requirements) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`.
- `legoEmail`: Email address to use when requesting new SSL certificates from Let's Encrypt.
Other common configuration options:
- `baseIP`: the desired [external IP address](#external-ip-recommended)
- `gitlab`: Choose the [desired edition](https://about.gitlab.com/pricing), either `ee` or `ce`. `ce` is the default.
- `gitlabEELicense`: For Enterprise Edition, the [license](https://docs.gitlab.com/ee/user/admin_area/license.html) can be installed directly via the Chart
- `provider`: Optimizes the deployment for a cloud provider. The default is `gke` for [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/), with `acs` also supported for the [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/).
For additional configuration options, consult the
[`values.yaml`](https://gitlab.com/charts/gitlab-omnibus/blob/master/values.yaml).
### Choosing a different GitLab release version
The version of GitLab installed is based on the `gitlab` setting (see [section](#configuring-and-installing-gitLab) above), and
the value of the corresponding helm setting: `gitlabCEImage` or `gitabEEImage`.
```yaml
gitlab: CE
gitlabCEImage: gitlab/gitlab-ce:9.5.2-ce.0
gitlabEEImage: gitlab/gitlab-ee:9.5.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.
### Persistent storage
NOTE: **Note:**
If you are using a machine type with support for less than 4 attached disks,
like an Azure trial, you should disable dedicated storage for Postgres and Redis.
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`, along with whether to provision separate storage for Postgres and Redis.
Basic configuration:
```yaml
redisImage: redis:3.2.10
redisDedicatedStorage: true
redisStorageSize: 5Gi
postgresImage: postgres:9.6.3
# If you disable postgresDedicatedStorage, you should consider bumping up gitlabRailsStorageSize
postgresDedicatedStorage: true
postgresStorageSize: 30Gi
gitlabRailsStorageSize: 30Gi
gitlabRegistryStorageSize: 30Gi
gitlabConfigStorageSize: 1Gi
```
### Routing and SSL
Ingress routing and SSL are automatically configured within this Chart. An NGINX
ingress is provisioned and configured, and will route traffic to any service.
SSL certificates are automatically created and configured by
[kube-lego](https://github.com/kubernetes/charts/tree/master/stable/kube-lego).
NOTE: **Note:**
Let's Encrypt limits a single TLD to five certificate requests within a single
week. This means that common DNS wildcard services like [nip.io](http://nip.io)
and [xip.io](http://xip.io) are unlikely to work.
## Installing GitLab using the Helm Chart
NOTE: **Note:**
You may see a temporary error message `SchedulerPredicates failed due to PersistentVolumeClaim is not bound`
while storage provisions. Once the storage provisions, the pods will automatically start.
This may take a couple minutes depending on your cloud provider. If the error persists,
please review the [requirements sections](#requirements) to ensure you have enough RAM, CPU, and storage.
Add the GitLab Helm repository and initialize Helm:
```bash
helm init
helm repo add gitlab https://charts.gitlab.io
```
Once you have reviewed the [configuration settings](#configuring-and-installing-gitlab),
you can install the chart. We recommending saving your configuration options in a
`values.yaml` file for easier upgrades in the future:
```bash
helm install --name gitlab -f values.yaml gitlab/gitlab-omnibus
```
Or you can pass them on the command line:
```bash
helm install --name gitlab --set baseDomain=gitlab.io,baseIP=192.0.2.1,gitlab=ee,gitlabEELicense=$LICENSE,legoEmail=email@gitlab.com gitlab/gitlab-omnibus
```
## Updating GitLab using the Helm Chart
If you are upgrading from a previous version to 0.1.35 or above, you will need to
change the access mode values for GitLab's storage. To do this, set the following
in `values.yaml` or on the CLI:
```sh
gitlabDataAccessMode=ReadWriteMany
gitlabRegistryAccessMode=ReadWriteMany
gitlabConfigAccessMode=ReadWriteMany
```
Once your GitLab Chart is installed, configuration changes and chart updates
should be done using `helm upgrade`:
```sh
helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus
```
## Upgrading from CE to EE using the Helm Chart
If you have installed the Community Edition using this chart, upgrading to
Enterprise Edition is easy.
If you are using a `values.yaml` file to specify the configuration options, edit
the file and set `gitlab=ee`. If you would like to run a specific version of
GitLab EE, set `gitlabEEImage` to be the desired GitLab
[docker image](https://hub.docker.com/r/gitlab/gitlab-ee/tags/). Then you can
use `helm upgrade` to update your GitLab instance to EE:
```bash
helm upgrade -f values.yaml gitlab gitlab/gitlab-omnibus
```
You can also upgrade and specify these options via the command line:
```bash
helm upgrade gitlab --set gitlab=ee,gitlabEEImage=gitlab/gitlab-ee:9.5.5-ee.0 gitlab/gitlab-omnibus
```
## Uninstalling GitLab using the Helm Chart
To uninstall the GitLab Chart, run the following:
```bash
helm delete --purge gitlab
```
## Troubleshooting
### Storage errors when updating `gitlab-omnibus` versions prior to 0.1.35
Users upgrading `gitlab-omnibus` from a version prior to 0.1.35, may see an error
like: `Error: UPGRADE FAILED: PersistentVolumeClaim "gitlab-gitlab-config-storage" is invalid: spec: Forbidden: field is immutable after creation`.
This is due to a change in the access mode for GitLab storage in version 0.1.35.
To successfully upgrade, the access mode flags must be set to `ReadWriteMany`
as detailed in the [update section](#updating-gitlab-using-the-helm-chart).
[kube-srv]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types
[storageclass]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#storageclasses
This document was moved to [another location](https://docs.gitlab.com/charts/).
doc/install/kubernetes/gitlab_runner_chart.md
View file @ 3b267450
# GitLab Runner Helm Chart
> **Note:**
These charts have been tested on Google Kubernetes Engine and Azure Container Service. Other Kubernetes installations may work as well, if not please [open an issue](https://gitlab.com/gitlab-org/gitlab-runner/issues).
---
redirect_to: https://docs.gitlab.com/runner/install/kubernetes.html
---
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.
For more information on available GitLab Helm Charts, please see our [overview](index.md).
## 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](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md) installed locally on your machine
## 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/gitlab-runner/blob/master/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) for more information.
Unless you need to specify additional configuration, you are [ready to install](#installing-gitlab-runner-using-the-helm-chart).
### Other configuration
The rest of the configuration is [documented in the `values.yaml`](https://gitlab.com/charts/gitlab-runner/blob/master/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 retrieved from your GitLab Instance.
## ref: https://docs.gitlab.com/ee/ci/runners/README.html
##
runnerRegistrationToken: ""
## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /etc/gitlab-runner/certs directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
##
#certsSecretName:
## 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
## For RBAC support:
rbac:
create: false
## Run the gitlab-bastion container with the ability to deploy/manage containers of jobs
## cluster-wide or only within namespace
clusterWideAccess: false
## Use the following Kubernetes Service Account name if RBAC is disabled in this Helm chart (see rbac.create)
##
# serviceAccountName: default
## Configuration for the Pods 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:stable-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
```
### Enabling RBAC support
If your cluster has RBAC enabled, you can choose to either have the chart create its own service account or provide one.
To have the chart create the service account for you, set `rbac.create` to true.
### Controlling maximum Runner concurrency
A single GitLab Runner deployed on Kubernetes is able to execute multiple jobs in parallel by automatically starting additional Runner pods. The [`concurrent` setting](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section) controls the maximum number of pods allowed at a single time, and defaults to `10`.
```yaml
## Configure the maximum number of concurrent jobs
## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
##
concurrent: 10
```
### 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:stable-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
```
### Providing a custom certificate for accessing GitLab
You can provide a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/)
to the GitLab Runner Helm Chart, which will be used to populate the container's
`/etc/gitlab-runner/certs` directory.
Each key name in the Secret will be used as a filename in the directory, with the
file content being the value associated with the key.
More information on how GitLab Runner uses these certificates can be found in the
[Runner Documentation](https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates).
- The key/file name used should be in the format `<gitlab-hostname>.crt`. For example: `gitlab.your-domain.com.crt`.
- Any intermediate certificates need to be concatenated to your server certificate in the same file.
- The hostname used should be the one the certificate is registered for.
The GitLab Runner Helm Chart does not create a secret for you. In order to create
the secret, you can prepare your certificate on you local machine, and then run
the `kubectl create secret` command from the directory with the certificate
```bash
kubectl
--namespace <NAMESPACE>
create secret generic <SECRET_NAME>
--from-file=<CERTFICATE_FILENAME>
```
- `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner.
- `<SECRET_NAME>` is the Kubernetes Secret resource name. For example: `gitlab-domain-cert`
- `<CERTFICATE_FILENAME>` is the filename for the certificate in your current directory that will be imported into the secret
You then need to provide the secret's name to the GitLab Runner chart.
Add the following to your `values.yaml`
```yaml
## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
## Provide resource name for a Kubernetes Secret Object in the same namespace,
## this is used to populate the /etc/gitlab-runner/certs directory
## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
##
certsSecretName: <SECRET NAME>
```
- `<SECRET_NAME>` is the Kubernetes Secret resource name. For example: `gitlab-domain-cert`
## Installing GitLab Runner using the Helm Chart
Add the GitLab Helm repository and initialize Helm:
```bash
helm repo add gitlab https://charts.gitlab.io
helm init
```
Once you [have configured](#configuring-gitlab-runner-using-the-helm-chart) GitLab Runner in your `values.yml` file,
run the following:
```bash
helm install --namespace <NAMESPACE> --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
[Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) 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 --namespace <NAMESPACE> -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
[Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) section to create it.
- `<RELEASE-NAME>` is the name you gave the chart when installing it.
In the [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, 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 [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, we called it `gitlab-runner`.
This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes.html).
doc/install/kubernetes/index.md
View file @ 3b267450
......@@ -21,16 +21,15 @@ of the application including how it should be deployed, upgraded, and configured
## GitLab Chart
This chart contains all the required components to get started, and can scale to
large deployments. It offers a number of benefits:
large deployments. It offers a number of benefits, among others:
- Horizontal scaling of individual components
- No requirement for shared storage to scale
- Containers do not need `root` permissions
- Automatic SSL with Let's Encrypt
- An unprivileged GitLab Runner
- and plenty more.
- Horizontal scaling of individual components.
- No requirement for shared storage to scale.
- Containers do not need `root` permissions.
- Automatic SSL with Let's Encrypt.
- An unprivileged GitLab Runner.
Learn more about the [GitLab chart](gitlab_chart.md).
Learn more about the [GitLab chart](https://docs.gitlab.com/charts/).
## GitLab Runner Chart
......@@ -39,4 +38,4 @@ and you'd like to leverage the Runner's
[Kubernetes capabilities](https://docs.gitlab.com/runner/executors/kubernetes.html),
it can be deployed with the GitLab Runner chart.
Learn more about [gitlab-runner chart](gitlab_runner_chart.md).
Learn more about the [GitLab Runner chart](https://docs.gitlab.com/runner/install/kubernetes.html).
doc/install/kubernetes/preparation/connect.md
View file @ 3b267450
# Connecting your computer to a cluster
---
redirect_to: https://docs.gitlab.com/charts/installation/cloud/
---
In order to deploy software and settings to a cluster, you must connect and authenticate to it.
## Connect to GKE cluster
The command for connection to the cluster can be obtained from the
[Google Cloud Platform Console](https://console.cloud.google.com/kubernetes/list)
by the individual cluster.
Look for the **Connect** button in the clusters list page or use the command below,
filling in your cluster's information:
```
gcloud container clusters get-credentials <cluster-name> --zone <zone> --project <project-id>
```
## Connect to EKS cluster
For the most up to date instructions, follow the Amazon EKS documentation on
[connecting to a cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#eks-configure-kubectl).
## Connect to local minikube cluster
If you are doing local development, you can use `minikube` as your
local cluster. If `kubectl cluster-info` is not showing `minikube` as the current
cluster, use `kubectl config set-cluster minikube` to set the active cluster.
This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/).
doc/install/kubernetes/preparation/eks.md
View file @ 3b267450
# Running GitLab on EKS
---
redirect_to: https://docs.gitlab.com/charts/installation/cloud/eks.html
---
There are a few nuances to Amazon EKS which are important to be aware of, when deploying GitLab.
## Persistent volume management
There are two methods to manage volume claims on Kubernetes:
1. Manually creating each persistent volume (recommended on EKS)
1. Utilizing dynamic provisioning to automatically create the persistent volumes
### Manual provisioning of volumes (Recommended)
Manually creating the volumes allows you to control the zone of each volume, as well as all other details supported by the underlying storage.
Follow our documentation on [manually creating persistent volumes](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md#manually-creating-static-volumes).
### Dynamic provisioning of volumes
Dynamic provisioning utilizes a Kubernetes provisioner, like `aws-ebs`, to automatically create persistent volumes to fulfill each claim.
With EKS, there are a few important details to keep in mind:
1. Clusters are required to span multiple AZ's
1. Kubernetes volume provisioners create volumes across zones without regard to which pod they belong to. This leads to scenarios where a pod with multiple volumes being unable to start due to the volumes being in different zones.
1. There is no default Storage Class.
The easiest way to solve this and still utilize dynamic provisioning is to utilize, or create, a Storage Class that is locked to a specific zone.
> **Note**: Restricting volumes to specific zone will cause GitLab and any other application using this Storage Class to only reside in that zone. For multiple zone support, utilize [manually provisioned volumes](#manual-provisioning-of-volumes-recommended).
To create the storage class, download and edit Amazon EKS's [sample Storage Class](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) and add the following parameter:
```yaml
parameters:
zone: <desired-zone>
```
Then [specify the Storage Class](https://gitlab.com/charts/gitlab/blob/master/doc/installation/storage.md#using-a-custom-storage-class) name when deploying GitLab.
## External access to GitLab
By default, GitLab will an deploy an ingress which will create an associated Elastic Load Balancer. Since the DNS names of ELB's cannot be known ahead of time, it is difficult to utilize Let's Encrypt to automatically provision HTTPS certificates.
We recommend [using your own certificates](https://gitlab.com/charts/gitlab/blob/master/doc/installation/tls.md#option-2-use-your-own-wildcard-certificate), and then mapping your desired DNS name to the created ELB using a CNAME record.
This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/eks.html).
doc/install/kubernetes/preparation/networking.md
View file @ 3b267450
# Networking Prerequisites
---
redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns
---
NOTE: **Note:**
Amazon EKS utilizes Elastic Load Balancers, which are addressed by DNS name and
cannot be known ahead of time. If you're using EKS, you can skip this section.
The `gitlab` chart configures a GitLab server and Kubernetes cluster which can support dynamic [Review Apps](https://docs.gitlab.com/ee/ci/review_apps/index.html), as well as services like the integrated [Container Registry](https://docs.gitlab.com/ee/user/project/container_registry.html).
To support the GitLab services and dynamic environments, a wildcard DNS entry is required which resolves to the external IP.
## External IP
To provision an external IP on GCP and Azure, simply request a new address from the Networking section. Ensure that the region matches the region your container cluster is created in. Note, it is important that the IP is not assigned at this point in time. It will be automatically assigned once the Helm chart is installed, to the Load Balancer.
Set `global.hosts.externalIP` to this IP address when [deploying GitLab](../gitlab_chart.md#installing-gitlab-using-the-helm-chart).
Then, create a [wildcard DNS record](#wildcard-dns-entry) which resolves to this IP address.
### Creating an external IP on GCP
When creating the external IP, it is critical to create it in the same region as your cluster. Otherwise, the IP address will fail to bind to the Load Balancer.
1. Open the [web console](https://console.cloud.google.com)
1. In the sidebar, browse to `VPC Network > External IP addresses`
1. Click `Reserve static address`
1. Choose `Regional` and select the region of your cluster
1. Leave `Attached to` blank, as it will be automatically assigned during deployment
## Wildcard DNS entry
Now that an external IP address has been allocated, ensure that the wildcard DNS entry you would like to use resolves to this IP. Typically this would be an `A record` for `*`, resolving to the external IP above.
Please consult the documentation for your DNS service for more information on creating DNS records:
- [Google Domains](https://support.google.com/domains/answer/3290350?hl=en)
- [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238)
Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#installing-gitlab-using-the-helm-chart).
This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns).
doc/install/kubernetes/preparation/rbac.md
View file @ 3b267450
# Role Based Access Control
---
redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#rbac
---
Until Kubernetes 1.7, there were no permissions within a cluster. With the launch
of 1.7, there is now a [role based access control system (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/)
which determines what services can perform actions within a cluster.
RBAC affects a few different aspects of GitLab:
- [Installation of GitLab using Helm](tiller.md#preparing-for-helm-with-rbac)
- Prometheus monitoring
- GitLab Runner
## Checking that RBAC is enabled
Try listing the current cluster roles, if it fails then `RBAC` is disabled.
The following command will output `false` if `RBAC` is disabled and `true` otherwise:
```sh
kubectl get clusterroles > /dev/null 2>&1 && echo true || echo false
```
This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#rbac).
doc/install/kubernetes/preparation/tiller.md
View file @ 3b267450
# Configuring and initializing Helm Tiller
To make use of Helm, you must have a [Kubernetes][k8s-io] cluster. Ensure you can
access your cluster using `kubectl`.
Helm consists of two parts, the `helm` client and a `tiller` server inside Kubernetes.
NOTE: **Note:**
If you are not able to run Tiller in your cluster, for example on OpenShift, it
is possible to use [Tiller locally](https://docs.gitlab.com/charts/installation/tools.html#local-tiller)
and avoid deploying it into the cluster. This should only be used when Tiller
cannot be normally deployed.
## Initialize Helm and Tiller
Tiller is deployed into the cluster and interacts with the Kubernetes API to deploy your applications. If role based access control (RBAC) is enabled, Tiller will need to be [granted permissions](#preparing-for-helm-with-rbac) to allow it to talk to the Kubernetes API.
If RBAC is not enabled, skip to [initializing Helm](#initialize-helm).
If you are not sure whether RBAC is enabled in your cluster, or to learn more, read through our [RBAC documentation](rbac.md).
## Preparing for Helm with RBAC
Helm's Tiller will need to be granted permissions to perform operations. These instructions grant cluster wide permissions, however for more advanced deployments [permissions can be restricted to a single namespace](https://docs.helm.sh/using_helm/#example-deploy-tiller-in-a-namespace-restricted-to-deploying-resources-only-in-that-namespace). To grant access to the cluster, we will create a new `tiller` service account and bind it to the `cluster-admin` role.
Create a file `rbac-config.yaml` with the following contents:
```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
name: tiller
namespace: kube-system
---
apiVersion: rbac.authorization.k8s.io/v1beta1
kind: ClusterRoleBinding
metadata:
name: tiller
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: cluster-admin
subjects:
- kind: ServiceAccount
name: tiller
namespace: kube-system
```
Next we need to connect to the cluster and upload the RBAC config.
### Upload the RBAC config
Some clusters require authentication to use `kubectl` to create the Tiller roles.
#### Upload the RBAC config as an admin user (GKE)
For GKE, you need to obtain the admin credentials. This command will output the admin password:
```
gcloud container clusters describe <cluster-name> --zone <zone> --project <project-id> --format='value(masterAuth.password)'
```
Use the admin password to set the admin credentials. Replace the password value below with the output value from the above step:
```
kubectl config set-credentials admin --username=admin --password=xxxxxxxxxxxxxx
```
Once credentials have been set, create the role:
```
kubectl --user=admin create -f rbac-config.yaml
```
#### Upload the RBAC config (Non-GKE clusters)
For other clusters like Amazon EKS, you can directly upload the RBAC configuration.
```
kubectl create -f rbac-config.yaml
```
## Initialize Helm
Deploy Helm Tiller with a service account:
```
helm init --service-account tiller
```
If your cluster previously had Helm/Tiller installed,
run the following to ensure that the deployed version of Tiller matches the local Helm version:
```
helm init --upgrade --service-account tiller
```
### Patching Helm Tiller for Amazon EKS
Helm Tiller requires a flag to be enabled to work properly on Amazon EKS:
```
kubectl -n kube-system patch deployment tiller-deploy -p '{"spec": {"template": {"spec": {"automountServiceAccountToken": true}}}}'
```
redirect_to: https://docs.gitlab.com/charts/installation/tools.html
---
[helm]: https://helm.sh
[helm-using]: https://docs.helm.sh/using_helm
[k8s-io]: https://kubernetes.io/
[gcp-k8s]: https://console.cloud.google.com/kubernetes/list
This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html).
doc/install/kubernetes/preparation/tools_installation.md
View file @ 3b267450
# Installing kubectl and Helm on your computer
---
redirect_to: https://docs.gitlab.com/charts/installation/tools.html
---
In order to work with the GitLab Helm charts, `kubectl` and `helm` must be installed and configured on your computer.
## Installing `kubectl`
`kubectl` is the Kubernetes command line tool, which can be used to deploy settings to the cluster.
Follow the [official documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/) for the most up to date instructions.
## Installing `helm`
Helm is a package management tool for Kubernetes, and is used to deploy charts.
You can get Helm from the project's [releases page](https://github.com/kubernetes/helm/releases), or follow other options under the official documentation of [Installing Helm](https://docs.helm.sh/using_helm/#installing-helm).
# Next steps
Once installed, proceed to the next [installation step](../gitlab_chart.md#installing-gitlab-using-the-helm-chart).
This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html).
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7