1 files changed, 55 insertions, 0 deletions
diff --git a/doc/development/agent/local.md b/doc/development/agent/local.md
index 603364567bf..670315db3a8 100644
--- a/doc/development/agent/local.md
+++ b/doc/development/agent/local.md
@@ -98,3 +98,58 @@ bazel test //internal/module/gitops/server:server_test
 - Bazel documentation about [specifying targets to build](https://docs.bazel.build/versions/master/guide.html#specifying-targets-to-build).
 - [The Bazel query](https://docs.bazel.build/versions/master/query.html)
 - [Bazel query how to](https://docs.bazel.build/versions/master/query-how-to.html)
+
+## KAS QA tests
+
+This section describes how to run KAS tests against different GitLab environments based on the
+[GitLab QA orchestrator](https://gitlab.com/gitlab-org/gitlab-qa).
+
+### Status
+
+The `kas` QA tests currently have some limitations. You can run them manually on GDK, but they don't
+run automatically with the nightly jobs against the live environment. See the section below
+to learn how to run them against different environments.
+
+### Prepare
+
+Before performing any of these tests, if you have a `k3s` instance running, make sure to
+stop it manually before running them. Otherwise, the tests might fail with the message
+`failed to remove k3s cluster`.
+
+You might need to specify the correct Agent image version that matches the `kas` image version. You can use the `GITLAB_AGENTK_VERSION` local env for this.
+
+### Against `staging`
+
+1. Go to your local `qa/qa/service/cluster_provider/k3s.rb` and comment out
+   [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/5b15540ea78298a106150c3a1d6ed26416109b9d/qa/qa/service/cluster_provider/k3s.rb#L8) and
+   [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/5b15540ea78298a106150c3a1d6ed26416109b9d/qa/qa/service/cluster_provider/k3s.rb#L36).
+   We don't allow local connections on `staging` as they require an admin user.
+1. Ensure you don't have an `EE_LICENSE` env var set as this would force an admin login.
+1. Go to your GDK root folder and `cd gitlab/qa`.
+1. Login with your user in staging and create a group to be used as sandbox.
+   Something like: `username-qa-sandbox`.
+1. Create an access token for your user with the `api` permission.
+1. Replace the values given below with your own and run:
+
+   ```shell
+   GITLAB_SANDBOX_NAME="<THE GROUP ID YOU CREATED ON STEP 2>" \
+   GITLAB_QA_ACCESS_TOKEN="<THE ACCESS TOKEN YOU CREATED ON STEP 3>" \
+   GITLAB_USERNAME="<YOUR STAGING USERNAME>" \
+   GITLAB_PASSWORD="<YOUR STAGING PASSWORD>" \
+   bundle exec bin/qa Test::Instance::All https://staging.gitlab.com -- --tag quarantine qa/specs/features/ee/api/7_configure/kubernetes/kubernetes_agent_spec.rb
+   ```
+
+### Against GDK
+
+1. Go to your `qa/qa/fixtures/kubernetes_agent/agentk-manifest.yaml.erb` and comment out [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/a55b78532cfd29426cf4e5b4edda81407da9d449/qa/qa/fixtures/kubernetes_agent/agentk-manifest.yaml.erb#L27) and uncomment [this line](https://gitlab.com/gitlab-org/gitlab/-/blob/a55b78532cfd29426cf4e5b4edda81407da9d449/qa/qa/fixtures/kubernetes_agent/agentk-manifest.yaml.erb#L28).
+   GDK's `kas` listens on `grpc`, not on `wss`.
+1. Go to the GDK's root folder and `cd gitlab/qa`.
+1. On the contrary to staging, run the QA test in GDK as admin, which is the default choice. To do so, use the default sandbox group and run the command below. Make sure to adjust your credentials if necessary, otherwise, the test might fail:
+
+   ```shell
+   GITLAB_USERNAME=root \
+   GITLAB_PASSWORD="5iveL\!fe" \
+   GITLAB_ADMIN_USERNAME=root \
+   GITLAB_ADMIN_PASSWORD="5iveL\!fe" \
+   bundle exec bin/qa Test::Instance::All http://gdk.test:3000 -- --tag quarantine qa/specs/features/ee/api/7_configure/kubernetes/kubernetes_agent_spec.rb
+   ```