Commit 6d5f7b50 authored by Tomasz Maczukin's avatar Tomasz Maczukin

Merge branch 'docs/runner-k8s' into 'master'

Replace the current k8s manual installation with the Helm chart

Closes #2964

See merge request !1250
parents 2fcd611a f34b8b23
# Run GitLab Runner on a Kubernetes cluster
# GitLab Runner Helm Chart
TIP: **Tip:**
We also provide a [GitLab Runner Helm Chart](https://docs.gitlab.com/ce/install/kubernetes/gitlab_runner_chart.html).
NOTE: **Note:**
This chart has 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).
To install the GitLab CI Runner on Kubernetes there are several resources that need to be defined and then pushed to the cluster with `kubectl`. This topic covers how to:
The official way of deploying a GitLab Runner instance into your
Kubernetes cluster is by using the `gitlab-runner` Helm chart.
1. Register the new runner using the API.
1. Define the runner ConfigMap in a yaml file.
1. Define the runner Deployment yaml file.
1. Push the definitions to a Kubernetes cluster using `kubectl`.
This chart configures the Runner to:
## Register the new runner using the API
- Run using the GitLab Runner [Kubernetes executor](../executors/kubernetes.md).
- For each new job it receives from GitLab CI/CD, it will provision a
new pod within the specified namespace to run it.
The runner must first be registered to your project, group or instance so that its **runner token** (not to be confused with the runner registration token) can be provided to the `ConfigMap` below. To do this:
## Prerequisites
1. Register a new runner using the [GitLab Runners API](https://docs.gitlab.com/ee/api/runners.html#register-a-new-runner) (example within) and provide the **registration token** from the CI/CD settings section of your project, group or instance as described in
[Configuring GitLab Runners](https://docs.gitlab.com/ee/ci/runners/README.html).
- 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.
1. Copy the **runner token** that is returned by the runner API registration command and paste it as the value of the `token = "...."` field of your `ConfigMap`.
## Configuring GitLab Runner using the Helm Chart
## Define the Runner `ConfigMap`
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.
Create a file named `runner_config.yml` from the following example:
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 full URL (e.g., `https://example.gitlab.com`) to register the Runner against.
- `runnerRegistrationToken` - The registration token for adding new Runners to
GitLab. This must be [retrieved from your GitLab instance](https://docs.gitlab.com/ee/ci/runners/).
Unless you need to specify any additional configuration, you are
ready to [install the Runner](#installing-gitlab-runner-using-the-helm-chart).
### Additional 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
apiVersion: v1
kind: ConfigMap
metadata:
name: gitlab-runner
namespace: gitlab
data:
config.toml: |
concurrent = 4
[[runners]]
name = "Kubernetes Runner"
url = "https://gitlab.com"
token = "...."
executor = "kubernetes"
[runners.kubernetes]
namespace = "gitlab"
image = "busybox"
## 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: https://gitlab.example.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/
##
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
## If RBAC is disabled in this Helm chart, use the following Kubernetes Service Account name.
##
# 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:18.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
```
Update the `url` and `token` with your values. The parameter `image` is optional and is the default Docker image used to be used to run jobs.
### Enabling RBAC support
>**Note:**
> Don't use the `gitlab-managed-apps` namespace for this runner. It should be reserved for applications installed through the GitLab UI.
If your cluster has RBAC enabled, you can choose to either have the chart create
its own service account or [provide one on your own](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#service-account-permissions).
To have the chart create the service account for you, set `rbac.create` to true:
## Define the Runner `Deployment`
```yaml
rbac:
create: true
```
Create a file named `runner_deployment.yml` from the following example:
To use an already existing service account, use:
```yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: gitlab-runner
namespace: gitlab
spec:
replicas: 1
selector:
matchLabels:
name: gitlab-runner
template:
metadata:
labels:
name: gitlab-runner
spec:
containers:
- args:
- run
image: gitlab/gitlab-runner:latest
name: gitlab-runner
volumeMounts:
- mountPath: /etc/gitlab-runner
name: config
- mountPath: /etc/ssl/certs
name: cacerts
readOnly: true
restartPolicy: Always
volumes:
- configMap:
name: gitlab-runner
name: config
- hostPath:
path: /usr/share/ca-certificates/mozilla
name: cacerts
rbac:
create: false
serviceAccountName: your-service-account
```
## Push the definitions to Kubernetes
### 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](../configuration/advanced-configuration.md#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
```
Assuming that your kubectl context has already been set to the cluster in question, issue these commands:
### 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 Runner documentation](../executors/kubernetes.md#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/CD jobs.
This comes with several risks that you can read about in the
[GitLab CI/CD Runner documentation](../executors/kubernetes.md#using-docker-in-your-builds).
If you are okay with the risks, and your GitLab 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
```
`kubectl apply -f runner_config.yml`
### Providing a custom certificate for accessing GitLab
`kubectl apply -f runner_deployment.yml`
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:
- 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>
```
Where:
- `<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>
```
Where:
- `<SECRET_NAME>` is the Kubernetes Secret resource name, for example `gitlab-domain-cert`.
More information on how GitLab Runner uses these certificates can be found in the
[Runner Documentation](../configuration/tls-self-signed.md#supported-options-for-self-signed-certificates).
## 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
```
Where:
- `<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 be 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>
```
The new runner will now show up in the GitLab web UI at the appropriate level (instance, group or project).
Where:
For more details see [Kubernetes executor](../executors/kubernetes.md)
and the [[runners.kubernetes] section of advanced configuration](../configuration/advanced-configuration.md#the-runnerskubernetes-section).
- `<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`.
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