diff options
Diffstat (limited to 'doc/user/clusters/agent')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_workflow.md | 32 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops.md | 12 | ||||
| -rw-r--r-- | doc/user/clusters/agent/gitops/helm.md | 9 | ||||
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 2 | ||||
| -rw-r--r-- | doc/user/clusters/agent/vulnerabilities.md | 75 |
5 files changed, 110 insertions, 20 deletions
diff --git a/doc/user/clusters/agent/ci_cd_workflow.md b/doc/user/clusters/agent/ci_cd_workflow.md index 454be3c53c7..2a66549f9cb 100644 --- a/doc/user/clusters/agent/ci_cd_workflow.md +++ b/doc/user/clusters/agent/ci_cd_workflow.md @@ -60,6 +60,7 @@ Authorization configuration can take one or two minutes to propagate. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327850) in GitLab 14.4. > - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346566) to remove hierarchy restrictions in GitLab 15.6. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/356831) to allow authorizing projects in a user namespace in GitLab 15.7. To authorize the agent to access the GitLab project where you keep Kubernetes manifests: @@ -73,7 +74,7 @@ To authorize the agent to access the GitLab project where you keep Kubernetes ma - id: path/to/project ``` - - Authorized projects must have the same root group as the agent's configuration project. + - Authorized projects must have the same root group or user namespace as the agent's configuration project. - You can install additional agents into the same cluster to accommodate additional hierarchies. - You can authorize up to 100 projects. @@ -286,6 +287,35 @@ 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)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/343885) in GitLab 15.7. + +By default, if your agent is [available to a project](#authorize-the-agent), all of the project's CI/CD jobs can use that agent. + +To restrict access to the agent to only jobs with specific environments, add `environments` to `ci_access.projects` or `ci_access.groups`. For example: + + ```yaml + ci_access: + projects: + - id: path/to/project-1 + - id: path/to/project-2 + environments: + - staging + - review/* + groups: + - id: path/to/group-1 + environments: + - production + ``` + +In this example: + +- All CI/CD jobs under `project-1` can access the agent. +- CI/CD jobs under `project-2` with `staging` or `review/*` environments can access the agent. + - `*` is a wildcard, so `review/*` matches all environments under `review`. +- CI/CD jobs for projects under `group-1` with `production` environments can access the agent. + ## Related topics - [Self-paced classroom workshop](https://gitlab-for-eks.awsworkshop.io) (Uses AWS EKS, but you can use for other Kubernetes clusters) diff --git a/doc/user/clusters/agent/gitops.md b/doc/user/clusters/agent/gitops.md index c0d4a5e088f..bd7dfb3abee 100644 --- a/doc/user/clusters/agent/gitops.md +++ b/doc/user/clusters/agent/gitops.md @@ -9,6 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/346567) from GitLab Premium to GitLab Free in 15.3. +> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/346585) to make the `id` attribute optional in GitLab 15.7. +> - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. With GitOps, you can manage containerized clusters and applications from a Git repository that: @@ -64,6 +66,10 @@ The following snippet shows an example of the possible keys and values for the G gitops: manifest_projects: - id: gitlab-org/cluster-integration/gitlab-agent + ref: # either `branch`, `tag` or `commit` can be specified + branch: production + # commit: <mysha> + # tag: v1.0 default_namespace: my-ns paths: # Read all YAML files from this directory. @@ -83,7 +89,11 @@ gitops: | Keyword | Description | |--|--| | `manifest_projects` | Projects where your Kubernetes manifests are stored. The agent monitors the files in the repositories in these projects. When manifest files change, the agent deploys the changes to the cluster. | -| `id` | Required. Path to a Git repository that has Kubernetes manifests in YAML or JSON format. No authentication mechanisms are currently supported. | +| `id` | Path to a Git repository that has Kubernetes manifests in YAML or JSON format. No authentication mechanisms are supported. Default is the agent configuration repository. | +| `ref` | Optional. Git reference in the configured Git repository to fetch the Kubernetes manifest files from. If not specified or empty, the default branch is used. If specified, it must contain either `branch`, `tag`, or `commit`. | +| `ref.branch` | Branch name in the configured Git repository to fetch the Kubernetes manifest files from. | +| `ref.tag` | Tag name in the configured Git repository to fetch the Kubernetes manifest files from. | +| `ref.commit` | Commit SHA in the configured Git repository to fetch the Kubernetes manifest files from. | | `default_namespace` | Namespace to use if not set explicitly in object manifest. Also used for inventory `ConfigMap` objects. | | `paths` | Repository paths to scan for manifest files. Directories with names that start with a dot `(.)` are ignored. | | `paths[].glob` | Required. See [doublestar](https://github.com/bmatcuk/doublestar#about) and [the match function](https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match) for globbing rules. | diff --git a/doc/user/clusters/agent/gitops/helm.md b/doc/user/clusters/agent/gitops/helm.md index 0ec87376636..b9a59d37f5d 100644 --- a/doc/user/clusters/agent/gitops/helm.md +++ b/doc/user/clusters/agent/gitops/helm.md @@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Using Helm charts to update a Kubernetes cluster (Alpha) **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/371019) in GitLab 15.4. +> - Specifying a branch, tag, or commit reference to fetch the Kubernetes manifest files [introduced](https://gitlab.com/groups/gitlab-org/-/epics/4516) in GitLab 15.7. 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 @@ -51,6 +52,8 @@ gitops: source: project: id: my-group/my-project-with-chart + ref: + branch: production path: dir-in-project/with/charts namespace: my-ns max_history: 1 @@ -68,6 +71,10 @@ gitops: | `max_history` | Optional. Maximum number of release [revisions to store in the cluster](https://helm.sh/docs/helm/helm_history/). | | `source` | Required. From where the chart should get installed. Only supports project sources. | | `source.project.id` | Required. ID of the project where Helm chart is committed. Authentication is not supported. | +| `source.project.ref` | Optional. Git reference in the configured Git repository to fetch the Chart from. If not specified or empty, the default branch is used. If specified, it must contain either `branch`, `tag`, or `commit`. | +| `source.project.ref.branch` | Branch name in the configured Git repository to fetch the Chart from. | +| `source.project.ref.tag` | Tag name in the configured Git repository to fetch the Chart from. | +| `source.project.ref.commit` | Commit SHA in the configured Git repository to fetch the Chart from. | | `source.project.path` | Optional. Path of the chart in the project repository. Root of the repository is used by default. Should be the directory with the `Chart.yaml` file. | ## Custom values diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index 2030052e3b0..62767f1dfd9 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -123,7 +123,7 @@ To install the agent on your cluster using Helm: 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). +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. ##### Customize the Helm installation diff --git a/doc/user/clusters/agent/vulnerabilities.md b/doc/user/clusters/agent/vulnerabilities.md index dcb3276deb5..d9a9981d211 100644 --- a/doc/user/clusters/agent/vulnerabilities.md +++ b/doc/user/clusters/agent/vulnerabilities.md @@ -12,17 +12,19 @@ info: To determine the technical writer assigned to the Stage/Group associated w 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 **(ULTIMATE)** +## Enable operational container scanning -You can use operational container scanning -to scan container images in your cluster for security vulnerabilities. +You can use operational container scanning to scan container images in your cluster for security vulnerabilities. You +can enable the scanner to run on a cadence as configured via the agent, or setup scan execution policies within a +project that houses the agent. 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 `container_scanning` -configuration block to your agent configuration with a `cadence` field -containing a CRON expression for when the scans will be run. +### 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 will be run. ```yaml container_scanning: @@ -34,29 +36,67 @@ The `cadence` field is required. GitLab supports the following types of CRON syn - A daily cadence of once per hour at a specified hour, for example: `0 18 * * *` - A weekly cadence of once per week on a specified day and at a specified hour, for example: `0 13 * * 0` -It is possible that other elements of the CRON syntax will work in the cadence field, however, GitLab does not officially test or support them. +NOTE: +Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. + +NOTE: +The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. By default, operational container scanning will attempt to scan the workloads in all -namespaces for vulnerabilities. The `vulnerability_report` block has a `namespaces` +namespaces for vulnerabilities. You can set the `vulnerability_report` block with the `namespaces` field which can be used to restrict which namespaces are scanned. For example, -if you would like to scan only the `development`, `staging`, and `production` -namespaces, you can use this configuration: +if you would like to scan only the `default`, `kube-system` namespaces, you can use this configuration: ```yaml container_scanning: cadence: '0 0 * * *' vulnerability_report: namespaces: - - development - - staging - - production + - default + - kube-system ``` -## View cluster vulnerabilities +## Enable via scan execution policies + +To enable scanning of all images within your Kubernetes cluster via scan execution policies, we can use the +[scan execution policy editor](../../application_security/policies/scan-execution-policies.md#scan-execution-policy-editor) +in order to create a new schedule rule. -Prerequisite: +NOTE: +The Kubernetes agent must be running in your cluster in order to scan running container images + +Here is an example of a policy which enables operational container scanning within the cluster the Kubernetes agent is attached to: + +```yaml +- name: Enforce Container Scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces + enabled: true + rules: + - type: schedule + cadence: '0 10 * * *' + agents: + <agent-name>: + namespaces: + - 'default' + - 'kube-system' + actions: + - scan: container_scanning +``` -- You must have at least the Developer role. +The keys for a schedule rule are: + +- cadence (required): a [CRON expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) for when the scans will be run +- agents:<agent-name> (required): The name of the agent to use for scanning +- agents:<agent-name>:namespaces (optional): The Kubernetes namespaces to scan. If omitted, all namespaces will be scanned + +NOTE: +Other elements of the [CRON syntax](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm) may work in the cadence field if supported by the [cron](https://github.com/robfig/cron) we are using in our implementation, however, GitLab does not officially test or support them. + +NOTE: +The CRON expression is evaluated in [UTC](https://www.timeanddate.com/worldclock/timezone/utc) using the system-time of the Kubernetes-agent pod. + +You can view the complete schema within the [scan execution policy documentation](../../application_security/policies/scan-execution-policies.md#scan-execution-policies-schema). + +## View cluster vulnerabilities To view vulnerability information in GitLab: @@ -68,3 +108,6 @@ To view vulnerability information in GitLab:  This information can also be found under [operational vulnerabilities](../../../user/application_security/vulnerability_report/index.md#operational-vulnerabilities). + +NOTE: +You must have at least the Developer role. |