Add latest changes from gitlab-org/gitlab@15-2-stable-eev15.2.0-rc42

7 files changed, 107 insertions, 46 deletions

diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index c04c5a1f7ec..dce02a72300 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -42,17 +42,19 @@ If you have multiple GitLab projects that contain Kubernetes manifests:
 1. [Install the GitLab agent](install/index.md) in its own project, or in one of the
    GitLab projects where you keep Kubernetes manifests.
 1. [Authorize the agent](#authorize-the-agent) to access your GitLab projects.
-1. Optional. For added security, [use impersonation](#use-impersonation-to-restrict-project-and-group-access).
+1. Optional. For added security, [use impersonation](#restrict-project-and-group-access-by-using-impersonation).
 1. [Update your `.gitlab-ci.yml` file](#update-your-gitlab-ciyml-file-to-run-kubectl-commands) to
    select the agent's Kubernetes context and run the Kubernetes API commands.
 1. Run your pipeline to deploy to or update the cluster.
 
 ## Authorize the agent
 
-You must authorize the agent to access the project where you keep your Kubernetes manifests.
+If you have multiple GitLab projects, you must authorize the agent to access the project where you keep your Kubernetes manifests.
 You can authorize the agent to access individual projects, or authorize a group or subgroup,
 so all projects within have access. For added security, you can also
-[use impersonation](#use-impersonation-to-restrict-project-and-group-access).
+[use impersonation](#restrict-project-and-group-access-by-using-impersonation).
+
+Authorization configuration can take one or two minutes to propagate.
 
 ### Authorize the agent to access your projects
 
@@ -60,7 +62,7 @@ so all projects within have access. For added security, you can also
 
 To authorize the agent to access the GitLab project where you keep Kubernetes manifests:
 
-1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file (`config.yaml`).
+1. On the top bar, select **Menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`).
 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `projects` attribute.
 1. For the `id`, add the path:
 
@@ -83,7 +85,7 @@ Choose the context to run `kubectl` commands from your CI/CD scripts.
 
 To authorize the agent to access all of the GitLab projects in a group or subgroup:
 
-1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file (`config.yaml`).
+1. On the top bar, select **Menu > Projects** and find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`).
 1. Edit the `config.yaml` file. Under the `ci_access` keyword, add the `groups` attribute.
 1. For the `id`, add the path:
 
@@ -154,7 +156,7 @@ deploy:
   # ... rest of your job configuration
 ```
 
-## Use impersonation to restrict project and group access **(PREMIUM)**
+## Restrict project and group access by using impersonation **(PREMIUM)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5.
 
@@ -170,6 +172,8 @@ You can impersonate:
 - The CI/CD job that accesses the cluster.
 - A specific user or system account defined within the cluster.
 
+Authorization configuration can take one or two minutes to propagate.
+
 ### Impersonate the agent
 
 The agent is impersonated by default. You don't need to do anything to impersonate it.
@@ -220,6 +224,24 @@ ci_access:
         ci_job: {}
 ```
 
+#### Example RBAC to restrict CI/CD jobs
+
+The following `RoleBinding` resource restricts all CI/CD jobs to view rights only.
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: ci-job-view
+roleRef:
+  name: view
+  kind: ClusterRole
+  apiGroup: rbac.authorization.k8s.io
+subjects:
+  - name: gitlab:ci_job
+    kind: Group
+```
+
 ### Impersonate a static identity
 
 For a given connection, you can use a static identity for the impersonation.
diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md
index 64eae308bec..73a35ffbc64 100644
--- a/doc/user/clusters/agent/gitops.md
+++ b/doc/user/clusters/agent/gitops.md
@@ -57,7 +57,7 @@ Any time you commit updates to your Kubernetes manifests, the agent updates the
 
 ## GitOps configuration reference
 
-The following snippet shows an example of the possible keys and values for the GitOps section of an agent configuration file.
+The following snippet shows an example of the possible keys and values for the GitOps section of an [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`).
 
 ```yaml
 gitops:
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index 5a69da28632..0d2b68e154d 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -43,21 +43,17 @@ This workflow is considered push-based, because GitLab is pushing requests from
 GitLab supports the following Kubernetes versions. You can upgrade your
 Kubernetes version to a supported version at any time:
 
-- 1.22 (support ends on March 22, 2023)
-- 1.21 (support ends on November 22, 2022)
-- 1.20 (support ends on July 22, 2022)
+- 1.24 (support ends on September 22, 2023 or when 1.27 becomes supported)
+- 1.23 (support ends on February 22, 2023 or when 1.26 becomes supported)
+- 1.22 (support ends on October 22, 2022)
+- 1.21 (support ends on August 22, 2022)
 
-GitLab supports at least two production-ready Kubernetes minor
-versions at any given time. GitLab regularly reviews the supported versions and
-provides a three-month deprecation period before removing support for a specific
-version. The list of supported versions is based on:
+GitLab aims to support a new minor Kubernetes version three months after its initial release. GitLab supports at least three production-ready Kubernetes minor
+versions at any given time.
 
-- The versions supported by major managed Kubernetes providers.
-- The versions [supported by the Kubernetes community](https://kubernetes.io/releases/version-skew-policy/#supported-versions).
+Support for deprecated APIs can be removed from the GitLab codebase when we drop support for the Kubernetes version that only supports the deprecated API.
 
-[This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for other Kubernetes versions.
-
-Some GitLab features might work on versions not listed here.
+Some GitLab features might work on versions not listed here. [This epic](https://gitlab.com/groups/gitlab-org/-/epics/4827) tracks support for Kubernetes versions.
 
 ## Migrate to the agent from the legacy certificate-based integration
 
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index 6c839f5ffc6..9282ac7fb40 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -89,8 +89,12 @@ You must register an agent before you can install the agent in your cluster. To
    - If you want to create a configuration with CI/CD defaults, type a name.
    - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list.
 1. Select **Register an agent**.
-1. GitLab generates an access token for the agent. Securely store this token. You need it to install the agent
+1. GitLab generates an access token for the agent. You need this token to install the agent
    in your cluster and to [update the agent](#update-the-agent-version) to another version.
+
+   WARNING:
+   Securely store the agent access token. A bad actor can use this token to access source code in the agent's configuration project, access source code in any public project on the GitLab instance, or even, under very specific conditions, obtain a Kubernetes manifest.
+
 1. Copy the command under **Recommended installation method**. You need it when you use
    the one-liner installation method to install the agent in your cluster.
 
@@ -154,8 +158,9 @@ GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org
 
 To configure your agent, add content to the `config.yaml` file:
 
-- [View the configuration reference](../gitops.md#gitops-configuration-reference) for a GitOps workflow.
-- [View the configuration reference](../ci_cd_workflow.md) for a GitLab CI/CD workflow.
+- For a GitOps workflow, [view the configuration reference](../gitops.md#gitops-configuration-reference).
+- For a GitLab CI/CD workflow, [authorize the agent to access your projects](../ci_cd_workflow.md#authorize-the-agent). Then
+  [add `kubectl` commands to your `.gitlab-ci.yml` file](../ci_cd_workflow.md#update-your-gitlab-ciyml-file-to-run-kubectl-commands).
 
 ## Install multiple agents in your cluster
 
diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md
index 0932e9179f9..0596755ec74 100644
--- a/doc/user/clusters/agent/troubleshooting.md
+++ b/doc/user/clusters/agent/troubleshooting.md
@@ -186,3 +186,25 @@ Alternatively, you can mount the certificate file at a different location and sp
 
 This error occurs when the project where you keep your manifests is not public. To fix it, make sure your project is public or your manifest files
 are stored in the repository where the agent is configured.
+
+## Failed to perform vulnerability scan on workload: jobs.batch already exists
+
+```json
+{
+  "level": "error",
+  "time": "2022-06-22T21:03:04.769Z",
+  "msg": "Failed to perform vulnerability scan on workload",
+  "mod_name": "starboard_vulnerability",
+  "error": "running scan job: creating job: jobs.batch \"scan-vulnerabilityreport-b8d497769\" already exists"
+}
+```
+
+The GitLab agent performs vulnerability scans by creating a job to scan each workload. If a scan
+is interrupted, these jobs may be left behind and will need to be cleaned up before more jobs can
+be run. You can clean up these jobs by running:
+
+```shell
+kubectl delete jobs -l app.kubernetes.io/managed-by=starboard -n gitlab-agent
+```
+
+[We're working on making the cleanup of these jobs more robust.](https://gitlab.com/gitlab-org/gitlab/-/issues/362016)
diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md
index 706ed122f7b..3b80a7a0f81 100644
--- a/doc/user/clusters/agent/vulnerabilities.md
+++ b/doc/user/clusters/agent/vulnerabilities.md
@@ -11,26 +11,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 To view cluster vulnerabilities, you can view the [vulnerability report](../../application_security/vulnerabilities/index.md).
 You can also configure your agent so the vulnerabilities are displayed with other agent information in GitLab.
 
-## View cluster vulnerabilities
-
-Prerequisite:
-
-- You must have at least the Developer role.
-
-To view vulnerability information in GitLab:
-
-1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file.
-1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
-1. Select the **Agent** tab.
-1. Select the agent you want to see the vulnerabilities for.
-
-![Cluster agent security tab UI](../img/cluster_agent_security_tab_v14_8.png)
-
-This information can also be found under [operational vulnerabilities](../../../user/application_security/vulnerability_report/index.md#operational-vulnerabilities).
-
-## Enable cluster vulnerability scanning **(ULTIMATE)**
+## Enable operational container scanning **(ULTIMATE)**
 
-You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md)
+You can use operational container scanning
 to scan container images in your cluster for security vulnerabilities.
 
 To begin scanning all resources in your cluster, add a `starboard`
@@ -49,7 +32,7 @@ The `cadence` field is required. GitLab supports the following types of CRON syn
 
 It is possible that other elements of the CRON syntax will work in the cadence field, however, GitLab does not officially test or support them.
 
-By default, cluster image scanning will attempt to scan the workloads in all
+By default, operational container scanning will attempt to scan the workloads in all
 namespaces for vulnerabilities. The `vulnerability_report` block has a `namespaces`
 field which can be used to restrict which namespaces are scanned. For example,
 if you would like to scan only the `development`, `staging`, and `production`
@@ -64,3 +47,20 @@ starboard:
       - staging
       - production
 ```
+
+## View cluster vulnerabilities
+
+Prerequisite:
+
+- You must have at least the Developer role.
+
+To view vulnerability information in GitLab:
+
+1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file.
+1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
+1. Select the **Agent** tab.
+1. Select an agent to view the cluster vulnerabilities.
+
+![Cluster agent security tab UI](../img/cluster_agent_security_tab_v14_8.png)
+
+This information can also be found under [operational vulnerabilities](../../../user/application_security/vulnerability_report/index.md#operational-vulnerabilities).
diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md
index 8872ecf7ce5..058243ec218 100644
--- a/doc/user/clusters/agent/work_with_agent.md
+++ b/doc/user/clusters/agent/work_with_agent.md
@@ -53,24 +53,40 @@ View and provide feedback about the UI in [this epic](https://gitlab.com/groups/
 
 ## Debug the agent
 
+> The `grpc_level` was [introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/669) in GitLab 15.1.
+
 To debug the cluster-side component (`agentk`) of the agent, set the log
 level according to the available options:
 
-- `off`
-- `warning`
 - `error`
+- `warning`
 - `info`
 - `debug`
 
-The log level defaults to `info`. You can change it by using a top-level `observability`
-section in the configuration file, for example:
+The agent has two loggers:
+
+- A general purpose logger, which defaults to `info`.
+- A gRPC logger, which defaults to `error`.
+
+One can change their log levels by using a top-level `observability` section in the [agent configuration file](install/index.md#configure-your-agent), for example setting the levels to `debug` and `warning`:
 
 ```yaml
 observability:
   logging:
     level: debug
+    grpc_level: warning
 ```
 
+When `grpc_level` is set to `info` or below, there will be a lot of gRPC logs.
+
+Commit the configuration changes and inspect the agent service logs:
+
+```shell
+kubectl logs -f -l=app=gitlab-agent -n gitlab-agent
+```
+
+For more information about debugging, see [troubleshooting documentation](troubleshooting.md).
+
 ## Reset the agent token
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327152) in GitLab 14.9.