pre-release: Add a page about telepresence login

Signed-off-by: Luke Shumaker <[email protected]>

doc-links.yml

@@ -38,6 +38,9 @@
        link: reference/tun-device
      - title: Client reference
        link: reference/client
+       items:
+         - title: login
+           link: reference/client/login
      - title: Laptop-side configuration
        link: reference/config
      - title: Cluster-side configuration

reference/client/login.md

@@ -0,0 +1,53 @@
+# `telepresence login`
+
+```console
+$ telepresence login --help
+Authenticate to Ambassador Cloud
+
+Usage:
+  telepresence login [flags]
+
+Flags:
+      --apikey string   Static API key to use instead of performing an interactive login
+```
+
+## Description
+
+Use `telepresence login` to explicitly authenticate with [Ambassador
+Cloud](https://www.getambassador.io/docs/cloud).  Unless the
+[`skipLogin` option](../../config) is set, other commands will
+automatically invoke the `telepresence login` interactive login
+procedure as nescessary, so it is rarely nescessary to explicitly run
+`telepresence login`; it should only be truly nescessary to explictly
+run `telepresence login` when you require a non-interactive login.
+
+The normal interactive login procedure involves launching a web
+browser, a user interacting with that web browser, and finally having
+the web browser make callbacks to the local Telepresence process.  If
+it is not possible to do this (perhaps you are using a headless remote
+box via SSH, or are using Telepresence in CI), then you may instead
+have Ambassador Cloud issue an API key that you pass to `telepresence
+login` with the `--apikey` flag.
+
+## Acquiring an API key
+
+1. Log in to Ambassador Cloud at https://app.getambassador.io/ .
+
+2. Click on your profile icon in the upper-left: ![Screenshot with the
+   mouse pointer over the upper-left profile icon](./apikey-2.png)
+
+3. Click on the "API Keys" menu button: ![Screenshot with the mouse
+   pointer over the "API Keys" menu button](./apikey-3.png)
+
+4. Click on the "generate new key" button in the upper-right:
+   ![Screenshot with the mouse pointer over the "generate new key"
+   button](./apikey-4.png)
+
+5. Enter a description for the key (perhaps the name of your laptop,
+   or perhaps the "CI"), and click "generate api key" to create it.
+
+You may now pass the API key as `KEY` to `telepresence login --apikey=KEY`.
+
+Telepresence will use that "master" API key to create narrower keys
+for different components of Telepresence.  You will see these appear
+in the Ambassador Cloud web interface.

releaseNotes.yml

@@ -43,6 +43,7 @@ items:
           environments where launching a web-browser is impossible,
           such as cloud shells, Docker containers, or CI.
         image: telepresence-2.3.7-newkey.png
+        docs: reference/client/login/
 
       - type: bugfix
         title: Better UX around intercepts with no local process running