Kubernetes Agent configuration repository

Version history
  • Introduced in GitLab Premium 13.7.
  • Introduced in GitLab 13.11, the Kubernetes Agent became available on GitLab.com.
  • Introduced 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 in GitLab 14.3.
  • The GitLab Kubernetes Agent was moved to GitLab Free in 14.5.
caution
This feature might not be available to you. Check the version history note above for details.

The GitLab Kubernetes Agent integration supports hosting your configuration for multiple GitLab Kubernetes Agents in a single repository. These agents can be running in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster.

The Agent bootstraps with the GitLab installation URL and an authentication token, 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 of your Agent:

|- .gitlab
    |- agents
       |- my_agent_1
          |- config.yaml

Synchronize manifest projects

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 with Kubernetes resource definitions in YAML or JSON format. The Agent monitors each project you declare, and when the project changes, GitLab deploys the changes using the Agent.

To use multiple YAML files, specify a paths attribute in the gitops.manifest_projects section.

gitops:
  # Manifest projects are watched by the agent. Whenever a project changes,
  # GitLab deploys the changes using the agent.
  manifest_projects:
    # No authentication mechanisms are currently supported.
    # The `id` is a path to a Git repository with Kubernetes resource definitions
    # in YAML or JSON format.
  - id: gitlab-org/cluster-integration/gitlab-agent
    # Namespace to use if not set explicitly in object manifest.
    # Also used for inventory ConfigMap objects.
    default_namespace: my-ns
    # Paths inside of the repository to scan for manifest files.
    # Directories with names starting with a dot are ignored.
    paths:
      # Read all .yaml files from team1/app1 directory.
      # See https://github.com/bmatcuk/doublestar#about and
      # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules.
    - glob: '/team1/app1/*.yaml'
      # Read all .yaml files from team2/apps and all subdirectories
    - glob: '/team2/apps/**/*.yaml'
      # If 'paths' is not specified or is an empty list, the configuration below is used
    - glob: '/**/*.{yaml,yml,json}'
    # Reconcile timeout defines whether the applier should wait
    # until all applied resources have been reconciled, and if so,
    # how long to wait.
    reconcile_timeout: 3600s # 1 hour by default
    # Dry run strategy defines whether changes should actually be performed,
    # or if it is just talk and no action.
    # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/common/common.go#L68-L89
    # Can be: none, client, server
    dry_run_strategy: none # 'none' by default
    # Prune defines whether pruning of previously applied
    # objects should happen after apply.
    prune: true # enabled by default
    # Prune timeout defines whether we should wait for all resources
    # to be fully deleted after pruning, and if so, how long we should
    # wait.
    prune_timeout: 3600s # 1 hour by default
    # Prune propagation policy defines the deletion propagation policy
    # that should be used for pruning.
    # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470
    # Can be: orphan, background, foreground
    prune_propagation_policy: foreground # 'foreground' by default
    # Inventory policy defines if an inventory object can take over
    # objects that belong to another inventory object or don't
    # belong to any inventory object.
    # This is done by determining if the apply/prune operation
    # can go through for a resource based on the comparison
    # the inventory-id value in the package and the owning-inventory
    # annotation (config.k8s.io/owning-inventory) in the live object.
    # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66
    # Can be: must_match, adopt_if_no_inventory, adopt_all
    inventory_policy: must_match # 'must_match' by default

Using multiple manifest projects

Storing Kubernetes manifests in more than one repository can be handy, for example:

  • You may store manifests for different applications in separate repositories.
  • Different teams can work on manifests of independent projects in separate repositories.

To use multiple repositories as the source of Kubernetes manifests, specify them in the list of manifest_projects in your config.yaml:

gitops:
  manifest_projects:
  - id: group1/project1
  - id: group2/project2

Note that repositories are synchronized concurrently and independently from each other, which means that, ideally, there should not be any dependencies shared by these repositories. Storing a logical group of manifests in a single repository may work better than distributing it across several repositories.

You cannot use a single repository as a source for multiple concurrent synchronization operations. If such functionality is needed, you may use multiple agents reading manifests from the same repository.

Ensure not to specify “overlapping” globs to avoid synchronizing the same files more than once. This is detected by the GitLab Kubernetes Agent and leads to an error.

INCORRECT - both globs match *.yaml files in the root directory:

gitops:
  manifest_projects:
  - id: project1
    paths:
    - glob: '/**/*.yaml'
    - glob: '/*.yaml'

CORRECT - single globs matches all *.yaml files recursively:

gitops:
  manifest_projects:
  - id: project1
    paths:
    - glob: '/**/*.yaml'

Authorize groups to use an Agent

Introduced in GitLab 14.3.

On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to disable the feature flag named group_authorized_agents. On GitLab.com, this feature is available.

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.

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. To authorize a group to access the Agent through the CI/CD Tunnel, use the ci_access attribute in your config.yaml configuration file.

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.

To authorize a group:

  1. Edit your config.yaml file under the .gitlab/agents/<agent name> directory.
  2. Add the ci_access root attribute.
  3. Add the groups attribute into ci_access.
  4. Add the group id into groups, identifying the authorized group through its path.

For example:

ci_access:
  # This agent is accessible from CI jobs in projects in these groups
  groups:
  - id: group/subgroup

Surface network security alerts from cluster to GitLab

The GitLab Agent provides an integration with Cilium. To integrate, add a top-level cilium section to your config.yml file. Currently, the only configuration option is the Hubble relay address:

cilium:
  hubble_relay_address: "<hubble-relay-host>:<hubble-relay-port>"

If your Cilium integration was performed through GitLab Managed Apps or the cluster management template, you can use hubble-relay.gitlab-managed-apps.svc.cluster.local:80 as the address:

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 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:

starboard:
  vulnerability_reports:
    filters: []

The namespaces that are able to be scanned depend on the Starboard Operator install mode. 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
starboard:
  vulnerability_reports:
    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:

starboard:
  vulnerability_reports:
    filters:
      - kinds:
        - Deployment
        containers:
        - ruby
        - postgres
        - nginx

There is also a global namespaces field that applies to all filters:

starboard:
  vulnerability_reports:
    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 level according to the available options:

  • off
  • warning
  • error
  • info
  • debug

The log level defaults to info. You can change it by using a top-level observability section in the configuration file, for example:

observability:
  logging:
    level: debug