Skip to content

Commit a4c1a19

Browse files
embikembik
committed
Distribute existing content from README.md to docs
On-behalf-of: SAP <[email protected]> Signed-off-by: Marvin Beckers <[email protected]>
1 parent 7b8b085 commit a4c1a19

File tree

9 files changed

+217
-105
lines changed

9 files changed

+217
-105
lines changed

‎README.md‎

Lines changed: 4 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# kcp-dev/kcp-operator
22

33
[![Go Report Card](https://goreportcard.com/badge/github.com/kcp-dev/kcp-operator)](https://goreportcard.com/report/github.com/kcp-dev/kcp-operator)
4-
[![GitHub](https://img.shields.io/github/license/kcp-dev/kcp-operator)](https://img.shields.io/github/license/kcp-dev/kcp-operator)
5-
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/kcp-dev/kcp-operator?sort=semver)](https://img.shields.io/github/v/release/kcp-dev/kcp-operator?sort=semver)
6-
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator?ref=badge_shield)
4+
[![GitHub](https://img.shields.io/github/license/kcp-dev/kcp-operator)](https://github.com/kcp-dev/kcp-operator/blob/main/LICENSE)
5+
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/kcp-dev/kcp-operator?sort=semver)](https://github.com/kcp-dev/kcp-operator/releases/latest)
6+
<!--[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator?ref=badge_shield)-->
77

88
> [!WARNING]
99
> While kcp-operator is usable, the project is still in an early state. Please only use it if you know what you are doing. We recommend against using it in production setups right now.
@@ -29,115 +29,15 @@ The table below marks known support of a kcp version in kcp-operator versions.
2929

3030
[^1]: While we try to support kcp's `main` branch, this support is best effort and should not be used for deploying actual kcp instances.
3131

32-
## Installation
33-
34-
### Requirements
35-
36-
- [cert-manager](https://cert-manager.io/)
37-
38-
39-
### Helm Chart
40-
41-
A Helm chart for kcp-operator is maintained in [kcp-dev/helm-charts](https://github.com/kcp-dev/helm-charts/tree/main/charts/kcp-operator). To install it, first add the Helm repository:
42-
43-
```sh
44-
helm repo add kcp https://kcp-dev.github.io/helm-charts
45-
```
46-
47-
And then install the chart:
48-
49-
```sh
50-
helm upgrade --install --create-namespace --namespace kcp-operator kcp/kcp-operator kcp-operator
51-
```
52-
53-
## Quickstart
54-
55-
### RootShard
56-
57-
> [!CAUTION]
58-
> Never deploy etcd like below in production as it sets up an etcd instance without authentication or TLS.
59-
60-
Running a root shard requires a running etcd instance/cluster. You can set up a simple one via Helm:
61-
62-
```sh
63-
$ helm install etcd oci://registry-1.docker.io/bitnamicharts/etcd --set auth.rbac.enabled=false --set auth.rbac.create=false
64-
```
65-
66-
In addition, the root shard requires a reference to a cert-manager `Issuer` to issue its PKI CAs. You can create a self-signing one:
67-
68-
```sh
69-
$ kubectl apply -f ./config/samples/cert-manager/issuer.yaml
70-
```
71-
72-
Afterward, create the `RootShard` sample object:
73-
74-
```sh
75-
$ kubectl apply -f ./config/samples/v1alpha1_rootshard.yaml
76-
```
77-
78-
kcp-operator will create the necessary resources to start a `Deployment` of a kcp root shard.
79-
80-
## Architecture
81-
82-
### Certificate Management
83-
84-
The placeholders `$rootshard` and `$frontproxy` in the chart are used to denote the name of the corresponding operator resource.
85-
86-
```mermaid
87-
graph TB
88-
A([kcp-pki-bootstrap]):::issuer --> B(kcp-pki-ca):::ca
89-
B --> C([$rootshard-ca]):::issuer
90-
91-
C --> D(kcp-etcd-client-ca):::ca
92-
C --> E(kcp-etcd-peer-ca):::ca
93-
C --> F($rootshard-front-proxy-client-ca):::ca
94-
C --> G($rootshard-server-ca):::ca
95-
C --> H($rootshard-requestheaer-client-ca):::ca
96-
C --> I($rootshard-client-ca):::ca
97-
C --> J(kcp-service-account-ca):::ca
98-
99-
D --> K([kcp-etcd-client-issuer]):::issuer
100-
E --> L([kcp-etcd-peer-issuer]):::issuer
101-
F --> M([$rootshard-front-proxy-client-ca]):::issuer
102-
G --> N([$rootshard-server-ca]):::issuer
103-
H --> O([$rootshard-requestheader-client-ca]):::issuer
104-
I --> P([$rootshard-client-ca]):::issuer
105-
J --> Q([kcp-service-account-issuer]):::issuer
106-
107-
K --- K1(kcp-etcd):::cert --> K2(kcp-etcd-client):::cert
108-
L --> L1(kcp-etcd-peer):::cert
109-
M --> M1($rootshard-$frontproxy-admin-kubeconfig):::cert
110-
N --- N1(kcp):::cert --- N2($rootshard-$frontproxy-server):::cert --> N3(kcp-virtual-workspaces):::cert
111-
O --- O1($rootshard-$frontproxy-requestheader):::cert --> O2("(kcp-front-proxy-vw-client)"):::cert
112-
P --- P1($rootshard-$frontproxy-kubeconfig):::cert --> P2(kcp-internal-admin-kubeconfig):::cert
113-
Q --> Q1(kcp-service-account):::cert
114-
115-
B --> R([$rootshard2-ca]):::issuer
116-
R --> S(...):::ca
117-
118-
classDef issuer color:#77F
119-
classDef ca color:#F77
120-
classDef cert color:orange
121-
```
122-
12332
## Contributing
12433

125-
Thanks for taking the time to start contributing!
34+
Thanks for taking the time to start contributing! Please check out our [contributor documentation](https://docs.kcp.io/kcp-operator/main/contributing).
12635

12736
### Before You Start
12837

12938
* Please familiarize yourself with the [Code of Conduct][4] before contributing.
13039
* See [our contributor documentation][2] for instructions on the developer certificate of origin that we require.
13140

132-
### Running E2E tests locally
133-
134-
In order to run the E2E tests locally, you will need to setup cert-manager with the sample clusterissuer:
135-
136-
```sh
137-
helm upgrade --install --namespace cert-manager --create-namespace --version v1.16.2 --set crds.enabled=true cert-manager jetstack/cert-manager
138-
kubectl apply -n cert-manager --filename hack/ci/testdata/clusterissuer.yaml
139-
```
140-
14141
### Pull Requests
14242

14343
* We welcome pull requests. Feel free to dig through the [issues][1] and jump in.

‎docs/content/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,48 @@
11
# kcp-operator Documentation
22

3+
[![Go Report Card](https://goreportcard.com/badge/github.com/kcp-dev/kcp-operator)](https://goreportcard.com/report/github.com/kcp-dev/kcp-operator)
4+
[![GitHub](https://img.shields.io/github/license/kcp-dev/kcp-operator)](https://github.com/kcp-dev/kcp-operator/blob/main/LICENSE)
5+
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/kcp-dev/kcp-operator?sort=semver)](https://github.com/kcp-dev/kcp-operator/releases/latest)
6+
<!--[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkcp-dev%2Fkcp-operator?ref=badge_shield)-->
7+
8+
!!! warning
9+
While kcp-operator is usable, the project is still in an early state. Please only use it if you know what you are doing. We recommend against using it in production setups right now.
10+
11+
kcp-operator is a Kubernetes operator to deploy and run [kcp](https://github.com/kcp-dev/kcp) instances on a Kubernetes cluster. kcp is a horizontally scalable control plane for Kubernetes-like APIs.
12+
13+
## Features
14+
15+
- Create and update core components of a kcp setup (root shard, additional shards, front proxy)
16+
- Support for multi-shard deployments of kcp
17+
- Generate and refresh kubeconfigs for accessing kcp instances or specific shards
18+
19+
## Support Matrix
20+
21+
The table below marks known support of a kcp version in kcp-operator versions.
22+
23+
| kcp | `main` |
24+
| ------ | ------------------ |
25+
| `main` | :warning: |
26+
| 0.27.x | :white_check_mark: |
27+
28+
<small>While we try to support kcp's `main` branch, this support is best effort and should not be used for deploying actual kcp instances.</small>
29+
30+
## Contributing
31+
32+
We ❤️ our contributors! If you're interested in helping us out, please head over to our [Contributing](./contributing/index.md)
33+
guide.
34+
35+
## Getting in touch
36+
37+
There are several ways to communicate with us:
38+
39+
- The [`#kcp-dev` channel](https://app.slack.com/client/T09NY5SBT/C021U8WSAFK) in the [Kubernetes Slack workspace](https://slack.k8s.io).
40+
- Our mailing lists:
41+
- [kcp-dev](https://groups.google.com/g/kcp-dev) for development discussions.
42+
- [kcp-users](https://groups.google.com/g/kcp-users) for discussions among users and potential users.
43+
- By joining the kcp-dev mailing list, you should receive an invite to our bi-weekly community meetings.
44+
- See recordings of past community meetings on [YouTube](https://www.youtube.com/channel/UCfP_yS5uYix0ppSbm2ltS5Q).
45+
- The next community meeting dates are available via our [CNCF community group](https://community.cncf.io/kcp/).
46+
- Check the [community meeting notes document](https://docs.google.com/document/d/1PrEhbmq1WfxFv1fTikDBZzXEIJkUWVHdqDFxaY1Ply4) for future and past meeting agendas.
47+
- Browse the [shared Google Drive](https://drive.google.com/drive/folders/1FN7AZ_Q1CQor6eK0gpuKwdGFNwYI517M?usp=sharing) to share design docs, notes, etc.
48+
- Members of the kcp-dev mailing list can view this drive.

‎docs/development/design.md‎ renamed to ‎docs/content/contributing/architecture.md‎

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
1-
# Design Notes for kcp-operator
1+
---
2+
description: >
3+
An overview of architecture design decisions made for kcp-operator.
4+
---
5+
6+
# Architecture
27

38
kcp-operator is a kubebuilder/controller-runtime based collection of controllers that allow setting up complex kcp environments.
49

@@ -28,3 +33,44 @@ The above flow chart renders the following considerations:
2833
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.
2934

3035
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.
36+
37+
## Certificate Management
38+
39+
The placeholders `$rootshard` and `$frontproxy` in the chart are used to denote the name of the corresponding operator resource.
40+
41+
```mermaid
42+
graph TB
43+
A([kcp-pki-bootstrap]):::issuer --> B(kcp-pki-ca):::ca
44+
B --> C([$rootshard-ca]):::issuer
45+
46+
C --> D(kcp-etcd-client-ca):::ca
47+
C --> E(kcp-etcd-peer-ca):::ca
48+
C --> F($rootshard-front-proxy-client-ca):::ca
49+
C --> G($rootshard-server-ca):::ca
50+
C --> H($rootshard-requestheaer-client-ca):::ca
51+
C --> I($rootshard-client-ca):::ca
52+
C --> J(kcp-service-account-ca):::ca
53+
54+
D --> K([kcp-etcd-client-issuer]):::issuer
55+
E --> L([kcp-etcd-peer-issuer]):::issuer
56+
F --> M([$rootshard-front-proxy-client-ca]):::issuer
57+
G --> N([$rootshard-server-ca]):::issuer
58+
H --> O([$rootshard-requestheader-client-ca]):::issuer
59+
I --> P([$rootshard-client-ca]):::issuer
60+
J --> Q([kcp-service-account-issuer]):::issuer
61+
62+
K --- K1(kcp-etcd):::cert --> K2(kcp-etcd-client):::cert
63+
L --> L1(kcp-etcd-peer):::cert
64+
M --> M1($rootshard-$frontproxy-admin-kubeconfig):::cert
65+
N --- N1(kcp):::cert --- N2($rootshard-$frontproxy-server):::cert --> N3(kcp-virtual-workspaces):::cert
66+
O --- O1($rootshard-$frontproxy-requestheader):::cert --> O2("(kcp-front-proxy-vw-client)"):::cert
67+
P --- P1($rootshard-$frontproxy-kubeconfig):::cert --> P2(kcp-internal-admin-kubeconfig):::cert
68+
Q --> Q1(kcp-service-account):::cert
69+
70+
B --> R([$rootshard2-ca]):::issuer
71+
R --> S(...):::ca
72+
73+
classDef issuer color:#77F
74+
classDef ca color:#F77
75+
classDef cert color:orange
76+
```

‎docs/content/contributing/continuous-integration/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Continuous Integration (CI)
2+
3+
kcp-operator uses a combination of [GitHub Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions) and
4+
and [prow](https://github.com/kubernetes/test-infra/tree/master/prow) to automate the build process.
5+
6+
Here are the most important links:
7+
8+
- [.github/workflows/](https://github.com/kcp-dev/kcp-operator/blob/main/.github/workflows/) defines the Github Actions based jobs.
9+
- [kcp-dev/kcp/.prow.yaml](https://github.com/kcp-dev/kcp-operator/blob/main/.prow.yaml) defines the prow based jobs.
10+
11+
## Running E2E tests locally
12+
13+
In order to run the E2E tests locally, you will need to setup cert-manager with the sample clusterissuer:
14+
15+
```sh
16+
helm upgrade --install --namespace cert-manager --create-namespace --version v1.16.2 --set crds.enabled=true cert-manager jetstack/cert-manager
17+
kubectl apply -n cert-manager --filename hack/ci/testdata/clusterissuer.yaml
18+
```

‎docs/content/contributing/index.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Contributing
2+
3+
We are excited to see that you might be interested in contributing to kcp-operator!
4+
5+
For general guidance and rules for contributing to a kcp project (which kcp-operator is), please
6+
visit the [main contributor guide on docs.kcp.io/kcp](https://docs.kcp.io/kcp/main/contributing/).
7+
8+
All contributions to kcp projects require a Developer Certificate of Origin (DCO). Please check out
9+
the [Getting Started section](https://docs.kcp.io/kcp/main/contributing/getting-started/#developer-certificate-of-origin-dco)
10+
that explains how to set it correctly.
11+
12+
## Further Reading
13+
14+
{% include "partials/section-overview.html" %}

‎docs/content/contributing/releasing.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
description: >
3+
The release process for cutting new minor and patch releases.
4+
---
5+
16
# Release Process
27

38
The guide describes how to release a new version of the kcp-operator.

‎docs/content/setup/index.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Setup
2+
3+
## Requirements
4+
5+
- [cert-manager](https://cert-manager.io/)
6+
7+
## Helm Chart
8+
9+
A Helm chart for kcp-operator is maintained in [kcp-dev/helm-charts](https://github.com/kcp-dev/helm-charts/tree/main/charts/kcp-operator). To install it, first add the Helm repository:
10+
11+
```sh
12+
helm repo add kcp https://kcp-dev.github.io/helm-charts
13+
```
14+
15+
And then install the chart:
16+
17+
```sh
18+
helm upgrade --install --create-namespace --namespace kcp-operator kcp/kcp-operator kcp-operator
19+
```
20+
21+
## Further Reading
22+
23+
{% include "partials/section-overview.html" %}

‎docs/content/setup/quickstart.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
description: >
3+
Take your first steps after installing kcp-operator.
4+
---
5+
6+
# Quickstart
7+
8+
Make sure you have kcp-operator installed according to the instructions given in [Setup](./index.md).
9+
10+
## RootShard
11+
12+
!!! warning
13+
Never deploy etcd like below in production as it sets up an etcd instance without authentication or TLS.
14+
15+
Running a root shard requires a running etcd instance/cluster. You can set up a simple one via Helm:
16+
17+
```sh
18+
$ helm install etcd oci://registry-1.docker.io/bitnamicharts/etcd --set auth.rbac.enabled=false --set auth.rbac.create=false
19+
```
20+
21+
In addition, the root shard requires a reference to a cert-manager `Issuer` to issue its PKI CAs. You can create a self-signing one:
22+
23+
```yaml
24+
apiVersion: cert-manager.io/v1
25+
kind: Issuer
26+
metadata:
27+
name: selfsigned
28+
spec:
29+
selfSigned: {}
30+
```
31+
32+
Afterward, create a `RootShard` object. You can find documentation for it in the [CRD reference](../reference/crd/operator.kcp.io/rootshards.md).
33+
34+
```yaml
35+
apiVersion: operator.kcp.io/v1alpha1
36+
kind: RootShard
37+
metadata:
38+
name: root
39+
spec:
40+
external:
41+
# replace the hostname with the external DNS name for your kcp instance
42+
hostname: example.operator.kcp.io
43+
port: 6443
44+
certificates:
45+
issuerRef:
46+
group: cert-manager.io
47+
kind: Issuer
48+
name: selfsigned
49+
cache:
50+
embedded:
51+
enabled: true
52+
etcd:
53+
endpoints:
54+
- http://etcd.default.svc.cluster.local:2379
55+
```
56+
57+
kcp-operator will create the necessary resources to start a `Deployment` of a kcp root shard.

‎docs/mkdocs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,9 @@ markdown_extensions:
122122
- pymdownx.superfences
123123
# Enable note/warning/etc. callouts
124124
- admonition
125+
- pymdownx.emoji:
126+
emoji_index: !!python/name:material.extensions.emoji.twemoji
127+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
125128

126129
# Live reload if any of these change when running 'mkdocs serve'
127130
watch:

0 commit comments

Comments
 (0)