diff options
Diffstat (limited to 'doc/user/clusters/agent')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_workflow.md | 14 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/flux_tutorial.md | 13 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 18 | ||||
| -rw-r--r-- | doc/user/clusters/agent/user_access.md | 56 | ||||
| -rw-r--r-- | doc/user/clusters/agent/vulnerabilities.md | 13 | ||||
| -rw-r--r-- | doc/user/clusters/agent/work_with_agent.md | 14 |
6 files changed, 93 insertions, 35 deletions
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 260263632c5..a1281d3d75c 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -15,9 +15,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - The ability to switch between certificate-based clusters and agents was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/335089) in GitLab 14.9. The certificate-based cluster context is always called `gitlab-deploy`. > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/80508) from _CI/CD tunnel_ to _CI/CD workflow_ in GitLab 14.9. -You can use a GitLab CI/CD workflow to safely deploy to and update your Kubernetes clusters. +You can use GitLab CI/CD to safely connect, deploy, and update your Kubernetes clusters. -To do so, you must first [install an agent in your cluster](install/index.md). When done, you have a Kubernetes context and can +To do so, [install an agent in your cluster](install/index.md). When done, you have a Kubernetes context and can run Kubernetes API commands in your GitLab CI/CD pipeline. To ensure access to your cluster is safe: @@ -25,11 +25,11 @@ To ensure access to your cluster is safe: - Each agent has a separate context (`kubecontext`). - Only the project where the agent is configured, and any additional projects you authorize, can access the agent in your cluster. -The CI/CD workflow requires runners to be registered with GitLab, but these runners do not have to be in the cluster where the agent is. +To use GitLab CI/CD to interact with your cluster, runners must be registered with GitLab. However, these runners do not have to be in the cluster where the agent is. -## GitLab CI/CD workflow steps +## Use GitLab CI/CD with your cluster -To update a Kubernetes cluster by using GitLab CI/CD, complete the following steps. +To update a Kubernetes cluster with GitLab CI/CD: 1. Ensure you have a working Kubernetes cluster and the manifests are in a GitLab project. 1. In the same GitLab project, [register and install the GitLab agent](install/index.md). @@ -64,7 +64,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 left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, select **Search or go to** 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 to the project. Do not wrap the path in quotation marks. @@ -89,7 +89,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 left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the [agent configuration file](install/index.md#create-an-agent-configuration-file) (`config.yaml`). +1. On the left sidebar, select **Search or go to** 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: diff --git a/doc/user/clusters/agent/gitops/flux_tutorial.md b/doc/user/clusters/agent/gitops/flux_tutorial.md index f2d65b900f0..27724a95291 100644 --- a/doc/user/clusters/agent/gitops/flux_tutorial.md +++ b/doc/user/clusters/agent/gitops/flux_tutorial.md @@ -83,7 +83,7 @@ You must register `agentk` before you install it in your cluster. To register `agentk`: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and 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**. @@ -123,9 +123,7 @@ To install `agentk`: name: gitlab-agent-token type: Opaque stringData: - values.yaml: |- - config: - token: "<your-token-here>" + token: "<your-token-here>" ``` 1. Apply `secret.yaml` to your cluster: @@ -173,12 +171,11 @@ To install `agentk`: values: config: kasAddress: "wss://kas.gitlab.com" - valuesFrom: - - kind: Secret - name: gitlab-agent-token - valuesKey: values.yaml + secretName: gitlab-agent-token ``` + The Helm release uses the secret from the previous step. + 1. To verify that `agentk` is installed and running in the cluster, run the following command: ```shell diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 75571d1a4f5..d620a9f658c 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -43,7 +43,7 @@ To install the agent in your cluster: 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/agent.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. +- You use [a GitLab CI/CD workflow](../ci_cd_workflow.md#use-gitlab-cicd-with-your-cluster) and want to authorize a different project to use the agent. - You [allow specific project or group members to access Kubernetes](../user_access.md). To create an agent configuration file: @@ -76,11 +76,11 @@ In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `ce Prerequisites: - For a [GitLab CI/CD workflow](../ci_cd_workflow.md), ensure that - [GitLab CI/CD is enabled](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project). + [GitLab CI/CD is not disabled](../../../../ci/enable_or_disable_ci.md#disable-cicd-in-a-project). You must register an agent before you can install the agent in your cluster. To register an agent: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** 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. Select **Operate > Kubernetes clusters**. @@ -114,22 +114,26 @@ To connect to multiple clusters, you must configure, register, and install an ag #### Install the agent with Helm +WARNING: +For simplicity, the default Helm chart configuration sets up a service account for the agent with `cluster-admin` rights. You should not use this on production systems. To deploy to a production system, follow the instructions in [Customize the Helm installation](#customize-the-helm-installation) to create a service account with the minimum permissions required for your deployment and specify that during installation. + To install the agent on your cluster using Helm: 1. [Install Helm](https://helm.sh/docs/intro/install/). 1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/). 1. Run the command you copied when you [registered your agent with GitLab](#register-the-agent-with-gitlab). - -Optionally, you can [customize the Helm installation](#customize-the-helm-installation). If you install the agent on a production system, you should customize the Helm installation to skip creating the service account. +1. Optional. [Customize the Helm installation](#customize-the-helm-installation). + If you install the agent on a production system, you should customize the Helm installation to restrict the permissions of the service account. See [How to deploy the GitLab Agent for Kubernetes with limited permissions](https://about.gitlab.com/blog/2021/09/10/setting-up-the-k-agent/). ##### Customize the Helm installation By default, the Helm installation command generated by GitLab: - Creates a namespace `gitlab-agent` for the deployment (`--namespace gitlab-agent`). You can skip creating the namespace by omitting the `--create-namespace` flag. -- Sets up a service account for the agent with `cluster-admin` rights. You can: +- Sets up a service account for the agent and assigns it the `cluster-admin` role. You can: - Skip creating the service account by adding `--set serviceAccount.create=false` to the `helm install` command. In this case, you must set `serviceAccount.name` to a pre-existing service account. - - Skip creating the RBAC permissions by adding `--set rbac.create=false` to the `helm install` command. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all. + - Customise the role assigned to the service account by adding `--set rbac.useExistingRole <your role name>` to the `helm install` command. In this case, you should have a pre-created role with restricted permissions that can be used by the service account. + - Skip role assignment altogether by adding `--set rbac.create=false` to your `helm install` command. In this case, you must create `ClusterRoleBinding` manually. - Creates a `Secret` resource for the agent's access token. To instead bring your own secret with a token, omit the token (`--set token=...`) and instead use `--set config.secretName=<your secret name>`. - Creates a `Deployment` resource for the `agentk` pod. diff --git a/doc/user/clusters/agent/user_access.md b/doc/user/clusters/agent/user_access.md index a5989d823f6..21dc249b1d1 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 ALL)** +# Grant users Kubernetes access **(FREE ALL BETA)** > - [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. @@ -141,6 +141,60 @@ subjects: kind: Group ``` +## Access a cluster with the Kubernetes API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/131144) in GitLab 16.4. + +You can configure an agent to allow GitLab users to access a cluster with the Kubernetes API. + +Prerequisite: + +- You have an agent configured with the `user_access` entry. + +To grant Kubernetes API access: + +1. On the left sidebar, select **Search or go to** and find your project. +1. Select **Operate > Kubernetes clusters** and retrieve the numerical ID of the agent you want to access. You need the ID to construct the full API token. +1. Create a [personal access token](../../profile/personal_access_tokens.md) with the `k8s_proxy` scope. You need the access token to construct the full API token. +1. Construct `kube config` entries to access the cluster: + 1. Make sure that the proper `kube config` is selected. + For example, you can set the `KUBECONFIG` environment variable. + 1. Add the GitLab KAS proxy cluster to the `kube config`: + + ```shell + kubectl config set-cluster <cluster_name> --server "https://kas.gitlab.com/k8s-proxy" + ``` + + The `server` argument points to the KAS address of your GitLab instance. + On GitLab.com, this is `https://kas.gitlab.com/k8s-proxy`. + You can get the KAS address of your instance when you register an agent. + + 1. Use your numerical agent ID and personal access token to construct an API token: + + ```shell + kubectl config set-credentials <gitlab_user> --token "pat:<agent-id>:<token>" + ``` + + 1. Add the context to combine the cluster and the user: + + ```shell + kubectl config set-context <gitlab_agent> --cluster <cluster_name> --user <gitlab_user> + ``` + + 1. Activate the new context: + + ```shell + kubectl config use-context <gitlab_agent> + ``` + +1. Check that the configuration works: + + ```shell + kubectl get nodes + ``` + +The configured user can access your cluster with the Kubernetes API. + ## Related topics - [Architectural blueprint](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kubernetes_user_access.md) diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index a967ec9ea24..a2dc50e43d7 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -9,9 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. -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. - ## Enable operational container scanning You can use operational container scanning to scan container images in your cluster for security vulnerabilities. You @@ -24,7 +21,7 @@ If both `agent config` and `scan execution policies` are configured, the configu ### Enable via agent configuration To enable scanning of all images within your Kubernetes cluster via the agent configuration, add a `container_scanning` configuration block to your agent -configuration with a `cadence` field containing a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans are run. +configuration with a `cadence` field containing a [CRON expression](https://en.wikipedia.org/wiki/Cron) for when the scans are run. ```yaml container_scanning: @@ -129,7 +126,7 @@ Resource requirements can only be set up using the agent configuration. If you e To view vulnerability information in GitLab: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select the **Agent** tab. 1. Select an agent to view the cluster vulnerabilities. @@ -140,3 +137,9 @@ This information can also be found under [operational vulnerabilities](../../../ NOTE: You must have at least the Developer role. + +## Scanning private images + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/415451) in GitLab 16.4. + +To scan private images, the scanner relies on the image pull secrets (direct references and from the service account) to pull the image. diff --git a/doc/user/clusters/agent/work_with_agent.md b/doc/user/clusters/agent/work_with_agent.md index 08e1021f886..70abbebaaad 100644 --- a/doc/user/clusters/agent/work_with_agent.md +++ b/doc/user/clusters/agent/work_with_agent.md @@ -4,9 +4,9 @@ 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 ALL)** +# Managing the agent for Kubernetes instances **(FREE ALL)** -Use the following tasks when working with the agent for Kubernetes. +Use the following tasks when you work with the agent for Kubernetes. ## View your agents @@ -18,7 +18,7 @@ Prerequisite: To view the list of agents: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains your agent configuration file. You cannot view registered agents from a project that does not contain the agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select **Agent** tab to view clusters connected to GitLab through the agent. @@ -40,7 +40,7 @@ is shared with a project, it automatically appears in the project agent tab. To view the list of shared agents: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. 1. Select the **Agent** tab. @@ -54,7 +54,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 left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains your agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains your agent configuration file. 1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to see activity for. @@ -115,7 +115,7 @@ An agent can have only two active tokens at one time. To reset the agent token without downtime: 1. Create a new token: - 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. + 1. On the left sidebar, select **Search or go to** and find your project. 1. Select **Operate > Kubernetes clusters**. 1. Select the agent you want to create a token for. 1. On the **Access tokens** tab, select **Create token**. @@ -137,7 +137,7 @@ clean up those resources manually. To remove an agent from the UI: -1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find the project that contains the agent configuration file. +1. On the left sidebar, select **Search or go to** and find the project that contains the agent configuration file. 1. Select **Operate > 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**. |