diff options
| author | John Jarvis <jarv@gitlab.com> | 2019-04-08 11:50:19 +0300 |
|---|---|---|
| committer | John Jarvis <jarv@gitlab.com> | 2019-04-08 11:50:19 +0300 |
| commit | b8ed65619075d3b5892a3ec16e562518d5285a75 (patch) | |
| tree | f6a31b4819339aeb170f9df5886afab23638f172 /doc | |
| parent | 9ed8b61b8692dbafe189fce68237efcc9345ee9f (diff) | |
| parent | 435c492bac54f588b92e733b632edd4149a6db37 (diff) | |
Merge branch 'master' into 11-10-stable
Diffstat (limited to 'doc')
34 files changed, 342 insertions, 1001 deletions
diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index 345e8646f9b..1780e1babe9 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -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. diff --git a/doc/administration/job_traces.md b/doc/administration/job_traces.md index 63945506f3c..aa9d87562a3 100644 --- a/doc/administration/job_traces.md +++ b/doc/administration/job_traces.md @@ -10,13 +10,13 @@ In the following table you can see the phases a trace goes through. | Phase | State | Condition | Data flow | Stored path | | ----- | ----- | --------- | --------- | ----------- | -| 1: patching | Live trace | When a job is running | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| -| 2: overwriting | Live trace | When a job is finished | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| -| 3: archiving | Archived trace | After a job is finished | Sidekiq moves live trace to artifacts folder |`#{ROOT_PATH}/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log`| +| 1: patching | Live trace | When a job is running | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| +| 2: overwriting | Live trace | When a job is finished | GitLab Runner => Unicorn => file storage |`#{ROOT_PATH}/gitlab-ci/builds/#{YYYY_mm}/#{project_id}/#{job_id}.log`| +| 3: archiving | Archived trace | After a job is finished | Sidekiq moves live trace to artifacts folder |`#{ROOT_PATH}/gitlab-rails/shared/artifacts/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log`| | 4: uploading | Archived trace | After a trace is archived | Sidekiq moves archived trace to [object storage](#uploading-traces-to-object-storage) (if configured) |`#{bucket_name}/#{disk_hash}/#{YYYY_mm_dd}/#{job_id}/#{job_artifact_id}/job.log`| The `ROOT_PATH` varies per your environment. For Omnibus GitLab it -would be `/var/opt/gitlab/gitlab-ci`, whereas for installations from source +would be `/var/opt/gitlab`, whereas for installations from source it would be `/home/git/gitlab`. ## Changing the job traces local location diff --git a/doc/api/commits.md b/doc/api/commits.md index c8c282a71d9..e205307eeca 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -155,7 +155,7 @@ Example response: } ``` -GitLab supports [form encoding](../README.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: +GitLab supports [form encoding](README.md#encoding-api-parameters-of-array-and-hash-types). The following is an example using Commit API with form encoding: ```bash curl --request POST \ diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index 02334f0298e..f36e352da67 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -159,7 +159,7 @@ Parameters: | --------- | ---- | -------- | ----------- | | `id` | integer | yes | The ID of the project owned by the authenticated user | | `name` | String | yes | The name of the cluster | -| `domain` | String |Â no | The [base domain](../user/project/clusters/index.md#base_domain) of the cluster | +| `domain` | String | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | | `enabled` | Boolean | no | Determines if cluster is active or not, defaults to true | | `platform_kubernetes_attributes[api_url]` | String | yes | The URL to access the Kubernetes API | | `platform_kubernetes_attributes[token]` | String | yes | The token to authenticate against Kubernetes | @@ -250,7 +250,7 @@ Parameters: | `id` | integer | yes | The ID of the project owned by the authenticated user | | `cluster_id` | integer | yes | The ID of the cluster | | `name` | String | no | The name of the cluster | -| `domain` | String |Â no | The [base domain](../user/project/clusters/index.md#base_domain) of the cluster | +| `domain` | String | no | The [base domain](../user/project/clusters/index.md#base-domain) of the cluster | | `platform_kubernetes_attributes[api_url]` | String | no | The URL to access the Kubernetes API | | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | diff --git a/doc/api/runners.md b/doc/api/runners.md index 0b7ef46888c..46f7b1d2a25 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -4,6 +4,29 @@ [ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640 +## Registration and authentication tokens + +There are two tokens to take into account when connecting a Runner with GitLab. + +| Token | Description | +| ----- | ----------- | +| Registration token | Token used to [register the Runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/README.md). | +| Authentication token | Token used to authenticate the Runner with the GitLab instance. It is obtained either automatically when [registering a Runner](https://docs.gitlab.com/runner/register/), or manually when [registering the Runner via the Runners API](#register-a-new-runner). | + +Here's an example of how the two tokens are used in Runner registration: + +1. You register the Runner via the GitLab API using a registration token, and an + authentication token is returned. +1. You use that authentication token and add it to the + [Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file): + + ```toml + [[runners]] + token = "<authentication_token>" + ``` + +GitLab and Runner are then connected. + ## List owned runners Get a list of specific runners available to the user. @@ -456,7 +479,7 @@ POST /runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Registration token ([Read how to obtain a token](../ci/runners/README.md)) | +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | | `description`| string | no | Runner's description| | `info` | hash | no | Runner's metadata | | `active` | boolean| no | Whether the Runner is active | @@ -466,7 +489,7 @@ POST /runners | `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | ``` -curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` Response: @@ -494,10 +517,10 @@ DELETE /runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Runner's authentication token | +| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | ``` -curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e" +curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>" ``` Response: @@ -516,10 +539,10 @@ POST /runners/verify | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Runner's authentication token | +| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | ``` -curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e" +curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>" ``` Response: diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 54493bc2922..eaafc7bc1c0 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -664,7 +664,7 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* ### Scoping environments with specs **[PREMIUM]** Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can behave differently for each -environment. For example, you can [create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-variables-premium). +environment. For example, you can [create a secret variable to be injected only into a production environment](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium). In most cases, these features use the _environment specs_ mechanism, which offers an efficient way to implement scoping within each environment group. diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index 908cf85980e..d6ad00a77da 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -511,7 +511,7 @@ Errors can be easily debugged through GitLab's build logs, and within minutes of you can see the changes live on your game. Setting up Continuous Integration and Continuous Deployment from the start with Dark Nova enables -rapid but stable development. We can easily test changes in a separate [environment](../../../ci/environments.md#introduction-to-environments-and-deployments), +rapid but stable development. We can easily test changes in a separate [environment](../../environments.md), or multiple environments if needed. Balancing and updating a multiplayer game can be ongoing and tedious, but having faith in a stable deployment with GitLab CI/CD allows a lot of breathing room in quickly getting changes to players. diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index d505f2ae4ce..6055d8c282a 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -127,7 +127,7 @@ displayed by GitLab:  At the end, if anything goes wrong, you can easily -[roll back](../environments.md#rolling-back-changes) all the changes: +[roll back](../environments.md#retrying-and-rolling-back) all the changes:  diff --git a/doc/ci/merge_request_pipelines/img/merge_request.png b/doc/ci/merge_request_pipelines/img/merge_request.png Binary files differindex cf9c628e9a0..d03fdc6a885 100644 --- a/doc/ci/merge_request_pipelines/img/merge_request.png +++ b/doc/ci/merge_request_pipelines/img/merge_request.png diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png Binary files differnew file mode 100644 index 00000000000..58d5581f628 --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png Binary files differnew file mode 100644 index 00000000000..0a84e61d284 --- /dev/null +++ b/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index e8953d235a7..4f61e97bd8a 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -2,14 +2,16 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6. -Usually, when you create a new merge request, a pipeline runs on the +Usually, when you create a new merge request, a pipeline runs with the new change and checks if it's qualified to be merged into a target branch. This -pipeline should contain only necessary jobs for checking the new changes. +pipeline should contain only necessary jobs for validating the new changes. For example, unit tests, lint checks, and [Review Apps](../review_apps/index.md) are often used in this cycle. With pipelines for merge requests, you can design a specific pipeline structure -for merge requests. +for when you are running a pipeline in a merge request. This +could be either adding or removing steps in the pipeline, to make sure that +your pipelines are as efficient as possible. ## Configuring pipelines for merge requests @@ -30,9 +32,7 @@ build: stage: build script: ./build only: - - branches - - tags - - merge_requests + - master test: stage: test @@ -43,6 +43,8 @@ test: deploy: stage: deploy script: ./deploy + only: + - master ``` After the merge request is updated with new commits: @@ -50,18 +52,58 @@ After the merge request is updated with new commits: - GitLab detects that changes have occurred and creates a new pipeline for the merge request. - The pipeline fetches the latest code from the source branch and run tests against it. -In the above example, the pipeline contains only `build` and `test` jobs. -Since the `deploy` job doesn't have the `only: merge_requests` parameter, -deployment jobs will not happen in the merge request. +In the above example, the pipeline contains only a `test` job. +Since the `build` and `deploy` jobs don't have the `only: merge_requests` parameter, +they will not run in the merge request. -Pipelines tagged with the **merge request** badge indicate that they were triggered +Pipelines tagged with the **detached** badge indicate that they were triggered when a merge request was created or updated. For example:  -The same tag is shown on the pipeline's details: +## Combined ref pipelines **[PREMIUM]** + +> [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. + +It's possible for your source and target branches to diverge, which can result +in the scenario that source branch's pipeline was green, the target's pipeline was green, +but the combined output fails. By having your merge request pipeline automatically +create a new ref that contains the merge result of the source and target branch +(then running a pipeline on that ref), we can better test that the combined result +is also valid. + +From GitLab 11.10, pipelines for merge requests run by default +on this merged result. That is, where the source and target branches are combined into a +new ref and a pipeline for this ref validates the result prior to merging. + + + +There are some cases where creating a combined ref is not possible or not wanted. +For example, a source branch that has conflicts with the target branch +or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state +and runs on the source branch ref as if it was a regular pipeline. + +The detached state serves to warn you that you are working in a situation +subjected to merge problems, and helps to highlight that you should +get out of WIP status or resolve merge conflicts as soon as possible. - +### Enabling combined ref pipelines + +This feature disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186). It can be enabled at the project level: + +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. Check **Merge pipelines will try to validate the post-merge result prior to merging**. +1. Click **Save changes** button. + + + +### Combined ref pipeline's limitations + +- This feature requires [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. +- This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. +- After the merge request pipeline succeeds, if the target branch has moved forward, the result of the pipeline is stale and must be retried. In busy repos, this can become a problem as it is highly probable that the target branch will have moved ahead. Improvements are [planned](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) for future versions of GitLab. +- Forking/cross-repo workflows are not currently supported. To follow progress, see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713). +- This feature is not available for [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md) yet. To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226). ## Excluding certain jobs @@ -138,3 +180,12 @@ External users could steal secret variables from the parent project by modifying We're discussing a secure solution of running pipelines for merge requests that submitted from forked projects, see [the issue about the permission extension](https://gitlab.com/gitlab-org/gitlab-ce/issues/23902). + +## Additional predefined variables + +By using pipelines for merge requests, GitLab exposes additional predefined variables to the pipeline jobs. +Those variables contain information of the associated merge request, so that it's useful +to integrate your job with [GitLab Merge Request API](../../api/merge_requests.md). + +You can find the list of avilable variables in [the reference sheet](../variables/predefined_variables.md). +The variable names begin with the `CI_MERGE_REQUEST_` prefix. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 38cd58f11ac..2ffa3d4edc7 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -295,7 +295,7 @@ You can do this straight from the pipeline graph. Just click on the play button to execute that particular job. For example, your pipeline start automatically, but require manual action to -[deploy to production](environments.md#manually-deploying-to-environments). In the example below, the `production` +[deploy to production](environments.md#configuring-manual-deployments). In the example below, the `production` stage has a job with a manual action.  @@ -313,7 +313,7 @@ For example, if you start rolling out new code and: - Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%. - Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline - and [rolling](environments.md#rolling-back-changes) back to the last stable version. + and [rolling](environments.md#retrying-and-rolling-back) back to the last stable version.  diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 53651a807c2..2fc1e14f02e 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -33,7 +33,7 @@ In this example, you can see a branch was: ## How do Review Apps work? -The basis of Review Apps in GitLab is [dynamic environments](../environments.md#dynamic-environments), which allow you to dynamically create a new environment for each branch. +The basis of Review Apps in GitLab is [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch. Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment. @@ -60,14 +60,14 @@ To get a better understanding of Review Apps, review documentation on how enviro 1. Learn about [environments](../environments.md) and their role in the development workflow. 1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. 1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. -1. Additionally, find out about [manual actions](../environments.md#manually-deploying-to-environments) and how you can use them to deploy to critical environments like production with the push of a button. +1. Additionally, find out about [manual actions](../environments.md#configuring-manual-deployments) and how you can use them to deploy to critical environments like production with the push of a button. 1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. ### Configuring dynamic environments Configuring Review Apps dynamic environments depends on your technology stack and infrastructure. -For more information, see [dynamic environments](../environments.md#dynamic-environments) documentation to understand how to define and create them. +For more information, see [dynamic environments](../environments.md#configuring-dynamic-environments) documentation to understand how to define and create them. ### Creating and destroying Review Apps diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 416627740d2..b429dc8c8be 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -23,6 +23,9 @@ future GitLab releases.** | `CHAT_INPUT` | 10.6 | all | Additional arguments passed in the [ChatOps](../chatops/README.md) command | | `CHAT_CHANNEL` | 10.6 | all | Source chat channel which triggered the [ChatOps](../chatops/README.md) command | | `CI` | all | 0.4 | Mark that job is executed in CI environment | +| `CI_BUILDS_DIR` | all | 11.10 | Top-level directory where builds are executed. | +| `CI_CONCURRENT_ID` | all | 11.10 | Unique ID of build execution within a single executor. | +| `CI_CONCURRENT_PROJECT_ID` | all | 11.10 | Unique ID of build execution within a single executor and project. | | `CI_COMMIT_BEFORE_SHA` | 11.2 | all | The previous latest commit present on a branch before a push request. | | `CI_COMMIT_DESCRIPTION` | 10.8 | all | The description of the commit: the message without first line, if the title is shorter than 100 characters; full message in other case. | | `CI_COMMIT_MESSAGE` | 10.8 | all | The full commit message. | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 686d36c50ee..cf2189cd00a 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -756,7 +756,7 @@ Manual actions are a special type of job that are not executed automatically, they need to be explicitly started by a user. An example usage of manual actions would be a deployment to a production environment. Manual actions can be started from the pipeline, job, environment, and deployment views. Read more at the -[environments documentation](../environments.md#manually-deploying-to-environments). +[environments documentation](../environments.md#configuring-manual-deployments). Manual actions can be either optional or blocking. Blocking manual actions will block the execution of the pipeline at the stage this action is defined in. It's @@ -2362,8 +2362,35 @@ variables: GIT_STRATEGY: clone GIT_CHECKOUT: "false" script: - - git checkout master - - git merge $CI_BUILD_REF_NAME + - git checkout -B master origin/master + - git merge $CI_COMMIT_SHA +``` + +#### Git clean flags + +> Introduced in GitLab Runner 11.10 + +The `GIT_CLEAN_FLAGS` variable is used to control the default behavior of +`git clean` after checking out the sources. You can set it globally or per-job in the +[`variables`](#variables) section. + +`GIT_CLEAN_FLAGS` accepts all possible options of the [git clean](https://git-scm.com/docs/git-clean) +command. + +`git clean` is disabled if `GIT_CHECKOUT: "false"` is specified. + +If `GIT_CLEAN_FLAGS` is: + +- Not specified, `git clean` flags default to `-ffdx`. +- Given the value `none`, `git clean` is not executed. + +For example: + +```yaml +variables: + GIT_CLEAN_FLAGS: -ffdx -e cache/ +script: + - ls -al cache/ ``` #### Job stages attempts @@ -2439,6 +2466,72 @@ CAUTION: **Deprecated:** `type` is deprecated, and could be removed in one of the future releases. Use [`stage`](#stage) instead. +## Custom build directories + +> [Introduced][https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267] in Gitlab Runner 11.10 + +NOTE: **Note:** +This can only be used when `custom_build_dir` is enabled in the [Runner's +configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). +This is the default configuration for `docker` and `kubernetes` executor. + +By default, GitLab Runner clones the repository in a unique subpath of the `$CI_BUILDS_DIR` directory. +However, sometimes your project might require the code in a specific directory, +but sometimes your project might require to have the code in a specific directory, +like Go projects, for example. In that case, you can specify the `GIT_CLONE_PATH` variable +to tell the Runner in which directory to clone the repository: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/project-name + +test: + script: + - pwd +``` + +The `GIT_CLONE_PATH` has to always be within `$CI_BUILDS_DIR`. The directory set in `$CI_BUILDS_DIR` +is dependent on executor and configuration of [runners.builds_dir](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) +setting. + +### Handling concurrency + +An executor using a concurrency greater than `1` might lead +to failures because multiple jobs might be working on the same directory if the `builds_dir` +is shared between jobs. +GitLab Runner does not try to prevent this situation. It is up to the administrator +and developers to comply with the requirements of Runner configuration. + +To avoid this scenario, you can use a unique path within `$CI_BUILDS_DIR`, because Runner +exposes two additional variables that provide a unique `ID` of concurrency: + +- `$CI_CONCURRENT_ID`: Unique ID for all jobs running within the given executor. +- `$CI_CONCURRENT_PROJECT_ID`: Unique ID for all jobs running within the given executor and project. + +The most stable configuration that should work well in any scenario and on any executor +is to use `$CI_CONCURRENT_ID` in the `GIT_CLONE_PATH`. For example: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/project-name + +test: + script: + - pwd +``` + +The `$CI_CONCURRENT_PROJECT_ID` should be used in conjunction with `$CI_PROJECT_PATH` +as the `$CI_PROJECT_PATH` provides a path of a repository. That is, `group/subgroup/project`. For example: + +```yml +variables: + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_PATH + +test: + script: + - pwd +``` + ## Special YAML features It's possible to use special YAML features like anchors (`&`), aliases (`*`) diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 6f6b361f423..548d72bea93 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -12,7 +12,15 @@ led by the [GitLab UI WG](https://gitlab.com/gitlab-com/www-gitlab-com/merge_req We have a few internal utility classes in [`common.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/framework/common.scss) and we use [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/) -New utility classes should be added to [`common.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/framework/common.scss). +New utility classes should be added to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/utilities.scss). Existing classes include: + +**Background color**: `.bg-variant-shade` e.g. `.bg-warning-400` +**Text color**: `.text-variant-shade` e.g. `.text-success-500` +- variant is one of 'primary', 'secondary', 'success', 'warning', 'error' +- shade is on of the shades listed on [colors](https://design.gitlab.com/foundations/colors/) + +**Font size**: `.text-size` e.g. `.text-2` +- **size** is number from 1-6 from our [Type scale](https://design.gitlab.com/foundations/typography) ### Naming diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index ffc71051377..55ca502f84a 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -130,9 +130,9 @@ secure note named **gitlab-{ce,ee} Review App's root password**. 1. Find and open the `task-runner` Deployment, e.g. `review-29951-issu-id2qax-task-runner`. 1. Click on the Pod in the "Managed pods" section, e.g. `review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz`. 1. Click on the `KUBECTL` dropdown, then `Exec` -> `task-runner`. -1. Replace `-c task-runner -- ls` with `-- /srv/gitlab/bin/rails c` from the +1. Replace `-c task-runner -- ls` with `-it -- gitlab-rails console` from the default command or - - Run `kubectl exec --namespace review-apps-ce -it review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz -- /srv/gitlab/bin/rails c` + - Run `kubectl exec --namespace review-apps-ce review-29951-issu-id2qax-task-runner-d5455cc8-2lsvz -it -- gitlab-rails console` and - Replace `review-apps-ce` with `review-apps-ee` if the Review App is running EE, and diff --git a/doc/install/README.md b/doc/install/README.md index 52011526768..53778f7f0d3 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -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 diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 9db246b3eb3..43655767002 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -1,156 +1,5 @@ -# 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/). diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index c0cb7694e91..43655767002 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -1,246 +1,5 @@ -# 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/). diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md index 68b2a146115..08ccf2cf9ad 100644 --- a/doc/install/kubernetes/gitlab_runner_chart.md +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -1,269 +1,5 @@ -# 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). diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md index ecc956d04e9..7312bf2d4f7 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -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). diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md index a3a0cba4bf2..db55e03d3d4 100644 --- a/doc/install/kubernetes/preparation/connect.md +++ b/doc/install/kubernetes/preparation/connect.md @@ -1,27 +1,5 @@ -# 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/). diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md index ea3b075dd82..975d35c11c6 100644 --- a/doc/install/kubernetes/preparation/eks.md +++ b/doc/install/kubernetes/preparation/eks.md @@ -1,45 +1,5 @@ -# 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). diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md index b9fb9a7399f..2af16a752dc 100644 --- a/doc/install/kubernetes/preparation/networking.md +++ b/doc/install/kubernetes/preparation/networking.md @@ -1,38 +1,5 @@ -# 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). diff --git a/doc/install/kubernetes/preparation/rbac.md b/doc/install/kubernetes/preparation/rbac.md index c5f8d7a7e9e..f94e7c24cdc 100644 --- a/doc/install/kubernetes/preparation/rbac.md +++ b/doc/install/kubernetes/preparation/rbac.md @@ -1,20 +1,5 @@ -# 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). diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md index 684df14ac2c..66d6c8faece 100644 --- a/doc/install/kubernetes/preparation/tiller.md +++ b/doc/install/kubernetes/preparation/tiller.md @@ -1,109 +1,5 @@ -# 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). diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md index d2f7a69a0af..66d6c8faece 100644 --- a/doc/install/kubernetes/preparation/tools_installation.md +++ b/doc/install/kubernetes/preparation/tools_installation.md @@ -1,19 +1,5 @@ -# 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). diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 7693109b3c4..9060360e6a2 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -955,7 +955,7 @@ required to go from `10%` to `100%`, you can jump to whatever job you want. You can also scale down by running a lower percentage job, just before hitting `100%`. Once you get to `100%`, you cannot scale down, and you'd have to roll back by redeploying the old version using the -[rollback button](../../ci/environments.md#rolling-back-changes) in the +[rollback button](../../ci/environments.md#retrying-and-rolling-back) in the environment page. Below, you can see how the pipeline will look if the rollout or staging diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 3bcfd30079d..9c3f6fcec9b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -151,6 +151,17 @@ There are two different ways to add a new project to a group:  +### Default project creation level + +Group owners or administrators can allow users with the +Developer role to create projects under groups. + +By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under agroup, but this can be changed either within the group settings for a group, or +be set globally by a GitLab administrator in the Admin area +at **Settings > General > Visibility and access controls**. + +Available settings are `No one`, `Maintainers`, or `Developers + Maintainers`. + ## Transfer projects into groups Learn how to [transfer a project into a group](../project/settings/index.md#transferring-an-existing-project-into-another-namespace). diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c94a3f4d3b5..878d30dddaa 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -570,7 +570,7 @@ deployment jobs, immediately before the jobs starts. However, sometimes GitLab can not create them. In such instances, your job will fail with the message: ```text -The job failed to complete prerequisite tasks +This job failed because the necessary resources were not successfully created. ``` To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#sidekiqlog). diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded.png b/doc/user/project/clusters/serverless/img/function-details-loaded.png Binary files differnew file mode 100644 index 00000000000..34465c5c087 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/function-details-loaded.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 96bf455116c..5b7e9ef906f 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -11,13 +11,12 @@ Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/ Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, container-based applications. Knative brings some significant benefits out of the box through its main components: -- [Build](https://github.com/knative/build): Source-to-container build orchestration. -- [Eventing](https://github.com/knative/eventing): Management and delivery of events. - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. +- [Eventing](https://github.com/knative/eventing): Management and delivery of events. For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). -With GitLab serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. +With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. ## Prerequisites @@ -41,13 +40,16 @@ To run Knative on Gitlab, you will need: wildcard domain where your applications will be served. Configure your DNS server to use the external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application and the [TriggerMesh CLI](https://github.com/triggermesh/tm) to simplify the - deployment of knative services and functions. + to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the + deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file will contain the information for all the functions being hosted in the repository as well as a reference to the runtime being used. -1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a `Dockerfile` in order to build your application. It should be included - at the root of your project's repo and expose port `8080`. +1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a + `Dockerfile` in order to build your applications. It should be included at the root of your + project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). 1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. See [Installing Applications](../index.md#installing-applications) for more information. @@ -89,10 +91,11 @@ Using functions is useful for dealing with independent events without needing to maintain a complex unified infrastructure. This allows you to focus on a single task that can be executed/scaled automatically and independently. -Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are offered: +Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: +- ruby - node.js -- kaniko +- Dockerfile You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. @@ -111,13 +114,17 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ include: template: Serverless.gitlab-ci.yml - functions: + functions:build: + extends: .serverless:build:functions + environment: production + + functions:deploy: extends: .serverless:deploy:functions environment: production ``` - This `.gitlab-ci.yml` creates a `functions` job that invokes some - predefined commands to deploy your functions to your cluster. + This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to + build and deploy your functions to your cluster. `Serverless.gitlab-ci.yml` is a template that allows customization. You can either import it with `include` parameter and use `extends` to @@ -135,29 +142,40 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ You can find the relevant files for this project in the [functions example project](https://gitlab.com/knative-examples/functions). ```yaml - service: my-functions - description: "Deploying functions from GitLab using Knative" + service: functions + description: "GitLab Serverless functions using Knative" provider: name: triggermesh - registry-secret: gitlab-registry environment: - FOO: BAR + FOO: value functions: - echo: - handler: echo - runtime: https://gitlab.com/triggermesh/runtimes/raw/master/nodejs.yaml - description: "echo function using node.js runtime" - buildargs: - - DIRECTORY=echo + echo-js: + handler: echo-js + source: ./echo-js + runtime: https://gitlab.com/gitlab-org/serverless/runtimes/nodejs + description: "node.js runtime function" + environment: + MY_FUNCTION: echo-js + + echo-rb: + handler: MyEcho.my_function + source: ./echo-rb + runtime: https://gitlab.com/gitlab-org/serverless/runtimes/ruby + description: "Ruby runtime function" + environment: + MY_FUNCTION: echo-rb + + echo-docker: + handler: echo-docker + source: ./echo-docker + description: "Dockerfile runtime function" environment: - FUNCTION: echo + MY_FUNCTION: echo-docker ``` -The `serverless.yml` file references both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`), -which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it -contains three sections with distinct parameters: +Explanation of the fields used above: ### `service` @@ -171,7 +189,6 @@ contains three sections with distinct parameters: | Parameter | Description | |-----------|-------------| | `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh `tm` CLI. | -| `registry-secret` | Indicates which registry will be used to store docker images. The sample function is using the GitLab Registry (`gitlab-registry`). A different registry host may be specified using `registry` key in the `provider` object. If changing the default, update the permission and the secret value on the `gitlab-ci.yml` file | | `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. | ### `functions` @@ -180,10 +197,10 @@ In the `serverless.yml` example above, the function name is `echo` and the subse | Parameter | Description | |-----------|-------------| -| `handler` | The function's file name. In the example above, both the function name and the handler are the same. | +| `handler` | The function's name. | +| `source` | Directory with sources of a functions. | | `runtime` | The runtime to be used to execute the function. | | `description` | A short description of the function. | -| `buildargs` | Pointer to the function file in the repo. In the sample the function is located in the `echo` directory. | | `environment` | Sets an environment variable for the specific function only. | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been @@ -284,3 +301,23 @@ The second to last line, labeled **Service domain** contains the URL for the dep browser to see the app live.  + +## Function details + +Go to the **Operations > Serverless** page and click on one of the function +rows to bring up the function details page. + + + +The pod count will give you the number of pods running the serverless function instances on a given cluster. + +### Prometheus support + +For the Knative function invocations to appear, +[Prometheus must be installed](../index.md#installing-applications). + +Once Prometheus is installed, a message may appear indicating that the metrics data _is +loading or is not available at this time._ It will appear upon the first access of the +page, but should go away after a few seconds. If the message does not disappear, then it +is possible that GitLab is unable to connect to the Prometheus instance running on the +cluster. |
