diff options
Diffstat (limited to 'doc/user')
60 files changed, 854 insertions, 246 deletions
diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 6025a5bbcda..d4853a5842e 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -49,3 +49,19 @@ and the default value is `30 days`. On GitLab.com they This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts-expire_in). To disable the expiration, set it to `0`. The default unit is in seconds. + +## Archive jobs **[CORE ONLY]** + +Archiving jobs is useful for reducing the CI/CD footprint on the system by +removing some of the capabilities of the jobs (metadata needed to run the job), +but persisting the traces and artifacts for auditing purposes. + +To set the duration for which the jobs will be considered as old and expired: + +1. Go to **Admin area > Settings > CI/CD > Continuous Integration and Deployment**. +1. Change the value of "Archive jobs". +1. Hit **Save changes** for the changes to take effect. + +Once that time passes, the jobs will be archived and no longer able to be +retried. Make it empty to never expire jobs. It has to be no less than 1 day, +for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 93aa41e9a98..6c6119a2691 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -1,6 +1,11 @@ -# Markdown +# GitLab Markdown -This markdown guide is valid for GitLab's system markdown entries and files. +This markdown guide is **valid for GitLab's system markdown entries and files**. +It is not valid for the [GitLab documentation website](https://docs.gitlab.com) +nor [GitLab's main website](https://about.gitlab.com), as they both use +[Kramdown](https://kramdown.gettalong.org) as their markdown engine. +The documentation website uses an extended Kramdown gem, [GitLab Kramdown](https://gitlab.com/gitlab-org/gitlab_kramdown). +Consult the [GitLab Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) for a complete Kramdown reference._ ## GitLab Flavored Markdown (GFM) @@ -8,21 +13,21 @@ GitLab uses "GitLab Flavored Markdown" (GFM). It extends the [CommonMark specifi You can use GFM in the following areas: -- comments -- issues -- merge requests -- milestones -- snippets (the snippet must be named with a `.md` extension) -- wiki pages -- markdown documents inside the repository +- Comments +- Issues +- Merge requests +- Milestones +- Snippets (the snippet must be named with a `.md` extension) +- Wiki pages +- Markdown documents inside repositories You can also use other rich text files in GitLab. You might have to install a dependency to do so. Please see the [`github-markup` gem readme](https://github.com/gitlabhq/markup#markups) for more information. > **Notes:** > -> For the best result, we encourage you to check this document out as rendered -> by GitLab itself: [markdown.md] +> For the best result, we encourage you to check this document out as [rendered +> by GitLab itself](markdown.md). > > As of 11.1, GitLab uses the [CommonMark Ruby Library][commonmarker] for Markdown processing of all new issues, merge requests, comments, and other Markdown content @@ -30,6 +35,9 @@ in the GitLab system. As of 11.3, wiki pages and Markdown files (`.md`) in the repositories are also processed with CommonMark. Older content in issues/comments are still processed using the [Redcarpet Ruby library][redcarpet]. > +> The documentation website had its [markdown engine migrated from Redcarpet to Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) +in October 2018. +> > _Where there are significant differences, we will try to call them out in this document._ ### Transitioning to CommonMark diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 1fd230a41aa..c4a2d5f66e5 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -95,7 +95,7 @@ The following table depicts the various user permission levels in a project. | Manage GitLab Pages | | | | ✓ | ✓ | | Manage GitLab Pages domains and certificates | | | | ✓ | ✓ | | Remove GitLab Pages | | | | | ✓ | -| View GitLab Pages protected by [access control](../administration/pages/index.md#access-control) | ✓ | ✓ | ✓ | ✓ | ✓ | +| View GitLab Pages protected by [access control](project/pages/introduction.md#gitlab-pages-access-control-core-only) | ✓ | ✓ | ✓ | ✓ | ✓ | | Manage clusters | | | | ✓ | ✓ | | Manage license policy **[ULTIMATE]** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 64219737d61..76f7e869ff7 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -158,7 +158,7 @@ authentication. If an SSH key is added to your GitLab account, you can generate a new set of recovery codes with SSH. 1. Run `ssh git@gitlab.example.com 2fa_recovery_codes`. -2. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. +1. You are prompted to confirm that you want to generate new codes. Continuing this process invalidates previously saved codes. ``` bash $ ssh git@gitlab.example.com 2fa_recovery_codes @@ -185,7 +185,7 @@ a new set of recovery codes with SSH. so you do not lose access to your account again. ``` -3. Go to the GitLab sign-in page and enter your username/email and password. +1. Go to the GitLab sign-in page and enter your username/email and password. When prompted for a two-factor code, enter one of the recovery codes obtained from the command-line output. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index da7c30b6b39..2f989a26725 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -97,13 +97,13 @@ You and GitLab admins can see your the abovementioned information on your profil > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/14078) in GitLab 11.3. -Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. +Enabling private contributions will include contributions to private projects, in the user contribution calendar graph and user recent activity. To enable private contributions: 1. Navigate to your personal [profile settings](#profile-settings). -2. Check the "Private contributions" option. -3. Hit **Update profile settings**. +1. Check the "Private contributions" option. +1. Hit **Update profile settings**. ## Current status diff --git a/doc/user/project/clusters/eks_and_gitlab/img/new_project.png b/doc/user/project/clusters/eks_and_gitlab/img/new_project.png Binary files differdeleted file mode 100644 index 02afc099f10..00000000000 --- a/doc/user/project/clusters/eks_and_gitlab/img/new_project.png +++ /dev/null diff --git a/doc/user/project/clusters/eks_and_gitlab/img/rbac.png b/doc/user/project/clusters/eks_and_gitlab/img/rbac.png Binary files differnew file mode 100644 index 00000000000..517e4f7ca44 --- /dev/null +++ b/doc/user/project/clusters/eks_and_gitlab/img/rbac.png diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index ef19b05fb9e..fa2ed21f980 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -1,75 +1,171 @@ ---- -author: Joshua Lambert -author_gitlab: joshlambert -level: intermediate -article_type: tutorial -date: 2018-06-05 ---- - # Connecting and deploying to an Amazon EKS cluster -## Introduction +In this tutorial, we will show how to integrate an +[Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin +deploying applications. -In this tutorial, we will show how easy it is to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab, and begin deploying applications. +## Introduction For an end-to-end walkthrough we will: -1. Start with a new project based on the sample Ruby on Rails template -1. Integrate an EKS cluster -1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application +1. Start with a new project based on the sample Ruby on Rails template. +1. Integrate an EKS cluster. +1. Utilize [Auto DevOps](../../../../topics/autodevops/) to build, test, and deploy our application. You will need: -1. An account on GitLab, like [GitLab.com](https://gitlab.com) -1. An Amazon EKS cluster -1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) +1. An account on GitLab, like [GitLab.com](https://gitlab.com). +1. An Amazon EKS cluster (with worker nodes properly configured). +1. `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). -If you don't have an Amazon EKS cluster, one can be created by following [the EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). +If you don't have an Amazon EKS cluster, one can be created by following the +[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). ## Creating a new project -On GitLab, create a new project by clicking on the `+` icon in the top navigation bar, and selecting `New project`. - - +On GitLab, create a new project by clicking on the `+` icon in the top navigation +bar and selecting **New project**. -On the new project screen, click on the `Create from template` tab, and select `Use template` for the Ruby on Rails sample project. +On the new project screen, click on the **Create from template** tab, and select +"Use template" for the Ruby on Rails sample project. -Give the project a name, and then select `Create project`. +Give the project a name, and then select **Create project**.  -## Connecting the EKS cluster +## Configuring and connecting the EKS cluster + +From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, +then click **Add an existing Kubernetes cluster**. + +A few details from the EKS cluster will be required to connect it to GitLab: + +1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to + authenticate to the EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: + + - List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + - Get the certificate with: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D + ``` + +1. **Create admin token**: A `cluster-admin` token is required to install and + manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller + and creates limited service accounts for each application. To create the + token we will create an admin service account as follows: + + 2.1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 2.2. Apply the service account to your cluster: + + ```bash + kubectl apply -f eks-admin-service-account.yaml + ``` + + Output: + + ```bash + serviceaccount "eks-admin" created + ``` -From the left side bar, hover over `Operations` and select `Kubernetes`, then click on `Add Kubernetes cluster`, and finally `Add an existing Kubernetes cluster`. + 2.3. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: -A few details from the EKS cluster will be required to connect it to GitLab. + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` -1. A valid Kubernetes certificate and token are needed to authenticate to the EKS cluster. A pair is created by default, which can be used. Open a shell and use `kubectl` to retrieve them: - * List the secrets with `kubectl get secrets`, and one should named similar to `default-token-xxxxx`. Copy that token name for use below. - * Get the certificate with `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 -D` - * Retrieve the token with `kubectl get secret <secret name> -o jsonpath="{['data']['token']}" | base64 -D`. -1. The API server endpoint is also required, so GitLab can connect to the cluster. This is displayed on the AWS EKS console, when viewing the EKS cluster details. + 2.4. Apply the cluster role binding to your cluster: + + ```bash + kubectl apply -f eks-admin-cluster-role-binding.yaml + ``` + + Output: + + ```bash + clusterrolebinding "eks-admin" created + ``` + + 2.5. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + +1. The API server endpoint is also required, so GitLab can connect to the cluster. + This is displayed on the AWS EKS console, when viewing the EKS cluster details. You now have all the information needed to connect the EKS cluster: -* Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. -* Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. -* API URL: Paste in the API server endpoint retrieved above. -* CA Certificate: Paste the certificate data from the earlier step, as-is. -* Paste the token value. -* Project namespace: This can be left blank to accept the default namespace, based on the project name. +- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. +- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. +- API URL: Paste in the API server endpoint retrieved above. +- CA Certificate: Paste the certificate data from the earlier step, as-is. +- Paste the admin token value. +- Project namespace: This can be left blank to accept the default namespace, based on the project name.  -Click on `Add Kubernetes cluster`, the cluster is now connected to GitLab. At this point, [Kubernetes deployment variables](../#deployment-variables) will automatically be available during CI jobs, making it easy to interact with the cluster. +Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. +At this point, [Kubernetes deployment variables](../#deployment-variables) will +automatically be available during CI/CD jobs, making it easy to interact with the cluster. If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. -## Disable Role-Based Access Control (RBAC) +## Disable Role-Based Access Control (RBAC) (optional) -Presently, Auto DevOps and one-click app installs do not support [Kubernetes role-based access control](https://kubernetes.io/docs/reference/access-authn-authz/rbac/). Support is [being worked on](https://gitlab.com/groups/gitlab-org/-/epics/136), but in the interim RBAC must be disabled to utilize for these features. +When connecting a cluster via GitLab integration, you may specify whether the +cluster is RBAC-enabled or not. This will affect how GitLab interacts with the +cluster for certain operations. If you **did not** check the "RBAC-enabled cluster" +checkbox at creation time, GitLab will assume RBAC is disabled for your cluster +when interacting with it. If so, you must disable RBAC on your cluster for the +integration to work properly. -> **Note**: Disabling RBAC means that any application running in the cluster, or user who can authenticate to the cluster, has full API access. This is a [security concern](https://docs.gitlab.com/ee/user/project/clusters/#security-implications), and may not be desirable. + + +NOTE: **Note**: Disabling RBAC means that any application running in the cluster, +or user who can authenticate to the cluster, has full API access. This is a +[security concern](../index.md#security-implications), and may not be desirable. To effectively disable RBAC, global permissions can be applied granting full access: @@ -83,56 +179,100 @@ kubectl create clusterrolebinding permissive-binding \ ## Deploy services to the cluster -GitLab supports one-click deployment of helpful services to the cluster, many of which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a list of applications is now available to deploy. +GitLab supports one-click deployment of helpful services to the cluster, many of +which support Auto DevOps. Back on the Kubernetes cluster screen in GitLab, a +list of applications is now available to deploy. -First install Helm Tiller, a package manager for Kubernetes. This enables deployment of the other applications. +First, install Helm Tiller, a package manager for Kubernetes. This enables +deployment of the other applications.  ### Deploying NGINX Ingress (optional) -Next, if you would like the deployed app to be reachable on the internet, deploy the Ingress. Note that this will also cause an [Elastic Load Balancer](https://aws.amazon.com/documentation/elastic-load-balancing/) to be created, which will incur additional AWS costs. +Next, if you would like the deployed app to be reachable on the internet, deploy +the Ingress. Note that this will also cause an +[Elastic Load Balancer](https://aws.amazon.com/documentation/elastic-load-balancing/) +to be created, which will incur additional AWS costs. -Once installed, you may see a `?` for `Ingress IP Address`. This is because the created ELB is available at a DNS name, not an IP address. To get the DNS name, run: `kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"`. Note, you may see a trailing `%` on some Kubernetes versions, do not include it. +Once installed, you may see a `?` for "Ingress IP Address". This is because the +created ELB is available at a DNS name, not an IP address. To get the DNS name, +run: -The Ingress is now available at this address, and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS CNAME record should be created for the desired domain name. For example `*.myekscluster.com` would point to the Ingress hostname obtained earlier. +```sh +kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}" +``` + +Note that you may see a trailing `%` on some Kubernetes versions, **do not include it**. + +The Ingress is now available at this address and will route incoming requests to +the proper service based on the DNS name in the request. To support this, a +wildcard DNS CNAME record should be created for the desired domain name. For example, +`*.myekscluster.com` would point to the Ingress hostname obtained earlier.  ### Deploying the GitLab Runner (optional) -If the project is on GitLab.com, free shared runners are available and you do not have to deploy one. If a project specific runner is desired, or there are no shared runners, it is easy to deploy one. +If the project is on GitLab.com, free shared Runners are available and you do +not have to deploy one. If a project specific Runner is desired, or there are no +shared Runners, it is easy to deploy one. -Simply click on the `Install` button for the GitLab Runner. It is important to note that the runner deployed is set as **privileged**, which means it essentially has root access to the underlying machine. This is required to build docker images, and so is on by default. +Simply click on the **Install** button for the GitLab Runner. It is important to +note that the Runner deployed is set as **privileged**, which means it essentially +has root access to the underlying machine. This is required to build docker images, +and so is on by default. ### Deploying Prometheus (optional) -GitLab is able to monitor applications automatically, utilizing [Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and memory metrics are automatically collected, and response metrics are retrieved from NGINX Ingress as well. +GitLab is able to monitor applications automatically, utilizing +[Prometheus](../../integrations/prometheus.html). Kubernetes container CPU and +memory metrics are automatically collected, and response metrics are retrieved +from NGINX Ingress as well. -To enable monitoring, simply install Prometheus into the cluster with the `Install` button. +To enable monitoring, simply install Prometheus into the cluster with the +**Install** button. ## Create a default Storage Class -Amazon EKS does not have a default Storage Class out of the box, which means requests for persistent volumes will not be automatically fulfilled. As part of Auto DevOps, the deployed Postgres instance requests persistent storage, and without a default storage class it will fail to start. +Amazon EKS doesn't have a default Storage Class out of the box, which means +requests for persistent volumes will not be automatically fulfilled. As part +of Auto DevOps, the deployed Postgres instance requests persistent storage, +and without a default storage class it will fail to start. -If a default Storage Class does not already exist and is desired, follow Amazon's [short guide](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) to create one. +If a default Storage Class doesn't already exist and is desired, follow Amazon's +[guide on storage classes](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) +to create one. -Alternatively, disable Postgres by setting the project variable [`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. +Alternatively, disable Postgres by setting the project variable +[`POSTGRES_ENABLED`](../../../../topics/autodevops/#environment-variables) to `false`. ## Deploy the app to EKS -With RBAC disabled and services deployed, [Auto DevOps](https://docs.gitlab.com/ee/topics/autodevops/) can now be leveraged to build, test, and deploy the app. To enable, click on `Settings` in the left sidebar, then `CI/CD`. You will see a section for `Auto DevOps`, expand it. Click on the radio button to `Enable Auto DevOps`. +With RBAC disabled and services deployed, +[Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged +to build, test, and deploy the app. -If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field. Otherwise, the deployed app will not be externally available outside of the cluster. To save, click `Save changes`. +[Enable Auto DevOps](../../../../topics/autodevops/index.md##enablingdisabling-auto-devops-at-the-project-level) +if not already enabled. If a wildcard DNS entry was created resolving to the +Load Balancer, enter it in the `domain` field under the Auto DevOps settings. +Otherwise, the deployed app will not be externally available outside of the cluster.  -A new pipeline will automatically be created, which will begin to build, test, and deploy the app. +A new pipeline will automatically be created, which will begin to build, test, +and deploy the app. -After the pipeline has finished, your app will be running in EKS and available to users. Click on `CI/CD` tab in the left navigation bar, and choose `Environments`. +After the pipeline has finished, your app will be running in EKS and available +to users. Click on **CI/CD > Environments**.  -You will see a list of the environments and their deploy status, as well as options to browse to the app, view monitoring metrics, and even access a shell on the running pod. +You will see a list of the environments and their deploy status, as well as +options to browse to the app, view monitoring metrics, and even access a shell +on the running pod. + +## Learn more -To learn more about Auto DevOps, review our [documentation](../../../../topics/autodevops/). +To learn more on automatically deploying your applications, +read about [Auto DevOps](../../../../topics/autodevops/index.md). diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 94744cf8500..ca262e4b76e 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -49,8 +49,8 @@ new Kubernetes cluster to your project: NOTE: **Note:** You need Maintainer [permissions] and above to access the Kubernetes page. -1. Click on **Add Kubernetes cluster**. -1. Click on **Create with Google Kubernetes Engine**. +1. Click **Add Kubernetes cluster**. +1. Click **Create with Google Kubernetes Engine**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. From there on, choose your cluster's settings: @@ -78,8 +78,8 @@ To add an existing Kubernetes cluster to your project: NOTE: **Note:** You need Maintainer [permissions] and above to access the Kubernetes page. -1. Click on **Add Kubernetes cluster**. -1. Click on **Add an existing Kubernetes cluster** and fill in the details: +1. Click **Add Kubernetes cluster**. +1. Click **Add an existing Kubernetes cluster** and fill in the details: - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - **Environment scope** (required)- The [associated environment](#setting-the-environment-scope) to this cluster. @@ -132,59 +132,63 @@ functionalities needed to successfully build and deploy a containerized application. Bare in mind that the same credentials are used for all the applications running on the cluster. -When GitLab creates the cluster, it enables and uses the legacy -[Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/). -The newer [RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) -authorization is [experimental](#role-based-access-control-rbac). +## Access controls -### Role-based access control (RBAC) **[CORE ONLY]** +When creating a cluster in GitLab, you will be asked if you would like to create an +[Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/) cluster, or +a [Role-based access control (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/) one. -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21401) in GitLab 11.4. +Whether ABAC or RBAC is enabled, GitLab will create the necessary +service accounts and privileges in order to install and run +[GitLab managed applications](#installing-applications): -CAUTION: **Warning:** -The RBAC authorization is experimental. +- A `gitlab` service account with `cluster-admin` privileges will be created in the + `default` namespace, which will be used by GitLab to manage the newly created cluster. -Once RBAC is enabled for a cluster, GitLab will create the necessary service accounts -and privileges in order to install and run [GitLab managed applications](#installing-applications). +- A project service account with [`edit` + privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + will be created in the project namespace (also created by GitLab), which will + be used in [deployment jobs](#deployment-variables). -If you are creating a [new GKE cluster via -GitLab](#adding-and-creating-a-new-gke-cluster-via-gitlab), you will be -asked if you would like to create an RBAC-enabled cluster. Enabling this -setting will create a `gitlab` service account which will be used by -GitLab to manage the newly created cluster. To enable this, this service -account will have the `cluster-admin` privilege. + NOTE: **Note:** + Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716) in GitLab 11.5. -If you are [adding an existing Kubernetes -cluster](#adding-an-existing-kubernetes-cluster), you will be asked if -the cluster you are adding is a RBAC-enabled cluster. Ensure the -token of the account has administrator privileges for the cluster. +- When you install Helm Tiller into your cluster, the `tiller` service account + will be created with `cluster-admin` privileges in the `gitlab-managed-apps` + namespace. This service account will be added to the installed Helm Tiller and will + be used by Helm to install and run [GitLab managed applications](#installing-applications). + Helm Tiller will also create additional service accounts and other resources for each + installed application. Consult the documentation of the Helm charts for each application + for details. -In both cases above, when you install Helm Tiller into your cluster, an -RBAC-enabled cluster will create a `tiller` service account, with `cluster-admin` -privileges in the `gitlab-managed-apps` namespace. This service account will be -added to the installed Helm Tiller and will be used by Helm to install and run -[GitLab managed applications](#installing-applications). +If you are [adding an existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster), +ensure the token of the account has administrator privileges for the cluster. -The table below summarizes which resources will be created in a -RBAC-enabled cluster : +The following sections summarize which resources will be created on ABAC/RBAC clusters. -| Name | Kind | Details | Created when | -| --- | --- | --- | --- | -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +### Attribute-based access control (ABAC) +| Name | Kind | Details | Created when | +| --- | --- | --- | --- | +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | -Helm Tiller will also create additional service accounts and other RBAC -resources for each installed application. Consult the documentation for the -Helm charts for each application for details. +### Role-based access control (RBAC) -NOTE: **Note:** -Auto DevOps will not successfully complete in a cluster that only has RBAC -authorization enabled. RBAC support for Auto DevOps is planned in a -[future release](https://gitlab.com/gitlab-org/gitlab-ce/issues/44597). +| Name | Kind | Details | Created when | +| --- | --- | --- | --- | +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | +| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating/Adding a new GKE Cluster | ### Security of GitLab Runners @@ -224,7 +228,11 @@ twice, which can lead to confusion during deployments. | [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | [stable/prometheus](https://github.com/helm/charts/tree/master/stable/prometheus) | | [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | | [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use [this](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) custom Jupyter image that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/amit1rrr/rubix). More information on creating executable runbooks can be found at [Nurtch Documentation](http://docs.nurtch.com/en/latest). **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | [jupyter/jupyterhub](https://jupyterhub.github.io/helm-chart/) | -| [Knative](https://cloud.google.com/knative) | 0.1.2 | Knative provides a platform to create, deploy, and manage serverless workloads from a Kubernetes cluster. It is used in conjunction with, and includes [Istio](https://istio.io) to provide an external IP address for all programs hosted by Knative. You will be prompted to enter a wildcard domain where your applications will be exposed. Configure your DNS server to use the external IP address for that domain. For any application created and installed, they will be accessible as <program_name>.<kubernetes_namespace>.<domain_name>. **Note**: This will require your kubernetes cluster to have RBAC enabled. | [knative/knative](https://storage.googleapis.com/triggermesh-charts) +| [Knative](https://cloud.google.com/knative) | 11.5+ | Knative provides a platform to create, deploy, and manage serverless workloads from a Kubernetes cluster. It is used in conjunction with, and includes [Istio](https://istio.io) to provide an external IP address for all programs hosted by Knative. You will be prompted to enter a wildcard domain where your applications will be exposed. Configure your DNS server to use the external IP address for that domain. For any application created and installed, they will be accessible as `<program_name>.<kubernetes_namespace>.<domain_name>`. This will require your kubernetes cluster to have [RBAC enabled](#role-based-access-control-rbac). | [knative/knative](https://storage.googleapis.com/triggermesh-charts) + +NOTE: **Note:** +As of GitLab 11.6 Helm Tiller will be upgraded to the latest version supported +by GitLab before installing any of the above applications. ## Getting the external IP address @@ -251,14 +259,17 @@ your ingress application in which case you should manually determine it. ### Manually determining the IP address -If the cluster is on GKE, click on the **Google Kubernetes Engine** link in the +If the cluster is on GKE, click the **Google Kubernetes Engine** link in the **Advanced settings**, or go directly to the [Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click on **Connect** and execute +and select the proper project and cluster. Then click **Connect** and execute the `gcloud` command in a local terminal or using the **Cloud Shell**. If the cluster is not on GKE, follow the specific instructions for your Kubernetes provider to configure `kubectl` with the right credentials. +The output of the following examples will show the external IP address of your +cluster. This information can then be used to set up DNS entries and forwarding +rules that allow external access to your deployed applications. If you installed the Ingress [via the **Applications**](#installing-applications), run the following command: @@ -267,26 +278,23 @@ run the following command: kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' ``` -NOTE: **Note:** For Istio/Knative, the command will be different: + ```bash kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' ``` -Otherwise, you can list the IP addresses of all load balancers: +Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: ```bash -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}". ``` -> **Note**: Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: -> ```bash -> kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}". -> ``` +Otherwise, you can list the IP addresses of all load balancers: -The output is the external IP address of your cluster. This information can then -be used to set up DNS entries and forwarding rules that allow external access to -your deployed applications. +```bash +kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' +``` ### Using a static IP @@ -296,7 +304,7 @@ your apps will not be able to be reached, and you'd have to change the DNS record again. In order to avoid that, you should change it into a static reserved IP. -[Read how to promote an ephemeral external IP address in GKE.](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip) +Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). ### Pointing your DNS at the cluster IP @@ -387,18 +395,22 @@ GitLab CI/CD build environment. | Variable | Description | | -------- | ----------- | | `KUBE_URL` | Equal to the API URL. | -| `KUBE_TOKEN` | The Kubernetes token. | +| `KUBE_TOKEN` | The Kubernetes token of the [project service account](#access-controls). | | `KUBE_NAMESPACE` | The Kubernetes namespace is auto-generated if not specified. The default value is `<project_name>-<project_id>`. You can overwrite it to use different one if needed, otherwise the `KUBE_NAMESPACE` variable will receive the default value. | -| `KUBE_CA_PEM_FILE` | Only present if a custom CA bundle was specified. Path to a file containing PEM data. | -| `KUBE_CA_PEM` | (**deprecated**) Only if a custom CA bundle was specified. Raw PEM data. | +| `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | +| `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. | +NOTE: **NOTE:** +Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main +service account of the cluster integration. + ## Enabling or disabling the Kubernetes cluster integration After you have successfully added your cluster information, you can enable the Kubernetes cluster integration: -1. Click the "Enabled/Disabled" switch +1. Click the **Enabled/Disabled** switch 1. Hit **Save** for the changes to take effect You can now start using your Kubernetes cluster for your deployments. @@ -415,7 +427,7 @@ When you remove a cluster, you only remove its relation to GitLab, not the cluster itself. To remove the cluster, you can do so by visiting the GKE dashboard or using `kubectl`. -To remove the Kubernetes cluster integration from your project, simply click on the +To remove the Kubernetes cluster integration from your project, simply click the **Remove integration** button. You will then be able to follow the procedure and add a Kubernetes cluster again. @@ -478,7 +490,13 @@ the deployment variables above, ensuring any pods you create are labelled with ## Read more -- [Connecting and deploying to an Amazon EKS cluster](eks_and_gitlab/index.md) +### Integrating Amazon EKS cluster with GitLab + +- Learn how to [connect and deploy to an Amazon EKS cluster](eks_and_gitlab/index.md). + +### Serverless + +- [Run serverless workloads on Kubernetes with Knative.](serverless/index.md) [permissions]: ../../permissions.md [ee]: https://about.gitlab.com/pricing/ diff --git a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png Binary files differnew file mode 100644 index 00000000000..64f95ed45f0 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png diff --git a/doc/user/project/clusters/runbooks/img/demo-runbook.png b/doc/user/project/clusters/runbooks/img/demo-runbook.png Binary files differnew file mode 100644 index 00000000000..25c9df4126d --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/demo-runbook.png diff --git a/doc/user/project/clusters/runbooks/img/gitlab-variables.png b/doc/user/project/clusters/runbooks/img/gitlab-variables.png Binary files differnew file mode 100644 index 00000000000..f76ed21145f --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/gitlab-variables.png diff --git a/doc/user/project/clusters/runbooks/img/helm-install.png b/doc/user/project/clusters/runbooks/img/helm-install.png Binary files differnew file mode 100644 index 00000000000..e39094bcbf7 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/helm-install.png diff --git a/doc/user/project/clusters/runbooks/img/ingress-install.png b/doc/user/project/clusters/runbooks/img/ingress-install.png Binary files differnew file mode 100644 index 00000000000..093c61f2d0e --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/ingress-install.png diff --git a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png Binary files differnew file mode 100644 index 00000000000..2115ec9745b --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png diff --git a/doc/user/project/clusters/runbooks/img/postgres-query.png b/doc/user/project/clusters/runbooks/img/postgres-query.png Binary files differnew file mode 100644 index 00000000000..3880438c97a --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/postgres-query.png diff --git a/doc/user/project/clusters/runbooks/img/sample-runbook.png b/doc/user/project/clusters/runbooks/img/sample-runbook.png Binary files differnew file mode 100644 index 00000000000..c12ce8990a4 --- /dev/null +++ b/doc/user/project/clusters/runbooks/img/sample-runbook.png diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 3b81e439119..e1b8dc07b50 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -10,8 +10,8 @@ Historically, runbooks took the form of a decision tree or a detailed step-by-step guide depending on the condition or system. Modern implementations have introduced the concept of an "executable -runbooks", where along with a well define process, operators can execute -code blocks or database queries against a given environment. +runbooks", where, along with a well-defined process, operators can execute +pre-written code blocks or database queries against a given environment. ## Nurtch Executable Runbooks @@ -45,5 +45,93 @@ To create an executable runbook, you will need: Nurtch is the company behind the [Rubix library](https://github.com/Nurtch/rubix). Rubix is an open-source python library that makes it easy to perform common DevOps tasks inside Jupyter Notebooks. Tasks such as plotting Cloudwatch metrics and rolling your ECS/Kubernetes app are simplified -down to a couple of lines of code. Check the [Nurtch Documentation](http://docs.nurtch.com/en/latest) +down to a couple of lines of code. See the [Nurtch Documentation](http://docs.nurtch.com/en/latest) for more information. + +## Configure an executable runbook with GitLab + +Follow this step-by-step guide to configure an executable runbook in GitLab using +the components outlined above and the preloaded demo runbook. + +### 1. Add a Kubernetes cluster + +Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab) +to add a Kubernetes cluster to your project. + +### 2. Install Helm Tiller, Ingress, and JupyterHub + +Once the cluster has been provisioned in GKE, click the **Install** button next to the **Helm Tiller** app. + + + +Once Tiller has been installed successfully, click the **Install** button next to the **Ingress** app. + + + +Once Ingress has been installed successfully, click the **Install** button next to the **JupyterHub** app. + + + +### 3. Login to JupyterHub and start the server + +Once JupyterHub has been installed successfully, navigate to the displayed **Jupyter Hostname** URL and click +**Sign in with GitLab**. Authentication is automatically enabled for any user of the GitLab instance via OAuth2. This +will redirect to GitLab in order to authorize JupyterHub to use your GitLab account. Click **Authorize**. + + + +Once the application has been authorized you will taken back to the JupyterHub application. Click **Start My Server**. +The server will take a couple of seconds to start. + +### 4. Configure access + +In order for the runbook to access your GitLab project, you will need to enter a +[GitLab Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) +as well as your Project ID in the **Setup** section of the demo runbook. + +Double-click the **DevOps-Runbook-Demo** folder located on the left panel. + + + +Double-click the "Nurtch-DevOps-Demo.ipynb" runbook. + + + +The contents on the runbook will be displayed on the right side of the screen. Under the "Setup" section, you will find +entries for both your `PRIVATE_TOKEN` and your `PROJECT_ID`. Enter both these values, conserving the single quotes as follows: + +```sql +PRIVATE_TOKEN = 'n671WNGecHugsdEDPsyo' +PROJECT_ID = '1234567' +``` + +Update the `VARIABLE_NAME` on the last line of this section to match the name of the variable you are using for your +access token. In this example our variable name is `PRIVATE_TOKEN`. + +```sql +VARIABLE_VALUE = project.variables.get('PRIVATE_TOKEN').value +``` + +### 5. Configure an operation + +For this example we'll use the "**Run SQL queries in Notebook**" section in the sample runbook to query +a postgres database. The first 4 lines of the section define the variables that are required for this query to function. + +```sql +%env DB_USER={project.variables.get('DB_USER').value} +%env DB_PASSWORD={project.variables.get('DB_PASSWORD').value} +%env DB_ENDPOINT={project.variables.get('DB_ENDPOINT').value} +%env DB_NAME={project.variables.get('DB_NAME').value} +``` + +Create the matching variables in your project's **Settings >> CI/CD >> Variables** + + + +Back in Jupyter, click the "Run SQL queries in Notebook" heading and the click *Run*. The results will be +displayed in-line as follows: + + + +You can try other operations such as running shell scripts or interacting with a Kubernetes cluster. Visit the +[Nurtch Documentation](http://docs.nurtch.com/) for more information.
\ No newline at end of file diff --git a/doc/user/project/clusters/serverless/img/deploy-stage.png b/doc/user/project/clusters/serverless/img/deploy-stage.png Binary files differnew file mode 100644 index 00000000000..dc2f8af9c63 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/deploy-stage.png diff --git a/doc/user/project/clusters/serverless/img/dns-entry.png b/doc/user/project/clusters/serverless/img/dns-entry.png Binary files differnew file mode 100644 index 00000000000..2e7655c6041 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/dns-entry.png diff --git a/doc/user/project/clusters/serverless/img/install-knative.png b/doc/user/project/clusters/serverless/img/install-knative.png Binary files differnew file mode 100644 index 00000000000..dd576a9df35 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/install-knative.png diff --git a/doc/user/project/clusters/serverless/img/knative-app.png b/doc/user/project/clusters/serverless/img/knative-app.png Binary files differnew file mode 100644 index 00000000000..54301e1786f --- /dev/null +++ b/doc/user/project/clusters/serverless/img/knative-app.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md new file mode 100644 index 00000000000..bdbc4f7f09d --- /dev/null +++ b/doc/user/project/clusters/serverless/index.md @@ -0,0 +1,137 @@ +# Serverless + +> Introduced in GitLab 11.5. + +Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/knative/). + +## Overview + +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 + +For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). + +## Requirements + +To run Knative on Gitlab, you will need: + +1. **Kubernetes:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. + The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). + GitLab recommends +1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install + all the other applications. +1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an + external IP address for all the applications served by Knative. You will be prompted to enter a + wildcard domain where your applications will be served. Configure your DNS server to use the + external IP address for that domain. +1. **Serverless `gitlab-ci.yml` Template:** 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. + + Add the following `.gitlab-ci.yml` to the root of your repository (you may skip this step if using the sample + [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned below). + + ```yaml + stages: + - build + - deploy + + build: + stage: build + image: + name: gcr.io/kaniko-project/executor:debug + entrypoint: [""] + only: + - master + script: + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json + - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE + + deploy: + stage: deploy + image: gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 + only: + - master + environment: production + script: + - echo "$CI_REGISTRY_IMAGE" + - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait + ``` + +1. **Dockerfile:** 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. + +## Installing Knative via GitLab's Kubernetes integration + +NOTE: **Note:** +Minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.50 GB memory. RBAC must be enabled. + +You may download the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + +1. [Add a Kubernetes cluster](https://docs.gitlab.com/ce/user/project/clusters/) and install Helm. + +1. Once Helm has been successfully installed, on the Knative app section, enter the domain to be used with + your application and click "Install". + +  + +1. After the Knative installation has finished, retrieve the Istio Ingress IP address by running the following command: + + ```bash + kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + + Output: + + ```bash + 35.161.143.124 my-machine-name:~ my-user$ + ``` + +1. The ingress is now available at this address and will route incoming requests to the proper service based on the DNS + name in the request. To support this, a wildcard DNS A record should be created for the desired domain name. For example, + if your Knative base domain is `knative.example.com` then you need to create an A record with domain `*.knative.example.com` + pointing the ip address of the ingress. + +  + +## Deploy the application with Knative + +With all the pieces in place, you can simply create a new CI pipeline to deploy the Knative application. Navigate to +**CI/CD >> Pipelines** and click the **Run Pipeline** button at the upper-right part of the screen. Then, on the +Pipelines page, click **Create pipeline**. + +## Obtain the URL for the Knative deployment + +Once all the stages of the pipeline finish, click the **deploy** stage. + + + +The output will look like this: + +```bash +Running with gitlab-runner 11.5.0~beta.844.g96d88322 (96d88322) + on docker-auto-scale 72989761 +Using Docker executor with image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Pulling docker image gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Using docker image sha256:6b3f6590a9b30bd7aafb9573f047d930c70066e43955b4beb18a1eee175f6de1 for gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 ... +Running on runner-72989761-project-4342902-concurrent-0 via runner-72989761-stg-srm-1541795796-27929c96... +Cloning repository... +Cloning into '/builds/danielgruesso/knative'... +Checking out 8671ad20 as master... +Skipping Git submodules setup +$ echo "$CI_REGISTRY_IMAGE" +registry.staging.gitlab.com/danielgruesso/knative +$ tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait +Deployment started. Run "tm -n knative-4342902 describe service knative" to see the details +Waiting for ready state....... +Service domain: knative.knative-4342902.knative.info +Job succeeded +``` + +The second to last line, labeled **Service domain** contains the URL for the deployment. Copy and paste the domain into your +browser to see the app live. + +
\ No newline at end of file diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 1b1827a2658..cac64fc0cb6 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -139,12 +139,12 @@ docker login registry.example.com -u <username> -p <token> 1. Check to make sure that the system clock on your Docker client and GitLab server have been synchronized (e.g. via NTP). -2. If you are using an S3-backed Registry, double check that the IAM +1. If you are using an S3-backed Registry, double check that the IAM permissions and the S3 credentials (including region) are correct. See [the sample IAM policy](https://docs.docker.com/registry/storage-drivers/s3/) for more details. -3. Check the Registry logs (e.g. `/var/log/gitlab/registry/current`) and the GitLab production logs +1. Check the Registry logs (e.g. `/var/log/gitlab/registry/current`) and the GitLab production logs for errors (e.g. `/var/log/gitlab/gitlab-rails/production.log`). You may be able to find clues there. diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md index dc73194309c..7688508c6ac 100644 --- a/doc/user/project/deploy_tokens/index.md +++ b/doc/user/project/deploy_tokens/index.md @@ -13,8 +13,8 @@ You can create as many deploy tokens as you like from the settings of your proje 1. Log in to your GitLab account. 1. Go to the project you want to create Deploy Tokens for. -1. Go to **Settings** > **Repository** -1. Click on "Expand" on **Deploy Tokens** section +1. Go to **Settings** > **Repository**. +1. Click on "Expand" on **Deploy Tokens** section. 1. Choose a name and optionally an expiry date for the token. 1. Choose the [desired scopes](#limiting-scopes-of-a-deploy-token). 1. Click on **Create deploy token**. @@ -46,8 +46,8 @@ the following table. To download a repository using a Deploy Token, you just need to: 1. Create a Deploy Token with `read_repository` as a scope. -2. Take note of your `username` and `token` -3. `git clone` the project using the Deploy Token: +1. Take note of your `username` and `token`. +1. `git clone` the project using the Deploy Token: ```sh git clone http://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git @@ -60,8 +60,8 @@ Replace `<username>` and `<deploy_token>` with the proper values. To read the container registry images, you'll need to: 1. Create a Deploy Token with `read_registry` as a scope. -2. Take note of your `username` and `token` -3. Log in to GitLab’s Container Registry using the deploy token: +1. Take note of your `username` and `token`. +1. Log in to GitLab’s Container Registry using the deploy token: ```sh docker login registry.example.com -u <username> -p <deploy_token> diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index f23623ed485..89a9f7da852 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -1,6 +1,6 @@ # Migrating from ClearCase -[ClearCase](https://www-03.ibm.com/software/products/en/clearcase/) is a set of +[ClearCase](https://www.ibm.com/us-en/marketplace/rational-clearcase) is a set of tools developed by IBM which also include a centralized version control system similar to Git. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index fcd6192e82f..42da2210fab 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -17,6 +17,7 @@ the [GitHub rake task](../../../administration/raketasks/github_import.md) to im GitHub without the constraints of a Sidekiq worker. The following aspects of a project are imported: + * Repository description (GitLab.com & 7.7+) * Git repository data (GitLab.com & 7.7+) * Issues (GitLab.com & 7.7+) @@ -65,9 +66,9 @@ developer documentation. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: -1. A GitLab account that has logged in using the GitHub icon +- A GitLab account that has logged in using the GitHub icon \- or - -2. A GitLab account with an email address that matches the [public email address](https://help.github.com/articles/setting-your-commit-email-address-on-github/) of the GitHub user +- A GitLab account with an email address that matches the [public email address](https://help.github.com/articles/setting-your-commit-email-address-on-github/) of the GitHub user User-matching attempts occur in that order, and if a user is not identified either way, the activity is associated with the user account that is performing the import. @@ -77,10 +78,10 @@ If you are using a self-hosted GitLab instance, this process requires that you h [GitHub integration][gh-import]. 1. From the top navigation bar, click **+** and select **New project**. -2. Select the **Import project** tab and then select **GitHub**. -3. Select the first button to **List your GitHub repositories**. You are redirected to a page on github.com to authorize the GitLab application. -4. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. -5. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). +1. Select the **Import project** tab and then select **GitHub**. +1. Select the first button to **List your GitHub repositories**. You are redirected to a page on github.com to authorize the GitLab application. +1. Click **Authorize gitlabhq**. You are redirected back to GitLab's Import page and all of your GitHub repositories are listed. +1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). ### Using a GitHub token @@ -92,12 +93,12 @@ integration enabled, that should be the preferred method to import your reposito If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: 1. Go to https://github.com/settings/tokens/new -2. Enter a token description. -3. Select the repo scope. -4. Click **Generate token**. -5. Copy the token hash. -6. Go back to GitLab and provide the token to the GitHub importer. -7. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. +1. Enter a token description. +1. Select the repo scope. +1. Click **Generate token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the GitHub importer. +1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads your repositories' information. Once done, you'll be taken to the importer page to select the repositories to import. ### Selecting which repositories to import @@ -107,10 +108,10 @@ your GitHub repositories are listed. 1. By default, the proposed repository namespaces match the names as they exist in GitHub, but based on your permissions, you can choose to edit these names before you proceed to import any of them. -2. Select the **Import** button next to any number of repositories, or select **Import all repositories**. -3. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will +1. Select the **Import** button next to any number of repositories, or select **Import all repositories**. +1. The **Status** column shows the import status of each repository. You can choose to leave the page open and it will update in realtime or you can return to it later. -4. Once a repository has been imported, click its GitLab path to open its GitLab URL. +1. Once a repository has been imported, click its GitLab path to open its GitLab URL. ## Mirroring and pipeline status sharing diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 24bf6541a9d..baf410d9c9e 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -29,7 +29,7 @@ Below is a valid example of a manifest file: ```xml <manifest> - <remote review="https://android-review.googlesource.com/" /> + <remote review="https://android.googlesource.com/" /> <project path="build/make" name="platform/build" /> <project path="build/blueprint" name="platform/build/blueprint" /> @@ -38,10 +38,10 @@ Below is a valid example of a manifest file: As a result, the following projects will be created: -| GitLab | Import URL | -|---|---| -| https://gitlab.com/YOUR_GROUP/build/make | https://android-review.googlesource.com/platform/build | -| https://gitlab.com/YOUR_GROUP/build/blueprint | https://android-review.googlesource.com/platform/build/blueprint | +| GitLab | Import URL | +|:------------------------------------------------|:------------------------------------------------------------| +| `https://gitlab.com/YOUR_GROUP/build/make` | <https://android.googlesource.com/platform/build> | +| `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> | ## Importing the repositories diff --git a/doc/user/project/integrations/bugzilla.md b/doc/user/project/integrations/bugzilla.md index 671804035cc..040e80d529d 100644 --- a/doc/user/project/integrations/bugzilla.md +++ b/doc/user/project/integrations/bugzilla.md @@ -16,8 +16,9 @@ Once you have configured and enabled Bugzilla you'll see the Bugzilla link on th ## Referencing issues in Bugzilla Issues in Bugzilla can be referenced in two alternative ways: -1. `#<ID>` where `<ID>` is a number (example `#143`). -2. `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is + +- `#<ID>` where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). diff --git a/doc/user/project/integrations/discord_notifications.md b/doc/user/project/integrations/discord_notifications.md new file mode 100644 index 00000000000..e157f5cc106 --- /dev/null +++ b/doc/user/project/integrations/discord_notifications.md @@ -0,0 +1,29 @@ +# Discord Notifications service + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22684) in GitLab 11.5. + +The Discord Notifications service sends event notifications from GitLab to the channel for which the webhook was created. + +To send GitLab event notifications to a Discord channel, create a webhook in Discord and configure it in GitLab. + +## Create webhook + +1. Open the Discord channel you want to receive GitLab event notifications. +1. From the channel menu, select **Edit channel**. +1. Click on **Webhooks** menu item. +1. Click the **Create Webhook** button and fill in the name of the bot that will post the messages. Optionally, edit the avatar. +1. Note the URL from the **WEBHOOK URL** field. +1. Click the **Save** button. + +## Configure created webhook in GitLab + +With the webhook URL created in the Discord channel, you can set up the Discord Notifications service in GitLab. + +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings. That is, **Project > Settings > Integrations**. +1. Select the **Discord Notifications** project service to configure it. +1. Check the **Active** checkbox to turn on the service. +1. Check the checkboxes corresponding to the GitLab events for which you want to send notifications to Discord. +1. Paste the webhook URL that you copied from the create Discord webhook step. +1. Configure the remaining options and click the **Save changes** button. + +The Discord channel you created the webhook for will now receive notification of the GitLab events that were configured. diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md index 2e6e8278e64..cae66526175 100644 --- a/doc/user/project/integrations/jira_cloud_configuration.md +++ b/doc/user/project/integrations/jira_cloud_configuration.md @@ -4,16 +4,15 @@ An API token is needed when integrating with JIRA Cloud, follow the steps below to create one: 1. Log in to https://id.atlassian.com with your email. -2. **Click API tokens**, then **Create API token**. +1. **Click API tokens**, then **Create API token**.   -3. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). +1. Make sure to write down your new API token as you will need it in the next [steps](jira.md#configuring-gitlab). NOTE: **Note** It is important that the user associated with this email has 'write' access to projects in JIRA. The JIRA configuration is complete. You are going to need this new created token and the email you used to log in when [configuring GitLab in the next section](jira.md#configuring-gitlab). - diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 7d84ad0b07c..20036183187 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -17,17 +17,17 @@ We have split this stage in steps so it is easier to follow.  -2. The next step is to create a new user (e.g., `gitlab`) who has write access +1. The next step is to create a new user (e.g., `gitlab`) who has write access to projects in Jira. Enter the user's name and a _valid_ e-mail address since Jira sends a verification e-mail to set up the password. _**Note:** Jira creates the username automatically by using the e-mail - prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create - an HTTP basic authentication password. You can do this by visiting the user + prefix. You can change it later, if needed. Our integration does not support SSO (such as SAML). You will need to create + an HTTP basic authentication password. You can do this by visiting the user profile, looking up the username, and setting a password._  -3. Create a `gitlab-developers` group which will have write access +1. Create a `gitlab-developers` group which will have write access to projects in Jira. Go to the **Groups** tab and select **Create group**.  @@ -36,13 +36,13 @@ We have split this stage in steps so it is easier to follow.  -4. To give the newly-created group 'write' access, go to +1. To give the newly-created group 'write' access, go to **Application access > View configuration** and add the `gitlab-developers` group to Jira Core.  -5. Add the `gitlab` user to the `gitlab-developers` group by going to +1. Add the `gitlab` user to the `gitlab-developers` group by going to **Users > GitLab user > Add group** and selecting the `gitlab-developers` group from the dropdown menu. Notice that the group says _Access_, which is intended as part of this process. diff --git a/doc/user/project/integrations/mattermost.md b/doc/user/project/integrations/mattermost.md index 89de1fe4dcb..ed4367c1135 100644 --- a/doc/user/project/integrations/mattermost.md +++ b/doc/user/project/integrations/mattermost.md @@ -4,9 +4,9 @@ To enable Mattermost integration you must create an incoming webhook integration: -1. Sign in to your Mattermost instance -1. Visit incoming webhooks, that will be something like: https://mattermost.example/your_team_name/integrations/incoming_webhooks/add -1. Choose a display name, description and channel, those can be overridden on GitLab +1. Sign in to your Mattermost instance. +1. Visit incoming webhooks, that will be something like: `https://mattermost.example.com/your_team_name/integrations/incoming_webhooks/add`. +1. Choose a display name, description and channel, those can be overridden on GitLab. 1. Save it, copy the **Webhook URL**, we'll need this later for GitLab. There might be some cases that Incoming Webhooks are blocked by admin, ask your mattermost admin to enable diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index efb0381d7aa..be45ce46dfd 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -30,6 +30,7 @@ Click on the service links to see further configuration instructions and details | [Bugzilla](bugzilla.md) | Bugzilla issue tracker | | Campfire | Simple web-based real-time group chat | | Custom Issue Tracker | Custom issue tracker | +| [Discord Notifications](discord_notifications.md) | Receive event notifications in Discord | | Drone CI | Continuous Integration platform built on Docker, written in Go | | [Emails on push](emails_on_push.md) | Email the commits and diff of each push to a list of recipients | | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 0b61a41aab0..7d0e567cae7 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -56,7 +56,7 @@ The [NGINX Ingress](../clusters/index.md#installing-applications) that is deploy Integration with Prometheus requires the following: 1. GitLab 9.0 or higher -1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/metrics.md) +1. Prometheus must be configured to collect one of the [supported metrics](prometheus_library/index.md) 1. Each metric must be have a label to indicate the environment 1. GitLab must have network connectivity to the Prometheus server @@ -65,7 +65,7 @@ Integration with Prometheus requires the following: Installing and configuring Prometheus to monitor applications is fairly straight forward. 1. [Install Prometheus](https://prometheus.io/docs/introduction/install/) -1. Set up one of the [supported monitoring targets](prometheus_library/metrics.md) +1. Set up one of the [supported monitoring targets](prometheus_library/index.md) 1. Configure the Prometheus server to [collect their metrics](https://prometheus.io/docs/operating/configuration/#scrape_config) #### Configuration in GitLab diff --git a/doc/user/project/integrations/prometheus_library/cloudwatch.md b/doc/user/project/integrations/prometheus_library/cloudwatch.md index bf6c0dc0e7e..66f1b587070 100644 --- a/doc/user/project/integrations/prometheus_library/cloudwatch.md +++ b/doc/user/project/integrations/prometheus_library/cloudwatch.md @@ -27,4 +27,4 @@ A sample Cloudwatch Exporter configuration file, configured for basic AWS ELB mo ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](metrics.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index cd398f7c0fd..abb0c01ad18 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -21,4 +21,4 @@ To get started with NGINX monitoring, you should install and configure the [HAPr ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](metrics.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/prometheus_library/index.md b/doc/user/project/integrations/prometheus_library/index.md new file mode 100644 index 00000000000..9b9b4f6c8ca --- /dev/null +++ b/doc/user/project/integrations/prometheus_library/index.md @@ -0,0 +1,33 @@ +# Prometheus Metrics library + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0. + +GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). + +## Exporters + +Currently supported exporters are: + +- [Kubernetes](kubernetes.md) +- [NGINX](nginx.md) +- [NGINX Ingress Controller](nginx_ingress.md) +- [HAProxy](haproxy.md) +- [Amazon Cloud Watch](cloudwatch.md) + +We have tried to surface the most important metrics for each exporter, and will +be continuing to add support for additional exporters in future releases. If you +would like to add support for other official exporters, contributions are welcome. + +## Identifying Environments + +GitLab retrieves performance data from the configured Prometheus server, and +attempts to identifying the presence of known metrics. Once identified, GitLab +then needs to be able to map the data to a particular environment. + +In order to isolate and only display relevant metrics for a given environment, +GitLab needs a method to detect which labels are associated. To do that, +GitLab uses the defined queries and fills in the environment specific variables. +Typically this involves looking for the +[`$CI_ENVIRONMENT_SLUG`](../../../../ci/variables/README.md#predefined-variables-environment-variables), +but may also include other information such as the project's Kubernetes namespace. +Each search query is defined in the [exporter specific documentation](#exporters). diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index ec16902fcc8..37a5388d2fc 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -1,19 +1 @@ -# Prometheus Metrics library - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935) in GitLab 9.0 - -GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). Currently supported exporters are: -* [Kubernetes](kubernetes.md) -* [NGINX](nginx.md) -* [NGINX Ingress Controller](nginx_ingress.md) -* [HAProxy](haproxy.md) -* [Amazon Cloud Watch](cloudwatch.md) - -We have tried to surface the most important metrics for each exporter, and will be continuing to add support for additional exporters in future releases. If you would like to add support for other official exporters, [contributions](#adding-to-the-library) are welcome. - -## Identifying Environments - -GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. - -In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, -GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the [$CI_ENVIRONMENT_SLUG](../../../../ci/variables/README.md#predefined-variables-environment-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#prometheus-metrics-library). +This document was moved to [another location](index.md). diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index 557487e1a75..c4fea178ab5 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -27,4 +27,4 @@ If you are using NGINX as your Kubernetes ingress, GitLab will [automatically de ## Specifying the Environment label In order to isolate and only display relevant metrics for a given environment -however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](metrics.md#identifying-environments). +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](index.md#identifying-environments). diff --git a/doc/user/project/integrations/redmine.md b/doc/user/project/integrations/redmine.md index de2cf6d4647..76a2617125e 100644 --- a/doc/user/project/integrations/redmine.md +++ b/doc/user/project/integrations/redmine.md @@ -18,15 +18,16 @@ in the table below.  -2. To disable the internal issue tracking system in a project, navigate to the General page, expand [Permissions](../settings/index.md#sharing-and-permissions), and slide the Issues switch invalid. +1. To disable the internal issue tracking system in a project, navigate to the General page, expand [Permissions](../settings/index.md#sharing-and-permissions), and slide the Issues switch invalid.  ## Referencing issues in Redmine Issues in Redmine can be referenced in two alternative ways: -1. `#<ID>` where `<ID>` is a number (example `#143`) -2. `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is + +- `#<ID>` where `<ID>` is a number (example `#143`). +- `<PROJECT>-<ID>` where `<PROJECT>` starts with a capital letter which is then followed by capital letters, numbers or underscores, and `<ID>` is a number (example `API_32-143`). diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 7c63967c829..4d1d95da6f0 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -338,10 +338,10 @@ payload will also include information about the target of the comment. For examp a comment on an issue will include the specific issue information under the `issue` key. Valid target types: -1. `commit` -2. `merge_request` -3. `issue` -4. `snippet` +- `commit` +- `merge_request` +- `issue` +- `snippet` #### Comment on commit diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index b6570c777ae..afb7d9ada5f 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -27,10 +27,11 @@ used: Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's source code that can match references to: -1. a local issue (`#123`), -2. a cross-project issue (`group/project#123`) -3. a link to an issue -(`https://gitlab.example.com/group/project/issues/123`). + +- A local issue (`#123`). +- A cross-project issue (`group/project#123`). +- A link to an issue + (`https://gitlab.example.com/group/project/issues/123`). --- diff --git a/doc/user/project/merge_requests/img/comment-on-any-diff-line.png b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png Binary files differnew file mode 100644 index 00000000000..856ede41527 --- /dev/null +++ b/doc/user/project/merge_requests/img/comment-on-any-diff-line.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differindex 3b3bf88df31..1cdac5ef573 100644 --- a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png +++ b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png diff --git a/doc/user/project/merge_requests/img/merge_request_pipeline.png b/doc/user/project/merge_requests/img/merge_request_pipeline.png Binary files differnew file mode 100644 index 00000000000..183d9cb910b --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 0a7f7d37384..a0e7c1c99d5 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -141,6 +141,15 @@ you hide discussions that are no longer relevant. [Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) +## Commenting on any file line in merge requests + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/13950) in GitLab 11.5. + +GitLab provides a way of leaving comments in any part of the file being changed +in a Merge Request. To do so, click the **...** button in the gutter of the Merge Request diff UI to expand the diff lines and leave a comment, just as you would for a changed line. + + + ## Resolve conflicts When a merge request has conflicts, GitLab may provide the option to resolve @@ -166,9 +175,26 @@ administrator to do so.  +### Adding patches when creating a merge request via e-mail + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22723) in GitLab 11.5. + +You can add commits to the merge request being created by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` will be considered patches and they will be processed +ordered by name. + +The combined size of the patches can be 2MB. + +If the source branch from the subject does not exist, it will be +created from the repository's HEAD or the specified target branch to +apply the patches. The target branch can be specified using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches will be applied on top of it. + ## Find the merge request that introduced a change -> **Note**: this feature was [implemented in GitLab 10.5](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383). +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5. When viewing the commit details page, GitLab will link to the merge request (or merge requests, if it's in more than one) containing that commit. @@ -205,9 +231,10 @@ have been marked as a **Work In Progress**. ## Merge request diff file navigation -The diff view has a file tree for file navigation. As you scroll through -diffs with a large number of files, you can easily jump to any changed file -using the file tree. +When reviewing changes in the **Changes** tab the diff can be navigated using +the file tree or file list. As you scroll through large diffs with many +changes, you can quickly jump to any changed file using the file tree or file +list.  @@ -232,6 +259,34 @@ all your changes will be available to preview by anyone with the Review Apps lin [Read more about Review Apps.](../../../ci/review_apps/index.md) +## Pipeline status in merge requests + +If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +you will be able to see: + +- Both pre and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If there's an [environment](../../../ci/environments.md) and the application is +successfully deployed to it, the deployed environment and the link to the +Review App will be shown as well. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the master branch and then triggers a deployment to the staging +environment. + +Deployments that are ongoing will be shown, as well as the deploying/deployed state +for environments. If it's the first time the branch is deployed, the link +will return a `404` error until done. During the deployment, the stop button will +be disabled. If the pipeline fails to deploy, the deployment info will be hidden. + + + +For more information, [read about pipelines](../../../ci/pipelines.md). + ## Bulk editing merge requests Find out about [bulk editing merge requests](../../project/bulk_editing.md). diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index 3cf46231a9d..7168fe63887 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -6,6 +6,26 @@ Milestones in GitLab are a way to track issues and merge requests created to ach Milestones allow you to organize issues and merge requests into a cohesive group, with an optional start date and an optional due date. +## Milestones as Agile sprints + +Milestones can be used as Agile sprints. +Set the milestone start date and due date to represent +the start and end of your Agile sprint. +Set the milestone title to the name of your Agile sprint, +such as `November 2018 sprint`. +Add an issue to your Agile sprint by associating +the milestone to the issue. + +## Milestones as releases + +Milestones can be used as releases. +Set the milestone due date to represent the release date of your release. +(And leave the milestone start date blank.) +Set the the milestone title to the version of your release, +such as `Version 9.4`. +Add an issue to your release by associating +the milestone to the issue. + ## Project milestones and group milestones - **Project milestones** can be assigned to issues or merge requests in that project only. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 23d5b34504c..9a53036b4d1 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -60,7 +60,7 @@ Let's consider the following scenario: hosted in private repositories and you have multiple CI jobs that make use of these repositories. -2. You invite a new [external user][ext]. CI jobs created by that user do not +1. You invite a new [external user][ext]. CI jobs created by that user do not have access to internal repositories, because the user also doesn't have the access from within GitLab. You as an employee have to grant explicit access for this user. This allows us to prevent from accidental data leakage. diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 89b9621b8b9..26891348b0c 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,5 +1,5 @@ --- -last_updated: 2018-08-16 +last_updated: 2018-11-19 author: Marcia Ramos author_gitlab: marcia level: beginner @@ -183,7 +183,7 @@ you can use the following setup: - In Cloudflare, create a DNS `A` record pointing `domain.com` to `35.185.44.232` - In GitLab, add the domain to GitLab Pages - In Cloudflare, create a DNS `TXT` record to verify your domain -- In Cloudflare, create a DNS `CNAME` record poiting `www` to `domain.com` +- In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com` ## SSL/TLS Certificates diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index fe4d15adfa1..9f9b64ec20d 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -441,6 +441,46 @@ The rest of the guide still applies. See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain). +## GitLab Pages access control **[CORE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. + +NOTE: **Note:** +GitLab Pages access control is not activated on GitLab.com. + +You can enable Pages access control on your project, so that only +[members of your project](../../permissions.md#project-members-permissions) +(at least Guest) can access your website: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Toggle the **Pages** button to enable the access control. + + NOTE: **Note:** + If you don't see the toggle button, that means that it's not enabled. + Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). + +1. The Pages access control dropdown allows you to set who can view pages hosted + with GitLab Pages, depending on your project's visibility: + + - If your project is private: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is internal: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is public: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + +1. Click **Save changes**. + +--- + +The next time someone tries to access your website and the access control is +enabled, they will be presented with a page to sign into GitLab and verify they +can access the website. + ## Limitations When using Pages under the general domain of a GitLab instance (`*.example.io`), diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 0a4542b71ed..85a03d125dd 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -53,6 +53,7 @@ discussions, and descriptions: | `/target_branch <Local branch Name>` | Set target branch | | ✓ | | `/wip` | Toggle the Work In Progress status | | ✓ | | `/merge` | Merge (when pipeline succeeds) | | ✓ | +| `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | ✓ | | ## Quick actions for commit messages diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 6d822d3f7f2..1710bba2fd0 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -53,17 +53,35 @@ To get started with the command line, please read through the Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository. +### Supported markup languages and extensions + +GitLab supports a number of markup languages (sometimes called [lightweight +markup languages](https://en.wikipedia.org/wiki/Lightweight_markup_language)) +that you can use for the content of your files in a repository. They are mostly +used for documentation purposes. + +Just pick the right extension for your files and GitLab will render them +according to the markup language. + +| Markup language | Extensions | +| --------------- | ---------- | +| Plain text | `txt` | +| [Markdown](../../markdown.md) | `mdown`, `mkd`, `mkdn`, `md`, `markdown` | +| [reStructuredText](http://docutils.sourceforge.net/rst.html) | `rst` | +| [Asciidoc](https://asciidoctor.org/docs/what-is-asciidoc/) | `adoc`, `ad`, `asciidoc` | +| [Textile](https://txstyle.org/) | `textile` | +| [rdoc](http://rdoc.sourceforge.net/doc/index.html) | `rdoc` | +| [Orgmode](https://orgmode.org/) | `org` | +| [creole](http://www.wikicreole.org/) | `creole` | +| [Mediawiki](https://www.mediawiki.org/wiki/MediaWiki) | `wiki`, `mediawiki` | + ### Repository README and index files When a `README` or `index` file is present in a repository, its contents will be automatically pre-rendered by GitLab without opening it. -They can either be plain text or have an extension of a supported markup language: - -- Asciidoc: `README.adoc` or `index.adoc` -- Markdown: `README.md` or `index.md` -- reStructuredText: `README.rst` or `index.rst` -- Text: `README.txt` or `index.txt` +They can either be plain text or have an extension of a +[supported markup language](#supported-markup-languages-and-extensions): Some things to note about precedence: @@ -75,10 +93,6 @@ Some things to note about precedence: precedence over `README.md`, and `README.rst` will take precedence over `README`. -NOTE: **Note:** -`index` files without an extension will not automatically pre-render. You'll -have to explicitly open them to see their contents. - ### Jupyter Notebook files > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2508) in GitLab 9.1 diff --git a/doc/user/project/settings/img/sharing_and_permissions_settings.png b/doc/user/project/settings/img/sharing_and_permissions_settings.png Binary files differindex f5e3e32f95c..6cb89c6ea1d 100644 --- a/doc/user/project/settings/img/sharing_and_permissions_settings.png +++ b/doc/user/project/settings/img/sharing_and_permissions_settings.png diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 084d1161633..d6754372816 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -18,6 +18,8 @@ Adjust your project's name, description, avatar, [default branch](../repository/  +The project description also partially supports [standard markdown](../../markdown.md#standard-markdown). You can use [emphasis](../../markdown.md#emphasis), [links](../../markdown.md#links), and [line-breaks](../../markdown.md#line-breaks) to add more context to the project description. + ### Sharing and permissions Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../container_registry.md) for your projects: diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 9429b1268f0..e6b1f6b6aae 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -22,6 +22,27 @@ searching. The file finder is launched using the keyboard shortcut `Command-p`, `Control-p`, or `t` (when editor is not in focus). Type the filename or file path fragments to start seeing results. +## Syntax highligting + +As expected from an IDE, syntax highlighting for many languages within +the Web IDE will make your direct editing even easier. + +The Web IDE currently provides: + +- Basic syntax colorization for a variety of programming, scripting and markup +languages such as XML, PHP, C#, C++, Markdown, Java, VB, Batch, Python, Ruby +and Objective-C. +- IntelliSense and validation support (displaying errors and warnings, providing +smart completions, formatting, and outlining) for some languages. For example: +TypeScript, JavaScript, CSS, LESS, SCSS, JSON and HTML. + +Because the Web IDE is based on the [Monaco Editor](https://microsoft.github.io/monaco-editor/), +you can find a more complete list of supported languages in the +[Monaco languages](https://github.com/Microsoft/monaco-languages) repository. + +NOTE: **Note:** +Single file editing is based on the [Ace Editor](https://ace.c9.io). + ## Stage and commit changes After making your changes, click the Commit button in the bottom left to diff --git a/doc/user/search/img/dashboard_links.png b/doc/user/search/img/dashboard_links.png Binary files differnew file mode 100644 index 00000000000..2c472c7e464 --- /dev/null +++ b/doc/user/search/img/dashboard_links.png diff --git a/doc/user/search/img/issues_assigned_to_you.png b/doc/user/search/img/issues_assigned_to_you.png Binary files differindex 36c670eedd5..d2fff5e9a67 100644 --- a/doc/user/search/img/issues_assigned_to_you.png +++ b/doc/user/search/img/issues_assigned_to_you.png diff --git a/doc/user/search/img/left_menu_bar.png b/doc/user/search/img/left_menu_bar.png Binary files differdeleted file mode 100644 index d68a71cba8e..00000000000 --- a/doc/user/search/img/left_menu_bar.png +++ /dev/null diff --git a/doc/user/search/index.md b/doc/user/search/index.md index 3f9d07dacaa..78c1294346b 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -2,27 +2,27 @@ ## Issues and merge requests -To search through issues and merge requests in multiple projects, you can use the left-sidebar. +To search through issues and merge requests in multiple projects, you can use the **Issues** or **Merge Requests** links +in the top-right part of your screen. -Click the menu bar, then **Issues** or **Merge Requests**, which work in the same way, -therefore, the following notes are valid for both. +Both of them work in the same way, therefore, the following notes are valid for both. The number displayed on their right represents the number of issues and merge requests assigned to you. - + When you click **Issues**, you'll see the opened issues assigned to you straight away:  -You can filter them by **Author**, **Assignee**, **Milestone**, and **Labels**, -searching through **Open**, **Closed**, and **All** issues. +You can search through **Open**, **Closed**, or **All** issues. -Of course, you can combine all filters together. +You can also filter the results using the search and filter field. This works in the same way as the ones found in the +per project pages described below. ### Issues and MRs assigned to you or created by you -You'll find a shortcut to issues and merge requests create by you or assigned to you +You'll also find shortcuts to issues and merge requests created by you or assigned to you on the search field on the top-right of your screen:  |
