Add latest changes from gitlab-org/gitlab@16-3-stable-eev16.3.0-rc42

18 files changed, 419 insertions, 98 deletions

diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md
index a0b42101dd5..260263632c5 100644
--- a/doc/user/clusters/agent/ci_cd_workflow.md
+++ b/doc/user/clusters/agent/ci_cd_workflow.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Using GitLab CI/CD with a Kubernetes cluster **(FREE)**
+# Using GitLab CI/CD with a Kubernetes cluster **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327409) in GitLab 14.1.
 > - The pre-configured variable `$KUBECONFIG` [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/324275) in GitLab 14.2.
@@ -196,7 +196,7 @@ To configure your client, do one of the following:
 - Place the certificates in an appropriate location in the job container by updating the container image or mounting via the runner.
 - Not recommended. Configure the Kubernetes client with `--insecure-skip-tls-verify=true`.
 
-## Restrict project and group access by using impersonation **(PREMIUM)**
+## Restrict project and group access by using impersonation **(PREMIUM ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5.
 > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/357934) in GitLab 15.5 to add impersonation support for environment tiers.
@@ -300,7 +300,7 @@ The identity can be specified with the following keys:
 
 See the [official Kubernetes documentation for details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation).
 
-## Restrict project and group access to specific environments **(FREE)**
+## Restrict project and group access to specific environments **(FREE ALL)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7.
 
diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md
index aff78ed477b..d79d32a1234 100644
--- a/doc/user/clusters/agent/gitops.md
+++ b/doc/user/clusters/agent/gitops.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Using GitOps with a Kubernetes cluster **(FREE)**
+# Using GitOps with a Kubernetes cluster **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
@@ -78,6 +78,7 @@ For additional repository structure recommendations, see the [Flux documentation
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/392852) in GitLab 16.1 with a [flag](../../../administration/feature_flags.md) named `notify_kas_on_git_push`. Disabled by default.
 > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/126527) in GitLab 16.2.
+> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/410429) in GitLab 16.3.
 
 Usually, the Flux source controller reconciles Git repositories at configured intervals.
 This can cause delays between a `git push` and the reconciliation of the cluster state, and results in
diff --git a/doc/user/clusters/agent/gitops/agent.md b/doc/user/clusters/agent/gitops/agent.md
index 07ed2b3a691..a4e83916acb 100644
--- a/doc/user/clusters/agent/gitops/agent.md
+++ b/doc/user/clusters/agent/gitops/agent.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Using GitOps with the agent for Kubernetes (deprecated) **(FREE)**
+# Using GitOps with the agent for Kubernetes (deprecated) **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
diff --git a/doc/user/clusters/agent/gitops/example_repository_structure.md b/doc/user/clusters/agent/gitops/example_repository_structure.md
index a5bc3b153fe..02eea3300af 100644
--- a/doc/user/clusters/agent/gitops/example_repository_structure.md
+++ b/doc/user/clusters/agent/gitops/example_repository_structure.md
@@ -1,78 +1,179 @@
 ---
 stage: Deploy
 group: Environments
-info: An example of how to structure a repository for GitOps deployments
+info: A tutorial for deploying a GitLab repository using Flux
 ---
 
-# Example GitOps repository structure **(FREE)**
+# Tutorial: Deploy a Git repository using Flux **(FREE ALL)**
 
-This page describes an example structure for a project that builds and deploys an application
-to a Kubernetes cluster with [GitOps](https://about.gitlab.com/topics/gitops) and the
-[GitLab agent for Kubernetes](../../agent/gitops.md).
+In this tutorial, you'll create a GitLab project that builds and deploys an application
+to a Kubernetes cluster using Flux. You'll set up a sample manifest project, configure it to
+push manifests to a deployment branch, and configure Flux to sync the deployment branch. With this
+setup, you can run additional steps in GitLab pipelines before Flux picks up the changes
+from the repository.
+
+This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md).
+
+To set up a repository for GitOps deployments:
+
+1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository)
+1. [Create a deployment branch](#create-a-deployment-branch)
+1. [Configure GitLab CI/CD to push to your branch](#configure-gitlab-cicd-to-push-to-your-branch)
+1. [Configure Flux to sync your manifests](#configure-flux-to-sync-your-manifests)
+1. [Verify your configuration](#verify-your-configuration)
+
+Prerequisites:
+
+- You have a Flux repository connected to a Kubernetes cluster.
+  If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md).
 
-You can find an example project that uses this structure
-[in this GitLab repository](https://gitlab.com/tigerwnz/minimal-gitops-app). You can use the example project
-as a starting point to create your own deployment project.
+## Create the Kubernetes manifest repository
 
-## Deployment workflow
+First, create a repository for your Kubernetes manifests:
 
-The default branch is the single source of truth for your application and the
-Kubernetes manifests that deploy it. To be reflected in a Kubernetes cluster,
-a code or configuration change must exist in the default branch.
+1. In GitLab, create a new repository called `web-app-manifests`.
+1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents:
 
-A GitLab agent for Kubernetes is installed in every Kubernetes cluster. The agent
-is configured to sync manifests from a corresponding branch in the repository.
-These branches represent the state of each cluster, and contain only commits that
-exist in the default branch.
-
-Changes are deployed by merging the default branch into the branch of a cluster.
-The agent that watches the branch picks up the change and syncs it to the cluster.
-
-For the actual deployment, the example project uses the GitLab agent for Kubernetes,
-but you can also use other GitOps tools.
-
-### Review apps
-
-Ephemeral environments such as [review apps](../../../../ci/review_apps/index.md)
-are deployed differently. Their configuration does not exist on the default branch,
-and the changes are not meant to be deployed to a permanent environment. Review app
-manifests are generated and deployed in a merge request feature branch, which is removed
-when the MR is merged.
-
-## Example deployment
-
-The example project deploys to two permanent environments, staging and production,
-which each have a dedicated Kubernetes cluster. A third cluster is used for ephemeral
-review apps.
-
-Each cluster has a corresponding branch that represents the current state of the cluster:
-`_gitlab/agents/staging`, `_gitlab/agents/production` and `_gitlab/agents/review`. Each branch is
-[protected](../../../../user/project/protected_branches.md) and
-a [project access token](../../../../user/project/settings/project_access_tokens.md)
-is created for each branch with a configuration that allows only the corresponding token to push to the branch.
-This ensures that environment branches are updated only through the configured process.
-
-Deployment branches are updated by CI/CD jobs. The access token that allows pushing to each
-branch is configured as a [CI/CD variable](../../../../ci/variables/index.md). These variables
-are protected, and only available to pipelines running on a protected branch.
-The CI/CD job merges the default branch `main` into the deployment branch, and pushes
-the deployment branch back to the repository using the provided token. To preserve the
-commit history between both branches, the CI/CD job uses a fast-forward merge.
-
-Each cluster has an agent for Kubernetes, and each agent is configured to
-sync manifests from the branch corresponding to its cluster.
-In your own project, you can different GitOps tool like Flux, or use the same configuration to deploy
-to virtual machines with GitLab CI/CD.
-
-### Application changes
-
-The example project follows this process to deploy an application change:
-
-1. A new feature branch is created with the desired changes. The pipeline builds an image,
-   runs the test suite, and deploy the changes to a review app in the `review` cluster.
-1. The feature branch is merged to `main` and the review app is removed.
-1. Manifests are updated on `main` (either directly or via merge request) to point to an updated
-   version of the deployed image. The pipeline automatically merges `main` into the `_gitlab/agents/staging`
-   branch, which updates the `staging` cluster.
-1. The `production` job is triggered manually, and merges `main` into the `_gitlab/agents/production` branch,
-   deploying to the `production` cluster.
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: nginx
+   spec:
+     replicas: 1
+     template:
+       spec:
+         containers:
+         - name: nginx
+           image: nginx:1.14.2
+           ports:
+           - containerPort: 80
+   ```
+
+1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents:
+
+   ```yaml
+   apiVersion: kustomize.config.k8s.io/v1beta1
+   kind: Kustomization
+   resources:
+     - nginx-deployment.yaml
+   commonLabels:
+     app: flux-branches-tutorial
+   ```
+
+## Create a deployment branch
+
+Next, create a branch to reflect the current state of your cluster.
+
+In this workflow, the default branch is the single source of truth for your application.
+To be reflected in a Kubernetes cluster, a code or configuration change must exist in the default branch.
+In a later step, you'll configure CI/CD to merge changes from the default branch into the deployment branch.
+
+To create a deployment branch:
+
+1. In `web-app-manifests`, create a branch named `_gitlab/deploy/example` from the default branch. The branch name in this example is chosen to
+   differentiate the deployment branch from feature branches, but this is not required. You can name the deployment branch whatever you like.
+1. Create a [project](../../../../user/project/settings/project_access_tokens.md),
+   [group](../../../../user/group/settings/group_access_tokens.md) or
+   [personal access token](../../../../user/profile/personal_access_tokens.md) with the `write_repository` scope.
+1. Create a [CI/CD variable](../../../../ci/variables/index.md) with a token value named `DEPLOYMENT_TOKEN`.
+   Remember to [mask](../../../../ci/variables/index.md#mask-a-cicd-variable) the value so that it won't show in
+   job logs.
+1. Add a rule to [protect](../../../../user/project/protected_branches.md)
+   your deployment branch with the following values:
+
+   - Allowed to merge: No one.
+   - Allowed to push and merge: Select the token you created in the previous step, or your user if you created
+     a personal access token.
+   - Allowed to force push: Turn off the toggle.
+   - Require approval from code owners: Turn off the toggle.
+
+This configuration ensures that only the corresponding token can push to the branch.
+
+You've successfully created a repository with a protected deployment branch!
+
+## Configure GitLab CI/CD to push to your branch
+
+Next, you'll configure CI/CD to merge changes from the default branch to your deployment branch.
+
+In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents:
+
+   ```yaml
+   deploy:
+     stage: deploy
+     environment: production
+     variables:
+       DEPLOYMENT_BRANCH: _gitlab/deploy/example
+     script:
+       - |
+         git config user.name "Deploy Example Bot"
+         git config user.email "test@example.com"
+         git fetch origin $DEPLOYMENT_BRANCH
+         git checkout $DEPLOYMENT_BRANCH
+         git merge $CI_COMMIT_SHA --ff-only
+         git push https://deploy:$DEPLOYMENT_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git HEAD:$DEPLOYMENT_BRANCH
+     resource_group: $CI_ENVIRONMENT_SLUG
+   ```
+
+This creates a CI/CD pipeline with a single `deploy` job that:
+
+1. Checks out your deployment branch.
+1. Merges new changes from the default branch into the deployment branch.
+1. Pushes the changes to your repository with the configured token.
+
+## Configure Flux to sync your manifests
+
+Next, configure your Flux repository to sync the deployment branch in by the `web-app-manifests` repository.
+
+To configure, create a [`GitRepository`](https://fluxcd.io/flux/components/source/gitrepositories/) resource:
+
+1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml`
+   with the following contents:
+
+   ```yaml
+   apiVersion: source.toolkit.fluxcd.io/v1
+   kind: GitRepository
+   metadata:
+     name: web-app-manifests
+     namespace: flux-system
+   spec:
+     interval: 5m0s
+     url: https://gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-branches
+     ref:
+       branch: _gitlab/deploy/example
+   ```
+
+   You will need to substitute the `url` with the URL of your `web-app-manifests` project.
+
+1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml`
+   with the following contents:
+
+   ```yaml
+   apiVersion: kustomize.toolkit.fluxcd.io/v1
+   kind: Kustomization
+   metadata:
+     name: nginx-source-kustomization
+     namespace: flux-system
+   spec:
+     interval: 1m0s
+     path: ./src
+     prune: true
+     sourceRef:
+       kind: GitRepository
+       name: web-app-manifests
+     targetNamespace: default
+   ```
+
+   This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry.
+
+1. Commit the new files and push.
+
+## Verify your configuration
+
+After the pipeline completes, you should see a newly created `nginx` pod in your cluster.
+
+If you want to see the deployment sync again, try updating the number of replicas in the
+`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change
+will sync to the cluster when the pipeline has finished.
+
+Congratulations! You successfully configured a project to deploy an application and synchronize your changes!
diff --git a/doc/user/clusters/agent/gitops/flux_oci_tutorial.md b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
new file mode 100644
index 00000000000..b970c818a72
--- /dev/null
+++ b/doc/user/clusters/agent/gitops/flux_oci_tutorial.md
@@ -0,0 +1,154 @@
+---
+stage: Deploy
+group: Environments
+info: A tutorial for deploying an OCI artifact using Flux
+---
+
+# Tutorial: Deploy an OCI artifact using Flux **(FREE ALL)**
+
+This tutorial teaches you how to package your Kubernetes manifests into an [OCI](https://opencontainers.org/)
+artifact and deploy them to your cluster using Flux. You'll set up a sample manifest project, configure it to
+store manifests as an artifact in the project's Container Registry, and configure Flux to sync the artifact. With this
+setup, you can run additional steps in GitLab pipelines before Flux picks up the changes
+from the OCI image.
+
+This tutorial deploys an application from a public project. If you want to add a non-public project, you should create a [project deploy token](../../../project/deploy_tokens/index.md).
+
+To deploy an OCI artifact using Flux:
+
+1. [Create the Kubernetes manifest repository](#create-the-kubernetes-manifest-repository)
+1. [Configure the manifest repository to create an OCI artifact](#configure-the-manifest-repository-to-create-an-oci-artifact)
+1. [Configure Flux to sync your artifact](#configure-flux-to-sync-your-artifact)
+1. [Verify your configuration](#verify-your-configuration)
+
+Prerequisites:
+
+- You have a Flux repository connected to a Kubernetes cluster.
+  If you're starting from scratch, see [Set up Flux for GitOps](flux_tutorial.md).
+
+## Create the Kubernetes manifest repository
+
+First, create a repository for your Kubernetes manifests:
+
+1. In GitLab, create a new repository called `web-app-manifests`.
+1. In `web-app-manifests`, add a file named `src/nginx-deployment.yaml` with the following contents:
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: nginx
+   spec:
+     replicas: 1
+     template:
+       spec:
+         containers:
+         - name: nginx
+           image: nginx:1.14.2
+           ports:
+           - containerPort: 80
+   ```
+
+1. In `web-app-manifests`, add a file named `src/kustomization.yaml` with the following contents:
+
+   ```yaml
+   apiVersion: kustomize.config.k8s.io/v1beta1
+   kind: Kustomization
+   resources:
+     - nginx-deployment.yaml
+   commonLabels:
+     app: flux-oci-tutorial
+   ```
+
+## Configure the manifest repository to create an OCI artifact
+
+Next, configure [GitLab CI/CD](../../../../ci/index.md) to package your manifests into an OCI artifact,
+and push the artifact to the [GitLab Container Registry](../../../packages/container_registry/index.md):
+
+1. In the root of `web-app-manifests`, create and push a [`.gitlab-ci.yml`](../../../../ci/yaml/gitlab_ci_yaml.md) file with the following contents:
+
+   ```yaml
+   package:
+     stage: deploy
+     image:
+       name: fluxcd/flux-cli:v2.0.0-rc.1
+       entrypoint: [""]
+     script:
+       - mkdir -p manifests
+       - kubectl kustomize ./src --output ./manifests
+       - |
+         flux push artifact oci://$CI_REGISTRY_IMAGE:latest \
+           --path="./manifests" \
+           --source="$CI_REPOSITORY_URL" \
+           --revision="$CI_COMMIT_SHORT_SHA" \
+           --creds="$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \
+           --annotations="org.opencontainers.image.url=$CI_PROJECT_URL" \
+           --annotations="org.opencontainers.image.title=$CI_PROJECT_NAME" \
+           --annotations="com.gitlab.job.id=$CI_JOB_ID" \
+           --annotations="com.gitlab.job.url=$CI_JOB_URL"
+   ```
+
+   When the file is pushed to GitLab, a CI/CD pipeline with a single `package` job is created. This job:
+
+   - Uses `kustomization.yaml` to render your final Kubernetes manifests.
+   - Packages your manifests into an OCI artifact.
+   - Pushes the OCI artifact to the Container Registry.
+
+   After the pipeline has completed, you can check your OCI artifact with the Container Registry UI.
+
+## Configure Flux to sync your artifact
+
+Next, configure your Flux repository to sync the artifact produced by the `web-app-manifests` repository.
+
+To configure, create an [`OCIRepository`](https://fluxcd.io/flux/components/source/ocirepositories/) resource:
+
+1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-source.yaml`
+   with the following contents:
+
+   ```yaml
+   apiVersion: source.toolkit.fluxcd.io/v1
+   kind: OCIRepository
+   metadata:
+     name: web-app-manifests
+     namespace: flux-system
+   spec:
+     interval: 1m0s
+     url: oci://registry.gitlab.com/gitlab-org/configure/examples/flux/web-app-manifests-oci
+     ref:
+       tag: latest
+   ```
+
+   You will need to substitute the `url` with the URL of your `web-app-manifests` project's container registry.
+
+1. In your local clone of your Flux repository, add a file named `clusters/my-cluster/web-app-manifests-kustomization.yaml`
+   with the following contents:
+
+   ```yaml
+   apiVersion: kustomize.toolkit.fluxcd.io/v1
+   kind: Kustomization
+   metadata:
+     name: nginx-source-kustomization
+     namespace: flux-system
+   spec:
+     interval: 1m0s
+     path: ./
+     prune: true
+     sourceRef:
+       kind: OCIRepository
+       name: web-app-manifests
+     targetNamespace: default
+   ```
+
+   This file adds a [Kustomization](https://fluxcd.io/flux/components/kustomize/kustomization/) resource that tells Flux to sync the manifests in the artifact fetched from the registry.
+
+1. Commit the new files and push.
+
+## Verify your configuration
+
+You should see a newly created `nginx` pod in your cluster.
+
+If you want to see the deployment sync again, try updating the number of replicas in the
+`src/nginx-deployment.yaml` file and push to the default branch. If all is working well, the change
+should sync to the cluster when the pipeline has finished.
+
+Congratulations! You successfully configured a project to deploy an application and synchronize your changes!
diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md
index 8aee0c01d65..f2d65b900f0 100644
--- a/doc/user/clusters/agent/gitops/flux_tutorial.md
+++ b/doc/user/clusters/agent/gitops/flux_tutorial.md
@@ -4,7 +4,7 @@ group: Environments
 info: A tutorial using Flux
 ---
 
-# Tutorial: Set up Flux for GitOps **(FREE)**
+# Tutorial: Set up Flux for GitOps **(FREE ALL)**
 
 This tutorial teaches you how to set up Flux for GitOps. You'll complete a bootstrap installation,
 install `agentk` in your cluster, and deploy a simple `nginx` application.
@@ -83,8 +83,19 @@ You must register `agentk` before you install it in your cluster.
 
 To register `agentk`:
 
-- Complete the steps in [Register the agent with GitLab](../install/index.md#register-the-agent-with-gitlab).
-  Be sure to save the agent registration token and `kas` address.
+1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project.
+   If you have an [agent configuration file](../install/index.md#create-an-agent-configuration-file),
+   it must be in this project. Your cluster manifest files should also be in this project.
+1. Select **Operate > Kubernetes clusters**.
+1. Select **Connect a cluster (agent)**.
+   - If you want to create a configuration with CI/CD defaults, type a name.
+   - If you already have an agent configuration file, select it from the list.
+1. Select **Register an agent**.
+1. Securely store the agent access token and `kasAddress` for later.
+
+The agent is registered for your project. You don't need to run any commands yet.
+
+In the next step, you'll use Flux to install `agentk` in your cluster.
 
 ## Install `agentk`
 
@@ -103,10 +114,24 @@ To install `agentk`:
      name: gitlab
    ```
 
-1. Apply the agent registration token as a secret in the cluster:
+1. Create a file called `secret.yaml` that contains your agent access token as a secret:
+
+   ```yaml
+   apiVersion: v1
+   kind: Secret
+   metadata:
+     name: gitlab-agent-token
+   type: Opaque
+   stringData:
+     values.yaml: |-
+       config:
+         token: "<your-token-here>"
+   ```
+
+1. Apply `secret.yaml` to your cluster:
 
    ```shell
-   kubectl create secret generic gitlab-agent-token -n gitlab --from-literal=token=YOUR-TOKEN-HERE
+   kubectl apply -f secret.yaml -n gitlab
    ```
 
    Although this step does not follow GitOps principles, it simplifies configuration for new Flux users.
@@ -147,8 +172,11 @@ To install `agentk`:
      interval: 1h0m0s
      values:
        config:
-         kasAddress: "wss://kas.gitlab.example.com"
-         secretName: "gitlab-agent-token"
+         kasAddress: "wss://kas.gitlab.com"  
+     valuesFrom:
+       - kind: Secret
+         name: gitlab-agent-token
+         valuesKey: values.yaml
    ```
 
 1. To verify that `agentk` is installed and running in the cluster, run the following command:
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md
index a0d6e0d415d..140ac060dc7 100644
--- a/doc/user/clusters/agent/index.md
+++ b/doc/user/clusters/agent/index.md
@@ -63,9 +63,9 @@ GitLab in a Kubernetes cluster, you might need a different version of Kubernetes
 You can upgrade your
 Kubernetes version to a supported version at any time:
 
+- 1.27 (support ends on July 22, 2024 or when 1.30 becomes supported)
 - 1.26 (support ends on March 22, 2024 or when 1.29 becomes supported)
 - 1.25 (support ends on October 22, 2023 or when 1.28 becomes supported)
-- 1.24 (support ends on July 22, 2023 or when 1.27 becomes supported)
 
 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.
@@ -80,6 +80,18 @@ Some GitLab features might work on versions not listed here. [This epic](https:/
 
 Read about how to [migrate to the agent for Kubernetes](../../infrastructure/clusters/migrate_to_gitlab_agent.md) from the certificate-based integration.
 
+## Agent connection
+
+The agent opens a bidirectional channel to KAS for communication.
+This channel is used for all communication between the agent and KAS:
+
+- Each agent can maintain up to 500 logical gRPC streams, including active and idle streams.
+- The number of TCP connections used by the gRPC streams is determined by gRPC itself.
+- Each connection has a maximum lifetime of two hours, with a one-hour grace period.
+  - A proxy in front of KAS might influence the maximum lifetime of connections. On GitLab.com, this is [two hours](https://gitlab.com/gitlab-cookbooks/gitlab-haproxy/-/blob/68df3484087f0af368d074215e17056d8ab69f1c/attributes/default.rb#L217). The grace period is 50% of the maximum lifetime.
+
+For detailed information about channel routing, see [Routing KAS requests in the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kas_request_routing.md).
+
 ## Related topics
 
 - [GitOps workflow](gitops.md)
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md
index c847eaff13f..75571d1a4f5 100644
--- a/doc/user/clusters/agent/install/index.md
+++ b/doc/user/clusters/agent/install/index.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Installing the agent for Kubernetes **(FREE)**
+# Installing the agent for Kubernetes **(FREE ALL)**
 
 > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
 > - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures.
diff --git a/doc/user/clusters/agent/troubleshooting.md b/doc/user/clusters/agent/troubleshooting.md
index eddc6ef3e16..c01b1337aca 100644
--- a/doc/user/clusters/agent/troubleshooting.md
+++ b/doc/user/clusters/agent/troubleshooting.md
@@ -239,3 +239,23 @@ Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): uncl
 ```
 
 This error is typically caused by an incompatible version of Helm. To resolve the issue, ensure that you are using a version of Helm [compatible with your version of Kubernetes](index.md#supported-kubernetes-versions-for-gitlab-features).
+
+## `GitLab Agent Server: Unauthorized` error on Dashboard for Kubernetes
+
+An error like `GitLab Agent Server: Unauthorized. Trace ID: <...>`
+on the [Dashboard for Kubernetes](../../../ci/environments/kubernetes_dashboard.md) page
+might be caused by one of the following:
+
+- The `user_access` entry in the agent configuration file doesn't exist or is wrong.
+  To resolve, see [Grant users Kubernetes access](user_access.md).
+- There are multiple [`_gitlab_kas` cookies](../../../administration/clusters/kas.md#kubernetes-api-proxy-cookie)
+  in the browser and sent to KAS. The most likely cause is multiple GitLab instances hosted
+  on the same site.
+  
+  For example, `gitlab.com` set a `_gitlab_kas` cookie targeted for `kas.gitlab.com`,
+  but the cookie is also sent to `kas.staging.gitlab.com`, which causes the error on `staging.gitlab.com`.
+  
+  To temporarily resolve, delete the `_gitlab_kas` cookie for `gitlab.com` from the browser cookie store.
+  [Issue 418998](https://gitlab.com/gitlab-org/gitlab/-/issues/418998) proposes a fix for this known issue.
+- GitLab and KAS run on different sites. For example, GitLab on `gitlab.example.com` and KAS on `kas.example.com`.
+  GitLab does not support this use case. For details, see [issue 416436](https://gitlab.com/gitlab-org/gitlab/-/issues/416436).
diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md
index 7e04091c940..a5989d823f6 100644
--- a/doc/user/clusters/agent/user_access.md
+++ b/doc/user/clusters/agent/user_access.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Grant users Kubernetes access (Beta) **(FREE)**
+# Grant users Kubernetes access (Beta) **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/390769) in GitLab 16.1, with [flags](../../../administration/feature_flags.md) named `environment_settings_to_graphql`, `kas_user_access`, `kas_user_access_project`, and `expose_authorized_cluster_agents`. This feature is in [Beta](../../../policy/experiment-beta-support.md#beta).
 > - Feature flag `environment_settings_to_graphql` [removed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/124177) in GitLab 16.2.
@@ -15,6 +15,11 @@ of a specific project or group.
 
 Granting access also activates the Dashboard for Kubernetes for a project or group.
 
+For self-managed instances, make sure you either:
+
+- Host your GitLab instance and [KAS](../../../administration/clusters/kas.md) on the same domain.
+- Host KAS on a subdomain of GitLab. For example, GitLab on `gitlab.com` and KAS on `kas.gitlab.com`.
+
 ## Configure Kubernetes access
 
 Configure access when you want to grant users access
@@ -51,7 +56,7 @@ user_access:
     - id: group-3/subgroup
 ```
 
-## Configure access with user impersonation **(PREMIUM)**
+## Configure access with user impersonation **(PREMIUM ALL)**
 
 You can grant access to a Kubernetes cluster and transform
 requests into impersonation requests for authenticated users.
diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md
index 74676e31d22..a967ec9ea24 100644
--- a/doc/user/clusters/agent/vulnerabilities.md
+++ b/doc/user/clusters/agent/vulnerabilities.md
@@ -4,7 +4,7 @@ group: Composition analysis
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Operational Container Scanning **(ULTIMATE)**
+# Operational Container Scanning **(ULTIMATE ALL)**
 
 > - [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 is scheduled for removal in GitLab 16.0.
diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md
index e8fb399d1b0..08e1021f886 100644
--- a/doc/user/clusters/agent/work_with_agent.md
+++ b/doc/user/clusters/agent/work_with_agent.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Working with the agent for Kubernetes **(FREE)**
+# Working with the agent for Kubernetes **(FREE ALL)**
 
 Use the following tasks when working with the agent for Kubernetes.
 
diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md
index 6ed0f08c4a7..a155dcf4a3c 100644
--- a/doc/user/clusters/cost_management.md
+++ b/doc/user/clusters/cost_management.md
@@ -6,7 +6,7 @@ remove_date: '2023-08-22'
 redirect_to: '../index.md'
 ---
 
-# Cluster cost management (removed) **(ULTIMATE)**
+# Cluster cost management (removed) **(ULTIMATE ALL)**
 
 This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7
 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0.
diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md
index fa56dc320be..4a6fa8d4862 100644
--- a/doc/user/clusters/environments.md
+++ b/doc/user/clusters/environments.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Cluster Environments (deprecated) **(PREMIUM)**
+# Cluster Environments (deprecated) **(PREMIUM ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13392) in GitLab 12.3 for group-level clusters.
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14809) in GitLab 12.4 for instance-level clusters.
diff --git a/doc/user/clusters/integrations.md b/doc/user/clusters/integrations.md
index 3076730b10f..0f389b94a33 100644
--- a/doc/user/clusters/integrations.md
+++ b/doc/user/clusters/integrations.md
@@ -6,7 +6,7 @@ remove_date: '2023-08-22'
 redirect_to: '../index.md'
 ---
 
-# Cluster integrations (removed) **(FREE)**
+# Cluster integrations (removed) **(FREE ALL)**
 
 This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/346541) in GitLab 14.7
 and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/399231) in 16.0.
diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md
index 9f769c6535c..3341074f54d 100644
--- a/doc/user/clusters/management_project.md
+++ b/doc/user/clusters/management_project.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Cluster management project (deprecated) **(FREE)**
+# Cluster management project (deprecated) **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32810) in GitLab 12.5.
 > - [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
diff --git a/doc/user/clusters/management_project_template.md b/doc/user/clusters/management_project_template.md
index f6bcff0481a..f4f42f4dc27 100644
--- a/doc/user/clusters/management_project_template.md
+++ b/doc/user/clusters/management_project_template.md
@@ -4,7 +4,7 @@ group: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Manage cluster applications **(FREE)**
+# Manage cluster applications **(FREE ALL)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25318) in GitLab 12.10 with Helmfile support via Helm v2.
 > - Helm v2 support was [dropped](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63577) in GitLab 14.0. Use Helm v3 instead.
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 fde8e455421..4bd42abb9e8 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: Environments
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
 ---
 
-# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE)**
+# Migrate from GitLab Managed Apps to Cluster Management Projects (deprecated) **(FREE ALL)**
 
 The GitLab Managed Apps were deprecated in GitLab 14.0
 in favor of user-controlled Cluster Management projects.
@@ -39,16 +39,16 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
    Either way, [run a pipeline manually](../../ci/pipelines/index.md#run-a-pipeline-manually) and read the logs of the
    `detect-helm2-releases` job to know if you have any Helm v2 releases and which are they.
 
-1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm docs on
+1. If you have no Helm v2 releases, skip this step. Otherwise, follow the official Helm documentation on
    [how to migrate from Helm v2 to Helm v3](https://helm.sh/blog/migrate-from-helm-v2-to-helm-v3/),
    and clean up the Helm v2 releases after you are confident that they have been successfully migrated.
 
 1. In this step you should already have only Helm v3 releases.
    Uncomment from the main [`./helmfile.yaml`](management_project_template.md#the-main-helmfileyml-file) the paths for the
    applications that you would like to manage with this project. Although you could uncomment all the ones you want to
-   managed at once, we recommend you repeat the following steps separately for each app, so you do not get lost during
+   managed at once, you should repeat the following steps separately for each app, so you do not get lost during
    the process.
-1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version currently deployed
+1. Edit the associated `applications/{app}/helmfiles.yaml` to match the chart version deployed
    for your app. Take a GitLab Runner Helm v3 release as an example:
 
    The following command lists the releases and their versions:
@@ -62,11 +62,11 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
 
    Take the version from the `CHART` column which is in the format `{release}-v{chart_version}`,
    then edit the `version:` attribute in the `./applications/gitlab-runner/helmfile.yaml`, so that it matches the version
-   you have currently deployed. This is a safe step to avoid upgrading versions during this migration.
+   you have deployed. This is a safe step to avoid upgrading versions during this migration.
    Make sure you replace `gitlab-managed-apps` from the above command if you have your apps deployed to a different
    namespace.
 
-1. Edit the `applications/{app}/values.yaml` associated with your app to match the currently
+1. Edit the `applications/{app}/values.yaml` associated with your app to match the
    deployed values. For example, for GitLab Runner:
 
    1. Copy the output of the following command (it might be big):
@@ -77,7 +77,7 @@ See also [video walk-throughs](#video-walk-throughs) with examples.
 
    1. Overwrite `applications/gitlab-runner/values.yaml` with the output of the previous command.
 
-   This safe step guarantees that no unexpected default values overwrite your currently deployed values.
+   This safe step guarantees that no unexpected default values overwrite your deployed values.
    For instance, your GitLab Runner could have its `gitlabUrl` or `runnerRegistrationToken` overwritten by mistake.
 
 1. Some apps require special attention: