[installer] add doc generator for Config

install/installer/Makefile

@@ -34,3 +34,8 @@ versionManifest:
 	@echo "Downloading version manifest for ${VERSION}"
 	docker run -it --rm eu.gcr.io/gitpod-core-dev/build/versions:${VERSION} cat versions.yaml > ${VERSION_MANIFEST}
 .PHONY: versionManifest
+
+config-doc:
+	@echo "Building doc from Config struct for current version"
+	go run ./scripts/structdoc.go
+.PHONY: config-doc

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

@@ -64,11 +64,14 @@ func (v version) Defaults(in interface{}) error {
 	return nil
 }
 
+// Config defines the v1 version structure of the gitpod config file
 type Config struct {
-	Kind       InstallationKind `json:"kind" validate:"required,installation_kind"`
-	Domain     string           `json:"domain" validate:"required,fqdn"`
-	Metadata   Metadata         `json:"metadata"`
-	Repository string           `json:"repository" validate:"required,ascii"`
+	// Installation type to run - for most users, this will be Full
+	Kind InstallationKind `json:"kind" validate:"required,installation_kind"`
+	// The domain to deploy to
+	Domain     string   `json:"domain" validate:"required,fqdn"`
+	Metadata   Metadata `json:"metadata"`
+	Repository string   `json:"repository" validate:"required,ascii"`
 
 	Observability Observability `json:"observability"`
 	Analytics     *Analytics    `json:"analytics,omitempty"`
@@ -103,6 +106,7 @@ type Config struct {
 }
 
 type Metadata struct {
+	// Location for your objectStorage provider
 	Region string `json:"region" validate:"required"`
 	// InstallationShortname establishes the "identity" of the (application) cluster.
 	InstallationShortname string `json:"shortname" validate:"required"`
@@ -219,9 +223,12 @@ type Resources struct {
 }
 
 type WorkspaceRuntime struct {
-	FSShiftMethod        FSShiftMethod `json:"fsShiftMethod" validate:"required,fs_shift_method"`
-	ContainerDRuntimeDir string        `json:"containerdRuntimeDir" validate:"required,startswith=/"`
-	ContainerDSocket     string        `json:"containerdSocket" validate:"required,startswith=/"`
+	// File system
+	FSShiftMethod FSShiftMethod `json:"fsShiftMethod" validate:"required,fs_shift_method"`
+	// The location of containerd socket on the host machine
+	ContainerDRuntimeDir string `json:"containerdRuntimeDir" validate:"required,startswith=/"`
+	// The location of containerd socket on the host machine
+	ContainerDSocket string `json:"containerdSocket" validate:"required,startswith=/"`
 }
 
 type WorkspaceTemplates struct {

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

@@ -0,0 +1,88 @@
+# Config v1
+
+Config defines the v1 version structure of the gitpod config file
+
+
+## Supported parameters
+| Property | Type | Required | Allowed| Description |
+| --- | --- | --- | --- | --- |
+|`kind`|string|N| `Meta`, `Workspace`, `Full` ||
+|`domain`|string|Y|  |  The domain to deploy to|
+|`metadata.region`|string|Y|  |  Location for your objectStorage provider|
+|`repository`|string|Y|  ||
+|`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|
+|`observability.tracing.endpoint`|string|N|  ||
+|`observability.tracing.agentHost`|string|N|  ||
+|`analytics.segmentKey`|string|N|  ||
+|`analytics.writer`|string|N|  ||
+|`database.inCluster`|bool|N|  ||
+|`database.external.certificate.kind`|string|N| `secret` ||
+|`database.external.certificate.name`|string|Y|  ||
+|`database.cloudSQL.serviceAccount.kind`|string|N| `secret` ||
+|`database.cloudSQL.serviceAccount.name`|string|Y|  ||
+|`database.cloudSQL.instance`|string|Y|  ||
+|`objectStorage.inCluster`|bool|N|  ||
+|`objectStorage.s3.endpoint`|string|Y|  ||
+|`objectStorage.s3.credentials.kind`|string|N| `secret` ||
+|`objectStorage.s3.credentials.name`|string|Y|  ||
+|`objectStorage.cloudStorage.serviceAccount.kind`|string|N| `secret` ||
+|`objectStorage.cloudStorage.serviceAccount.name`|string|Y|  ||
+|`objectStorage.cloudStorage.project`|string|Y|  ||
+|`objectStorage.azure.credentials.kind`|string|N| `secret` ||
+|`objectStorage.azure.credentials.name`|string|Y|  ||
+|`containerRegistry.inCluster`|bool|Y|  ||
+|`containerRegistry.external.url`|string|Y|  ||
+|`containerRegistry.external.certificate.kind`|string|N| `secret` ||
+|`containerRegistry.external.certificate.name`|string|Y|  ||
+|`containerRegistry.s3storage.bucket`|string|Y|  ||
+|`containerRegistry.s3storage.certificate.kind`|string|N| `secret` ||
+|`containerRegistry.s3storage.certificate.name`|string|Y|  ||
+|`certificate.kind`|string|N| `secret` ||
+|`certificate.name`|string|Y|  ||
+|`imagePullSecrets[ ].kind`|string|N| `secret` ||
+|`imagePullSecrets[ ].name`|string|Y|  ||
+|`workspace.runtime.fsShiftMethod`|string|N| `fuse`, `shiftfs` ||
+|`workspace.runtime.containerdRuntimeDir`|string|Y|  |  The location of containerd socket on the host machine|
+|`workspace.runtime.containerdSocket`|string|Y|  |  The location of containerd socket on the host machine|
+|`workspace.resources.requests`||Y|  |  todo(sje): add custom validation to corev1.ResourceList|
+|`workspace.resources.limits`||N|  ||
+|`workspace.resources.dynamicLimits`||N|  ||
+|`workspace.templates.default`||N|  ||
+|`workspace.templates.prebuild`||N|  ||
+|`workspace.templates.ghost`||N|  ||
+|`workspace.templates.imagebuild`||N|  ||
+|`workspace.templates.regular`||N|  ||
+|`workspace.templates.probe`||N|  ||
+|`workspace.maxLifetime`||Y|  |  MaxLifetime is the maximum time a workspace is allowed to run. After that, the workspace times out despite activity|
+|`workspace.timeoutDefault`||N|  |  TimeoutDefault is the default timeout of a regular workspace|
+|`workspace.timeoutExtended`||N|  |  TimeoutExtended is the workspace timeout that a user can extend to for one workspace|
+|`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)|
+|`openVSX.url`|string|N|  ||
+|`authProviders[ ].kind`|string|N| `secret` ||
+|`authProviders[ ].name`|string|Y|  ||
+|`blockNewUsers.enabled`|bool|N|  ||
+|`blockNewUsers.passlist[ ]`|[]string|N|  ||
+|`license.kind`|string|N| `secret` ||
+|`license.name`|string|Y|  ||
+|`sshGatewayHostKey.kind`|string|N| `secret` ||
+|`sshGatewayHostKey.name`|string|Y|  ||
+|`disableDefinitelyGp`|bool|N|  ||
+|`apiVersion`|string|Y|  |API version of the Gitpod config defintion. `v1` in this version of Config|
+
+
+# Experimental config parameters v1
+
+Additional config parameters that are in experimental state
+
+## Supported parameters
+| Property | Type | Required | Allowed| Description |
+| --- | --- | --- | --- | --- |
+|`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|
+|`experimental.workspace.tracing.samplerParam`|float64|N|  ||
+|`experimental.workspace.stage`|string|N|  ||
+|`experimental.workspace.stage`|string|N|  ||
+|`experimental.workspace.registryFacade`||N|  ||
+|`experimental.webapp`|WebAppConfig|N|  ||
+|`experimental.ide`|IDEConfig|N|  ||
+
+

install/installer/scripts/README.md

@@ -0,0 +1,30 @@
+# StructDoc script
+
+This directory contains a small script that would automatically generate a
+markdown documentation for the supported parameters in the config file. The
+script is intended to serve as an easy way to enable the creation of this doc
+considering the heavily changing nature of the config. The script lets one also
+create documentation for different versions of the Config file as well.
+
+This script essentially parses the AST of the `config` package to aquire the
+structure names, fields and docs associated to them. The script is highly
+customized for parsing the `Config` struct, so cannot be applied for any other
+structs for generic doc generation.
+
+## Usage
+
+This script is intended to be run from the root directory of the installer
+
+``` sh
+$ go run ./scripts/structdoc.go --version "v1"
+INFO[0000] Generating doc for config version v1         
+INFO[0000] The doc is written to the file pkg/config/v1/config.md 
+
+# Alternatively one can also use the make target
+# to create the doc for current version
+$ make config-doc
+Building doc from Config struct for current version
+go run ./scripts/structdoc.go
+INFO[0000] Generating doc for config version v1         
+INFO[0000] The doc is written to the file pkg/config/v1/config.md 
+```