Skip to content

Commit 4af27d9

Browse files
jnummelinjnummelin
authored
Merge pull request #156 from jnummelin/docs/generate-reference
Add generated reference docs for custom resources
2 parents 81f4196 + dfa96b2 commit 4af27d9

File tree

8 files changed

+7857
-36
lines changed

8 files changed

+7857
-36
lines changed

‎Makefile‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ $(LOCALBIN):
1212
KUSTOMIZE ?= $(LOCALBIN)/kustomize
1313
CONTROLLER_GEN ?= $(LOCALBIN)/controller-gen
1414
ENVTEST ?= $(LOCALBIN)/setup-envtest
15+
CRDOC ?= $(LOCALBIN)/crdoc
1516

1617
# Image URL to use all building/pushing image targets
1718
IMG ?= quay.io/k0sproject/k0smotron:latest
@@ -188,6 +189,14 @@ docs-serve-dev:
188189
-p '$(DOCS_DEV_PORT):8000' \
189190
k0sdocs.docker-image.serve-dev
190191

192+
crdoc: $(CRDOC) ## Download crdoc locally if necessary. If wrong version is installed, it will be overwritten.
193+
$(CRDOC): Makefile.variables | $(LOCALBIN)
194+
GOBIN=$(LOCALBIN) go install fybrik.io/crdoc@$(CRDOC_VERSION)
195+
196+
.PHONY: docs-generate-reference
197+
docs-generate-reference: $(CRDOC)
198+
$(CRDOC) --resources config/crd/bases/ --output docs/resource-reference.md
199+
191200
.PHONY: $(smoketests)
192201
$(smoketests): release k0smotron-image-bundle.tar
193202
$(MAKE) -C inttest $@

‎Makefile.variables‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ KUSTOMIZE_VERSION ?= v5.0.1
22
CONTROLLER_TOOLS_VERSION ?= v0.11.4
33
GO_VERSION ?= 1.20.4
44
GOLANGCILINT_VERSION ?= 1.52.2
5+
CRDOC_VERSION ?= v0.6.2

‎docs/capi-aws.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ As soon as the bootstrap and control-plane controllers are up and running you ca
2020

2121
!!! note "k0smotron is currently only able to work with [externally managed](https://cluster-api-aws.sigs.k8s.io/topics/bring-your-own-aws-infrastructure.html) cluster infrastructure."
2222
This is because in CAPA there is no way to disable it to provision all control plane related infrastructure (VPC, ELB, etc.).
23-
This also renders k0smotron unable to dynamically edit the `AWSCluster` API endpoint details. Make sure you VPC and subnets you are planning to use full fill the [needed prerequisites](https://cluster-api-aws.sigs.k8s.io/topics/bring-your-own-aws-infrastructure.html#prerequisites).
23+
This also renders k0smotron unable to dynamically edit the `AWSCluster` API endpoint details. Make sure your VPC and subnets you are planning to use fullfill the [needed prerequisites](https://cluster-api-aws.sigs.k8s.io/topics/bring-your-own-aws-infrastructure.html#prerequisites).
2424

2525
Here is an example:
2626

‎docs/capi-bootstrap.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,3 +37,5 @@ spec:
3737
As k0s comes with all the needed bells and whistles to get k8s worker node up, we do not need to specify any details in this simple example.
3838
3939
Check the [examples](capi-examples.md) pages for more detailed examples how k0smotron can be used with various Cluster API infrastructure providers.
40+
41+
For reference on what can be configured via `K0sWorkerConfig` see the [reference docs](resource-reference.md#bootstrapclusterx-k8siov1beta1).

‎docs/capi-controlplane.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,4 +41,6 @@ spec:
4141
load-balancer.hetzner.cloud/location: fsn1
4242
```
4343

44-
The `K0smotronControlPlane.spec` field is a direct mapping of the "standalone" k0smotron cluster [configuration](configuration.md).
44+
Check the [examples](capi-examples.md) pages for more detailed examples how k0smotron can be used with various Cluster API infrastructure providers.
45+
46+
For a full reference on `K0smotronControlPlane` configurability see the [reference docs](resource-reference.md#controlplaneclusterx-k8siov1beta1).

‎docs/configuration.md‎

Lines changed: 5 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
11
# Configuration
22

3-
## Configuration file reference#
4-
5-
The default k0smotron configuration file is a YAML file that contains the following values:
3+
K0smotron managed control planes are managed using custom resource objects.
64

75
```yaml
86
apiVersion: k0smotron.io/v1beta1
@@ -21,40 +19,13 @@ spec:
2119
type: emptyDir
2220
```
2321
24-
## `spec` Key Detail
25-
26-
| Element | Description |
27-
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
28-
| `replicas` | Replicas is the desired number of replicas of the k0s control planes. If unspecified, defaults to 1. If the value is above 1, k0smotron requires kine datasource URL to be set. |
29-
| `k0sImage` | The k0s image to be deployed. |
30-
| `K0sVersion` | The k0s version to be deployed. |
31-
| `externalAddress` | ExternalAddress defines k0s external address. See [https://docs.k0sproject.io/stable/configuration/#specapi](https://docs.k0sproject.io/stable/configuration/#specapi) |
32-
| `service` | `Service` defines the service configuration. |
33-
| `persistence` | `Persistence` defines the persistence configuration. |
34-
| `kineDataSourceURL` | Defines the kine datasource URL. Required for HA controlplane setup. Must be set if replicas > 1. |
35-
| `k0sConfig` | Defines k0sConfig defines the k0s configuration. Note, that some fields will be overwritten by k0smotron. If empty, will be used default configuration. More info: https://docs.k0sproject.io/stable/configuration/ |
36-
37-
### `spec.service`
38-
39-
| Element | Description |
40-
|--------------------|----------------------------------------------------------|
41-
| `type` | Service type. Possible values: `NodePort`,`LoadBalancer` |
42-
| `apiPort` | Defines the kubernetes API port. |
43-
| `konnectivityPort` | Defines the konnectivity port. |
44-
45-
### `spec.persistence`
46-
47-
| Element | Description |
48-
|-------------------------|------------------------------------------------------------------------------------------------------------|
49-
| `type` | Persistence type. Possible values: `emptyDir`,`hostPath`,`pvc` |
50-
| `hostPath` | Defines the host path configuration. Will be used as is in case of `.spec.persistence.type` is `hostPath`. |
51-
| `persistentVolumeClaim` | Defines the PVC configuration. Will be used as is in case of `.spec.persistence.type` is `pvc`. |
52-
22+
For full reference of the fields check out the [reference docs](resource-reference.md#cluster).
5323
5424
## K0s configuration
5525
56-
K0smotron allows you to configure k0s via `spec.k0sConfig` field. If empty, will be used default configuration.
57-
More info about the k0s config: https://docs.k0sproject.io/stable/configuration/
26+
K0smotron allows you to configure k0s via `spec.k0sConfig` field. If empty, will be used default configuration.
27+
28+
Refer to [k0s docs](https://docs.k0sproject.io/stable/configuration/) for a reference on k0s configuration.
5829

5930
**Note**: some fields will be overwritten by k0smotron. K0smotron will set the following fields:
6031

0 commit comments

Comments
 (0)