github.com/nilium/gitlab-runner@v12.5.0+incompatible/docs/install/kubernetes.md (about)

     1  # GitLab Runner Helm Chart
     2  
     3  NOTE: **Note:**
     4  This chart has been tested on Google Kubernetes Engine and Azure Container Service.
     5  Other Kubernetes installations may work as well, if not please
     6  [open an issue](https://gitlab.com/gitlab-org/charts/gitlab-runner/issues).
     7  
     8  The official way of deploying a GitLab Runner instance into your
     9  Kubernetes cluster is by using the `gitlab-runner` Helm chart.
    10  
    11  This chart configures the Runner to:
    12  
    13  - Run using the GitLab Runner [Kubernetes executor](../executors/kubernetes.md).
    14  - For each new job it receives from GitLab CI/CD, it will provision a
    15    new pod within the specified namespace to run it.
    16  
    17  ## Prerequisites
    18  
    19  - Your GitLab Server's API is reachable from the cluster.
    20  - Kubernetes 1.4+ with Beta APIs enabled.
    21  - The `kubectl` CLI installed locally and authenticated for the cluster.
    22  - The [Helm client](https://helm.sh/docs/using_helm/#installing-the-helm-client) installed locally on your machine.
    23  
    24  ## Configuring GitLab Runner using the Helm Chart
    25  
    26  Create a `values.yaml` file for your GitLab Runner configuration. See
    27  [Helm docs](https://helm.sh/docs/chart_template_guide/#values-files)
    28  for information on how your values file will override the defaults.
    29  
    30  The default configuration can always be found in the
    31  [`values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml)
    32  in the chart repository.
    33  
    34  ### Required configuration
    35  
    36  In order for GitLab Runner to function, your config file **must** specify the following:
    37  
    38  - `gitlabUrl` - the GitLab server full URL (e.g., `https://example.gitlab.com`) to register the Runner against.
    39  - `runnerRegistrationToken` - The registration token for adding new Runners to
    40    GitLab. This must be [retrieved from your GitLab instance](https://docs.gitlab.com/ee/ci/runners/).
    41  
    42  Unless you need to specify any additional configuration, you are
    43  ready to [install the Runner](#installing-gitlab-runner-using-the-helm-chart).
    44  
    45  ### Additional configuration
    46  
    47  The rest of the configuration is
    48  [documented in the `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/master/values.yaml) in the chart repository.
    49  
    50  Here is a snippet of the important settings:
    51  
    52  ```yaml
    53  ## The GitLab Server URL (with protocol) that want to register the runner against
    54  ## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register
    55  ##
    56  gitlabUrl: https://gitlab.example.com/
    57  
    58  ## The registration token for adding new Runners to the GitLab server. This must
    59  ## be retrieved from your GitLab instance.
    60  ## ref: https://docs.gitlab.com/ee/ci/runners/
    61  ##
    62  runnerRegistrationToken: ""
    63  
    64  ## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
    65  ## Provide resource name for a Kubernetes Secret Object in the same namespace,
    66  ## this is used to populate the /etc/gitlab-runner/certs directory
    67  ## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
    68  ##
    69  #certsSecretName:
    70  
    71  ## Configure the maximum number of concurrent jobs
    72  ## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
    73  ##
    74  concurrent: 10
    75  
    76  ## Defines in seconds how often to check GitLab for a new builds
    77  ## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
    78  ##
    79  checkInterval: 30
    80  
    81  ## For RBAC support:
    82  rbac:
    83    create: false
    84  
    85    ## Run the gitlab-bastion container with the ability to deploy/manage containers of jobs
    86    ## cluster-wide or only within namespace
    87    clusterWideAccess: false
    88  
    89    ## If RBAC is disabled in this Helm chart, use the following Kubernetes Service Account name.
    90    ##
    91    # serviceAccountName: default
    92  
    93  ## Configuration for the Pods that the runner launches for each new job
    94  ##
    95  runners:
    96    ## Default container image to use for builds when none is specified
    97    ##
    98    image: ubuntu:18.04
    99  
   100    ## Run all containers with the privileged flag enabled
   101    ## This will allow the docker:stable-dind image to run if you need to run Docker
   102    ## commands. Please read the docs before turning this on:
   103    ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind
   104    ##
   105    privileged: false
   106  
   107    ## Namespace to run Kubernetes jobs in (defaults to 'default')
   108    ##
   109    # namespace:
   110  
   111    ## Build Container specific configuration
   112    ##
   113    builds:
   114      # cpuLimit: 200m
   115      # memoryLimit: 256Mi
   116      cpuRequests: 100m
   117      memoryRequests: 128Mi
   118  
   119    ## Service Container specific configuration
   120    ##
   121    services:
   122      # cpuLimit: 200m
   123      # memoryLimit: 256Mi
   124      cpuRequests: 100m
   125      memoryRequests: 128Mi
   126  
   127    ## Helper Container specific configuration
   128    ##
   129    helpers:
   130      # cpuLimit: 200m
   131      # memoryLimit: 256Mi
   132      cpuRequests: 100m
   133      memoryRequests: 128Mi
   134  ```
   135  
   136  ### Enabling RBAC support
   137  
   138  If your cluster has RBAC enabled, you can choose to either have the chart create
   139  its own service account or [provide one on your own](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#service-account-permissions).
   140  
   141  To have the chart create the service account for you, set `rbac.create` to true:
   142  
   143  ```yaml
   144  rbac:
   145    create: true
   146  ```
   147  
   148  To use an already existing service account, use:
   149  
   150  ```yaml
   151  rbac:
   152    create: false
   153    serviceAccountName: your-service-account
   154  ```
   155  
   156  ### Controlling maximum Runner concurrency
   157  
   158  A single GitLab Runner deployed on Kubernetes is able to execute multiple jobs
   159  in parallel by automatically starting additional Runner pods. The
   160  [`concurrent` setting](../configuration/advanced-configuration.md#the-global-section)
   161  controls the maximum number of pods allowed at a single time, and defaults to `10`:
   162  
   163  ```yaml
   164  ## Configure the maximum number of concurrent jobs
   165  ## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section
   166  ##
   167  concurrent: 10
   168  ```
   169  
   170  ### Running Docker-in-Docker containers with GitLab Runners
   171  
   172  See [Running Privileged Containers for the Runners](#running-privileged-containers-for-the-runners) for how to enable it,
   173  and the [GitLab Runner documentation](../executors/kubernetes.md#using-docker-in-your-builds) on running dind.
   174  
   175  ### Running privileged containers for the Runners
   176  
   177  You can tell the GitLab Runner to run using privileged containers. You may need
   178  this enabled if you need to use the Docker executable within your GitLab CI/CD jobs.
   179  
   180  This comes with several risks that you can read about in the
   181  [GitLab CI/CD Runner documentation](../executors/kubernetes.md#using-docker-in-your-builds).
   182  
   183  If you are okay with the risks, and your GitLab Runner instance is registered
   184  against a specific project in GitLab that you trust the CI jobs of, you can
   185  enable privileged mode in `values.yaml`:
   186  
   187  ```yaml
   188  runners:
   189    ## Run all containers with the privileged flag enabled
   190    ## This will allow the docker:stable-dind image to run if you need to run Docker
   191    ## commands. Please read the docs before turning this on:
   192    ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind
   193    ##
   194    privileged: true
   195  ```
   196  
   197  ### Providing a custom certificate for accessing GitLab
   198  
   199  You can provide a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/)
   200  to the GitLab Runner Helm Chart, which will be used to populate the container's
   201  `/etc/gitlab-runner/certs` directory.
   202  
   203  Each key name in the Secret will be used as a filename in the directory, with the
   204  file content being the value associated with the key:
   205  
   206  - The key/file name used should be in the format `<gitlab-hostname>.crt`, for example
   207    `gitlab.your-domain.com.crt`.
   208  - Any intermediate certificates need to be concatenated to your server certificate in the same file.
   209  - The hostname used should be the one the certificate is registered for.
   210  
   211  The GitLab Runner Helm Chart does not create a secret for you. In order to create
   212  the secret, you can prepare your certificate on you local machine, and then run
   213  the `kubectl create secret` command from the directory with the certificate:
   214  
   215  ```bash
   216  kubectl
   217    --namespace <NAMESPACE>
   218    create secret generic <SECRET_NAME>
   219    --from-file=<CERTFICATE_FILENAME>
   220  ```
   221  
   222  Where:
   223  
   224  - `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner.
   225  - `<SECRET_NAME>` is the Kubernetes Secret resource name. For example: `gitlab-domain-cert`.
   226  - `<CERTFICATE_FILENAME>` is the filename for the certificate in your current directory that will be imported into the secret.
   227  
   228  You then need to provide the secret's name to the GitLab Runner chart.
   229  Add the following to your `values.yaml`:
   230  
   231  ```yaml
   232  ## Set the certsSecretName in order to pass custom certificates for GitLab Runner to use
   233  ## Provide resource name for a Kubernetes Secret Object in the same namespace,
   234  ## this is used to populate the /etc/gitlab-runner/certs directory
   235  ## ref: https://docs.gitlab.com/runner/configuration/tls-self-signed.html#supported-options-for-self-signed-certificates
   236  ##
   237  certsSecretName: <SECRET NAME>
   238  ```
   239  
   240  Where:
   241  
   242  - `<SECRET_NAME>` is the Kubernetes Secret resource name, for example `gitlab-domain-cert`.
   243  
   244  More information on how GitLab Runner uses these certificates can be found in the
   245  [Runner Documentation](../configuration/tls-self-signed.md#supported-options-for-self-signed-certificates).
   246  
   247  ## Installing GitLab Runner using the Helm Chart
   248  
   249  Add the GitLab Helm repository and initialize Helm:
   250  
   251  ```bash
   252  helm repo add gitlab https://charts.gitlab.io
   253  helm init
   254  ```
   255  
   256  Once you [have configured](#configuring-gitlab-runner-using-the-helm-chart) GitLab Runner in your `values.yml` file,
   257  run the following:
   258  
   259  ```bash
   260  helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner
   261  ```
   262  
   263  Where:
   264  
   265  - `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner.
   266  - `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the
   267    [Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) section to create it.
   268  
   269  ## Updating GitLab Runner using the Helm Chart
   270  
   271  Once your GitLab Runner Chart is installed, configuration changes and chart updates should be done using `helm upgrade`:
   272  
   273  ```bash
   274  helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner
   275  ```
   276  
   277  Where:
   278  
   279  - `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed.
   280  - `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the
   281    [Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) section to create it.
   282  - `<RELEASE-NAME>` is the name you gave the chart when installing it.
   283    In the [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, we called it `gitlab-runner`.
   284  
   285  ## Uninstalling GitLab Runner using the Helm Chart
   286  
   287  To uninstall the GitLab Runner Chart, run the following:
   288  
   289  ```bash
   290  helm delete --namespace <NAMESPACE> <RELEASE-NAME>
   291  ```
   292  
   293  Where:
   294  
   295  - `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed.
   296  - `<RELEASE-NAME>` is the name you gave the chart when installing it.
   297    In the [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, we called it `gitlab-runner`.