Merge branch 'master' of github.com:gravitational/teleport into STeve…

…/48762_ssh_tsh

.github/ISSUE_TEMPLATE/test-plan-docs.md

@@ -1,49 +1,52 @@
 ---
-name: Documentation Test Plan
-about: Manual test plan for Teleport major releases
+name: Documentation Release Plan
+about: Documentation checks and changes to perform for major Teleport releases
 title: "Teleport X Docs Test Plan"
 labels: testplan
 ---
 
-Perform the following checks on the Teleport documentation whenever we roll out
-a new major version of Teleport on Teleport Cloud. Use `/docs/upcoming-releases`
-to determine the rollout date.
+Perform the following tasks whenever we roll out a new major version of
+Teleport. 
 
-## Is the internal documentation coverage record up to date?
+We need to make sure that the documentation site presents accurate information
+to Teleport Enterprise (Cloud) users by default. Since we roll out a new major
+Teleport version to Teleport Enterprise (Cloud) users several weeks after we
+release the version, documentation release steps take place in two
+phases:
 
-- [ ] Identify features within the new release that we want to include as topics
-  in our measurement of documentation coverage. Update our internal
-  documentation coverage record to include the new topics. See our internal
-  knowledge base for the location of the coverage record.
+- **Phase One:** We have released a new major version of Teleport but have not
+  rolled it out to Teleport Enterprise (Cloud) customers.
+- **Phase Two:** We have rolled out the new major version of Teleport to
+  Teleport Enterprise (Cloud) customers.
 
-## Is the docs site configuration accurate?
+Use `/docs/upcoming-releases` to determine the Teleport Enterprise (Cloud)
+rollout date.
 
-> [!IMPORTANT] 
-> **Do not merge the new docs site configuration** before we roll out a new
-> major version to Teleport Enterprise (Cloud).
+## Phase One tasks
 
-- [ ] Verify the latest version in `gravitational/docs/config.json`
+Make sure these tasks are complete by the time we have released a new major
+version of Teleport.
 
-- [ ] Verify that `gravitational/docs/.gitmodules` contains the latest release
-
-- [ ] Ensure that submodule directories in `gravitational/docs` correspond to
-    those in `.gitmodules`.
+- [ ] Identify features within the new release that we want to include as topics
+  in our measurement of documentation coverage. Update our internal
+  documentation coverage record to include the new topics. See our internal
+  knowledge base for the location of the coverage record.
 
-    Remove the directory of the EOL release and create one for the next release
-    using a command similar to the following:
+- [ ] Update the submodule configuration in `gravitational/docs-website`.
 
-    ```bash
-    git submodule add https://github.com/gravitational/teleport content/<VERSION>.x
-    ```
+  Remove the directory of the EOL release. Create a directory for the next
+  release using a command similar to the following:
+
+  ```bash
+  git submodule add https://github.com/gravitational/teleport content/<VERSION>.x
+  ```
 
-## Is the docs site content up to date with the new release?
+  Verify that `gravitational/docs-website/.gitmodules` contains the latest
+  release and not the EOL release.
 
 - [ ] Verify that Teleport version variables are correct and reflect the upcoming
-  release. Check `docs/config.json` for this.
-
-- [ ] Ensure that redirects (as configured in `docs/config.json`) only exist for
-  the default version of the docs site, and have been removed from other
-  versions.
+  release. Check `docs/config.json` for this in all supported branches of
+  `gravitational/teleport`.
 
 - [ ] Remove version warnings in the docs that mention a version we no longer
   support _except_ for the last EOL version. E.g., if we no longer support
@@ -52,11 +55,11 @@ to determine the rollout date.
 
 - [ ] Verify that all necessary documentation for the release was backported to
   the release branch:
-  - [ ] Diff between master and release branch and make sure there are no missed
-    PRs
+  - [ ] Diff between `master` and the new release branch and make sure there are
+    no missed PRs.
   - [ ] Ensure that the release branch's documentation content reflects all
     changes introduced by the release. If not, plan to update the docs ASAP and
-    notify all relevant teams of the delay (e.g., Developer Relations).
+    notify all relevant teams of the delay.
 
 - [ ] Verify that the [changelog](../../CHANGELOG.md) is up to date and complete
   for the default docs version. If one release branch has a more complete
@@ -67,38 +70,47 @@ to determine the rollout date.
   $ git checkout origin/branch/v<release_version> -- CHANGELOG.md
   ```
 
-- [ ] Verify the supported versions table in the FAQ
-  (https://goteleport.com/docs/faq/#supported-versions)
+- [ ] Update the supported versions table in the FAQ
+  (https://goteleport.com/docs/faq/#supported-versions).
 
-- [ ] Verify that the [Upcoming Releases
-  Page](../../docs/pages/upcoming-releases.mdx) only exists for the major
-  version of Teleport we are releasing. Ensure that this page contains the
-  latest information:
+- [ ] Verify the accuracy of critical docs pages. Follow the docs guides below
+  and verify their accuracy while using the newly released major version of
+  Teleport.
 
-  ```bash
-  $ git checkout origin/branch/v<last_version> -- docs/pages/upcoming-releases.mdx
-  ```
+  - [ ] General [installation page](../../docs/pages/installation.mdx): ensure
+    that installation methods support the new release candidate.
+  - [ ] [Teleport Community
+    Edition](../../docs/pages/admin-guides/deploy-a-cluster/linux-demo.mdx) demo
+    guide.
+  - [ ] [Teleport Enterprise (Cloud)](../../docs/pages/get-started.mdx) getting
+    started guide.
+  - [ ] [Teleport Enterprise (Self-Hosted) with
+    Helm](../../docs/pages/admin-guides/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx)
+  - [ ] [Teleport Enterprise (Self-Hosted) with
+    Terraform](../../docs/pages/admin-guides/deploy-a-cluster/deployments/aws-ha-autoscale-cluster-terraform.mdx)
 
-## Verify the accuracy of critical docs pages
+## Phase Two changes
 
-Follow the docs guides below and verify their accuracy. To do so, open the
-version of the docs site that corresponds to the major release we're testing
-for. For example, for Teleport 12 release use `branch/v12` branch and make sure
-to select "Version 12.0" in the documentation version switcher.
+Make sure these tasks are complete by the time we have rolled out a new major
+version of Teleport to Teleport Enterprise (Cloud) customers.
 
-### Installation
+- [ ] Update the docs site configuration in
+  `gravitational/docs-website/config.json`: ensure that the EOL version has
+  `"deprecated": true` assigned and the newly rolled out version has
+  `"isDefault" true`. Remove the `"isDefault": true` assignment from the
+  previous version.
 
-- [ ] General [installation page](../../docs/pages/installation.mdx): ensure that
-  installation methods support the new release candidate.
-- [ ] Enterprise Cloud [downloads
-  page](../../docs/pages/choose-an-edition/teleport-cloud/downloads.mdx): ensure that
-  the release cnadidate is available at the repositories we link to.
+- [ ] Copy the changelog from the previous default branch to the new one:
+
+  ```bash
+  $ git checkout origin/branch/v<release_version> -- CHANGELOG.md
+  ```
 
-### Getting started
+- [ ] Verify that the [Upcoming Releases
+  Page](../../docs/pages/upcoming-releases.mdx) only exists for the major
+  version of Teleport we have rolled out. Ensure that this page contains the
+  latest information:
 
-- [ ] [Teleport Community Edition](../../docs/pages/index.mdx)
-- [ ] [Teleport Enterprise (Cloud)](../../docs/pages/choose-an-edition/teleport-cloud/get-started.mdx).
-- [ ] [Teleport Enterprise (Self-Hosted) with
-  Helm](../../docs/pages/deploy-a-cluster/helm-deployments/kubernetes-cluster.mdx)
-- [ ] [Teleport Enterprise (Self-Hosted) with
-  Terraform](../../docs/pages/deploy-a-cluster/deployments/aws-ha-autoscale-cluster-terraform.mdx)
+  ```bash
+  $ git checkout origin/branch/v<last_version> -- docs/pages/upcoming-releases.mdx
+  ```

.github/ISSUE_TEMPLATE/webtestplan.md

@@ -123,10 +123,9 @@ All actions should require re-authn with a webauthn device.
 For each, test the invite, reset, and login flows
 
 - [ ] Verify that input fields validates
-- [ ] Verify with `second_factor` type to `off`
-- [ ] Verify with `second_factor` type to `otp`, requires otp
-- [ ] Verify with `second_factor` type to `webauthn`, requires hardware key
-- [ ] Verify with `second_factor` type to `on`, requires a MFA device
+- [ ] Verify with `second_factors` set to `["otp"]`, requires otp
+- [ ] Verify with `second_factors` set to `["webauthn"]`, requires hardware key
+- [ ] Verify with `second_factors` set to `["webauthn", "otp"]`, requires a MFA device
 - [ ] Verify that error message is shown if an invite/reset is expired/invalid
 - [ ] Verify that account is locked after several unsuccessful login attempts
 
@@ -808,16 +807,16 @@ Add the following to enable read access to trusted clusters
 - Auth methods
   - Verify that the app supports clusters using different auth settings
     (`auth_service.authentication` in the cluster config):
-    - [ ] `type: local`, `second_factor: "otp"`
+    - [ ] `type: local`, `second_factors: ["otp"]`
       - [ ] Test per-session MFA items listed later in the test plan.
-    - [ ] `type: local`, `second_factor: "webauthn"`,
+    - [ ] `type: local`, `second_factors: ["webauthn"]`,
       - [ ] Test per-session MFA items listed later in the test plan.
-    - [ ] `type: local`, `second_factor: "webauthn"`, log in passwordlessly with hardware key
-    - [ ] `type: local`, `second_factor: "webauthn"`, log in passwordlessly with touch ID
-    - [ ] `type: local`, `second_factor: "on"`, log in with OTP
+    - [ ] `type: local`, `second_factors: ["webauthn"]`, log in passwordlessly with hardware key
+    - [ ] `type: local`, `second_factors: ["webauthn"]`, log in passwordlessly with touch ID
+    - [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with OTP
       - [ ] Test per-session MFA items listed later in the test plan.
-    - [ ] `type: local`, `second_factor: "on"`, log in with hardware key
-    - [ ] `type: local`, `second_factor: "on"`, log in with passwordless auth
+    - [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with hardware key
+    - [ ] `type: local`, `second_factors: ["webauthn", "otp"]`, log in with passwordless auth
     - [ ] Verify that the passwordless credential picker works.
       - To make the picker show up, you need to add the same MFA device with passwordless
         capabilities to multiple users.

.github/workflows/doc-tests.yaml

@@ -50,7 +50,7 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          repository: 'gravitational/docs'
+          repository: 'gravitational/docs-website'
           path: 'docs'
 
       # Cache node_modules. Unlike the example in the actions/cache repo, this
@@ -80,30 +80,35 @@ jobs:
         # use for the live docs site in that we only test a single version of
         # the content.
         #
-        # To do this, we replace the three submodules we use for building the
-        # live docs site with a single submodule, pointing to the
-        # gravitational/teleport branch we are linting.
-        #
+        # To do this, we delete the three submodules we use for building the
+        # live docs site and copy a gravitational/teleport clone into the
+        # content directory.
+        # 
         # The docs engine expects a config.json file at the root of the
         # gravitational/docs clone that associates directories with git
         # submodules. By default, these directories represent versioned branches
         # of gravitational/teleport. We override this in order to build only a
         # single version of the docs.
+        #
+        # We also replace data fetched from Sanity CMS with hardcoded JSON
+        # objects to remove the need to authenticate with Sanity. Each includes
+        # the minimal set of data required for docs builds to succeed.
         run: |
           echo "" > .gitmodules
           rm -rf content/*
-          cd content
           # Rather than using a submodule, copy the teleport source into the
           # content directory.
-          cp -r $GITHUB_WORKSPACE/teleport $GITHUB_WORKSPACE/docs/content
-          cd $GITHUB_WORKSPACE/docs
-          echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"teleport\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
-          cat <<< "$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json)" > package.json
-          yarn build-node
+          cp -r "$GITHUB_WORKSPACE/teleport" "$GITHUB_WORKSPACE/docs/content/current"
+          jq -nr --arg version "current" '{"versions": [{"name": $version,"branch": $version,"deprecated": false,"isDefault": true}]}' > config.json
+          NEW_PACKAGE_JSON=$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json);
+          NEW_PACKAGE_JSON=$(jq '.scripts."prepare-sanity-data" = "echo Using pre-populated Sanity data"' <<< "$NEW_PACKAGE_JSON");
+          echo "$NEW_PACKAGE_JSON" > package.json;
+          echo "{}" > data/events.json
+          echo '{"bannerButtons":{"second":{"title":"LOG IN","url":"https://teleport.sh"},"first":{"title":"Support","url":"https://goteleport.com/support/"}},"navbarData":{"rightSide":{},"logo":"/favicon.svg","menu":[]}}' > data/navbar.json
 
       - name: Check spelling
         working-directory: 'docs'
-        run: yarn spellcheck content/teleport
+        run: yarn spellcheck content/current
 
       - name: Lint docs formatting
         working-directory: 'docs'

.github/workflows/docs-amplify.yaml

@@ -0,0 +1,42 @@
+name: Docs Preview
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - .github/workflows/docs-amplify.yaml
+  workflow_dispatch:
+
+permissions:
+  pull-requests: write
+  id-token: write
+
+jobs:
+  amplify-preview:
+    name: Prepare Amplify preview URL
+    runs-on: ubuntu-22.04-2core-arm64
+    environment: docs-amplify
+    steps:    
+    - name: Configure AWS credentials
+      uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4
+      with:
+        aws-region: us-west-2
+        role-to-assume: ${{ vars.IAM_ROLE }}
+
+    - name: Create Amplify preview environment
+      uses: gravitational/shared-workflows/tools/amplify-preview@tools/amplify-preview/v0.0.1
+      continue-on-error: true
+      with:
+        app_ids: ${{ vars.AMPLIFY_APP_IDS }}
+        create_branches: "true"
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        wait: "true"
+
+    - name: Print failure message
+      if: failure()
+      env:
+        ERR_TITLE: Teleport Docs preview build failed
+        ERR_MESSAGE: >-
+          Please refer to the following documentation for help: https://www.notion.so/goteleport/How-to-Amplify-deployments-162fdd3830be8096ba72efa1a49ee7bc?pvs=4
+      run: |
+        echo ::error title=$ERR_TITLE::$ERR_MESSAGE
+        exit 1

.github/workflows/update-docs-webhook.yaml

@@ -15,18 +15,11 @@ jobs:
     environment: update-docs
     strategy:
       fail-fast: false
-      matrix:
-        webhooks:
-        - url_secret_name: DOCS_DEPLOY_HOOK
-          http_method: GET
-        - url_secret_name: AMPLIFY_DOCS_DEPLOY_HOOK
-          http_method: POST
     steps:
       - name: Call deployment webhook
         env:
-          WEBHOOK_URL: ${{ secrets[matrix.webhooks.url_secret_name] }}
-          HTTP_METHOD: ${{ matrix.webhooks.http_method }}
+          WEBHOOK_URL: ${{ secrets.AMPLIFY_DOCS_DEPLOY_HOOK }}
         run: |
-          if curl -X "$HTTP_METHOD" --silent --fail --show-error "$WEBHOOK_URL" > /dev/null; then
+          if curl -X POST --silent --fail --show-error "$WEBHOOK_URL" > /dev/null; then
             echo "Triggered successfully"
           fi