diff options
Diffstat (limited to 'doc/administration/integration')
-rw-r--r-- | doc/administration/integration/kroki.md | 162 | ||||
-rw-r--r-- | doc/administration/integration/plantuml.md | 4 | ||||
-rw-r--r-- | doc/administration/integration/terminal.md | 22 |
3 files changed, 175 insertions, 13 deletions
diff --git a/doc/administration/integration/kroki.md b/doc/administration/integration/kroki.md new file mode 100644 index 00000000000..dead5640873 --- /dev/null +++ b/doc/administration/integration/kroki.md @@ -0,0 +1,162 @@ +# Kroki diagrams **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241744) in GitLab 13.7. + +When [Kroki](https://kroki.io) integration is enabled and configured in +GitLab you can use it to create diagrams in AsciiDoc and Markdown documents. + +## Kroki Server + +When Kroki is enabled, GitLab sends diagrams to an instance of Kroki to display them as images. +You can use the free public cloud instance `https://kroki.io` or you can [install Kroki](https://docs.kroki.io/kroki/setup/install/) +on your own infrastructure. +After you've installed Kroki, make sure to update the server URL to point to your instance. + +### Docker + +With Docker, run a container like this: + +```shell +docker run -d --name kroki -p 8080:8000 yuzutech/kroki +``` + +The **Kroki URL** is the hostname of the server running the container. + +The [`yuzutech/kroki`](https://hub.docker.com/r/yuzutech/kroki) image contains the following diagrams libraries out-of-the-box: + +- [Bytefield](https://bytefield-svg.deepsymmetry.org/) +- [Ditaa](http://ditaa.sourceforge.net) +- [Erd](https://github.com/BurntSushi/erd) +- [GraphViz](https://www.graphviz.org/) +- [Nomnoml](https://github.com/skanaar/nomnoml) +- [PlantUML](https://github.com/plantuml/plantuml) + - [C4 model](https://github.com/RicardoNiepel/C4-PlantUML) (with PlantUML) +- [Svgbob](https://github.com/ivanceras/svgbob) +- [UMlet](https://github.com/umlet/umlet) +- [Vega](https://github.com/vega/vega) +- [Vega-Lite](https://github.com/vega/vega-lite) +- [WaveDrom](https://wavedrom.com/) + +If you want to use additional diagram libraries, +read the [Kroki installation](https://docs.kroki.io/kroki/setup/install/#_images) to learn how to start Kroki companion containers. + +## Enable Kroki in GitLab + +You need to enable Kroki integration from Settings under Admin Area. +To do that, log in with an administrator account and follow these steps: + +1. Select the Admin Area (**{admin}**) icon. +1. Navigate to **Settings > General**. +1. Expand the **Kroki** section. +1. Select **Enable Kroki** checkbox. +1. Enter the **Kroki URL**. + +## Create diagrams + +With Kroki integration enabled and configured, you can start adding diagrams to +your AsciiDoc or Markdown documentation using delimited blocks: + +- **Markdown** + + ````markdown + ```plantuml + Bob -> Alice : hello + Alice -> Bob : hi + ``` + ```` + +- **AsciiDoc** + + ```plaintext + [plantuml] + .... + Bob->Alice : hello + Alice -> Bob : hi + .... + ``` + +The above blocks are converted to an HTML image tag with source pointing to the +Kroki instance. If the Kroki server is correctly configured, this should +render a nice diagram instead of the block: + +![PlantUML diagram](../img/kroki_plantuml_diagram.png) + +Kroki supports more than a dozen diagram libraries. Here's a few examples: + +**GraphViz** + +```plaintext +[graphviz] +.... +digraph finite_state_machine { + rankdir=LR; + node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8; + node [shape = circle]; + LR_0 -> LR_2 [ label = "SS(B)" ]; + LR_0 -> LR_1 [ label = "SS(S)" ]; + LR_1 -> LR_3 [ label = "S($end)" ]; + LR_2 -> LR_6 [ label = "SS(b)" ]; + LR_2 -> LR_5 [ label = "SS(a)" ]; + LR_2 -> LR_4 [ label = "S(A)" ]; + LR_5 -> LR_7 [ label = "S(b)" ]; + LR_5 -> LR_5 [ label = "S(a)" ]; + LR_6 -> LR_6 [ label = "S(b)" ]; + LR_6 -> LR_5 [ label = "S(a)" ]; + LR_7 -> LR_8 [ label = "S(b)" ]; + LR_7 -> LR_5 [ label = "S(a)" ]; + LR_8 -> LR_6 [ label = "S(b)" ]; + LR_8 -> LR_5 [ label = "S(a)" ]; +} +.... +``` + +![GraphViz diagram](../img/kroki_graphviz_diagram.png) + +**C4 (based on PlantUML)** + +```plaintext +[c4plantuml] +.... +@startuml +!include C4_Context.puml + +title System Context diagram for Internet Banking System + +Person(customer, "Banking Customer", "A customer of the bank, with personal bank accounts.") +System(banking_system, "Internet Banking System", "Allows customers to check their accounts.") + +System_Ext(mail_system, "E-mail system", "The internal Microsoft Exchange e-mail system.") +System_Ext(mainframe, "Mainframe Banking System", "Stores all of the core banking information.") + +Rel(customer, banking_system, "Uses") +Rel_Back(customer, mail_system, "Sends e-mails to") +Rel_Neighbor(banking_system, mail_system, "Sends e-mails", "SMTP") +Rel(banking_system, mainframe, "Uses") +@enduml +.... +``` + +![C4 PlantUML diagram](../img/kroki_c4_diagram.png) + +**Nomnoml** + +```plaintext +[nomnoml] +.... +[Pirate|eyeCount: Int|raid();pillage()| + [beard]--[parrot] + [beard]-:>[foul mouth] +] + +[<abstract>Marauder]<:--[Pirate] +[Pirate]- 0..7[mischief] +[jollyness]->[Pirate] +[jollyness]->[rum] +[jollyness]->[singing] +[Pirate]-> *[rum|tastiness: Int|swig()] +[Pirate]->[singing] +[singing]<->[rum] +.... +``` + +![Nomnoml diagram](../img/kroki_nomnoml_diagram.png) diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 5bdea9d8843..a7458999aaa 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,7 +1,7 @@ --- stage: Create group: Source Code -info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers" +info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments" type: reference, howto --- @@ -137,7 +137,7 @@ that, login with an Admin account and do following: - Check **Enable PlantUML** checkbox. - Set the PlantUML instance as `https://gitlab.example.com/-/plantuml/`. -NOTE: **Note:** +NOTE: If you are using a PlantUML server running v1.2020.9 and above (for example, [plantuml.com](https://plantuml.com)), set the `PLANTUML_ENCODING` environment variable to enable the `deflate` compression. On Omnibus, diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 3c53535d856..f4c242b6e72 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -1,14 +1,14 @@ --- -stage: none -group: unassigned -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +stage: Create +group: Ecosystem +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Web terminals > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7690) in GitLab 8.15. -NOTE: **Note:** +NOTE: Only project maintainers and owners can access web terminals. With the introduction of the [Kubernetes integration](../../user/project/clusters/index.md), @@ -27,7 +27,7 @@ In brief: - When a user navigates to the terminal page for an environment, they are served a JavaScript application that opens a WebSocket connection back to GitLab. - The WebSocket is handled in [Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse), - rather than the Rails application server. + rather than the Rails application server. - Workhorse queries Rails for connection details and user permissions. Rails queries Kubernetes for them in the background using [Sidekiq](../troubleshooting/sidekiq.md). - Workhorse acts as a proxy server between the user's browser and the Kubernetes @@ -44,14 +44,14 @@ everything protected with authorization guards. This is described in more detail below. - Interactive web terminals are completely disabled unless [`[session_server]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) is configured. -- Every time the runner starts, it will generate an `x509` certificate that will be used for a `wss` (Web Socket Secure) connection. +- Every time the runner starts, it generates an `x509` certificate that is used for a `wss` (Web Socket Secure) connection. - For every created job, a random URL is generated which is discarded at the end of the job. This URL is used to establish a web socket connection. The URL for the session is in the format `(IP|HOST):PORT/session/$SOME_HASH`, where the `IP/HOST` and `PORT` are the configured [`listen_address`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section). - Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection. - The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly. ## Enabling and disabling terminal support -NOTE: **Note:** +NOTE: AWS Elastic Load Balancers (ELBs) do not support web sockets. AWS Application Load Balancers (ALBs) must be used if you want web terminals to work. See [AWS Elastic Load Balancing Product Comparison](https://aws.amazon.com/elasticloadbalancing/features/#compare) @@ -72,7 +72,7 @@ guides document the necessary steps for a selection of popular reverse proxies: - [HAProxy](https://www.haproxy.com/blog/websockets-load-balancing-with-haproxy/) - [Varnish](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html) -Workhorse won't let WebSocket requests through to non-WebSocket endpoints, so +Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so it's safe to enable support for these headers globally. If you'd rather had a narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` (although this may still have a few false positives). @@ -85,7 +85,7 @@ document for more details. If you'd like to disable web terminal support in GitLab, just stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse -proxy in the chain. For most users, this will be the NGINX server bundled with +proxy in the chain. For most users, this is the NGINX server bundled with Omnibus GitLab, in which case, you need to: - Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file @@ -95,9 +95,9 @@ Omnibus GitLab, in which case, you need to: For your own load balancer, just reverse the configuration changes recommended by the above guides. -When these headers are not passed through, Workhorse will return a +When these headers are not passed through, Workhorse returns a `400 Bad Request` response to users attempting to use a web terminal. In turn, -they will receive a `Connection failed` message. +they receive a `Connection failed` message. ## Limiting WebSocket connection time |