Kubernetes Agent development (PREMIUM ONLY)

This page contains developer-specific information about the GitLab Kubernetes Agent. End-user documentation about the GitLab Kubernetes Agent is also available.

The agent can help you perform tasks like these:

Architecture of the Kubernetes Agent

The GitLab Kubernetes Agent and the GitLab Kubernetes Agent Server use bidirectional streaming to allow the connection acceptor (the gRPC server, GitLab Kubernetes Agent Server) to act as a client. The connection acceptor sends requests as gRPC replies. The client-server relationship is inverted because the connection must be initiated from inside the Kubernetes cluster to bypass any firewall or NAT the cluster may be located behind. To learn more about this inversion, read issue #212810.

This diagram describes how GitLab (GitLab RoR), the GitLab Kubernetes Agent (agentk), and the GitLab Kubernetes Agent Server (kas) work together.

graph TB
  agentk -- gRPC bidirectional streaming --> kas

  subgraph "GitLab"
  kas[kas]
  GitLabRoR[GitLab RoR] -- gRPC --> kas
  kas -- gRPC --> Gitaly[Gitaly]
  kas -- REST API --> GitLabRoR
  end

  subgraph "Kubernetes cluster"
  agentk[agentk]
  end
  • GitLab RoR is the main GitLab application. It uses gRPC to talk to kas.
  • agentk is the GitLab Kubernetes Agent. It keeps a connection established to a kas instance, waiting for requests to process. It may also actively send information about things happening in the cluster.
  • kas is the GitLab Kubernetes Agent Server, and is responsible for:
    • Accepting requests from agentk.
    • Authentication of requests from agentk by querying GitLab RoR.
    • Fetching agent's configuration from a corresponding Git repository by querying Gitaly.
    • Matching incoming requests from GitLab RoR with existing connections from the right agentk, forwarding requests to it and forwarding responses back.
    • (Optional) Sending notifications through ActionCable for events received from agentk.
    • Polling manifest repositories for GitOps support by communicating with Gitaly.

To learn more about how the repository is structured, see GitLab Kubernetes Agent repository overview.

Guiding principles

GitLab prefers to add logic into kas rather than agentk. agentk should be kept streamlined and small to minimize the need for upgrades. On GitLab.com, kas is managed by GitLab, so upgrades and features can be added without requiring you to upgrade agentk in your clusters.

agentk can't be viewed as a dumb reverse proxy because features are planned to be built on top of the cache with informers.