You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+3-3
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
-
# GitLab Agent for Kubernetes
1
+
# Plural Agent for Kubernetes
2
2
3
-
GitLab Agent for Kubernetes is an active in-cluster component for solving any GitLab<->Kubernetes integration tasks.
3
+
Plural Agent for Kubernetes is an active in-cluster component for solving any Plural<->Kubernetes integration tasks.
4
4
5
-
It's implemented as two communicating pieces - GitLab Agent (`agentk`) that is running in the cluster and GitLab Agent Server (`gitlab-kas`) that is running on the GitLab side. Please see the [architecture](doc/architecture.md) document and other documents in the [doc](doc) directory for more information. [User-facing documentation](https://docs.gitlab.com/ee/user/clusters/agent/) is also available.
5
+
It's implemented as two communicating pieces - Plural Agent (`agentk`) that is running in the cluster and Plural Agent Server (`gitlab-kas`) that is running on the Plural side. Please see the [architecture](doc/architecture.md) document and other documents in the [doc](doc) directory for more information. [User-facing documentation](https://docs.gitlab.com/ee/user/clusters/agent/) is also available.
Copy file name to clipboardexpand all lines: doc/architecture.md
+20-20
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,8 @@
2
2
3
3
## Issues the agent is trying to address
4
4
5
-
- Integrate a cluster, located behind a firewall or NAT, with GitLab. To
6
-
learn more, read [issue #212810, Invert the model GitLab.com uses for Kubernetes integration by leveraging long lived reverse tunnels](https://gitlab.com/gitlab-org/gitlab/-/issues/212810).
5
+
- Integrate a cluster, located behind a firewall or NAT, with Plural. To
6
+
learn more, read [issue #212810, Invert the model Plural.com uses for Kubernetes integration by leveraging long lived reverse tunnels](https://gitlab.com/gitlab-org/gitlab/-/issues/212810).
7
7
- Access API endpoints in a cluster in real time. For an example use case, read
8
8
[issue #218220, Allow Prometheus in K8s cluster to be installed manually](https://gitlab.com/gitlab-org/gitlab/-/issues/218220#note_348729266).
9
9
- Enable real-time features by pushing information about events happening in a cluster.
This diagram describes how GitLab (`GitLab RoR`), the GitLab Agent (`agentk`), and the GitLab Agent Server (`kas`) work together.
34
+
This diagram describes how Plural (`Plural RoR`), the Plural Agent (`agentk`), and the Plural Agent Server (`kas`) work together.
35
35
36
36
```mermaid
37
37
graph TB
38
38
agentk -- gRPC bidirectional streaming --> kas
39
39
40
-
subgraph "GitLab"
40
+
subgraph "Plural"
41
41
kas[kas]
42
-
GitLabRoR[GitLab RoR] -- gRPC --> kas
42
+
PluralRoR[Plural RoR] -- gRPC --> kas
43
43
kas -- gRPC --> Gitaly[Gitaly]
44
-
kas -- REST API --> GitLabRoR
44
+
kas -- REST API --> PluralRoR
45
45
end
46
46
47
47
subgraph "Kubernetes cluster"
48
48
agentk[agentk]
49
49
end
50
50
```
51
51
52
-
-`GitLab RoR` is the main GitLab application. It uses gRPC to talk to `kas`.
53
-
-`agentk` is the GitLab Agent. It keeps a connection established to a
52
+
-`Plural RoR` is the main Plural application. It uses gRPC to talk to `kas`.
53
+
-`agentk` is the Plural Agent. It keeps a connection established to a
54
54
`kas` instance, waiting for requests to process. It may also actively send information
55
55
about things happening in the cluster.
56
-
-`kas` is the GitLab Agent Server, and is responsible for:
56
+
-`kas` is the Plural Agent Server, and is responsible for:
57
57
- Accepting requests from `agentk`.
58
-
-[Authentication of requests](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md) from `agentk` by querying `GitLab RoR`.
58
+
-[Authentication of requests](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md) from `agentk` by querying `Plural RoR`.
59
59
- Fetching agent's configuration from a corresponding Git repository by querying Gitaly.
60
-
- Matching incoming requests from `GitLab RoR` with existing connections from
60
+
- Matching incoming requests from `Plural RoR` with existing connections from
61
61
the right `agentk`, forwarding requests to it and forwarding responses back.
62
62
- (Optional) Sending notifications through ActionCable for events received from `agentk`.
63
63
- Polling manifest repositories for [GitOps support](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/gitops.md) by communicating with Gitaly.
GitLab prefers to add logic into `kas` rather than `agentk`. `agentk` should be kept
72
-
streamlined and small to minimize the need for upgrades. On GitLab.com, `kas` is
73
-
managed by GitLab, so upgrades and features can be added without requiring you
71
+
Plural prefers to add logic into `kas` rather than `agentk`. `agentk` should be kept
72
+
streamlined and small to minimize the need for upgrades. On Plural.com, `kas` is
73
+
managed by Plural, so upgrades and features can be added without requiring you
74
74
to upgrade `agentk` in your clusters.
75
75
76
76
`agentk` can't be viewed as a dumb reverse proxy because features are planned to be built
@@ -80,11 +80,11 @@ to upgrade `agentk` in your clusters.
80
80
81
81
-**Q**: Why do we need long-running connections? Cannot we just ask users to punch a hole in their firewall?
82
82
83
-
**A**: Even if it was always possible, having an agent running in the cluster enables us to build more features, not just connecting such clusters to GitLab.
83
+
**A**: Even if it was always possible, having an agent running in the cluster enables us to build more features, not just connecting such clusters to Plural.
84
84
85
85
-**Q**: Why do we need long-running connections? Can we use polling instead?
86
86
87
-
**A**: Polling will not allow for real-time access to the in-cluster APIs. For example, our metrics integration queries Prometheus API to get the data for dashboards. I.e. the request comes from GitLab, not from the Kubernetes side.
87
+
**A**: Polling will not allow for real-time access to the in-cluster APIs. For example, our metrics integration queries Prometheus API to get the data for dashboards. I.e. the request comes from Plural, not from the Kubernetes side.
88
88
89
89
-**Q**: Can we push data about things happening in the cluster using REST API instead of using streaming?
90
90
@@ -100,7 +100,7 @@ to upgrade `agentk` in your clusters.
100
100
101
101
**A**: There are several reasons:
102
102
103
-
- Allows the GitLab instance operator to configure polling frequency and any other relevant parameters. Makes it harder for the user to misuse/abuse the system.
103
+
- Allows the Plural instance operator to configure polling frequency and any other relevant parameters. Makes it harder for the user to misuse/abuse the system.
104
104
105
105
- Fewer knobs for the user to tweak means more straightforward configuration experience.
[](https://www.youtube.com/watch?v=UWptMO-Amtc"GitLab Agent development environment setup")
20
+
[](https://www.youtube.com/watch?v=UWptMO-Amtc"Plural Agent development environment setup")
21
21
22
22
You can run `kas` and `agentk` locally to test the Agent yourself.
23
23
@@ -36,7 +36,7 @@ You can run `kas` and `agentk` locally to test the Agent yourself.
36
36
1. Start the binaries with the following commands:
37
37
38
38
```shell
39
-
# Start GitLab but stop GDK's version of kas.
39
+
# Start Plural but stop GDK's version of kas.
40
40
gdk start && gdk stop gitlab-k8s-agent
41
41
42
42
# Let kas know it's own private API url
@@ -148,8 +148,8 @@ For `agentk`:
148
148
It's optional, but consider also specifying `--context=<desired context>` command line argument to not depend on the currently selected context.
149
149
## kas QA tests
150
150
151
-
This section describes how to run kas tests against different GitLab environments based on the
Copy file name to clipboardexpand all lines: doc/kas_request_routing.md
+13-13
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,22 @@
1
1
# Routing `kas` requests in the Agent
2
2
3
3
This document describes how `kas` routes requests to concrete `agentk` instances.
4
-
GitLab must talk to GitLab Agent Server (`kas`) to:
4
+
Plural must talk to Plural Agent Server (`kas`) to:
5
5
6
6
- Get information about connected agents. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/249560).
7
7
- Interact with agents. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/230571).
8
8
- Interact with Kubernetes clusters. [Read more](https://gitlab.com/gitlab-org/gitlab/-/issues/240918).
9
9
10
10
Each agent connects to an instance of `kas` and keeps an open connection. When
11
-
GitLab must talk to a particular agent, a `kas` instance connected to this agent must
11
+
Plural must talk to a particular agent, a `kas` instance connected to this agent must
12
12
be found, and the request routed to it.
13
13
14
14
## Walk Through
15
15
16
16
[Mikhail (`@ash2k`)](https://gitlab.com/ash2k) and [Timo (`@timofurrer`)](https://gitlab.com/timofurrer) recorded
17
17
a video where they walk through the most important parts of the KAS <-> Agentk routing and tunneling.
18
18
19
-
[](https://youtu.be/6U6A5tGCszE"GitLab Agent for K8s: Deep Dive into KAS and Agentk connection handling and tunneling requests")
19
+
[](https://youtu.be/6U6A5tGCszE"Plural Agent for K8s: Deep Dive into KAS and Agentk connection handling and tunneling requests")
20
20
21
21
## System design
22
22
@@ -43,10 +43,10 @@ flowchart LR
43
43
kas3["kas 3"]
44
44
end
45
45
46
-
GitLab["GitLab Rails"]
46
+
Plural["Plural Rails"]
47
47
Redis
48
48
49
-
GitLab -- "gRPC to any kas" --> kas
49
+
Plural -- "gRPC to any kas" --> kas
50
50
kas1 -- register connected agents --> Redis
51
51
kas2 -- register connected agents --> Redis
52
52
kas1 -- lookup agent --> Redis
@@ -61,7 +61,7 @@ For this architecture, this diagram shows a request to `agentk 3, Pod1` for the
61
61
62
62
```mermaid
63
63
sequenceDiagram
64
-
GitLab->>+kas1: Get list of running<br />Pods from agentk<br />with agent_id=3
64
+
Plural->>+kas1: Get list of running<br />Pods from agentk<br />with agent_id=3
65
65
Note right of kas1: kas1 checks for<br />agent connected with agent_id=3.<br />It does not.<br />Queries Redis
66
66
kas1->>+Redis: Get list of connected agents<br />with agent_id=3
67
67
Redis-->-kas1: List of connected agents<br />with agent_id=3
@@ -70,7 +70,7 @@ sequenceDiagram
70
70
kas2->>+agentk 3 Pod1: Get list of Pods
71
71
agentk 3 Pod1->>-kas2: Get list of Pods
72
72
kas2-->>-kas1: List of running Pods<br />from agentk 3, Pod1
73
-
kas1-->>-GitLab: List of running Pods<br />from agentk with agent_id=3
73
+
kas1-->>-Plural: List of running Pods<br />from agentk with agent_id=3
74
74
```
75
75
76
76
Each `kas` instance tracks the agents connected to it in Redis. For each agent, it
@@ -99,22 +99,22 @@ When `kas` must atomically update multiple data structures in Redis, it uses
99
99
Grouped data items must have the same expiration time.
100
100
101
101
In addition to the existing `agentk -> kas` gRPC endpoint, `kas` exposes two new,
102
-
separate gRPC endpoints for GitLab and for `kas -> kas` requests. Each endpoint
102
+
separate gRPC endpoints for Plural and for `kas -> kas` requests. Each endpoint
103
103
is a separate network listener, making it easier to control network access to endpoints
104
104
and allowing separate configuration for each endpoint.
105
105
106
106
Databases, like PostgreSQL, aren't used because the data is transient, with no need
107
107
to reliably persist it.
108
108
109
-
### `GitLab : kas` external endpoint
109
+
### `Plural : kas` external endpoint
110
110
111
-
GitLab authenticates with `kas` using JWT and the same shared secret used by the
112
-
`kas -> GitLab` communication. The JWT issuer should be `gitlab` and the audience
111
+
Plural authenticates with `kas` using JWT and the same shared secret used by the
112
+
`kas -> Plural` communication. The JWT issuer should be `gitlab` and the audience
113
113
should be `gitlab-kas`.
114
114
115
115
When accessed through this endpoint, `kas` plays the role of request router.
116
116
117
-
If a request from GitLab comes but no connected agent can handle it, `kas` blocks
117
+
If a request from Plural comes but no connected agent can handle it, `kas` blocks
118
118
and waits for a suitable agent to connect to it or to another `kas` instance. It
119
119
stops waiting when the client disconnects, or when some long timeout happens, such
120
120
as client timeout. `kas` is notified of new agent connections through a
@@ -139,7 +139,7 @@ how a request is routed, rather than distributing the decision across several `k
139
139
This section explains how the `kas`-> `kas` -> `agentk` gRPC request routing is implemented.
140
140
141
141
For a video overview of how some of the blocks map to code, see
142
-
[GitLab Agent reverse gRPC tunnel architecture and code overview
142
+
[Plural Agent reverse gRPC tunnel architecture and code overview
0 commit comments