Merge branch '346726-document-how-to-customize-the-permissions-for-agentk' into 'master'

Resolve "Document how to customize the permissions for 'agentk'"

See merge request gitlab-org/gitlab!77230

doc/administration/clusters/kas.md

@@ -6,13 +6,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Install the GitLab Agent Server (KAS) **(FREE SELF)**
 
+> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`.
 > [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
 
 The GitLab Agent Server (KAS) is a GitLab backend service dedicated to
 managing the [GitLab Agent](../../user/clusters/agent/index.md).
 
 The KAS is already installed and available in GitLab.com under `wss://kas.gitlab.com`.
-See [how to use GitLab.com's KAS](../../user/clusters/agent/install/index.md#set-up-the-agent-server).
 This document describes how to install a KAS for GitLab self-managed instances.
 
 ## Installation options

doc/user/clusters/agent/ci_cd_tunnel.md

@@ -19,11 +19,8 @@ Only CI/CD jobs set in the configuration project can access one of the configure
 
 ## Prerequisites
 
-- A running [`kas` instance](install/index.md#set-up-the-agent-server).
-- A [configuration repository](install/index.md#define-a-configuration-repository) with an agent config file
-  installed (`.gitlab/agents/<agent-name>/config.yaml`).
-- A [registered agent](install/index.md#register-an-agent-with-gitlab).
-- The agent [installed in the cluster](install/index.md#install-the-agent-into-the-cluster).
+- An existing Kubernetes cluster.
+- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster).
 
 ## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD
 

doc/user/clusters/agent/install/index.md

@@ -10,33 +10,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 To get started with the Agent, install it in your cluster.
 
-Pre-requisites:
+## Prerequisites **(SELF)**
 
 - An existing Kubernetes cluster.
-- An account on GitLab.
+- On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md).
 
 ## Installation steps
 
 To install the [Agent](../index.md) in your cluster:
 
-1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance.
 1. [Define a configuration repository](#define-a-configuration-repository).
 1. [Register an agent with GitLab](#register-an-agent-with-gitlab).
 1. [Install the agent into the cluster](#install-the-agent-into-the-cluster).
-1. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret).
-1. [Create manifest files](#create-manifest-files).
 
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process.
 
-### Set up the Agent Server
-
-> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`.
-
-To use the KAS:
-
-- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md).
-- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`.
-
 ### Define a configuration repository
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository.
@@ -62,7 +50,7 @@ WARNING:
 The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized.
 
 You **don't have to add any content** to this file when you create it. The fact that the file exists
-tells GitLab that this is an agent configuration file. It doesn't do anything so far, but, later on, you can use this
+tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this
 file to [configure the agent](../repository.md) by setting up parameters such as:
 
 - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md).
@@ -71,10 +59,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as
 
 To see all the settings available, read the [Agent configuration repository documentation](../repository.md).
 
-### Access your cluster from GitLab CI/CD
-
-Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD.
-
 ### Register an agent with GitLab
 
 > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI.
@@ -92,242 +76,53 @@ In GitLab:
 1. The form reveals your registration token. Securely store this secret token as you cannot view it again.
 1. Copy the command under **Recommended installation method**.
 
+### Install the agent into the cluster
+
 In your computer:
 
 1. Open your local terminal and connect to your cluster.
-1. Run the command you copied from the installation form.
+1. Run the command you copied when registering your cluster in the previous step.
 
-### Install the agent into the cluster
+See the following sections to learn about customizing the installation.
 
-To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace,
-for example, `gitlab-kubernetes-agent`, run:
+## Simple installation method
 
-```shell
-kubectl create namespace gitlab-kubernetes-agent
-```
+The command provided by GitLab does the following things:
 
-To perform a one-liner installation, run the command below. Make sure to replace:
+- Creates a namespace for the deployment (`gitlab-kubernetes-agent`).
+- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account).
+- Creates a `Secret` resource for the agent registration token.
+- Creates a `Deployment` resource for the `agentk` pod.
 
-- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output).
-- `gitlab-kubernetes-agent` with the namespace you defined in the previous step.
-- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`.
-- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu.
+The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run:
 
 ```shell
-docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f -
+docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
 ```
 
 WARNING:
 `--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for
 testing purposes but for production please make sure to specify a matching version explicitly.
 
-To find out the various options the above Docker container supports, run:
-
-```shell
-docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
-```
-
-## Advanced installation
+## Advanced installation method
 
 For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent).
 
 Otherwise, follow the manual installation steps described below.
 
-### Create the Kubernetes secret
-
-After generating the token, you must apply it to the Kubernetes cluster.
+### Customize the permissions for the `agentk` service account
 
-To create your Secret, run:
+The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent.
 
-```shell
-kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN'
-```
-
-The following example file contains the
-Kubernetes resources required for the Agent to be installed. You can modify this
-example [`resources.yml` file](#example-resourcesyml-file) in the following ways:
-
-- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`.
-- You can configure `kas-address` (Agent Server) in several ways.
-  The agent can use the WebSockets or gRPC protocols to connect to the Agent Server.
-  Select the option appropriate for your cluster configuration and GitLab architecture:
-  - The `wss` scheme (an encrypted WebSockets connection) is specified by default
-    after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab.
-    When using the sub-chart, you must set `wss://kas.host.tld:443` as
-    `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation.
-    When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as
-    `kas-address`, where `GitLab.host.tld` is your GitLab hostname.
-  - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`)
-    to use an unencrypted WebSockets connection.
-    When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`).
-  - Specify the `grpc` scheme if both Agent and Server are installed in one cluster.
-    In this case, you may specify `kas-address` value as
-    `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas`
-    is the name of the service created by `gitlab-kas` chart, and `<your-namespace>`
-    is the namespace where the chart was installed.
-  - Specify the `grpcs` scheme to use an encrypted gRPC connection.
-  - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the
-    `kas-address` for `wss` and `ws` schemes to whatever you need.
-    Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress)
-    to learn more about it.
-  - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details.
-- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your
-  secret name in the `secretName:` section.
-
-To apply this file, run the following command:
+As part of the advanced installation method, you can restrict the agent access rights using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation.
 
-```shell
-kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml
-```
+To create restricted permissions:
 
-To review your configuration, run the following command:
+1. Copy the `cluster` directory.
+1. Edit the `kustomization.yaml` and `components/*` files based on your requirements.
+1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration.
 
-```shell
-$ kubectl get pods -n gitlab-kubernetes-agent
-
-NAMESPACE                NAME                                          READY   STATUS    RESTARTS   AGE
-gitlab-kubernetes-agent  gitlab-kubernetes-agent-77689f7dcb-5skqk      1/1     Running   0          51s
-```
-
-#### Example `resources.yml` file
-
-```yaml
----
-apiVersion: v1
-kind: Namespace
-metadata:
-  name: gitlab-kubernetes-agent
----
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: gitlab-kubernetes-agent
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: gitlab-kubernetes-agent
-spec:
-  replicas: 1
-  selector:
-    matchLabels:
-      app: gitlab-kubernetes-agent
-  template:
-    metadata:
-      labels:
-        app: gitlab-kubernetes-agent
-    spec:
-      serviceAccountName: gitlab-kubernetes-agent
-      containers:
-      - name: agent
-        # Make sure to specify a matching version for production
-        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z"
-        args:
-        - --token-file=/config/token
-        - --kas-address
-        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
-        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
-        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
-        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
-        volumeMounts:
-        - name: token-volume
-          mountPath: /config
-      volumes:
-      - name: token-volume
-        secret:
-          secretName: gitlab-kubernetes-agent-token
-  strategy:
-    type: RollingUpdate
-    rollingUpdate:
-      maxSurge: 0
-      maxUnavailable: 1
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: gitlab-kubernetes-agent-write
-rules:
-- resources:
-  - '*'
-  apiGroups:
-  - '*'
-  verbs:
-  - create
-  - update
-  - delete
-  - patch
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: gitlab-kubernetes-agent-write-binding
-roleRef:
-  name: gitlab-kubernetes-agent-write
-  kind: ClusterRole
-  apiGroup: rbac.authorization.k8s.io
-subjects:
-- name: gitlab-kubernetes-agent
-  kind: ServiceAccount
-  namespace: gitlab-kubernetes-agent
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRole
-metadata:
-  name: gitlab-kubernetes-agent-read
-rules:
-- resources:
-  - '*'
-  apiGroups:
-  - '*'
-  verbs:
-  - get
-  - list
-  - watch
----
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-metadata:
-  name: gitlab-kubernetes-agent-read-binding
-roleRef:
-  name: gitlab-kubernetes-agent-read
-  kind: ClusterRole
-  apiGroup: rbac.authorization.k8s.io
-subjects:
-- name: gitlab-kubernetes-agent
-  kind: ServiceAccount
-  namespace: gitlab-kubernetes-agent
-```
-
-### Create manifest files
-
-In a previous step, you configured a `config.yaml` to point to the GitLab projects
-the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a
-templating engine or other means.
-
-The agent is authorized to download manifests for the configuration
-project, and public projects. Support for other private projects is
-planned in the issue [Agent authorization for private manifest
-projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
-
-Each time you push a change to a monitored manifest repository, the Agent logs the change:
-
-```plaintext
-2020-09-15_14:09:04.87946 gitlab-k8s-agent      : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea
-```
-
-#### Example manifest file
-
-This file creates a minimal `ConfigMap`:
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: demo-map
-  namespace: gitlab-kubernetes-agent  # Can be any namespace managed by you that the agent has access to.
-data:
-  key: value
-```
+The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time.
 
 ## Example projects