Skip to content

Commit a84bece

Browse files
ThomasK33ThomasK33
authored
🤖 refactor: Kubernetes-style linked API reference types (#64)
## Summary This PR reworks generated API reference docs to use a Kubernetes-style, linkable layout that is easier to scan. ## Background Our previous output flattened nested fields into tree-style rows within the top-level Spec/Status tables. That made pages dense and hard to navigate, and repeated shared types across rows. ## Implementation - Updated `hack/crd-ref-docs/templates/markdown/gv_list.tpl` to: - keep top-level Spec/Status tables focused on direct fields, - render local project types as same-page links, - collect referenced local types recursively, - emit a `## Referenced types` section with type-specific field tables. - Kept Kubernetes built-in types linked to upstream Kubernetes API docs via `crd-ref-docs` link rendering. - Regenerated docs under `docs/reference/api/*.md`. ## Validation - `make verify-vendor` - `make test` - `make build` - `make lint` - `make docs-reference` - `mkdocs build --strict` ## Risks Low to medium. This change is template/output focused and does not affect runtime behavior, but link structure and table formatting could impact readability and downstream docs expectations. --- _Generated with `mux` • Model: `openai:gpt-5.3-codex` • Thinking: `xhigh` • Cost: `$0.67`_ <!-- mux-attribution: model=openai:gpt-5.3-codex thinking=xhigh costs=0.67 -->
1 parent 968dd47 commit a84bece

7 files changed

Lines changed: 317 additions & 163 deletions

File tree

‎docs/reference/api/codercontrolplane.md‎

Lines changed: 44 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -13,33 +13,55 @@
1313

1414
| Field | Type | Description |
1515
| --- | --- | --- |
16-
| `image` | `string` | Image is the container image used for the Coder control plane pod. |
17-
| `replicas` | `int32` | Replicas is the desired number of control plane pods. |
18-
| `service` | `ServiceSpec` | Service controls the service created in front of the control plane. |
19-
| ├─ `type` | `corev1.ServiceType` | Type controls the Kubernetes service type. |
20-
| ├─ `port` | `int32` | Port controls the exposed service port. |
21-
| └─ `annotations` | `map[string]string` | Annotations are applied to the reconciled service object. |
22-
| `extraArgs` | `[]string` | ExtraArgs are appended to the default Coder server arguments. |
23-
| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the Coder control plane container. |
24-
| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
25-
| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) |
26-
| `operatorAccess` | `OperatorAccessSpec` | OperatorAccess configures bootstrap API access to the coderd instance. |
27-
| ├─ `disabled` | `bool` | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. |
28-
| └─ `generatedTokenSecretName` | `string` | GeneratedTokenSecretName stores the generated operator API token. |
16+
| `image` | string | Image is the container image used for the Coder control plane pod. |
17+
| `replicas` | integer | Replicas is the desired number of control plane pods. |
18+
| `service` | [ServiceSpec](#servicespec) | Service controls the service created in front of the control plane. |
19+
| `extraArgs` | string array | ExtraArgs are appended to the default Coder server arguments. |
20+
| `extraEnv` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#envvar-v1-core) array | ExtraEnv are injected into the Coder control plane container. |
21+
| `imagePullSecrets` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array | ImagePullSecrets are used by the pod to pull private images. |
22+
| `operatorAccess` | [OperatorAccessSpec](#operatoraccessspec) | OperatorAccess configures bootstrap API access to the coderd instance. |
2923

3024
## Status
3125

3226
| Field | Type | Description |
3327
| --- | --- | --- |
34-
| `observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. |
35-
| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
36-
| `url` | `string` | URL is the in-cluster URL for the control plane service. |
37-
| `operatorTokenSecretRef` | `SecretKeySelector` | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. |
38-
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
39-
| └─ `key` | `string` | Key is the key inside the Secret data map. |
40-
| `operatorAccessReady` | `bool` | OperatorAccessReady reports whether operator API access bootstrap succeeded. |
41-
| `phase` | `string` | Phase is a high-level readiness indicator. |
42-
| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |
28+
| `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. |
29+
| `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. |
30+
| `url` | string | URL is the in-cluster URL for the control plane service. |
31+
| `operatorTokenSecretRef` | [SecretKeySelector](#secretkeyselector) | OperatorTokenSecretRef points to the Secret key containing the `coder-k8s-operator` API token. |
32+
| `operatorAccessReady` | boolean | OperatorAccessReady reports whether operator API access bootstrap succeeded. |
33+
| `phase` | string | Phase is a high-level readiness indicator. |
34+
| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. |
35+
36+
## Referenced types
37+
38+
### OperatorAccessSpec
39+
40+
OperatorAccessSpec configures the controller-managed coderd operator user.
41+
42+
| Field | Type | Description |
43+
| --- | --- | --- |
44+
| `disabled` | boolean | Disabled turns off creation and management of the `coder-k8s-operator` user and API token. |
45+
| `generatedTokenSecretName` | string | GeneratedTokenSecretName stores the generated operator API token. |
46+
47+
### SecretKeySelector
48+
49+
SecretKeySelector identifies a key in a Secret.
50+
51+
| Field | Type | Description |
52+
| --- | --- | --- |
53+
| `name` | string | Name is the Kubernetes Secret name. |
54+
| `key` | string | Key is the key inside the Secret data map. |
55+
56+
### ServiceSpec
57+
58+
ServiceSpec defines the Service configuration reconciled by the operator.
59+
60+
| Field | Type | Description |
61+
| --- | --- | --- |
62+
| `type` | [ServiceType](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#servicetype-v1-core) | Type controls the Kubernetes service type. |
63+
| `port` | integer | Port controls the exposed service port. |
64+
| `annotations` | object (keys:string, values:string) | Annotations are applied to the reconciled service object. |
4365

4466
## Source
4567

‎docs/reference/api/coderprovisioner.md‎

Lines changed: 53 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -13,45 +13,64 @@
1313

1414
| Field | Type | Description |
1515
| --- | --- | --- |
16-
| `controlPlaneRef` | `corev1.LocalObjectReference` | ControlPlaneRef identifies which CoderControlPlane instance to join. |
17-
| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) |
18-
| `organizationName` | `string` | OrganizationName is the Coder organization. Defaults to "default". |
19-
| `bootstrap` | `CoderProvisionerBootstrapSpec` | Bootstrap configures credentials for provisioner key management. |
20-
| └─ `credentialsSecretRef` | `SecretKeySelector` | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. |
21-
| &nbsp;&nbsp;&nbsp;├─ `name` | `string` | Name is the Kubernetes Secret name. |
22-
| &nbsp;&nbsp;&nbsp;└─ `key` | `string` | Key is the key inside the Secret data map. |
23-
| `key` | `CoderProvisionerKeySpec` | Key configures provisioner key naming and secret storage. |
24-
| ├─ `name` | `string` | Name is the provisioner key name in coderd. Defaults to the CR name. |
25-
| ├─ `secretName` | `string` | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". |
26-
| └─ `secretKey` | `string` | SecretKey is the data key in the Secret. Defaults to "key". |
27-
| `replicas` | `int32` | Replicas is the desired number of provisioner pods. |
28-
| `tags` | `map[string]string` | Tags are attached to the provisioner key for job routing. |
29-
| `image` | `string` | Image is the container image. Defaults to the control plane image. |
30-
| `extraArgs` | `[]string` | ExtraArgs are appended after "provisionerd start". |
31-
| `extraEnv` | `[]corev1.EnvVar` | ExtraEnv are injected into the provisioner container. |
32-
| `resources` | `corev1.ResourceRequirements` | Resources for the provisioner container. |
33-
| `imagePullSecrets` | `[]corev1.LocalObjectReference` | ImagePullSecrets are used by the pod to pull private images. |
34-
| └─ `name` | `string` | Name of the referent. This field is effectively required, but due to backwards compatibility is allowed to be empty. Instances of this type with an empty value here are almost certainly wrong. More info: [https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names) |
35-
| `terminationGracePeriodSeconds` | `int64` | TerminationGracePeriodSeconds for the provisioner pods. |
16+
| `controlPlaneRef` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) | ControlPlaneRef identifies which CoderControlPlane instance to join. |
17+
| `organizationName` | string | OrganizationName is the Coder organization. Defaults to "default". |
18+
| `bootstrap` | [CoderProvisionerBootstrapSpec](#coderprovisionerbootstrapspec) | Bootstrap configures credentials for provisioner key management. |
19+
| `key` | [CoderProvisionerKeySpec](#coderprovisionerkeyspec) | Key configures provisioner key naming and secret storage. |
20+
| `replicas` | integer | Replicas is the desired number of provisioner pods. |
21+
| `tags` | object (keys:string, values:string) | Tags are attached to the provisioner key for job routing. |
22+
| `image` | string | Image is the container image. Defaults to the control plane image. |
23+
| `extraArgs` | string array | ExtraArgs are appended after "provisionerd start". |
24+
| `extraEnv` | [EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#envvar-v1-core) array | ExtraEnv are injected into the provisioner container. |
25+
| `resources` | [ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#resourcerequirements-v1-core) | Resources for the provisioner container. |
26+
| `imagePullSecrets` | [LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#localobjectreference-v1-core) array | ImagePullSecrets are used by the pod to pull private images. |
27+
| `terminationGracePeriodSeconds` | integer | TerminationGracePeriodSeconds for the provisioner pods. |
3628

3729
## Status
3830

3931
| Field | Type | Description |
4032
| --- | --- | --- |
41-
| `observedGeneration` | `int64` | ObservedGeneration tracks the spec generation this status reflects. |
42-
| `readyReplicas` | `int32` | ReadyReplicas is the number of ready pods observed in the deployment. |
43-
| `phase` | `string` | Phase is a high-level readiness indicator. |
44-
| `conditions` | `[]metav1.Condition` | Conditions are Kubernetes-standard conditions for this resource. |
45-
| `organizationID` | `string` | OrganizationID is the organization ID last applied to the provisioner key. |
46-
| `organizationName` | `string` | OrganizationName is the organization name last applied to the provisioner key. |
47-
| `provisionerKeyID` | `string` | ProvisionerKeyID is the provisioner key ID last applied in coderd. |
48-
| `provisionerKeyName` | `string` | ProvisionerKeyName is the provisioner key name last applied in coderd. |
49-
| `tagsHash` | `string` | TagsHash is a deterministic hash of spec.tags last applied to the provisioner key. |
50-
| `controlPlaneRefName` | `string` | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. |
51-
| `controlPlaneURL` | `string` | ControlPlaneURL is the control plane URL last applied to the provisioner key. |
52-
| `secretRef` | `SecretKeySelector` | SecretRef references the provisioner key secret data currently in use. |
53-
| ├─ `name` | `string` | Name is the Kubernetes Secret name. |
54-
| └─ `key` | `string` | Key is the key inside the Secret data map. |
33+
| `observedGeneration` | integer | ObservedGeneration tracks the spec generation this status reflects. |
34+
| `readyReplicas` | integer | ReadyReplicas is the number of ready pods observed in the deployment. |
35+
| `phase` | string | Phase is a high-level readiness indicator. |
36+
| `conditions` | [Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#condition-v1-meta) array | Conditions are Kubernetes-standard conditions for this resource. |
37+
| `organizationID` | string | OrganizationID is the organization ID last applied to the provisioner key. |
38+
| `organizationName` | string | OrganizationName is the organization name last applied to the provisioner key. |
39+
| `provisionerKeyID` | string | ProvisionerKeyID is the provisioner key ID last applied in coderd. |
40+
| `provisionerKeyName` | string | ProvisionerKeyName is the provisioner key name last applied in coderd. |
41+
| `tagsHash` | string | TagsHash is a deterministic hash of spec.tags last applied to the provisioner key. |
42+
| `controlPlaneRefName` | string | ControlPlaneRefName is the control plane ref name last applied to the provisioner key. |
43+
| `controlPlaneURL` | string | ControlPlaneURL is the control plane URL last applied to the provisioner key. |
44+
| `secretRef` | [SecretKeySelector](#secretkeyselector) | SecretRef references the provisioner key secret data currently in use. |
45+
46+
## Referenced types
47+
48+
### CoderProvisionerBootstrapSpec
49+
50+
CoderProvisionerBootstrapSpec configures credentials for provisioner key management.
51+
52+
| Field | Type | Description |
53+
| --- | --- | --- |
54+
| `credentialsSecretRef` | [SecretKeySelector](#secretkeyselector) | CredentialsSecretRef points to a Secret containing a Coder session token with permission to manage provisioner keys. |
55+
56+
### CoderProvisionerKeySpec
57+
58+
CoderProvisionerKeySpec configures provisioner key naming and storage.
59+
60+
| Field | Type | Description |
61+
| --- | --- | --- |
62+
| `name` | string | Name is the provisioner key name in coderd. Defaults to the CR name. |
63+
| `secretName` | string | SecretName is the Kubernetes Secret to store the key. Defaults to "\{crName\}-provisioner-key". |
64+
| `secretKey` | string | SecretKey is the data key in the Secret. Defaults to "key". |
65+
66+
### SecretKeySelector
67+
68+
SecretKeySelector identifies a key in a Secret.
69+
70+
| Field | Type | Description |
71+
| --- | --- | --- |
72+
| `name` | string | Name is the Kubernetes Secret name. |
73+
| `key` | string | Key is the key inside the Secret data map. |
5574

5675
## Source
5776

‎docs/reference/api/codertemplate.md‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,23 +13,23 @@
1313

1414
| Field | Type | Description |
1515
| --- | --- | --- |
16-
| `organization` | `string` | Organization is the Coder organization name (must match the organization prefix in metadata.name). |
17-
| `versionID` | `string` | VersionID is the Coder template version UUID used on creation (required for CREATE). |
18-
| `displayName` | `string` | |
19-
| `description` | `string` | |
20-
| `icon` | `string` | |
21-
| `running` | `bool` | Running is a legacy flag retained temporarily for in-repo callers that still read template run-state directly. |
16+
| `organization` | string | Organization is the Coder organization name (must match the organization prefix in metadata.name). |
17+
| `versionID` | string | VersionID is the Coder template version UUID used on creation (required for CREATE). |
18+
| `displayName` | string | |
19+
| `description` | string | |
20+
| `icon` | string | |
21+
| `running` | boolean | Running is a legacy flag retained temporarily for in-repo callers that still read template run-state directly. |
2222

2323
## Status
2424

2525
| Field | Type | Description |
2626
| --- | --- | --- |
27-
| `id` | `string` | |
28-
| `organizationName` | `string` | |
29-
| `activeVersionID` | `string` | |
30-
| `deprecated` | `bool` | |
31-
| `updatedAt` | `metav1.Time` | |
32-
| `autoShutdown` | `metav1.Time` | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. |
27+
| `id` | string | |
28+
| `organizationName` | string | |
29+
| `activeVersionID` | string | |
30+
| `deprecated` | boolean | |
31+
| `updatedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | |
32+
| `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | AutoShutdown is a legacy timestamp retained temporarily for in-repo callers that still surface template shutdown timestamps. |
3333

3434
## Source
3535

‎docs/reference/api/coderworkspace.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,25 @@
1313

1414
| Field | Type | Description |
1515
| --- | --- | --- |
16-
| `organization` | `string` | Organization is the Coder organization name. |
17-
| `templateName` | `string` | TemplateName resolves via TemplateByName(organization, templateName). |
18-
| `templateVersionID` | `string` | TemplateVersionID optionally pins to a specific template version. |
19-
| `running` | `bool` | Running drives start/stop via CreateWorkspaceBuild. |
20-
| `ttlMillis` | `int64` | |
21-
| `autostartSchedule` | `string` | |
16+
| `organization` | string | Organization is the Coder organization name. |
17+
| `templateName` | string | TemplateName resolves via TemplateByName(organization, templateName). |
18+
| `templateVersionID` | string | TemplateVersionID optionally pins to a specific template version. |
19+
| `running` | boolean | Running drives start/stop via CreateWorkspaceBuild. |
20+
| `ttlMillis` | integer | |
21+
| `autostartSchedule` | string | |
2222

2323
## Status
2424

2525
| Field | Type | Description |
2626
| --- | --- | --- |
27-
| `id` | `string` | |
28-
| `ownerName` | `string` | |
29-
| `organizationName` | `string` | |
30-
| `templateName` | `string` | |
31-
| `latestBuildID` | `string` | |
32-
| `latestBuildStatus` | `string` | |
33-
| `autoShutdown` | `metav1.Time` | |
34-
| `lastUsedAt` | `metav1.Time` | |
27+
| `id` | string | |
28+
| `ownerName` | string | |
29+
| `organizationName` | string | |
30+
| `templateName` | string | |
31+
| `latestBuildID` | string | |
32+
| `latestBuildStatus` | string | |
33+
| `autoShutdown` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | |
34+
| `lastUsedAt` | [Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.35/#time-v1-meta) | |
3535

3636
## Source
3737

0 commit comments

Comments
 (0)