Skip to content

Commit b80d7bb

Browse files
xrstfxrstf
committed
introduce arch section in the docs, write some infos about the new internal proxy
On-behalf-of: @SAP [email protected]
1 parent 6c09b2c commit b80d7bb

File tree

8 files changed

+142
-77
lines changed

8 files changed

+142
-77
lines changed

‎docs/content/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
nav:
22
- Home: README.md
33
- Setup: setup
4+
- Architecture: architecture
45
- Reference: reference
56
- Contributing: contributing

‎docs/content/architecture/.pages‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
nav:
2+
- index.md
3+
- basics.md
4+
- front-proxy.md
5+
- Certificate Management: pki.md

‎docs/content/architecture/basics.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
description: >
3+
A general overview over the resources provided by the kcp-operator.
4+
---
5+
6+
# Basics
7+
8+
kcp-operator ships with a number of resources that, together, can be used to create a kcp installation.
9+
10+
## Resource Relationships
11+
12+
```mermaid
13+
flowchart TD
14+
FrontProxy -- ObjRef (n:1)--> RootShard
15+
Shard --ObjRef (n:1)--> RootShard
16+
RootShard --ObjRef (1:1, optional)--> CacheServer
17+
Shard --ObjRef (n:1, optional)--> CacheServer
18+
Kubeconfig --ObjRef (n:1)-->Shard
19+
Kubeconfig --ObjRef (n:1)-->RootShard
20+
Kubeconfig --ObjRef (n:1)-->FrontProxy
21+
```
22+
23+
### `RootShard` & `Shard`
24+
25+
Each kcp installation consists at the minimum of one root shard and one [front-proxy](front-proxy.md), but you can add additional "regular" shards to scale kcp horizontally.
26+
27+
Creating a new `RootShard` object means creating a new kcp installation, as you cannot have more than one root shard in one kcp installation, however multiple installations can run in the same Kubernetes namespace (though this is not necessarily recommended). The `RootShard` object's name is not really important inside kcp itself.
28+
29+
Each additional shard is created by creating a `Shard` object, which will reference the root shard it belongs to. Shard names are relevant in kcp, as each shard will register itself on its root shard, using the name of the `Shard` object.
30+
31+
### `FrontProxy`
32+
33+
The kcp front-proxy can be used to provide access to either a whole or a subset of a kcp installation. Its main purpose is to act as a gateway, since it builds up a runtime map of all existing workspaces across all shards that it targets, so it knows where to route a request to `/clusters/root:my-team` to the shard where the logicalcluster for that workspace resides.
34+
35+
A kcp installation can contain multiple front-proxies with different settings; one might perform additional authentication while another might pass unauthenticated requests to the shards (which will then perform their own authentication).
36+
37+
For developing controllers against kcp, it is often necessary to access the shards directly, so front-proxies are not the only way to access kcp.
38+
39+
### `Kubeconfig`
40+
41+
Kubeconfigs allow the easy creation of credentials to access kcp. As a sharded system, kcp relies on client certificate authentication and the kcp-operator will ensure the correct certificates are generated and then neatly wrapped up in ready-to-use kubeconfig Secrets.
42+
43+
Kubeconfigs can be configured to point to a specific shard or to a front-proxy instance, which affects which client CA is used to generate the certificates.
44+
45+
## Cross-Namespace/Cluster References
46+
47+
Due to the potential "global" nature of a kcp setup it might be necessary to run kcp-operator on multiple clusters while attempting to form one single kcp setup with multiple shards and front proxies.
48+
49+
To make this possible, resources with object references (see above) could have a secondary way of reading necessary configuration (instead of a `corev1.LocalObjectReference`). This could be a reference to a `ConfigMap` or a `Secret` (to be determined) which are automatically generated for various resource types. A sync process (outside of the kcp-operator) could then sync the `ConfigMap` (or the `Secret`, or a custom resource type) across namespaces or even clusters, where e.g. a `Shard` object references a `Secret` which was generated for a `RootShard` on another cluster.

‎docs/content/architecture/front-proxy.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: >
3+
Explains how the kcp front-proxy can be used to ingest traffic.
4+
---
5+
6+
# kcp front-proxy
7+
8+
The kcp front-proxy can be used to provide access to either a whole or a subset of a kcp installation. Its main purpose is to act as a gateway, since it builds up a runtime map of all existing workspaces across all shards that it targets, so it knows where to route a request to `/clusters/root:my-team` to the shard where the logicalcluster for that workspace resides.
9+
10+
!!! warning
11+
Currently it is required to have at least one front-proxy in a kcp installation, which must be reachable at the hostname also configured as the external name for the root shard. Without a front-proxy, new workspaces will not be able to be scheduled.
12+
13+
The front-proxy must exist even if there is only one shard (the RootShard). This is a requirement of kcp, not the operator itself.
14+
15+
## Usage
16+
17+
As mentioned above, your first front-proxy should have the same external hostname as is configured on the root shard. Every additional front-proxy can be served at arbitrary hostnames. Since the CA used to generate the serving certs for front-proxies is embedded in kubeconfigs generated by the kcp-operator, there is no need to use well-known CAs or ACME providers like Let's Encrypt, unless you intend to also access kcp from systems that do not use kubeconfig files and have no way to configure additional CAs.
18+
19+
## Mode of Operation
20+
21+
The kcp front-proxy will build up a runtime map of all shards, workspaces and logicalclusters in a kcp installation. For this it connects dynamically to each shard individually and begins to watch the necessary resources. This runtime index is then used to route incoming requests to their target shards.
22+
23+
The proxy can optionally perform authentication, for example using OIDC, and pass authentication information (like username and groups) on to the shard (via HTTP headers). This can be configured for each front-proxy individually. If no authentication is performed, the requests will be passed unauthenticated to their target shards, where then authentication happens.
24+
25+
## RootShard Proxy
26+
27+
The kcp-operator will deploy an internal front-proxy for every `RootShard` (i.e. one for each kcp installation). This internal proxy is solely used by the operator itself to allow it to resolve workspace paths to logicalclusters and provision resources inside those workspaces.
28+
29+
The reason a standalone proxy is deployed is that the admin-configured front-proxies (based on `FrontProxy` objects) can be configured to drop sensitive groups, like `system:masters`, from incoming requests. This is a security measure, ensuring no super admin access is possible to kcp from the outside.

‎docs/content/architecture/index.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Architecture
2+
3+
This section describes how the kcp-operator is designed and meant to be used.
4+
5+
## Overview
6+
7+
- [Basics](basics.md) – A general overview over the resources provided by the kcp-operator.
8+
- [front-proxy](front-proxy.md) – Explains how the kcp front-proxy can be used to ingest traffic.
9+
- [Certificate Management](pki.md) – This page describes the various CAs and certificates used in a kcp installation.
10+
<!--
11+
- [Sharding](sharding.md) – How `RootShards` and `Shards` work together to create a scalable kcp setup.
12+
- [Kubeconfigs](kubeconfigs.md) – Shows how `Kubeconfig` objects can be used to provide credentials to kcp.
13+
-->

‎docs/content/architecture/pki.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
description: >
3+
Explains the various certificate authorities and certificates used by the kcp-operator.
4+
---
5+
6+
## kcp PKI
7+
8+
The placeholders `$rootshard` and `$frontproxy` in the chart are used to denote the name of the corresponding operator resource.
9+
10+
```mermaid
11+
graph TB
12+
A([kcp-pki-bootstrap]):::issuer --> B(kcp-pki-ca):::ca
13+
B --> C([$rootshard-ca]):::issuer
14+
15+
C --> D(kcp-etcd-client-ca):::ca
16+
C --> E(kcp-etcd-peer-ca):::ca
17+
C --> F($rootshard-front-proxy-client-ca):::ca
18+
C --> G($rootshard-server-ca):::ca
19+
C --> H($rootshard-requestheaer-client-ca):::ca
20+
C --> I($rootshard-client-ca):::ca
21+
C --> J(kcp-service-account-ca):::ca
22+
23+
D --> K([kcp-etcd-client-issuer]):::issuer
24+
E --> L([kcp-etcd-peer-issuer]):::issuer
25+
F --> M([$rootshard-front-proxy-client-ca]):::issuer
26+
G --> N([$rootshard-server-ca]):::issuer
27+
H --> O([$rootshard-requestheader-client-ca]):::issuer
28+
I --> P([$rootshard-client-ca]):::issuer
29+
J --> Q([kcp-service-account-issuer]):::issuer
30+
31+
K --- K1(kcp-etcd):::cert --> K2(kcp-etcd-client):::cert
32+
L --> L1(kcp-etcd-peer):::cert
33+
M --> M1($rootshard-$frontproxy-admin-kubeconfig):::cert
34+
N --- N1(kcp):::cert --- N2($rootshard-$frontproxy-server):::cert --> N3(kcp-virtual-workspaces):::cert
35+
O --- O1($rootshard-$frontproxy-requestheader):::cert --> O2("(kcp-front-proxy-vw-client)"):::cert
36+
P --- P1($rootshard-$frontproxy-kubeconfig):::cert --> P2(kcp-internal-admin-kubeconfig):::cert
37+
Q --> Q1(kcp-service-account):::cert
38+
39+
B --> R([$rootshard2-ca]):::issuer
40+
R --> S(...):::ca
41+
42+
classDef issuer color:#77F
43+
classDef ca color:#F77
44+
classDef cert color:orange
45+
```

‎docs/content/contributing/.pages‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
nav:
22
- index.md
33
- local-setup.md
4-
- architecture.md
54
- releasing.md
65
- continuous-integration

‎docs/content/contributing/architecture.md‎

Lines changed: 0 additions & 76 deletions
This file was deleted.

0 commit comments

Comments
 (0)