Skip to content

Commit f69d933

Browse files
ironcladlouironcladlou
committed
Improve API reference docs
This commit updates API documentation on the Go types and also improves the generated API documentation to include only the public types, as well as other minor small fixes for readability. Note that the `+gencopy` comments added to the API types are to work around an issue[1] in the upstream docs generation code which doesn't yet understand the `+kubebuilder:object:root` tag. This is necessary to make the generator understand which types are "public" (e.g. HostedCluster and NodePool). [1] ahmetb/gen-crd-api-reference-docs#26
1 parent 00ee359 commit f69d933

File tree

11 files changed

+1175
-1511
lines changed

11 files changed

+1175
-1511
lines changed

‎api/v1alpha1/doc.go‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,6 @@ HyperShift clusters are deployed in a topology which isolates the "control plane
88
(e.g. etcd, the API server, controller manager, etc.) from the "data plane" (e.g.
99
worker nodes and their kubelets, and the infrastructure on which they run). This
1010
enables "hosted control plane as a service" use cases.
11-
12-
The API is represented as Kubernetes Custom Resource Definitions in the
13-
hypershift.openshift.io API group.
1411
*/
1512
// +kubebuilder:object:generate=true
1613
// +groupName=hypershift.openshift.io

‎api/v1alpha1/hosted_controlplane.go‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,21 @@ type HostedControlPlaneSpec struct {
9797
SecretEncryption *SecretEncryptionSpec `json:"secretEncryption,omitempty"`
9898
}
9999

100+
// AvailabilityPolicy specifies a high level availability policy for components.
100101
type AvailabilityPolicy string
101102

102103
const (
104+
// HighlyAvailable means components should be resilient to problems across fault
105+
// boundaries as defined by the component to which the policy is attached. This
106+
// usually means running critical workloads with 3 replicas and with little or
107+
// no toleration of disruption of the component.
103108
HighlyAvailable AvailabilityPolicy = "HighlyAvailable"
104-
SingleReplica AvailabilityPolicy = "SingleReplica"
109+
110+
// SingleReplica means components are not expected to be resilient to problems
111+
// across most fault boundaries associated with high availability. This usually
112+
// means running critical workloads with just 1 replica and with toleration of
113+
// full disruption of the component.
114+
SingleReplica AvailabilityPolicy = "SingleReplica"
105115
)
106116

107117
type KubeconfigSecretRef struct {

‎api/v1alpha1/hostedcluster_types.go‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,8 @@ type HostedClusterSpec struct {
129129
// TODO (alberto): include Ignition endpoint here.
130130
Services []ServicePublishingStrategyMapping `json:"services"`
131131

132-
// ControllerAvailabilityPolicy specifies whether to run control plane controllers in HA mode
132+
// ControllerAvailabilityPolicy specifies an availability policy to apply
133+
// to critical control plane components.
133134
// Defaults to SingleReplica when not set.
134135
// +optional
135136
ControllerAvailabilityPolicy AvailabilityPolicy `json:"controllerAvailabilityPolicy,omitempty"`
@@ -832,6 +833,14 @@ type ClusterConfiguration struct {
832833
Items []runtime.RawExtension `json:"items,omitempty"`
833834
}
834835

836+
// +genclient
837+
838+
// HostedCluster is the primary representation of a HyperShift cluster and encapsulates
839+
// the control plane and common data plane configuration. Creating a HostedCluster
840+
// results in a fully functional OpenShift control plane with no attached nodes.
841+
// To support workloads (e.g. pods), a HostedCluster may have one or more associated
842+
// NodePool resources.
843+
//
835844
// +kubebuilder:object:root=true
836845
// +kubebuilder:resource:path=hostedclusters,shortName=hc;hcs,scope=Namespaced
837846
// +kubebuilder:storageversion
@@ -841,12 +850,14 @@ type ClusterConfiguration struct {
841850
// +kubebuilder:printcolumn:name="Progress",type="string",JSONPath=".status.version.history[?(@.state!=\"\")].state",description="Progress"
842851
// +kubebuilder:printcolumn:name="Available",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].status",description="Available"
843852
// +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].reason",description="Reason"
844-
// HostedCluster is the Schema for the hostedclusters API
845853
type HostedCluster struct {
846854
metav1.TypeMeta `json:",inline"`
847855
metav1.ObjectMeta `json:"metadata,omitempty"`
848856

849-
Spec HostedClusterSpec `json:"spec,omitempty"`
857+
// Spec is the desired behavior of the HostedCluster.
858+
Spec HostedClusterSpec `json:"spec,omitempty"`
859+
860+
// Status is the latest observed status of the HostedCluster.
850861
Status HostedClusterStatus `json:"status,omitempty"`
851862
}
852863

‎api/v1alpha1/nodepool_types.go‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,12 @@ func init() {
3030
SchemeBuilder.Register(&NodePoolList{})
3131
}
3232

33-
// NodePool defines the desired state of NodePool
33+
// +genclient
34+
35+
// NodePool is a scalable set of worker nodes attached to a HostedCluster. NodePool
36+
// machine architectures are uniform within a given pool, and are independent of
37+
// the control plane’s underlying machine architecture.
38+
//
3439
// +kubebuilder:resource:path=nodepools,shortName=np;nps,scope=Namespaced
3540
// +kubebuilder:storageversion
3641
// +kubebuilder:subresource:status
@@ -47,7 +52,10 @@ type NodePool struct {
4752
metav1.TypeMeta `json:",inline"`
4853
metav1.ObjectMeta `json:"metadata,omitempty"`
4954

50-
Spec NodePoolSpec `json:"spec,omitempty"`
55+
// Spec is the desired behavior of the NodePool.
56+
Spec NodePoolSpec `json:"spec,omitempty"`
57+
58+
// Status is the most recently observed status of the NodePool.
5159
Status NodePoolStatus `json:"status,omitempty"`
5260
}
5361

‎cmd/install/assets/hypershift-operator/hypershift.openshift.io_hostedclusters.yaml‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,11 @@ spec:
4343
name: v1alpha1
4444
schema:
4545
openAPIV3Schema:
46-
description: HostedCluster is the Schema for the hostedclusters API
46+
description: HostedCluster is the primary representation of a HyperShift cluster
47+
and encapsulates the control plane and common data plane configuration.
48+
Creating a HostedCluster results in a fully functional OpenShift control
49+
plane with no attached nodes. To support workloads (e.g. pods), a HostedCluster
50+
may have one or more associated NodePool resources.
4751
properties:
4852
apiVersion:
4953
description: 'APIVersion defines the versioned schema of this representation
@@ -58,7 +62,7 @@ spec:
5862
metadata:
5963
type: object
6064
spec:
61-
description: HostedClusterSpec defines the desired state of HostedCluster
65+
description: Spec is the desired behavior of the HostedCluster.
6266
properties:
6367
auditWebhook:
6468
description: AuditWebhook contains metadata for configuring an audit
@@ -144,9 +148,9 @@ spec:
144148
type: array
145149
type: object
146150
controllerAvailabilityPolicy:
147-
description: ControllerAvailabilityPolicy specifies whether to run
148-
control plane controllers in HA mode Defaults to SingleReplica when
149-
not set.
151+
description: ControllerAvailabilityPolicy specifies an availability
152+
policy to apply to critical control plane components. Defaults to
153+
SingleReplica when not set.
150154
type: string
151155
dns:
152156
description: DNS configuration for the cluster
@@ -812,7 +816,7 @@ spec:
812816
- sshKey
813817
type: object
814818
status:
815-
description: HostedClusterStatus defines the observed state of HostedCluster
819+
description: Status is the latest observed status of the HostedCluster.
816820
properties:
817821
conditions:
818822
items:

‎cmd/install/assets/hypershift-operator/hypershift.openshift.io_nodepools.yaml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ spec:
5151
name: v1alpha1
5252
schema:
5353
openAPIV3Schema:
54-
description: NodePool defines the desired state of NodePool
54+
description: NodePool is a scalable set of worker nodes attached to a HostedCluster.
55+
NodePool machine architectures are uniform within a given pool, and are
56+
independent of the control plane’s underlying machine architecture.
5557
properties:
5658
apiVersion:
5759
description: 'APIVersion defines the versioned schema of this representation
@@ -66,7 +68,7 @@ spec:
6668
metadata:
6769
type: object
6870
spec:
69-
description: NodePoolSpec defines the desired state of NodePool
71+
description: Spec is the desired behavior of the NodePool.
7072
properties:
7173
autoScaling:
7274
properties:
@@ -325,7 +327,7 @@ spec:
325327
- release
326328
type: object
327329
status:
328-
description: NodePoolStatus defines the observed state of NodePool
330+
description: Status is the most recently observed status of the NodePool.
329331
properties:
330332
conditions:
331333
items:

‎docs/api-doc-gen/config.json‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,29 @@
11
{
22
"hideMemberFields": [
3-
"TypeMeta"
3+
"TypeMeta"
44
],
55
"hideTypePatterns": [
6-
"ParseError$",
7-
"List$"
6+
"ParseError$",
7+
"List$",
8+
"HostedControlPlane*$",
9+
"KubeconfigSecretRef",
10+
"APIEndpoint",
11+
"AWSEndpointService*"
812
],
913
"externalPackages": [
10-
{
11-
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
12-
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
13-
},
14-
{
15-
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
16-
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
17-
}
14+
{
15+
"typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
16+
"docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
17+
},
18+
{
19+
"typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
20+
"docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
21+
}
1822
],
1923
"typeDisplayNamePrefixOverrides": {
20-
"k8s.io/api/": "Kubernetes ",
21-
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
22-
"k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
24+
"k8s.io/api/": "Kubernetes ",
25+
"k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
26+
"k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
2327
},
2428
"markdownDisabled": false
2529
}

‎docs/api-doc-gen/templates/pkg.tpl‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,17 +29,6 @@ title: API Reference
2929
{{ end }}
3030
{{ end }}
3131

32-
Resource Types:
33-
<ul>
34-
{{- range (visibleTypes (sortedTypes .Types)) -}}
35-
{{ if isExportedType . -}}
36-
<li>
37-
<a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
38-
</li>
39-
{{- end }}
40-
{{- end -}}
41-
</ul>
42-
4332
{{ range (visibleTypes (sortedTypes .Types))}}
4433
{{ template "type" . }}
4534
{{ end }}

‎docs/api-doc-gen/templates/type.tpl‎

Lines changed: 30 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
{{ define "type" }}
22

3-
<h3 id="{{ anchorIDForType . }}">
4-
{{- .Name.Name }}
5-
{{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
6-
</h3>
3+
{{ if isExportedType . -}}
4+
## {{- .Name.Name }} { #{{ anchorIDForType . }} }
5+
{{ else -}}
6+
### {{- .Name.Name }} { #{{ anchorIDForType . }} }
7+
{{ end -}}
8+
79
{{ with (typeReferences .) }}
810
<p>
911
(<em>Appears on:</em>
@@ -22,6 +24,30 @@
2224
{{ safe (renderComments .CommentLines) }}
2325
</p>
2426

27+
{{ with (constantsOfType .) }}
28+
<table>
29+
<thead>
30+
<tr>
31+
<th>Value</th>
32+
<th>Description</th>
33+
</tr>
34+
</thead>
35+
<tbody>
36+
{{- range . -}}
37+
<tr>
38+
{{- /*
39+
renderComments implicitly creates a <p> element, so we
40+
add one to the display name as well to make the contents
41+
of the two cells align evenly.
42+
*/ -}}
43+
<td><p>{{ typeDisplayName . }}</p></td>
44+
<td>{{ safe (renderComments .CommentLines) }}</td>
45+
</tr>
46+
{{- end -}}
47+
</tbody>
48+
</table>
49+
{{ end }}
50+
2551
{{ if .Members }}
2652
<table>
2753
<thead>

0 commit comments

Comments
 (0)