diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/administration/high_availability/database.md | 11 | ||||
| -rw-r--r-- | doc/administration/high_availability/gitlab.md | 35 | ||||
| -rw-r--r-- | doc/administration/integration/terminal.md | 16 | ||||
| -rw-r--r-- | doc/administration/monitoring/prometheus/index.md | 13 | ||||
| -rw-r--r-- | doc/api/jobs.md | 5 | ||||
| -rw-r--r-- | doc/api/settings.md | 2 | ||||
| -rw-r--r-- | doc/ci/autodeploy/index.md | 130 | ||||
| -rw-r--r-- | doc/ci/environments.md | 7 | ||||
| -rw-r--r-- | doc/ci/variables/README.md | 4 | ||||
| -rw-r--r-- | doc/development/fe_guide/icons.md | 114 | ||||
| -rw-r--r-- | doc/development/fe_guide/index.md | 4 | ||||
| -rw-r--r-- | doc/development/fe_guide/vue.md | 190 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/development/accessibility.md | 49 | ||||
| -rw-r--r-- | doc/user/project/integrations/img/kubernetes_configuration.png | bin | 14407 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/integrations/kubernetes.md | 138 | ||||
| -rw-r--r-- | doc/user/project/integrations/project_services.md | 1 |
16 files changed, 271 insertions, 448 deletions
diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index ca6d8d2de67..b5124b1d540 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -33,16 +33,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL: external_url 'https://gitlab.example.com' # Disable all components except PostgreSQL - postgresql['enable'] = true - bootstrap['enable'] = false - nginx['enable'] = false - unicorn['enable'] = false - sidekiq['enable'] = false - redis['enable'] = false - prometheus['enable'] = false - gitaly['enable'] = false - gitlab_workhorse['enable'] = false - mailroom['enable'] = false + roles ['postgres_role'] # PostgreSQL configuration gitlab_rails['db_password'] = 'DB password' diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index e201848791c..0d9c10687f2 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -47,7 +47,8 @@ for each GitLab application server in your environment. URL. Depending your the NFS configuration, you may need to change some GitLab data locations. See [NFS documentation](nfs.md) for `/etc/gitlab/gitlab.rb` configuration values for various scenarios. The example below assumes you've - added NFS mounts in the default data locations. + added NFS mounts in the default data locations. Additionally the UID and GIDs + given are just examples and you should configure with your preferred values. ```ruby external_url 'https://gitlab.example.com' @@ -68,6 +69,14 @@ for each GitLab application server in your environment. gitlab_rails['redis_port'] = '6379' gitlab_rails['redis_host'] = '10.1.0.6' # IP/hostname of Redis server gitlab_rails['redis_password'] = 'Redis Password' + + # Ensure UIDs and GIDs match between servers for permissions via NFS + user['uid'] = 9000 + user['gid'] = 9000 + web_server['uid'] = 9001 + web_server['gid'] = 9001 + registry['uid'] = 9002 + registry['gid'] = 9002 ``` > **Note:** To maintain uniformity of links across HA clusters, the `external_url` @@ -75,25 +84,24 @@ for each GitLab application server in your environment. servers should point to the external url that users will use to access GitLab. In a typical HA setup, this will be the url of the load balancer which will route traffic to all GitLab application servers in the HA cluster. - -1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + + > **Note:** When you specify `https` in the `external_url`, as in the example + above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If + certificates are not present, Nginx will fail to start. See + [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) + for more information. ## First GitLab application server -As a final step, run the setup rake task on the first GitLab application server. -It is not necessary to run this on additional application servers. +As a final step, run the setup rake task **only on** the first GitLab application server. +Do not run this on additional application servers. 1. Initialize the database by running `sudo gitlab-rake gitlab:setup`. +1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. > **WARNING:** Only run this setup task on **NEW** GitLab instances because it will wipe any existing data. -> **Note:** When you specify `https` in the `external_url`, as in the example - above, GitLab assumes you have SSL certificates in `/etc/gitlab/ssl/`. If - certificates are not present, Nginx will fail to start. See - [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) - for more information. - ## Extra configuration for additional GitLab application servers Additional GitLab servers (servers configured **after** the first GitLab server) @@ -101,8 +109,7 @@ need some extra configuration. 1. Configure shared secrets. These values can be obtained from the primary GitLab server in `/etc/gitlab/gitlab-secrets.json`. Add these to - `/etc/gitlab/gitlab.rb` **prior to** running the first `reconfigure` in - the steps above. + `/etc/gitlab/gitlab.rb` **prior to** running the first `reconfigure`. ```ruby gitlab_shell['secret_token'] = 'fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359e5be59b02538e1fa6cae8f93f7d23355341cea2b93600dab6d6c3edcdced558fc6d739860' @@ -115,6 +122,8 @@ need some extra configuration. from running on upgrade. Only the primary GitLab application server should handle migrations. +1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + ## Troubleshooting - `mount: wrong fs type, bad option, bad superblock on` diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 91e844c7b42..32ad63c3706 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,12 +1,13 @@ # Web terminals -> [Introduced][ce-7690] in GitLab 8.15. Only project masters and owners can - access web terminals. +> +[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690) +in GitLab 8.15. Only project masters and owners can access web terminals. -With the introduction of the [Kubernetes project service][kubservice], GitLab -gained the ability to store and use credentials for a Kubernetes cluster. One -of the things it uses these credentials for is providing access to -[web terminals](../../ci/environments.html#web-terminals) for environments. +With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), +GitLab gained the ability to store and use credentials for a Kubernetes cluster. +One of the things it uses these credentials for is providing access to +[web terminals](../../ci/environments.md#web-terminals) for environments. ## How it works @@ -80,6 +81,3 @@ Terminal sessions use long-lived connections; by default, these may last forever. You can configure a maximum session time in the Admin area of your GitLab instance if you find this undesirable from a scalability or security point of view. - -[ce-7690]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7690 -[kubservice]: ../../user/project/integrations/kubernetes.md diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index f47add48345..1c79e86dcb4 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -29,7 +29,8 @@ For installations from source you'll have to install and configure it yourself. Prometheus and it's exporters are on by default, starting with GitLab 9.0. Prometheus will run as the `gitlab-prometheus` user and listen on -`http://localhost:9090`. Each exporter will be automatically be set up as a +`http://localhost:9090`. By default Prometheus is only accessible from the GitLab server itself. +Each exporter will be automatically set up as a monitoring target for Prometheus, unless individually disabled. To disable Prometheus and all of its exporters, as well as any added in the future: @@ -44,14 +45,16 @@ To disable Prometheus and all of its exporters, as well as any added in the futu 1. Save the file and [reconfigure GitLab][reconfigure] for the changes to take effect -## Changing the port Prometheus listens on +## Changing the port and address Prometheus listens on >**Note:** The following change was added in [GitLab Omnibus 8.17][1261]. Although possible, -it's not recommended to change the default address and port Prometheus listens +it's not recommended to change the port Prometheus listens on as this might affect or conflict with other services running on the GitLab server. Proceed at your own risk. +In order to access Prometheus from outside the GitLab server you will need to +set a FQDN or IP in `prometheus['listen_address']`. To change the address/port that Prometheus listens on: 1. Edit `/etc/gitlab/gitlab.rb` @@ -80,9 +83,9 @@ You can visit `http://localhost:9090` for the dashboard that Prometheus offers b >**Note:** If SSL has been enabled on your GitLab instance, you may not be able to access -Prometheus on the same browser as GitLab due to [HSTS][hsts]. We plan to +Prometheus on the same browser as GitLab if using the same FQDN due to [HSTS][hsts]. We plan to [provide access via GitLab][multi-user-prometheus], but in the interim there are -some workarounds: using a separate browser for Prometheus, resetting HSTS, or +some workarounds: using a separate FQDN, using server IP, using a separate browser for Prometheus, resetting HSTS, or having [Nginx proxy it][nginx-custom-config]. The performance data collected by Prometheus can be viewed directly in the diff --git a/doc/api/jobs.md b/doc/api/jobs.md index e4e48edd9a7..0fbfc7cf0fd 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -38,6 +38,7 @@ Example of response "size": 1000 }, "finished_at": "2015-12-24T17:54:27.895Z", + "artifacts_expire_at": "2016-01-23T17:54:27.895Z" "id": 7, "name": "teaspoon", "pipeline": { @@ -81,6 +82,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "artifacts_file": null, "finished_at": "2015-12-24T17:54:24.921Z", + "artifacts_expire_at": "2016-01-23T17:54:24.921Z", "id": 6, "name": "rspec:other", "pipeline": { @@ -152,6 +154,7 @@ Example of response "size": 1000 }, "finished_at": "2015-12-24T17:54:27.895Z", + "artifacts_expire_at": "2016-01-23T17:54:27.895Z" "id": 7, "name": "teaspoon", "pipeline": { @@ -195,6 +198,7 @@ Example of response "created_at": "2015-12-24T15:51:21.727Z", "artifacts_file": null, "finished_at": "2015-12-24T17:54:24.921Z", + "artifacts_expire_at": "2016-01-23T17:54:24.921Z" "id": 6, "name": "rspec:other", "pipeline": { @@ -261,6 +265,7 @@ Example of response "created_at": "2015-12-24T15:51:21.880Z", "artifacts_file": null, "finished_at": "2015-12-24T17:54:31.198Z", + "artifacts_expire_at": "2016-01-23T17:54:31.198Z", "id": 8, "name": "rubocop", "pipeline": { diff --git a/doc/api/settings.md b/doc/api/settings.md index e06b1bfb6df..1ebfe4924b1 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -133,7 +133,7 @@ PUT /application/settings | `repository_checks_enabled` | boolean | no | GitLab will periodically run 'git fsck' in all project and wiki repositories to look for silent disk corruption issues. | | `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | | `require_two_factor_authentication` | boolean | no | Require all users to setup Two-factor authentication | -| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is null which means there is no restriction. | +| `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is null which means there is no restriction. | | `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up | | `sentry_dsn` | string | yes (if `sentry_enabled` is true) | Sentry Data Source Name | diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md index 7102af5c529..985ec4b972c 100644 --- a/doc/ci/autodeploy/index.md +++ b/doc/ci/autodeploy/index.md @@ -1,129 +1 @@ -# Auto Deploy - -> [Introduced][mr-8135] in GitLab 8.15. -> Auto deploy is an experimental feature and is **not recommended for Production use** at this time. - -> As of GitLab 9.1, access to the container registry is only available while the -Pipeline is running. Restarting a pod, scaling a service, or other actions which -require on-going access **will fail**. On-going secure access is planned for a -subsequent release. - -> As of GitLab 10.0, Auto Deploy templates are **deprecated** and the -functionality has been included in [Auto -DevOps](../../topics/autodevops/index.md). - -Auto deploy is an easy way to configure GitLab CI for the deployment of your -application. GitLab Community maintains a list of `.gitlab-ci.yml` -templates for various infrastructure providers and deployment scripts -powering them. These scripts are responsible for packaging your application, -setting up the infrastructure and spinning up necessary services (for -example a database). - -## How it works - -The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy] -project which is used to simplify the deployment process to Kubernetes by -providing intelligent `build`, `deploy`, and `destroy` commands which you can -use in your `.gitlab-ci.yml` as is. It uses [Herokuish](https://github.com/gliderlabs/herokuish), -which uses [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) -to do some of the work, plus some of GitLab's own tools to package it all up. For -your convenience, a [Docker image][kube-image] is also provided. - -You can use the [Kubernetes project service](../../user/project/integrations/kubernetes.md) -to store credentials to your infrastructure provider and they will be available -during the deployment. - -## Quick start - -We made a [simple guide](quick_start_guide.md) to using Auto Deploy with GitLab.com. - -For a demonstration of GitLab Auto Deploy, read the blog post [Auto Deploy from GitLab to an OpenShift Container Cluster](https://about.gitlab.com/2017/05/16/devops-containers-gitlab-openshift/) - -## Supported templates - -The list of supported auto deploy templates is available in the -[gitlab-ci-yml project][auto-deploy-templates]. - -## Configuration - ->**Note:** -In order to understand why the following steps are required, read the -[how it works](#how-it-works) section. - -To configure Autodeploy, you will need to: - -1. Enable a deployment [project service][project-services] to store your - credentials. For example, if you want to deploy to OpenShift you have to - enable [Kubernetes service][kubernetes-service]. -1. Configure GitLab Runner to use the - [Docker or Kubernetes executor](https://docs.gitlab.com/runner/executors/) with - [privileged mode enabled][docker-in-docker]. -1. Navigate to the "Project" tab and click "Set up auto deploy" button. -  -1. Select a template. -  -1. Commit your changes and create a merge request. -1. Test your deployment configuration using a [Review App][review-app] that was - created automatically for you. - -## Private project support - -> Experimental support [introduced][mr-2] in GitLab 9.1. - -When a project has been marked as private, GitLab's [Container Registry][container-registry] requires authentication when downloading containers. Auto deploy will automatically provide the required authentication information to Kubernetes, allowing temporary access to the registry. Authentication credentials will be valid while the pipeline is running, allowing for a successful initial deployment. - -After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release. - -## PostgreSQL database support - -> Experimental support [introduced][mr-8] in GitLab 9.1. - -In order to support applications that require a database, [PostgreSQL][postgresql] is provisioned by default. Credentials to access the database are preconfigured, but can be customized by setting the associated [variables](#postgresql-variables). These credentials can be used for defining a `DATABASE_URL` of the format: `postgres://user:password@postgres-host:postgres-port/postgres-database`. It is important to note that the database itself is temporary, and contents will be not be saved. - -PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`. - -The following PostgreSQL variables are supported: - -1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL -1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL -1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL -1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL - -## Auto Monitoring - -> Introduced in [GitLab 9.5](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438). - -Apps auto-deployed using one the [Kubernetes templates](#supported-templates) can also be automatically monitored for: - -* Response Metrics: latency, throughput, error rate -* System Metrics: CPU utilization, memory utilization - -Metrics are gathered from [nginx-ingress](../../user/project/integrations/prometheus_library/nginx_ingress.md) and [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md). - -To view the metrics, open the [Monitoring dashboard for a deployed environment](../environments.md#monitoring-environments). - - - -### Configuring Auto Monitoring - -If GitLab has been deployed using the [omnibus-gitlab](../../install/kubernetes/gitlab_omnibus.md) Helm chart, no configuration is required. - -If you have installed GitLab using a different method: - -1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster -1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress/blob/master/examples/customization/custom-vts-metrics/nginx/nginx-vts-metrics-conf.yaml). -1. Finally, [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) the NGINX Ingress deployment to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`. - -[mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135 -[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2 -[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8 -[project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html -[project-services]: ../../user/project/integrations/project_services.md -[auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy -[kubernetes-service]: ../../user/project/integrations/kubernetes.md -[docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor -[review-app]: ../review_apps/index.md -[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" -[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project" -[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html -[postgresql]: https://www.postgresql.org/ +This document was moved to [another location](../../topics/autodevops/index.md#auto-deploy). diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 3a491f0073c..0d54f375c93 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -24,7 +24,7 @@ Environments are like tags for your CI jobs, describing where code gets deployed Deployments are created when [jobs] deploy versions of code to environments, so every environment can have one or more deployments. GitLab keeps track of your deployments, so you always know what is currently being deployed on your -servers. If you have a deployment service such as [Kubernetes][kubernetes-service] +servers. If you have a deployment service such as [Kubernetes][kube] enabled for your project, you can use it to assist with your deployments, and can even access a [web terminal](#web-terminals) for your environment from within GitLab! @@ -605,7 +605,7 @@ Web terminals were added in GitLab 8.15 and are only available to project masters and owners. If you deploy to your environments with the help of a deployment service (e.g., -the [Kubernetes service][kubernetes-service]), GitLab can open +the [Kubernetes integration][kube]), GitLab can open a terminal session to your environment! This is a very powerful feature that allows you to debug issues without leaving the comfort of your web browser. To enable it, just follow the instructions given in the service integration @@ -671,7 +671,6 @@ Below are some links you may find interesting: [Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs [yaml]: yaml/README.md -[kubernetes-service]: ../user/project/integrations/kubernetes.md [environments]: #environments [deployments]: #deployments [permissions]: ../user/permissions.md @@ -683,5 +682,5 @@ Below are some links you may find interesting: [gitlab-flow]: ../workflow/gitlab_flow.md [gitlab runner]: https://docs.gitlab.com/runner/ [git-strategy]: yaml/README.md#git-strategy -[kube]: ../user/project/integrations/kubernetes.md +[kube]: ../user/project/clusters/index.md [prom]: ../user/project/integrations/prometheus.md diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index aedf7958c8a..683846a536b 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -215,8 +215,8 @@ are set in the build environment. These variables are only defined for [deployment jobs](../environments.md). Please consult the documentation of the project services that you are using to learn which variables they define. -An example project service that defines deployment variables is -[Kubernetes Service](../../user/project/integrations/kubernetes.md#deployment-variables). +An example project service that defines deployment variables is the +[Kubernetes integration](../../user/project/clusters/index.md#deployment-variables). ## Debug tracing diff --git a/doc/development/fe_guide/icons.md b/doc/development/fe_guide/icons.md index b469a9c6aef..3d8da6accc1 100644 --- a/doc/development/fe_guide/icons.md +++ b/doc/development/fe_guide/icons.md @@ -1,26 +1,44 @@ -# Icons +# Icons and SVG Illustrations -We are using SVG Icons in GitLab with a SVG Sprite, due to this the icons are only loaded once and then referenced through an ID. The sprite SVG is located under `/assets/icons.svg`. Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome usages. +We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository. +This repository is published on [npm][npm] and managed as a dependency via yarn. +You can browse all available Icons and Illustrations [here][svg-preview]. +To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`. -### Usage in HAML/Rails +## Icons -To use a sprite Icon in HAML or Rails we use a specific helper function : +We are using SVG Icons in GitLab with a SVG Sprite. +This means the icons are only loaded once, and are referenced through an ID. +The sprite SVG is located under `/assets/icons.svg`. + +Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome icons. -`sprite_icon(icon_name, size: nil, css_class: '')` +### Usage in HAML/Rails -**icon_name** Use the icon_name that you can find in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`). +To use a sprite Icon in HAML or Rails we use a specific helper function : -**size (optional)** Use one of the following sizes : 16,24,32,48,72 (this will be translated into a `s16` class) +```ruby +sprite_icon(icon_name, size: nil, css_class: '') +``` -**css_class (optional)** If you want to add additional css classes +- **icon_name** Use the icon_name that you can find in the SVG Sprite + ([Overview is available here][svg-preview]). +- **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class) +- **css_class (optional)** If you want to add additional css classes **Example** -`= sprite_icon('issues', size: 72, css_class: 'icon-danger')` +```haml += sprite_icon('issues', size: 72, css_class: 'icon-danger') +``` **Output from example above** -`<svg class="s72 icon-danger"><use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use></svg>` +```html +<svg class="s72 icon-danger"> + <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use> +</svg> +``` ### Usage in Vue @@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\ Sample usage : -`<icon - name="retry" - :size="32" - css-classes="top" - />` - -**name** Name of the Icon in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`). - -**size (optional)** Number value for the size which is then mapped to a specific CSS class (Available Sizes: 8,12,16,18,24,32,48,72 are mapped to `sXX` css classes) - -**css-classes (optional)** Additional CSS Classes to add to the svg tag. +```javascript +<script> +import Icon from "~/vue_shared/components/icon.vue" + +export default { + components: { + Icon, + }, +}; +<script> +<template> + <icon + name="issues" + :size="72" + css-classes="icon-danger" + /> +</template> +``` + +- **name** Name of the Icon in the SVG Sprite ([Overview is available here][svg-preview]). +- **size (optional)** Number value for the size which is then mapped to a specific CSS class + (Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes) +- **css-classes (optional)** Additional CSS Classes to add to the svg tag. ### Usage in HTML/JS -Please use the following function inside JS to render an icon : +Please use the following function inside JS to render an icon: `gl.utils.spriteIcon(iconName)` -## Adding a new icon to the sprite +## SVG Illustrations -All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency. +Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. +Please use the class `svg-content` around it to ensure nice rendering. -To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs`. +### Usage in HAML/Rails -# SVG Illustrations +**Example** -Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. Please use the class `svg-content` around it to ensure nice rendering. The illustrations are also organised in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository (as they are then automatically optimised). +```haml +.svg-content + = image_tag 'illustrations/merge_requests.svg' +``` -**Example** +### Usage in Vue -`= image_tag 'illustrations/merge_requests.svg'` +To use an SVG illustrations in a template provide the path as a property and display it through a standard img tag. + +Component: + +```js +<script> +export default { + props: { + svgIllustrationPath: { + type: String, + required: true, + }, + }, +}; +<script> +<template> + <img :src="svgIllustrationPath" /> +</template> +``` + +[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs +[gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs +[svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 6d3796e7560..11b9a2e6a64 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -54,8 +54,8 @@ Vuex specific design patterns and practices. ## [Axios](axios.md) Axios specific practices and gotchas. -## [Icons](icons.md) -How we use SVG for our Icons. +## [Icons and Illustrations](icons.md) +How we use SVG for our Icons and Illustrations. ## [Components](components.md) diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index f971d8b7388..e31ee087358 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -8,7 +8,7 @@ All new features built with Vue.js must follow a [Flux architecture][flux]. The main goal we are trying to achieve is to have only one data flow and only one data entry. In order to achieve this goal, you can either use [vuex](#vuex) or use the [store pattern][state-management], explained below: -Each Vue bundle needs a Store - where we keep all the data -,a Service - that we use to communicate with the server - and a main Vue component. +Each Vue bundle needs a Store - where we keep all the data -, a Service - that we use to communicate with the server - and a main Vue component. Think of the Main Vue Component as the entry point of your application. This is the only smart component that should exist in each Vue feature. @@ -17,7 +17,7 @@ This component is responsible for: 1. Calling the Store to store the data received 1. Mounting all the other components -  + You can also read about this architecture in vue docs about [state management][state-management] and about [one way data flow][one-way-data-flow]. @@ -51,14 +51,14 @@ of the new feature should be. The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. -Don't forget to follow [these steps.][page_specific_javascript] +Don't forget to follow [these steps][page_specific_javascript]. ### Bootstrapping Gotchas -#### Providing data from Haml to JavaScript +#### Providing data from HAML to JavaScript While mounting a Vue application may be a need to provide data from Rails to JavaScript. To do that, provide the data through `data` attributes in the HTML element and query them while mounting the application. -_Note:_ You should only do this while initing the application, because the mounted element will be replaced with Vue-generated DOM. +_Note:_ You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM. The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function instead of querying the DOM inside the main vue component is that makes tests easier by avoiding the need to @@ -68,6 +68,7 @@ create a fixture or an HTML element in the unit test. See the following example: // haml .js-vue-app{ data: { endpoint: 'foo' }} +// index.js document.addEventListener('DOMContentLoaded', () => new Vue({ el: '.js-vue-app', data() { @@ -87,13 +88,11 @@ document.addEventListener('DOMContentLoaded', () => new Vue({ ``` #### Accessing the `gl` object -When we need to query the `gl` object for data that won't change during the application's lyfecyle, we should do it in the same place where we query the DOM. +When we need to query the `gl` object for data that won't change during the application's life cyle, we should do it in the same place where we query the DOM. By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier. It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component: -##### example: ```javascript - document.addEventListener('DOMContentLoaded', () => new Vue({ el: '.js-vue-app', render(createElement) { @@ -121,25 +120,6 @@ in one table would not be a good use of this pattern. You can read more about components in Vue.js site, [Component System][component-system] -#### Components Gotchas -1. Using SVGs icons in components: To use an SVG icon in a template use the `icon.vue` -1. Using SVGs illustrations in components: To use an SVG illustrations in a template provide the path as a prop and display it through a standard img tag. - ```javascript - <script> - export default { - props: { - svgIllustrationPath: { - type: String, - required: true, - }, - }, - }; - <script> - <template> - <img :src="svgIllustrationPath" /> - </template> - ``` - ### A folder for the Store #### Vuex @@ -163,13 +143,13 @@ Refer to [axios](axios.md) for more details. Axios instance should only be imported in the service file. - ```javascript - import axios from 'javascripts/lib/utils/axios_utils'; - ``` +```javascript +import axios from '~/lib/utils/axios_utils'; +``` ### End Result -The following example shows an application: +The following example shows an application: ```javascript // store.js @@ -177,8 +157,8 @@ export default class Store { /** * This is where we will iniatialize the state of our data. - * Usually in a small SPA you don't need any options when starting the store. In the case you do - * need guarantee it's an Object and it's documented. + * Usually in a small SPA you don't need any options when starting the store. + * In that case you do need guarantee it's an Object and it's documented. * * @param {Object} options */ @@ -186,7 +166,7 @@ export default class Store { this.options = options; // Create a state object to handle all our data in the same place - this.todos = []: + this.todos = []; } setTodos(todos = []) { @@ -207,7 +187,7 @@ export default class Store { } // service.js -import axios from 'javascripts/lib/utils/axios_utils' +import axios from '~/lib/utils/axios_utils' export default class Service { constructor(options) { @@ -233,8 +213,8 @@ export default { type: Object, required: true, }, - } -} + }, +}; </script> <template> <div> @@ -275,7 +255,7 @@ export default { }, created() { - this.service = new Service('todos'); + this.service = new Service('/todos'); this.getTodos(); }, @@ -284,9 +264,9 @@ export default { getTodos() { this.isLoading = true; - this.service.getTodos() - .then(response => response.json()) - .then((response) => { + this.service + .getTodos() + .then(response => { this.store.setTodos(response); this.isLoading = false; }) @@ -296,18 +276,21 @@ export default { }); }, - addTodo(todo) { - this.service.addTodo(todo) - then(response => response.json()) - .then((response) => { - this.store.addTodo(response); - }) - .catch(() => { - // Show an error - }); - } - } -} + addTodo(event) { + this.service + .addTodo({ + title: 'New entry', + text: `You clicked on ${event.target.tagName}`, + }) + .then(response => { + this.store.addTodo(response); + }) + .catch(() => { + // Show an error + }); + }, + }, +}; </script> <template> <div class="container"> @@ -333,7 +316,7 @@ export default { <div> </template> -// bundle.js +// index.js import todoComponent from 'todos_main_component.vue'; new Vue({ @@ -365,76 +348,79 @@ Each Vue component has a unique output. This output is always present in the ren Although we can test each method of a Vue component individually, our goal must be to test the output of the render/template function, which represents the state at all times. -Make use of Vue Resource Interceptors to mock data returned by the service. +Make use of the [axios mock adapter](axios.md#mock-axios-response-on-tests) to mock data returned. Here's how we would test the Todo App above: ```javascript -import component from 'todos_main_component'; +import Vue from 'vue'; +import axios from '~/lib/utils/axios_utils'; +import MockAdapter from 'axios-mock-adapter'; describe('Todos App', () => { - it('should render the loading state while the request is being made', () => { + let vm; + let mock; + + beforeEach(() => { + // Create a mock adapter for stubbing axios API requests + mock = new MockAdapter(axios); + const Component = Vue.extend(component); - const vm = new Component().$mount(); + // Mount the Component + vm = new Component().$mount(); + }); + + afterEach(() => { + // Reset the mock adapter + mock.restore(); + // Destroy the mounted component + vm.$destroy(); + }); + it('should render the loading state while the request is being made', () => { expect(vm.$el.querySelector('i.fa-spin')).toBeDefined(); }); - describe('with data', () => { - // Mock the service to return data - const interceptor = (request, next) => { - next(request.respondWith(JSON.stringify([{ + it('should render todos returned by the endpoint', done => { + // Mock the get request on the API endpoint to return data + mock.onGet('/todos').replyOnce(200, [ + { title: 'This is a todo', - body: 'This is the text' - }]), { - status: 200, - })); - }; - - let vm; - - beforeEach(() => { - Vue.http.interceptors.push(interceptor); - - const Component = Vue.extend(component); + text: 'This is the text', + }, + ]); - vm = new Component().$mount(); + Vue.nextTick(() => { + const items = vm.$el.querySelectorAll('.js-todo-list div') + expect(items.length).toBe(1); + expect(items[0].textContent).toContain('This is the text'); + done(); }); + }); - afterEach(() => { - Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor); - }); + it('should add a todos on button click', (done) => { + // Mock the put request and check that the sent data object is correct + mock.onPut('/todos').replyOnce((req) => { + expect(req.data).toContain('text'); + expect(req.data).toContain('title'); - it('should render todos', (done) => { - setTimeout(() => { - expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1); - done(); - }, 0); + return [201, {}]; }); - }); - describe('add todo', () => { - let vm; - beforeEach(() => { - const Component = Vue.extend(component); - vm = new Component().$mount(); - }); - it('should add a todos', (done) => { - setTimeout(() => { - vm.$el.querySelector('.js-add-todo').click(); + vm.$el.querySelector('.js-add-todo').click(); - // Add a new interceptor to mock the add Todo request - Vue.nextTick(() => { - expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2); - }); - }, 0); + // Add a new interceptor to mock the add Todo request + Vue.nextTick(() => { + expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2); + done(); }); }); }); ``` -#### `mountComponent` helper + +### `mountComponent` helper There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props: ```javascript @@ -447,13 +433,10 @@ const data = {prop: 'foo'}; const vm = mountComponent(Component, data); ``` -#### Test the component's output +### Test the component's output The main return value of a Vue component is the rendered output. In order to test the component we need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that: -### Stubbing API responses -Refer to [mock axios](axios.md#mock-axios-response-on-tests) - [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards @@ -466,4 +449,3 @@ Refer to [mock axios](axios.md#mock-axios-response-on-tests) [issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6 [flux]: https://facebook.github.io/flux [axios]: https://github.com/axios/axios -[axios-interceptors]: https://github.com/axios/axios#interceptors diff --git a/doc/development/new_fe_guide/development/accessibility.md b/doc/development/new_fe_guide/development/accessibility.md index ed35f08432f..2a3a126ca5c 100644 --- a/doc/development/new_fe_guide/development/accessibility.md +++ b/doc/development/new_fe_guide/development/accessibility.md @@ -1,3 +1,48 @@ -# Accessibility +# Accessiblity +Using semantic HTML plays a key role when it comes to accessibility. -> TODO: Add content +## Accessible Rich Internet Applications - ARIA +WAI-ARIA, the Accessible Rich Internet Applications specification, defines a way to make Web content and Web applications more accessible to people with disabilities. + +> Note: It is [recommended][using-aria] to use semantic elements as the primary method to achieve accessibility rather than adding aria attributes. Adding aria attributes should be seen as a secondary method for creating accessible elements. + +### Role +The `role` attribute describes the role the element plays in the context of the document. + +Check the list of WAI-ARIA roles [here][roles] + +## Icons +When using icons or images that aren't absolutely needed to understand the context, we should use `aria-hidden="true"`. + +On the other hand, if an icon is crucial to understand the context we should do one of the following: +1. Use `aria-label` in the element with a meaningful description +1. Use `aria-labelledby` to point to an element that contains the explanation for that icon + +## Form inputs +In forms we should use the `for` attribute in the label statement: +``` +<div> + <label for="name">Fill in your name:</label> + <input type="text" id="name" name="name"> +</div> +``` + +## Testing + +1. On MacOS you can use [VoiceOver][voice-over] by pressing `cmd+F5`. +1. On Windows you can use [Narrator][narrator] by pressing Windows logo key + Ctrl + Enter. + +## Online resources + +- [Chrome Accessibility Developer Tools][dev-tools] for testing accessibility +- [Audit Rules Page][audit-rules] for best practices +- [Lighthouse Accessibility Score][lighthouse] for accessibility audits + +[using-aria]: https://www.w3.org/TR/using-aria/#notes2 +[dev-tools]: https://github.com/GoogleChrome/accessibility-developer-tools +[audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules +[aria-w3c]: https://www.w3.org/TR/wai-aria-1.1/ +[roles]: https://www.w3.org/TR/wai-aria-1.1/#landmark_roles +[voice-over]: https://www.apple.com/accessibility/mac/vision/ +[narrator]: https://www.microsoft.com/en-us/accessibility/windows +[lighthouse]: https://developers.google.com/web/tools/lighthouse/scoring#a11y diff --git a/doc/user/project/integrations/img/kubernetes_configuration.png b/doc/user/project/integrations/img/kubernetes_configuration.png Binary files differdeleted file mode 100644 index e535e2b8d46..00000000000 --- a/doc/user/project/integrations/img/kubernetes_configuration.png +++ /dev/null diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index f502d1c9821..9342a2cbb00 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -1,137 +1 @@ ---- -last_updated: 2017-12-28 ---- - -# GitLab Kubernetes / OpenShift integration - -CAUTION: **Warning:** -The Kubernetes service integration has been deprecated in GitLab 10.3. If the -service is active, the cluster information will still be editable, however we -advise to disable and reconfigure the clusters using the new -[Clusters](../clusters/index.md) page. If the service is inactive, the fields -will not be editable. Read [GitLab 10.3 release post](https://about.gitlab.com/2017/12/22/gitlab-10-3-released/#kubernetes-integration-service) for more information. - -GitLab can be configured to interact with Kubernetes, or other systems using the -Kubernetes API (such as OpenShift). - -Each project can be configured to connect to a different Kubernetes cluster, see -the [configuration](#configuration) section. - -## Configuration - -Navigate to the [Integrations page](project_services.md#accessing-the-project-services) -of your project and select the **Kubernetes** service to configure it. Fill in -all the needed parameters, check the "Active" checkbox and hit **Save changes** -for the changes to take effect. - - - -The Kubernetes service takes the following parameters: - -- **API URL** - - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes - exposes several APIs, we want the "base" URL that is common to all of them, - e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. -- **CA certificate** (optional) - - If the API is using a self-signed TLS certificate, you'll also need to include - the `ca.crt` contents here. -- **Project namespace** (optional) - The following apply: - - By default you don't have to fill it in; by leaving it blank, GitLab will - create one for you. - - Each project should have a unique namespace. - - The project namespace is not necessarily the namespace of the secret, if - you're using a secret with broader permissions, like the secret from `default`. - - You should **not** use `default` as the project namespace. - - If you or someone created a secret specifically for the project, usually - with limited permissions, the secret's namespace and project namespace may - be the same. -- **Token** - - GitLab authenticates against Kubernetes using service tokens, which are - scoped to a particular `namespace`. If you don't have a service token yet, - you can follow the - [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) - to create one. You can also view or create service tokens in the - [Kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#config) - (under **Config > Secrets**). - -TIP: **Tip:** -If you have a single cluster that you want to use for all your projects, -you can pre-fill the settings page with a default template. To configure the -template, see [Services Templates](services_templates.md). - -## Deployment variables - -The Kubernetes service exposes the following -[deployment variables](../../../ci/variables/README.md#deployment-variables) in the -GitLab CI/CD build environment: - -- `KUBE_URL` - Equal to the API URL. -- `KUBE_TOKEN` - The Kubernetes token. -- `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. -- `KUBECONFIG` - Path to a file containing `kubeconfig` for this deployment. - CA bundle would be embedded if specified. - -## What you can get with the Kubernetes integration - -Here's what you can do with GitLab if you enable the Kubernetes integration. - -### Deploy Boards - -> Available in [GitLab Premium][ee]. - -GitLab's Deploy Boards offer a consolidated view of the current health and -status of each CI [environment](../../../ci/environments.md) running on Kubernetes, -displaying the status of the pods in the deployment. Developers and other -teammates can view the progress and status of a rollout, pod by pod, in the -workflow they already use without any need to access Kubernetes. - -[> Read more about Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) - -### Canary Deployments - -> Available in [GitLab Premium][ee]. - -Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) -and visualize your canary deployments right inside the Deploy Board, without -the need to leave GitLab. - -[> Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) - -### Kubernetes monitoring - -Automatically detect and monitor Kubernetes metrics. Automatic monitoring of -[NGINX ingress](./prometheus_library/nginx.md) is also supported. - -[> Read more about Kubernetes monitoring](prometheus_library/kubernetes.md) - -### Auto DevOps - -Auto DevOps automatically detects, builds, tests, deploys, and monitors your -applications. - -To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) -you will need the Kubernetes project integration enabled. - -[> Read more about Auto DevOps](../../../topics/autodevops/index.md) - -### Web terminals - -NOTE: **Note:** -Introduced in GitLab 8.15. You must be the project owner or have `master` permissions -to use terminals. Support is limited to the first container in the -first pod of your environment. - -When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals) -support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in -Docker and Kubernetes, so you get a new shell session within your existing -containers. To use this integration, you should deploy to Kubernetes using -the deployment variables above, ensuring any pods you create are labelled with -`app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest! - -[ee]: https://about.gitlab.com/products/ +This document was moved to [another location](../clusters/index.md). diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 074eeb729e3..8c51eb9915e 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -39,7 +39,6 @@ Click on the service links to see further configuration instructions and details | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | -| [Kubernetes](kubernetes.md) _(Has been deprecated in GitLab 10.3)_ | A containerized deployment service | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | | [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | |
