Improve API reference docs

api/v1alpha1/doc.go

@@ -1,4 +1,14 @@
-// Package v1alpha1 contains API Schema definitions for the hypershift.openshift.io v1alpha1 API group
+/*
+Package v1alpha1 contains the HyperShift API.
+
+The HyperShift API enables creating and managing lightweight, flexible, heterogeneous
+OpenShift clusters at scale.
+
+HyperShift clusters are deployed in a topology which isolates the "control plane"
+(e.g. etcd, the API server, controller manager, etc.) from the "data plane" (e.g.
+worker nodes and their kubelets, and the infrastructure on which they run). This
+enables "hosted control plane as a service" use cases.
+*/
 // +kubebuilder:object:generate=true
 // +groupName=hypershift.openshift.io
 package v1alpha1

api/v1alpha1/hosted_controlplane.go

@@ -97,11 +97,21 @@ type HostedControlPlaneSpec struct {
 	SecretEncryption *SecretEncryptionSpec `json:"secretEncryption,omitempty"`
 }
 
+// AvailabilityPolicy specifies a high level availability policy for components.
 type AvailabilityPolicy string
 
 const (
+	// HighlyAvailable means components should be resilient to problems across fault
+	// boundaries as defined by the component to which the policy is attached. This
+	// usually means running critical workloads with 3 replicas and with little or
+	// no toleration of disruption of the component.
 	HighlyAvailable AvailabilityPolicy = "HighlyAvailable"
-	SingleReplica   AvailabilityPolicy = "SingleReplica"
+
+	// SingleReplica means components are not expected to be resilient to problems
+	// across most fault boundaries associated with high availability. This usually
+	// means running critical workloads with just 1 replica and with toleration of
+	// full disruption of the component.
+	SingleReplica AvailabilityPolicy = "SingleReplica"
 )
 
 type KubeconfigSecretRef struct {

api/v1alpha1/hostedcluster_types.go

@@ -129,7 +129,8 @@ type HostedClusterSpec struct {
 	// TODO (alberto): include Ignition endpoint here.
 	Services []ServicePublishingStrategyMapping `json:"services"`
 
-	// ControllerAvailabilityPolicy specifies whether to run control plane controllers in HA mode
+	// ControllerAvailabilityPolicy specifies an availability policy to apply
+	// to critical control plane components.
 	// Defaults to SingleReplica when not set.
 	// +optional
 	ControllerAvailabilityPolicy AvailabilityPolicy `json:"controllerAvailabilityPolicy,omitempty"`
@@ -841,6 +842,14 @@ type ClusterConfiguration struct {
 	Items []runtime.RawExtension `json:"items,omitempty"`
 }
 
+// +genclient
+
+// HostedCluster is the primary representation of a HyperShift cluster and encapsulates
+// the control plane and common data plane configuration. Creating a HostedCluster
+// results in a fully functional OpenShift control plane with no attached nodes.
+// To support workloads (e.g. pods), a HostedCluster may have one or more associated
+// NodePool resources.
+//
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:path=hostedclusters,shortName=hc;hcs,scope=Namespaced
 // +kubebuilder:storageversion
@@ -850,12 +859,14 @@ type ClusterConfiguration struct {
 // +kubebuilder:printcolumn:name="Progress",type="string",JSONPath=".status.version.history[?(@.state!=\"\")].state",description="Progress"
 // +kubebuilder:printcolumn:name="Available",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].status",description="Available"
 // +kubebuilder:printcolumn:name="Reason",type="string",JSONPath=".status.conditions[?(@.type==\"Available\")].reason",description="Reason"
-// HostedCluster is the Schema for the hostedclusters API
 type HostedCluster struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   HostedClusterSpec   `json:"spec,omitempty"`
+	// Spec is the desired behavior of the HostedCluster.
+	Spec HostedClusterSpec `json:"spec,omitempty"`
+
+	// Status is the latest observed status of the HostedCluster.
 	Status HostedClusterStatus `json:"status,omitempty"`
 }
 

api/v1alpha1/nodepool_types.go

@@ -30,7 +30,12 @@ func init() {
 	SchemeBuilder.Register(&NodePoolList{})
 }
 
-// NodePool defines the desired state of NodePool
+// +genclient
+
+// NodePool is a scalable set of worker nodes attached to a HostedCluster. NodePool
+// machine architectures are uniform within a given pool, and are independent of
+// the control plane’s underlying machine architecture.
+//
 // +kubebuilder:resource:path=nodepools,shortName=np;nps,scope=Namespaced
 // +kubebuilder:storageversion
 // +kubebuilder:subresource:status
@@ -47,7 +52,10 @@ type NodePool struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata,omitempty"`
 
-	Spec   NodePoolSpec   `json:"spec,omitempty"`
+	// Spec is the desired behavior of the NodePool.
+	Spec NodePoolSpec `json:"spec,omitempty"`
+
+	// Status is the most recently observed status of the NodePool.
 	Status NodePoolStatus `json:"status,omitempty"`
 }
 

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

@@ -43,7 +43,11 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: HostedCluster is the Schema for the hostedclusters API
+        description: HostedCluster is the primary representation of a HyperShift cluster
+          and encapsulates the control plane and common data plane configuration.
+          Creating a HostedCluster results in a fully functional OpenShift control
+          plane with no attached nodes. To support workloads (e.g. pods), a HostedCluster
+          may have one or more associated NodePool resources.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -58,7 +62,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: HostedClusterSpec defines the desired state of HostedCluster
+            description: Spec is the desired behavior of the HostedCluster.
             properties:
               auditWebhook:
                 description: AuditWebhook contains metadata for configuring an audit
@@ -144,9 +148,9 @@ spec:
                     type: array
                 type: object
               controllerAvailabilityPolicy:
-                description: ControllerAvailabilityPolicy specifies whether to run
-                  control plane controllers in HA mode Defaults to SingleReplica when
-                  not set.
+                description: ControllerAvailabilityPolicy specifies an availability
+                  policy to apply to critical control plane components. Defaults to
+                  SingleReplica when not set.
                 type: string
               dns:
                 description: DNS configuration for the cluster
@@ -813,7 +817,7 @@ spec:
             - sshKey
             type: object
           status:
-            description: HostedClusterStatus defines the observed state of HostedCluster
+            description: Status is the latest observed status of the HostedCluster.
             properties:
               conditions:
                 items:

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

@@ -51,7 +51,9 @@ spec:
     name: v1alpha1
     schema:
       openAPIV3Schema:
-        description: NodePool defines the desired state of NodePool
+        description: NodePool is a scalable set of worker nodes attached to a HostedCluster.
+          NodePool machine architectures are uniform within a given pool, and are
+          independent of the control plane’s underlying machine architecture.
         properties:
           apiVersion:
             description: 'APIVersion defines the versioned schema of this representation
@@ -66,7 +68,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: NodePoolSpec defines the desired state of NodePool
+            description: Spec is the desired behavior of the NodePool.
             properties:
               autoScaling:
                 properties:
@@ -325,7 +327,7 @@ spec:
             - release
             type: object
           status:
-            description: NodePoolStatus defines the observed state of NodePool
+            description: Status is the most recently observed status of the NodePool.
             properties:
               conditions:
                 items:

docs/api-doc-gen/config.json

@@ -1,25 +1,29 @@
 {
   "hideMemberFields": [
-      "TypeMeta"
+    "TypeMeta"
   ],
   "hideTypePatterns": [
-      "ParseError$",
-      "List$"
+    "ParseError$",
+    "List$",
+    "HostedControlPlane*$",
+    "KubeconfigSecretRef",
+    "APIEndpoint",
+    "AWSEndpointService*"
   ],
   "externalPackages": [
-      {
-          "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
-          "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
-      },
-      {
-          "typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
-          "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
-      }
+    {
+      "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$",
+      "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration"
+    },
+    {
+      "typeMatchPrefix": "^k8s\\.io/(api|apimachinery|apiextensions-apiserver/pkg/apis)/",
+      "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}"
+    }
   ],
   "typeDisplayNamePrefixOverrides": {
-      "k8s.io/api/": "Kubernetes ",
-      "k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
-      "k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
+    "k8s.io/api/": "Kubernetes ",
+    "k8s.io/apimachinery/pkg/apis/": "Kubernetes ",
+    "k8s.io/apiextensions-apiserver/pkg/apis/": "Kubernetes "
   },
   "markdownDisabled": false
 }

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

@@ -29,17 +29,6 @@ title: API Reference
         {{ end }}
     {{ end }}
 
-    Resource Types:
-    <ul>
-    {{- range (visibleTypes (sortedTypes .Types)) -}}
-        {{ if isExportedType . -}}
-        <li>
-            <a href="{{ linkForType . }}">{{ typeDisplayName . }}</a>
-        </li>
-        {{- end }}
-    {{- end -}}
-    </ul>
-
     {{ range (visibleTypes (sortedTypes .Types))}}
         {{ template "type" .  }}
     {{ end }}

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

@@ -1,9 +1,11 @@
 {{ define "type" }}
 
-<h3 id="{{ anchorIDForType . }}">
-    {{- .Name.Name }}
-    {{ if eq .Kind "Alias" }}(<code>{{.Underlying}}</code> alias)</p>{{ end -}}
-</h3>
+{{ if isExportedType . -}}
+## {{- .Name.Name }} { #{{ anchorIDForType . }} }
+{{ else -}}
+### {{- .Name.Name }} { #{{ anchorIDForType . }} }
+{{ end -}}
+
 {{ with (typeReferences .) }}
     <p>
         (<em>Appears on:</em>
@@ -22,6 +24,30 @@
     {{ safe (renderComments .CommentLines) }}
 </p>
 
+{{ with (constantsOfType .) }}
+<table>
+    <thead>
+        <tr>
+            <th>Value</th>
+            <th>Description</th>
+        </tr>
+    </thead>
+    <tbody>
+      {{- range . -}}
+      <tr>
+        {{- /*
+            renderComments implicitly creates a <p> element, so we
+            add one to the display name as well to make the contents
+            of the two cells align evenly.
+        */ -}}
+        <td><p>{{ typeDisplayName . }}</p></td>
+        <td>{{ safe (renderComments .CommentLines) }}</td>
+      </tr>
+      {{- end -}}
+    </tbody>
+</table>
+{{ end }}
+
 {{ if .Members }}
 <table>
     <thead>