Add gitaly-ssh README with comparison to gitlab-shell

1 files changed, 64 insertions, 0 deletions

diff --git a/cmd/gitaly-ssh/README.md b/cmd/gitaly-ssh/README.md
new file mode 100644
index 000000000..74a78a0ca
--- /dev/null
+++ b/cmd/gitaly-ssh/README.md
@@ -0,0 +1,64 @@
+# gitaly-ssh
+
+Gitaly-ssh is a helper executable that enables Git data traffic
+(`git fetch`) between Gitaly servers within a single GitLab
+installation. It acts as a plugin to `git fetch` using the
+`GIT_SSH_COMMAND` environment variable.
+
+The implementation shares code with how gitlab-shell handles Git SSH traffic
+from real users, but it cuts out SSH itself.
+
+## How gitlab-shell does it
+
+A normal `git fetch` over SSH goes through these steps. Note that here
+`git fetch` runs on the computer of a GitLab user.
+
+```mermaid
+sequenceDiagram
+  participant User as User
+  participant UserGit as git fetch
+  participant SSHClient as User's SSH Client
+  participant SSHD as GitLab SSHD
+  participant GitLabShell as gitlab-shell
+  participant GitalyServer as Gitaly
+  participant GitalyGit as git upload-pack
+
+  User ->> UserGit: Runs git fetch
+  UserGit ->> SSHClient: Spawns SSH client
+  Note over User,SSHClient: On user's local machine
+
+  SSHClient ->> SSHD: SSH session
+  Note over SSHClient,SSHD: Session over Internet
+
+  SSHD ->> GitLabShell: spawns gitlab-shell
+  GitLabShell ->> GitalyServer: gRPC SSHUploadPack
+  GitalyServer ->> GitalyGit: spawns git upload-pack
+
+  Note over GitalyServer,GitalyGit: On Gitaly server
+  Note over SSHD,GitalyGit: On GitLab server
+```
+
+## How gitaly-ssh does it
+
+In contrast, with `gitaly-ssh`, `git fetch` is run by one Gitaly server
+('gitaly 1') that wants to fetch data from another ('gitaly 2'). Note
+that there is no SSH client or server in this chain.
+
+```mermaid
+sequenceDiagram
+  participant Gitaly1 as Gitaly 1
+  participant Gitaly1Git as git fetch
+  participant GitalySSH as gitaly-ssh
+  participant Gitaly2 as Gitaly 2
+  participant Gitaly2Git as git upload-pack
+
+  Gitaly1 ->> Gitaly1Git: Spawns git-fetch
+  Gitaly1Git ->> GitalySSH: Spawns gitaly-ssh
+  Note over Gitaly1,GitalySSH: On Gitaly server 1
+
+  GitalySSH ->> Gitaly2: grpc SSHUploadPack
+  Note over GitalySSH,Gitaly2: Internal network (TCP/Unix)
+
+  Gitaly2 ->> Gitaly2Git: Spawns git upload-pack
+  Note over Gitaly2,Gitaly2Git: On Gitaly server 2
+```
\ No newline at end of file