diff options
Diffstat (limited to 'doc/user/clusters/agent/repository.md')
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 240 |
1 files changed, 208 insertions, 32 deletions
diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md index cbb27a3f343..6ceb2766cc9 100644 --- a/doc/user/clusters/agent/repository.md +++ b/doc/user/clusters/agent/repository.md @@ -4,12 +4,13 @@ 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/#designated-technical-writers --- -# Kubernetes Agent configuration repository **(PREMIUM)** +# Kubernetes Agent configuration repository **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com. > - [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. > - The `ci_access` attribute was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - The GitLab Kubernetes Agent was [moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -22,17 +23,19 @@ The Agent bootstraps with the GitLab installation URL and an authentication toke and you provide the rest of the configuration in your repository, following Infrastructure as Code (IaaC) best practices. -A minimal repository layout looks like this, with `my_agent_1` as the name +A minimal repository layout looks like this, with `my-agent-1` as the name of your Agent: ```plaintext |- .gitlab |- agents - |- my_agent_1 + |- my-agent-1 |- config.yaml ``` -## Synchronize manifest projects +Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name). + +## Synchronize manifest projects **(PREMIUM)** Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` section. Each `id` in the `manifest_projects` section is the path to a Git repository @@ -132,7 +135,7 @@ INCORRECT - both globs match `*.yaml` files in the root directory: ```yaml gitops: manifest_projects: - - id: project1 + - id: project1 paths: - glob: '/**/*.yaml' - glob: '/*.yaml' @@ -143,51 +146,140 @@ CORRECT - single globs matches all `*.yaml` files recursively: ```yaml gitops: manifest_projects: - - id: project1 + - id: project1 paths: - glob: '/**/*.yaml' ``` -## Authorize groups to use an Agent +## Authorize projects and groups to use an Agent + +> - Group authorization [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +> - Project authorization [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. + +If you use the same cluster across multiple projects, you can set up the [CI/CD Tunnel](ci_cd_tunnel.md) +to grant access to an Agent from one or more projects or groups. This way, all the authorized +projects can access the same Agent, which facilitates you to save resources and have a scalable setup. + +When you authorize a project to use an agent through the [CI/CD Tunnel](ci_cd_tunnel.md), +the selected Kubernetes context is automatically injected into CI/CD jobs, allowing you to +run Kubernetes commands from your authorized projects' scripts. When you authorize a group, +all the projects that belong to that group can access the selected agent. -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. +An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration +project. You can authorize up to 100 projects and 100 groups per Agent. -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, -ask an administrator to [enable the `group_authorized_agents` flag](../../../administration/feature_flags.md). -On GitLab.com, this feature is available. +### Authorize projects to use an Agent -If you use the same cluster across multiple projects, you can set up the CI/CD Tunnel -to grant the Agent access to one or more groups. This way, all the projects that belong -to the authorized groups can access the same Agent. This enables you to save resources and -have a scalable setup. +To grant projects access to the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md): -When you authorize a group, the agent's Kubernetes context is automatically injected -into every project of the authorized group, and users can select the connection as -described in the [CI/CD Tunnel documentation](ci_cd_tunnel.md). -To authorize a group to access the Agent through the [CI/CD Tunnel](ci_cd_tunnel.md), -use the `ci_access` attribute in your `config.yaml` configuration file. +1. Go to your Agent's configuration project. +1. Edit the Agent's configuration file (`config.yaml`). +1. Add the `projects` attribute into `ci_access`. +1. Identify the project through its path: -An Agent can only authorize groups in the same group hierarchy as the Agent's configuration project. At most -100 groups can be authorized per Agent. + ```yaml + ci_access: + projects: + - id: path/to/project + ``` -To authorize a group: +### Authorize groups to use an Agent -1. Edit your `config.yaml` file under the `.gitlab/agents/<agent name>` directory. -1. Add the `ci_access` root attribute. +To grant access to all projects within a group: + +1. Go to your Agent's configuration project. +1. Edit the Agent's configuration file (`config.yaml`). 1. Add the `groups` attribute into `ci_access`. -1. Add the group `id` into `groups`, identifying the authorized group through its path. +1. Identify the group or subgroup through its path: + + ```yaml + ci_access: + groups: + - id: path/to/group/subgroup + ``` + +### Use impersonation to restrict project and group access **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345014) in GitLab 14.5. + +By default, the [CI/CD Tunnel](ci_cd_tunnel.md) inherits all the permissions from the service account used to install the +Agent in the cluster. +To restrict access to your cluster, you can use [impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation). + +To specify impersonations, use the `access_as` attribute in your Agent's configuration file and use Kubernetes RBAC rules to manage impersonated account permissions. + +You can impersonate: + +- The Agent itself (default). +- The CI job that accesses the cluster. +- A specific user or system account defined within the cluster. + +#### Impersonate the Agent -For example: +The Agent is impersonated by default. You don't need to do anything to impersonate it. + +#### Impersonate the CI job that accesses the cluster + +To impersonate the CI job that accesses the cluster, add the `ci_job: {}` key-value +under the `access_as` key. + +When the agent makes the request to the actual Kubernetes API, it sets the +impersonation credentials in the following way: + +- `UserName` is set to `gitlab:ci_job:<job id>`. Example: `gitlab:ci_job:1074499489`. +- `Groups` is set to: + - `gitlab:ci_job` to identify all requests coming from CI jobs. + - The list of IDs of groups the project is in. + - The project ID. + - The slug of the environment this job belongs to. + + Example: for a CI job in `group1/group1-1/project1` where: + + - Group `group1` has ID 23. + - Group `group1/group1-1` has ID 25. + - Project `group1/group1-1/project1` has ID 150. + - Job running in a prod environment. + + Group list would be `[gitlab:ci_job, gitlab:group:23, gitlab:group:25, gitlab:project:150, gitlab:project_env:150:prod]`. + +- `Extra` carries extra information about the request. The following properties are set on the impersonated identity: + +| Property | Description | +| -------- | ----------- | +| `agent.gitlab.com/id` | Contains the agent ID. | +| `agent.gitlab.com/config_project_id` | Contains the agent's configuration project ID. | +| `agent.gitlab.com/project_id` | Contains the CI project ID. | +| `agent.gitlab.com/ci_pipeline_id` | Contains the CI pipeline ID. | +| `agent.gitlab.com/ci_job_id` | Contains the CI job ID. | +| `agent.gitlab.com/username` | Contains the username of the user the CI job is running as. | +| `agent.gitlab.com/environment_slug` | Contains the slug of the environment. Only set if running in an environment. | + +Example to restrict access by the CI job's identity: ```yaml ci_access: - # This agent is accessible from CI jobs in projects in these groups - groups: - - id: group/subgroup + projects: + - id: path/to/project + access_as: + ci_job: {} ``` -## Surface network security alerts from cluster to GitLab +#### Impersonate a static identity + +For the given CI/CD Tunnel connection, you can use a static identity for the impersonation. + +Add the `impersonate` key under the `access_as` key to make the request using the provided identity. + +The identity can be specified with the following keys: + +- `username` (required) +- `uid` +- `groups` +- `extra` + +See the [official Kubernetes documentation for more details](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation) on the usage of these keys. + +## Surface network security alerts from cluster to GitLab **(ULTIMATE)** The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts). To integrate, add a top-level `cilium` section to your `config.yml` file. Currently, the @@ -207,6 +299,90 @@ cilium: hubble_relay_address: "hubble-relay.gitlab-managed-apps.svc.cluster.local:80" ``` +## Scan your container images for vulnerabilities + +You can use [cluster image scanning](../../application_security/cluster_image_scanning/index.md) +to scan container images in your cluster for security vulnerabilities. + +To begin scanning all resources in your cluster, add a `starboard` +configuration block to your agent's `config.yaml` with no `filters`: + +```yaml +starboard: + vulnerability_report: + filters: [] +``` + +The namespaces that are able to be scanned depend on the [Starboard Operator install mode](https://aquasecurity.github.io/starboard/latest/operator/configuration/#install-modes). +By default, the Starboard Operator only scans resources in the `default` namespace. To change this +behavior, edit the `STARBOARD_OPERATOR` environment variable in the `starboard-operator` deployment +definition. + +By adding filters, you can limit scans by: + +- Resource name +- Kind +- Container name +- Namespace + +```yaml +starboard: + vulnerability_report: + filters: + - namespaces: + - staging + - production + kinds: + - Deployment + - DaemonSet + containers: + - ruby + - postgres + - nginx + resources: + - my-app-name + - postgres + - ingress-nginx +``` + +A resource is scanned if the resource matches any of the given names and all of the given filter +types (`namespaces`, `kinds`, `containers`, `resources`). If a filter type is omitted, then all +names are scanned. In this example, a resource isn't scanned unless it has a container named `ruby`, +`postgres`, or `nginx`, and it's a `Deployment`: + +```yaml +starboard: + vulnerability_report: + filters: + - kinds: + - Deployment + containers: + - ruby + - postgres + - nginx +``` + +There is also a global `namespaces` field that applies to all filters: + +```yaml +starboard: + vulnerability_report: + namespaces: + - production + filters: + - kinds: + - Deployment + - kinds: + - DaemonSet + resources: + - log-collector +``` + +In this example, the following resources are scanned: + +- All deployments (`Deployment`) in the `production` namespace +- All daemon sets (`DaemonSet`) named `log-collector` in the `production` namespace + ## Debugging To debug the cluster-side component (`agentk`) of the GitLab Kubernetes Agent, set the log |