diff --git a/docs/content/concepts/terminology.md b/docs/content/concepts/terminology.md index 966e4b82431..9b5d9bad443 100644 --- a/docs/content/concepts/terminology.md +++ b/docs/content/concepts/terminology.md @@ -47,6 +47,23 @@ tooling such as kubectl and client-go. We're working with the upstream community on adding support for the multi-cluster setups to the Kubernetes controller-runtime. +```mermaid +graph TB + subgraph KCP_Server ["KCP Server"] + KS[Kubernetes API Server
Core Components] + KCP_Extensions[KCP Extensions
APIBinding, Workspace,
WorkspaceType, Partition, etc...] + end + + KS --> KCP_Extensions + KCP_Extensions --> KS + + User1[User/Team A] --> KCP_Server + User2[User/Team B] --> KCP_Server + Kubectl[kubectl] --> KCP_Server + Client[Kubernetes Client] --> KCP_Server + +``` + ## Logical Cluster A logical cluster is a way to subdivide a kcp server and its `etcd` datastore into multiple clusters without requiring @@ -85,9 +102,37 @@ such as Workspace, to create logical cluster. unless stated otherwise, what applies to a workspace applies to a logical cluster as well, because Workspaces are abstractions built on top of logical clusters. +```mermaid +graph TB + subgraph KCP_Server ["KCP Server"] + subgraph WorkspaceLayer [Workspace Layer] + WS1[Workspace: bobs
Type: organization
Phase: Ready] + WS2[Workspace: alice
Type: universal
Phase: Ready] + end + + subgraph LogicalClusterLayer [Logical Cluster Layer - Auto-created] + LC1[Logical Cluster
:root:bobs] + LC2[Logical Cluster
:root:alice] + end + + subgraph StorageLayer [Storage Layer] + ETCD[(etcd
Single Storage Cluster)] + end + end + + WS1 -->|auto-creates| LC1 + WS2 -->|auto-creates| LC2 + + LC1 -->|stores data in
/bobs/ prefix| ETCD + LC2 -->|stores data in
/alice/ prefix| ETCD + + User1[User: Bob] -->|kubectl ws use :root:bobs| LC1 + User2[User: Alice] -->|kubectl ws use :root:alice| LC2 +``` + ## Workspace -A Workspace is an abstraction used to create and provision logical clusters. Aside from creating the LogicalCluster +A Workspace is an abstraction used to create and provision logical clusters. Aside from creating the `LogicalCluster` object, the responsibility of a Workspace is to initialize the given logical cluster by installing the required resources for the given workspace type, creating the initial objects, and more. @@ -108,6 +153,22 @@ A Workspace's path is based on the hierarchy and the user provided name. For exa The workspace path is used for building the workspace URL and for accessing the workspace via the `ws` kubectl plugin. More information, including examples, can be found in the the [Workspaces document](workspaces/index.md). +```mermaid +graph TB + Root[Root Workspace
root] + + Root --> Corp1[Acme Corp
root:acme-corp] + Root --> Corp2[Startup XYZ
root:startup-xyz] + + Corp1 --> Eng[Engineering
root:acme-corp:engineering] + Corp1 --> Mkt[Marketing
root:acme-corp:marketing] + + Eng --> Team1[App Team 1
root:acme-corp:engineering:app-team-1] + Eng --> Team2[App Team 2
root:acme-corp:engineering:app-team-2] + Eng --> Platform[Platform
root:acme-corp:engineering:platform] + + Corp2 --> Dev[Development
root:startup-xyz:dev] +``` ### Workspace Types @@ -122,6 +183,29 @@ By default, each workspace has the [built-in APIs installed and available to its More information, including a list of Workspace Types and examples, can be found in the [Workspace Types document](workspaces/workspace-types.md). +```mermaid +graph LR + subgraph Types ["Workspace Types (Templates)"] + OrgType[organization
Pre-configured for organizational structure] + UniversalType[universal
General-purpose workspace] + end + + subgraph Instances ["Workspace Instances"] + OrgWS[wildwestdebug
TYPE: organization] + UniversalWS[my-app-workspace
TYPE: universal] + end + + subgraph Users ["User Personas"] + Teams[Teams & Organizations] + Developers[Individual Developers] + end + + OrgType -.->|instantiated as| OrgWS + UniversalType -.->|instantiated as| UniversalWS + + OrgWS -.->|used by| Teams + UniversalWS -.->|used by| Developers +``` ## Virtual Workspaces @@ -187,6 +271,38 @@ The general workflow is: - Users can now create API resources of those types in their workspace. You can build and run controllers that are going to reconcile those resources across different workspaces. +```mermaid +graph TB + Title[API Exporting/Binding = Sharing Tools Between Workspaces/Logical Clusters] + + subgraph ToolOwner [Infra: Has Unique Tools] + Infra[Infra Workspace] + SpecialTool[Special Database API
PostgreSQL Operator] + APIExport[API Export
I'm sharing my Database tool] + end + + subgraph ToolUsers [App Teams - Need Tools] + AppTeam1[App Team 1 Workspace] + AppTeam2[App Team 2 Workspace] + APIBinding1[API Binding
I want to use Database tool] + APIBinding2[API Binding
I want to use Database tool] + end + + Title --> ToolOwner + + Infra --> SpecialTool + SpecialTool --> APIExport + + APIExport -->|shares with| APIBinding1 + APIExport -->|shares with| APIBinding2 + + APIBinding1 --> AppTeam1 + APIBinding2 --> AppTeam2 + + AppTeam1 --> CanUse1[App Team 1:
can now create PostgreSQL databases] + AppTeam2 --> CanUse2[App Team 2:
can now create PostgreSQL databases] +``` + ## Shard A failure domain within the larger control plane service that cuts across the primary functionality. Most distributed @@ -218,3 +334,16 @@ available shards. !!! note Depending on how you setup kcp, you might have front proxy running even though you don't have a sharded setup. + +```mermaid +graph TB + Users[All Users & kubectl] --> FrontProxy[kcp-front-proxy
Smart Router] + + FrontProxy --> Shard1[Shard 1
Workspaces: frontend-team, mobile-team] + FrontProxy --> Shard2[Shard 2
Workspaces: backend-team, data-team] + FrontProxy --> Shard3[Shard 3
Workspaces: platform-team, infra-team] + + Shard1 --> etcd1[etcd Storage
Frontend & Mobile data] + Shard2 --> etcd2[etcd Storage
Backend & Data team data] + Shard3 --> etcd3[etcd Storage
Platform & Infra data] +```