Add latest changes from gitlab-org/gitlab@15-4-stable-eev15.4.0-rc42

11 files changed, 173 insertions, 33 deletions

diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index 16b92eb92a3..7a6c6dc8cd6 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -62,7 +62,7 @@ Authorization configuration can take one or two minutes to propagate.
 
 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](install/index.md#create-an-agent-configuration-file) (`config.yaml`).
+1. On the top bar, select **Main 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:
 
@@ -85,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](install/index.md#create-an-agent-configuration-file) (`config.yaml`).
+1. On the top bar, select **Main 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:
 
@@ -127,7 +127,7 @@ Run `kubectl config get-contexts`.
 
 ### Environments with both certificate-based and agent-based connections
 
-When you deploy to an environment that has both a 
+When you deploy to an environment that has both a
 [certificate-based cluster](../../infrastructure/clusters/index.md) (deprecated) and an agent connection:
 
 - The certificate-based cluster's context is called `gitlab-deploy`. This context
diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md
index 4978b56917b..67439788ef7 100644
--- a/doc/user/clusters/agent/gitops.md
+++ b/doc/user/clusters/agent/gitops.md
@@ -49,7 +49,7 @@ For details, view the [architecture documentation](https://gitlab.com/gitlab-org
 
 To update a Kubernetes cluster by using GitOps, complete the following steps.
 
-1. Ensure you have a working Kubernetes cluster, and that the manifests are in a GitLab project.
+1. Ensure you have a working Kubernetes cluster, and that the manifests or [Helm charts](gitops/helm.md) are in a GitLab project.
 1. In the same project, [register and install the GitLab agent](install/index.md).
 1. Configure the agent configuration file so that the agent monitors the project for changes to the Kubernetes manifests.
    Use the [GitOps configuration reference](#gitops-configuration-reference) for guidance.
@@ -112,12 +112,12 @@ a Kubernetes SIG project. You can read more about the available annotations in t
 
 ## Automatic drift remediation
 
-Drift happens when the current configuration of an infrastructure resource differs from its expected configuration.
-Typically, this is caused by manually editing resources directly through the service that created the resource. Minimizing the
-risk of drift helps to ensure configuration consistency and successful operations.
+Drift happens when the current configuration of an infrastructure resource differs from its desired configuration.
+Typically, this is caused by manually editing resources directly rather than via the used infrastructure-as-code
+mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations.
 
-In GitLab, the agent for Kubernetes regularly compares the expected state from the `git` repository with
-the known state from the `cluster`. Deviations from the `git` state are fixed at every check. These checks
+In GitLab, the agent for Kubernetes regularly compares the desired state from the `git` repository with
+the actual state from the Kubernetes cluster. Deviations from the `git` state are fixed at every check. These checks
 happen automatically every 5 minutes. They are not configurable.
 
 The agent uses [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/).
@@ -127,6 +127,7 @@ are checked for drift. This facilitates the use of in-cluster controllers to mod
 
 ## Related topics
 
+- [Deploying Helm charts with the GitOps workflow](gitops/helm.md)
 - [GitOps working examples for training and demos](https://gitlab.com/groups/guided-explorations/gl-k8s-agent/gitops/-/wikis/home)
 - [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters)
 - [Managing Kubernetes secrets in a GitOps workflow](gitops/secrets_management.md)
diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md
new file mode 100644
index 00000000000..bdc2664e7ba
--- /dev/null
+++ b/doc/user/clusters/agent/gitops/helm.md
@@ -0,0 +1,112 @@
+---
+stage: Configure
+group: Configure
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4.
+
+You can deploy Helm charts to your Kubernetes cluster and keep the resources in your cluster in sync
+with your charts and values. To do this, you use the pull-based GitOps features of the agent for
+Kubernetes.
+
+This feature is in Alpha and [an epic exists](https://gitlab.com/groups/gitlab-org/-/epics/7938)
+to track future work. Please tell us about your use cases by leaving comments in the epic.
+
+NOTE:
+This feature is Alpha. In future releases, to accommodate new features, the configuration format might change without notice.
+
+## GitOps workflow steps
+
+To update a Kubernetes cluster by using GitOps with charts, complete the following steps.
+
+1. Ensure you have a working Kubernetes cluster, and that the chart is in a GitLab project.
+1. In the same project, [register and install the GitLab agent](../install/index.md).
+1. Configure the agent configuration file so that the agent monitors the project for changes to the chart.
+   Use the [GitOps configuration reference](#helm-configuration-reference) for guidance.
+
+## Helm chart with GitOps workflow
+
+To update a Kubernetes cluster by using Helm charts:
+
+1. Ensure you have a working Kubernetes cluster.
+1. In a GitLab project:
+   - Store your Helm charts.
+   - [Register and install the GitLab agent](../install/index.md).
+1. Update the agent configuration file so that the agent monitors the project for changes to the chart.
+   Use the [configuration reference](#helm-configuration-reference) for guidance.
+
+Any time you commit updates to your chart repository, the agent applies the chart in the cluster.
+
+## Helm configuration reference
+
+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:
+  charts:
+  - release_name: my-application-release
+    source:
+      project:
+        id: my-group/my-project-with-chart
+        path: dir-in-project/with/charts
+    namespace: my-ns
+    max_history: 1
+```
+
+| Keyword | Description |
+|--|--|
+| `charts` | List of charts you want to be applied in your cluster. Charts are applied concurrently. All charts must be in the same directory. |
+| `release_name` | Required. Name of the release to use when applying the chart. |
+| `id` | Required. ID of the project where Helm chart is committed. No authentication mechanisms are currently supported. |
+| `path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. This is the directory with the `Chart.yaml` file. |
+| `namespace` | Optional. Namespace to use when applying the chart. Defaults to `default`. |
+| `max_history` | Optional. Maximum number of release [revisions to store in the cluster](https://helm.sh/docs/helm/helm_history/). |
+
+## Automatic drift remediation
+
+Drift happens when the current configuration of an infrastructure resource differs from its desired configuration.
+Typically, drift is caused by manually editing resources directly, rather than by editing the code that describes the desired state. Minimizing the risk of drift helps to ensure configuration consistency and successful operations.
+mechanism. Minimizing the risk of drift helps to ensure configuration consistency and successful operations.
+
+In GitLab, the agent for Kubernetes regularly compares the desired state from the chart source with
+the actual state from the Kubernetes cluster. Deviations from the desired state are fixed at every check. These checks
+happen automatically every 5 minutes. They are not configurable.
+
+## Example repository layout
+
+```plaintext
+/my-chart
+ ├── templates
+ |   └── ...
+ ├── charts
+ |   └── ...
+ ├── Chart.yaml
+ ├── Chart.lock
+ ├── values.yaml
+ ├── values.schema.json
+ └── some-file-used-in-chart.txt
+```
+
+## Known issues
+
+The following are known issues:
+
+- Your chart must be in a GitLab project. The project must be an agent configuration project or a public
+  project. This known issue also exists for manifest-based GitOps and is tracked in
+  [this epic](https://gitlab.com/groups/gitlab-org/-/epics/7704).
+- Values for the chart must be in a `values.yaml` file. This file must be with the chart,
+  in the same project and path.
+- Because of drift detection and remediation, release history, stored in the cluster, is not useful.
+  A new release is created every five minutes and the oldest release is discarded.
+  Eventually history consists only of the same information.
+  View [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/372023) for details.
+
+## Troubleshooting
+
+### Agent cannot find values for the chart
+
+Make sure values are in `values.yaml` and in the same directory as the `Chart.yaml` file.
+The filename must be lowercase, with `.yaml` extension (not `.yml`).
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index 0d2b68e154d..eb62a733d36 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -29,14 +29,40 @@ For more details about the agent's purpose and architecture, see the [architectu
 
 ## Workflows
 
-You can choose from two primary workflows.
+You can choose from two primary workflows. The GitOps workflow is recommended.
 
-In a [**GitOps** workflow](gitops.md), you keep your Kubernetes manifests in GitLab. You install a GitLab agent in your cluster, and
-any time you update your manifests, the agent updates the cluster. This workflow is fully driven with Git and is considered pull-based,
+### GitOps workflow
+
+In a [**GitOps** workflow](gitops.md):
+
+- You keep your Kubernetes manifests in GitLab.
+- You install a GitLab agent in your cluster.
+- Any time you update your manifests, the agent updates the cluster.
+- The cluster automatically cleans up unexpected changes. It uses
+  [server-side applies](https://kubernetes.io/docs/reference/using-api/server-side-apply/)
+  to fix any configuration inconsistencies that third parties introduce.
+
+This workflow is fully driven with Git and is considered **pull-based**,
 because the cluster is pulling updates from your GitLab repository.
 
-In a [**CI/CD** workflow](ci_cd_workflow.md), you use GitLab CI/CD to query and update your cluster by using the Kubernetes API.
-This workflow is considered push-based, because GitLab is pushing requests from GitLab CI/CD to your cluster.
+GitLab recommends this workflow. We are actively investing in this workflow
+so we can provide a first-class experience.
+
+### GitLab CI/CD workflow
+
+In a [**CI/CD** workflow](ci_cd_workflow.md):
+
+- You configure GitLab CI/CD to use the Kubernetes API to query and update your cluster.
+
+This workflow is considered **push-based**, because GitLab is pushing requests
+from GitLab CI/CD to your cluster.
+
+Use this workflow:
+
+- When you have a heavily pipeline-oriented processes.
+- When you need to migrate to the agent but the GitOps workflow cannot support the use case you need.
+
+This workflow has a weaker security model and is not recommended for production deployments.
 
 ## Supported cluster versions
 
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index 4b0d8b77493..0240fbb45f0 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -40,7 +40,7 @@ To install the agent in your cluster:
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository.
 > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
 
-The agent uses a YAML file for configuration settings. You must create this file if:
+For configuration settings, the agent uses a YAML file in the GitLab project. You must create this file if:
 
 - You use [a GitOps workflow](../gitops.md#gitops-workflow-steps).
 - You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#gitlab-cicd-workflow-steps) and want to authorize a different project to use the agent.
@@ -56,7 +56,7 @@ To create an agent configuration file:
    - Start with an alphanumeric character.
    - End with an alphanumeric character.
 
-1. In the repository, create a directory in this location:
+1. In the repository, in the default branch, create this directory at the root:
 
    ```plaintext
    .gitlab/agents/<agent-name>
@@ -81,7 +81,7 @@ Prerequisites:
 
 You must register an agent before you can install the agent in your cluster. To register an agent:
 
-1. On the top bar, select **Menu > Projects** and find your project.
+1. On the top bar, select **Main menu > Projects** and find your project.
    If you have an [agent configuration file](#create-an-agent-configuration-file),
    it must be in this project. Your cluster manifest files should also be in this project.
 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**.
diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md
index 5afe3ccec2b..2d20675b68b 100644
--- a/doc/user/clusters/agent/vulnerabilities.md
+++ b/doc/user/clusters/agent/vulnerabilities.md
@@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Operational Container Scanning **(ULTIMATE)**
 
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8.
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8.
+> - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/368828) the starboard directive in GitLab 15.4. The starboard directive will be removed in GitLab 16.0.
 
 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.
@@ -19,12 +20,12 @@ to scan container images in your cluster for security vulnerabilities.
 NOTE:
 In GitLab 15.0 and later, you do not need to install Starboard operator in the Kubernetes cluster.
 
-To begin scanning all resources in your cluster, add a `starboard`
+To begin scanning all resources in your cluster, add a `container_scanning`
 configuration block to your agent configuration with a `cadence` field
 containing a CRON expression for when the scans will be run.
 
 ```yaml
-starboard:
+container_scanning:
   cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time)
 ```
 
@@ -42,7 +43,7 @@ if you would like to scan only the `development`, `staging`, and `production`
 namespaces, you can use this configuration:
 
 ```yaml
-starboard:
+container_scanning:
   cadence: '0 0 * * *'
   vulnerability_report:
     namespaces:
@@ -59,7 +60,7 @@ Prerequisite:
 
 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 top bar, select **Main 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.
diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md
index 058243ec218..b28f7546379 100644
--- a/doc/user/clusters/agent/work_with_agent.md
+++ b/doc/user/clusters/agent/work_with_agent.md
@@ -18,7 +18,7 @@ Prerequisite:
 
 To view the list of agents:
 
-1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file.
+1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file.
 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
 1. Select **Agent** tab to view clusters connected to GitLab through the agent.
 
@@ -37,7 +37,7 @@ The activity logs help you to identify problems and get the information
 you need for troubleshooting. You can see events from a week before the
 current date. To view an agent's activity:
 
-1. On the top bar, select **Menu > Projects** and find the project that contains your agent configuration file.
+1. On the top bar, select **Main menu > Projects** and find the project that contains your agent configuration file.
 1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
 1. Select the agent you want to see activity for.
 
@@ -59,7 +59,6 @@ To debug the cluster-side component (`agentk`) of the agent, set the log
 level according to the available options:
 
 - `error`
-- `warning`
 - `info`
 - `debug`
 
@@ -95,7 +94,7 @@ For more information about debugging, see [troubleshooting documentation](troubl
 To reset the agent token without downtime:
 
 1. Create a new token:
-   1. On the top bar, select **Menu > Projects** and find your project.
+   1. On the top bar, select **Main menu > Projects** and find your project.
    1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
    1. Select the agent you want to create a token for.
    1. On the **Access tokens** tab, select **Create token**.
@@ -117,7 +116,7 @@ clean up those resources manually.
 
 To remove an agent from the UI:
 
-1. On the top bar, select **Menu > Projects** and find the project that contains the agent configuration file.
+1. On the top bar, select **Main menu > Projects** and find the project that contains the agent configuration file.
 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**.
 1. In the table, in the row for your agent, in the **Options** column, select the vertical ellipsis (**{ellipsis_v}**).
 1. Select **Delete agent**.
diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md
index cf71729b517..96f41531576 100644
--- a/doc/user/clusters/environments.md
+++ b/doc/user/clusters/environments.md
@@ -33,7 +33,7 @@ With cluster environments, you can gain insight into:
 
 ![Cluster environments page](img/cluster_environments_table_v12_3.png)
 
-Access to cluster environments is restricted to 
+Access to cluster environments is restricted to
 [group maintainers and owners](../permissions.md#group-members-permissions)
 
 ## Usage
diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md
index 361276194b0..62f70faa630 100644
--- a/doc/user/clusters/management_project.md
+++ b/doc/user/clusters/management_project.md
@@ -61,7 +61,7 @@ To associate a cluster management project with your cluster:
      **Infrastructure > Kubernetes clusters** page.
    - [Group-level cluster](../group/clusters/index.md), go to your group's **Kubernetes**
      page.
-   - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Menu > Admin > Kubernetes**.
+   - [Instance-level cluster](../instance/clusters/index.md), on the top bar, select **Main menu > Admin > Kubernetes**.
 1. Expand **Advanced settings**.
 1. From the **Cluster management project** dropdown, select the cluster management project
 you created in the previous step.
diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md
index 4b00784a7ae..cd71be321cc 100644
--- a/doc/user/clusters/management_project_template.md
+++ b/doc/user/clusters/management_project_template.md
@@ -45,7 +45,8 @@ If you have already configured the agent and connected a cluster with GitLab:
 
 To create a project from the cluster management project template:
 
-1. On the top bar, select **Menu > Projects > Create new project**.
+1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**.
+1. On the right of the page, select **New project**.
 1. Select **Create from template**.
 1. From the list of templates, next to **GitLab Cluster Management**, select **Use template**.
 1. Enter the project details.
@@ -80,7 +81,7 @@ If you remove everything below this comment, the pipeline will succeed.
 
 ### The main `helmfile.yml` file
 
-The template contains a [Helmfile](https://github.com/roboll/helmfile) you can use to manage
+The template contains a [Helmfile](https://github.com/helmfile/helmfile) you can use to manage
 cluster applications with [Helm v3](https://helm.sh/).
 
 This file has a list of paths to other Helm files for each app. They're all commented out by default, so you must uncomment
@@ -89,7 +90,7 @@ the paths for the apps that you would like to use in your cluster.
 By default, each `helmfile.yaml` in these sub-paths has the attribute `installed: true`. This means that every time
 the pipeline runs, Helmfile tries to either install or update your apps according to the current state of your
 cluster and Helm releases. If you change this attribute to `installed: false`, Helmfile tries try to uninstall this app
-from your cluster. [Read more](https://github.com/roboll/helmfile) about how Helmfile works.
+from your cluster. [Read more](https://helmfile.readthedocs.io/en/latest/) about how Helmfile works.
 
 ### Built-in applications
 
diff --git a/doc/user/clusters/migrating_from_gma_to_project_template.md b/doc/user/clusters/migrating_from_gma_to_project_template.md
index 9a59d135fa0..ce39e13d928 100644
--- a/doc/user/clusters/migrating_from_gma_to_project_template.md
+++ b/doc/user/clusters/migrating_from_gma_to_project_template.md
@@ -4,7 +4,7 @@ group: Configure
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Migrate from GitLab Managed Apps to Cluster Management Projects **(FREE)**
+# Migrate from GitLab Managed Apps to Cluster Management Projects (DEPRECATED) **(FREE)**
 
 The GitLab Managed Apps were deprecated in GitLab 14.0
 in favor of user-controlled Cluster Management projects.