Skip to content

Commit c285c4e

Browse files
nandajavarmanandajavarma
committed
[installer] add script to build config doc
1 parent 43a41f2 commit c285c4e

File tree

5 files changed

+470
-7
lines changed

5 files changed

+470
-7
lines changed

‎install/installer/Makefile

+5
Original file line numberDiff line numberDiff line change
@@ -34,3 +34,8 @@ versionManifest:
3434
@echo "Downloading version manifest for ${VERSION}"
3535
docker run -it --rm eu.gcr.io/gitpod-core-dev/build/versions:${VERSION} cat versions.yaml > ${VERSION_MANIFEST}
3636
.PHONY: versionManifest
37+
38+
config-doc:
39+
@echo "Building doc from Config struct for current version"
40+
go run ./scripts/structdoc.go
41+
.PHONY: config-doc

‎install/installer/pkg/config/v1/config.go

+14-7
Original file line numberDiff line numberDiff line change
@@ -63,11 +63,14 @@ func (v version) Defaults(in interface{}) error {
6363
return nil
6464
}
6565

66+
// Config defines the v1 version structure of the gitpod config file
6667
type Config struct {
67-
Kind InstallationKind `json:"kind" validate:"required,installation_kind"`
68-
Domain string `json:"domain" validate:"required,fqdn"`
69-
Metadata Metadata `json:"metadata"`
70-
Repository string `json:"repository" validate:"required,ascii"`
68+
// Installation type to run - for most users, this will be Full
69+
Kind InstallationKind `json:"kind" validate:"required,installation_kind"`
70+
// The domain to deploy to
71+
Domain string `json:"domain" validate:"required,fqdn"`
72+
Metadata Metadata `json:"metadata"`
73+
Repository string `json:"repository" validate:"required,ascii"`
7174

7275
Observability Observability `json:"observability"`
7376
Analytics *Analytics `json:"analytics,omitempty"`
@@ -98,6 +101,7 @@ type Config struct {
98101
}
99102

100103
type Metadata struct {
104+
// Location for your objectStorage provider
101105
Region string `json:"region" validate:"required"`
102106
}
103107

@@ -210,9 +214,12 @@ type Resources struct {
210214
}
211215

212216
type WorkspaceRuntime struct {
213-
FSShiftMethod FSShiftMethod `json:"fsShiftMethod" validate:"required,fs_shift_method"`
214-
ContainerDRuntimeDir string `json:"containerdRuntimeDir" validate:"required,startswith=/"`
215-
ContainerDSocket string `json:"containerdSocket" validate:"required,startswith=/"`
217+
// File system
218+
FSShiftMethod FSShiftMethod `json:"fsShiftMethod" validate:"required,fs_shift_method"`
219+
// The location of containerd socket on the host machine
220+
ContainerDRuntimeDir string `json:"containerdRuntimeDir" validate:"required,startswith=/"`
221+
// The location of containerd socket on the host machine
222+
ContainerDSocket string `json:"containerdSocket" validate:"required,startswith=/"`
216223
}
217224

218225
type WorkspaceTemplates struct {

‎install/installer/pkg/config/v1/config.md

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Config v1
2+
3+
Config defines the v1 version structure of the gitpod config file
4+
5+
6+
## Supported parameters
7+
| Property | Type | Required | Allowed| Description |
8+
| --- | --- | --- | --- | --- |
9+
|`kind`|string|N| `Meta`, `Workspace`, `Full` ||
10+
|`domain`|string|Y| | The domain to deploy to|
11+
|`metadata.region`|string|Y| | Location for your objectStorage provider|
12+
|`repository`|string|Y| ||
13+
|`observability.logLevel`|string|N| `trace`, `debug`, `info`, `warning`, `error`, `fatal`, `panic` |Taken from github.com/gitpod-io/gitpod/components/gitpod-protocol/src/util/logging.ts|
14+
|`observability.tracing.endpoint`|string|N| ||
15+
|`observability.tracing.agentHost`|string|N| ||
16+
|`analytics.segmentKey`|string|N| ||
17+
|`analytics.writer`|string|N| ||
18+
|`database.inCluster`|bool|N| ||
19+
|`database.external.certificate.kind`|string|N| `secret` ||
20+
|`database.external.certificate.name`|string|Y| ||
21+
|`database.cloudSQL.serviceAccount.kind`|string|N| `secret` ||
22+
|`database.cloudSQL.serviceAccount.name`|string|Y| ||
23+
|`database.cloudSQL.instance`|string|Y| ||
24+
|`objectStorage.inCluster`|bool|N| ||
25+
|`objectStorage.s3.endpoint`|string|Y| ||
26+
|`objectStorage.s3.credentials.kind`|string|N| `secret` ||
27+
|`objectStorage.s3.credentials.name`|string|Y| ||
28+
|`objectStorage.cloudStorage.serviceAccount.kind`|string|N| `secret` ||
29+
|`objectStorage.cloudStorage.serviceAccount.name`|string|Y| ||
30+
|`objectStorage.cloudStorage.project`|string|Y| ||
31+
|`objectStorage.azure.credentials.kind`|string|N| `secret` ||
32+
|`objectStorage.azure.credentials.name`|string|Y| ||
33+
|`containerRegistry.inCluster`|bool|Y| ||
34+
|`containerRegistry.external.url`|string|Y| ||
35+
|`containerRegistry.external.certificate.kind`|string|N| `secret` ||
36+
|`containerRegistry.external.certificate.name`|string|Y| ||
37+
|`containerRegistry.s3storage.bucket`|string|Y| ||
38+
|`containerRegistry.s3storage.certificate.kind`|string|N| `secret` ||
39+
|`containerRegistry.s3storage.certificate.name`|string|Y| ||
40+
|`certificate.kind`|string|N| `secret` ||
41+
|`certificate.name`|string|Y| ||
42+
|`imagePullSecrets[ ].kind`|string|N| `secret` ||
43+
|`imagePullSecrets[ ].name`|string|Y| ||
44+
|`workspace.runtime.fsShiftMethod`|string|N| `fuse`, `shiftfs` ||
45+
|`workspace.runtime.containerdRuntimeDir`|string|Y| | The location of containerd socket on the host machine|
46+
|`workspace.runtime.containerdSocket`|string|Y| | The location of containerd socket on the host machine|
47+
|`workspace.resources.requests`||Y| | todo(sje): add custom validation to corev1.ResourceList|
48+
|`workspace.resources.limits`||N| ||
49+
|`workspace.resources.dynamicLimits`||N| ||
50+
|`workspace.templates.default`||N| ||
51+
|`workspace.templates.prebuild`||N| ||
52+
|`workspace.templates.ghost`||N| ||
53+
|`workspace.templates.imagebuild`||N| ||
54+
|`workspace.templates.regular`||N| ||
55+
|`workspace.templates.probe`||N| ||
56+
|`workspace.maxLifetime`||Y| | MaxLifetime is the maximum time a workspace is allowed to run. After that, the workspace times out despite activity|
57+
|`workspace.timeoutDefault`||N| | TimeoutDefault is the default timeout of a regular workspace|
58+
|`workspace.timeoutExtended`||N| | TimeoutExtended is the workspace timeout that a user can extend to for one workspace|
59+
|`workspace.timeoutAfterClose`||N| | TimeoutAfterClose is the time a workspace timed out after it has been closed (“closed” means that it does not get a heartbeat from an IDE anymore)|
60+
|`openVSX.url`|string|N| ||
61+
|`authProviders[ ].kind`|string|N| `secret` ||
62+
|`authProviders[ ].name`|string|Y| ||
63+
|`blockNewUsers.enabled`|bool|N| ||
64+
|`blockNewUsers.passlist[ ]`|[]string|N| ||
65+
|`license.kind`|string|N| `secret` ||
66+
|`license.name`|string|Y| ||
67+
|`sshGatewayHostKey.kind`|string|N| `secret` ||
68+
|`sshGatewayHostKey.name`|string|Y| ||
69+
|`disableDefinitelyGp`|bool|N| ||
70+
|`apiVersion`|string|Y| |API version of the Gitpod config defintion. `v1` in this version of Config|
71+
72+
73+
# Experimental config parameters v1
74+
75+
Additional config parameters that are in experimental state
76+
77+
## Supported parameters
78+
| Property | Type | Required | Allowed| Description |
79+
| --- | --- | --- | --- | --- |
80+
|`experimental.workspace.tracing.samplerType`|string|N| `const`, `probabilistic`, `rateLimiting`, `remote` |Values taken from https://github.com/jaegertracing/jaeger-client-go/blob/967f9c36f0fa5a2617c9a0993b03f9a3279fadc8/config/config.go#L71|
81+
|`experimental.workspace.tracing.samplerParam`|float64|N| ||
82+
|`experimental.workspace.stage`|string|N| ||
83+
|`experimental.workspace.stage`|string|N| ||
84+
|`experimental.workspace.registryFacade`||N| ||
85+
|`experimental.webapp`|WebAppConfig|N| ||
86+
|`experimental.ide`|IDEConfig|N| ||
87+
88+

‎install/installer/scripts/README.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# StructDoc script
2+
3+
This directory contains a small script that would automatically generate a
4+
markdown documentation for the supported parameters in the config file. The
5+
script is intended to serve as an easy way to enable the creation of this doc
6+
considering the heavily changing nature of the config. The script lets one also
7+
create documentation for different versions of the Config file as well.
8+
9+
This script essentially parses the AST of the `config` package to aquire the
10+
structure names, fields and docs associated to them. The script is highly
11+
customized for parsing the `Config` struct, so cannot be applied for any other
12+
structs for generic doc generation.
13+
14+
## Usage
15+
16+
This script is intended to be run from the root directory of the installer
17+
18+
``` sh
19+
$ go run ./scripts/structdoc.go --version "v1"
20+
INFO[0000] Generating doc for config version v1
21+
INFO[0000] The doc is written to the file pkg/config/v1/config.md
22+
23+
# Alternatively one can also use the make target
24+
# to create the doc for current version
25+
$ make config-doc
26+
Building doc from Config struct for current version
27+
go run ./scripts/structdoc.go
28+
INFO[0000] Generating doc for config version v1
29+
INFO[0000] The doc is written to the file pkg/config/v1/config.md
30+
```

0 commit comments

Comments
 (0)