Improve open API docs

kubernetes-sigs · Jul 8, 2022 · be103c1 · be103c1
1 parent 26943ea
commit be103c1
Show file tree

Hide file tree

Showing 4 changed files with 98 additions and 34 deletions.
diff --git a/exp/runtime/catalog/openapi.go b/exp/runtime/catalog/openapi.go
@@ -37,8 +37,15 @@ func (c *Catalog) OpenAPI(version string) (*spec3.OpenAPI, error) {
 		Version: "3.0.0",
 		Info: &spec.Info{
 			InfoProps: spec.InfoProps{
-				Description: "Open API specification for Cluster API Runtime SDK",
-				Title:       "Cluster API - Runtime SDK",
+				Description: "This document defines the Open API specification of the services that Cluster API runtime is going " +
+					"to call while managing the Cluster's lifecycle.\n" +
+					"\n" +
+					"Services described in this specification are also referred to as Runtime Hooks, given that they allow " +
+					"external components to hook-in the cluster's lifecycle. The corresponding components implementing handlers " +
+					"for Runtime Hooks calls are referred to as Runtime Extensions.\n" +
+					"\n" +
+					"More information is available in the [Cluster API book](https://cluster-api.sigs.k8s.io/).",
+				Title: "Cluster API - Runtime SDK",
 				License: &spec.License{
 					Name: "Apache 2.0",
 					URL:  "http://www.apache.org/licenses/LICENSE-2.0.html",
@@ -88,9 +95,10 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
 		path = GVHToPath(gvh, "{name}")
 		operation.Parameters = append(operation.Parameters, &spec3.Parameter{
 			ParameterProps: spec3.ParameterProps{
-				Name:     "name",
-				In:       "path",
-				Required: true,
+				Name:        "name",
+				In:          "path",
+				Description: "The handler name. Handlers for the same hook within a single external component implementing Runtime Extensions must have different names",
+				Required:    true,
 				Schema: &spec.Schema{
 					SchemaProps: spec.SchemaProps{
 						Type: []string{"string"},
@@ -131,7 +139,7 @@ func addHookAndTypesToOpenAPI(openAPI *spec3.OpenAPI, c *Catalog, gvh GroupVersi
 	responseTypeName := typeName(responseType, responseGVK)
 	operation.Responses.StatusCodeResponses[http.StatusOK] = &spec3.Response{
 		ResponseProps: spec3.ResponseProps{
-			Description: "OK",
+			Description: "Status code 200 indicates that the request has been processed successfully. Runtime Extension authors must use fields in the response like e.g. status and message to return processing outcomes.",
 			Content:     createContent(responseTypeName),
 		},
 	}

diff --git a/exp/runtime/hooks/api/v1alpha1/discovery_types.go b/exp/runtime/hooks/api/v1alpha1/discovery_types.go
@@ -91,9 +91,14 @@ func Discovery(*DiscoveryRequest, *DiscoveryResponse) {}
 
 func init() {
 	catalogBuilder.RegisterHook(Discovery, &runtimecatalog.HookMeta{
-		Tags:        []string{"Discovery"},
-		Summary:     "Discovery hook",
-		Description: "Discovery hook discovers the supported hooks of a RuntimeExtension",
-		Singleton:   true,
+		Tags:    []string{"Discovery"},
+		Summary: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled",
+		Description: "Cluster API Runtime will call this hook when an ExtensionConfig is reconciled. " +
+			"Runtime Extension implementers must use this hook to inform the Cluster API runtime about all the handlers " +
+			"that are defined in an external component implementing Runtime Extensions.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- When using Runtime SDK utils, a handler for this hook is automatically generated",
+		Singleton: true,
 	})
 }
diff --git a/exp/runtime/hooks/api/v1alpha1/lifecyclehooks_types.go b/exp/runtime/hooks/api/v1alpha1/lifecyclehooks_types.go
@@ -180,38 +180,77 @@ func BeforeClusterDelete(*BeforeClusterDeleteRequest, *BeforeClusterDeleteRespon
 
 func init() {
 	catalogBuilder.RegisterHook(BeforeClusterCreate, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called before Cluster topology is created.",
-		Description: "This blocking hook is called after the Cluster is created by the user and immediately before all the objects which are part of a Cluster topology are going to be created.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook before a Cluster's topology is created",
+		Description: "Cluster API Runtime will call this hook after the Cluster is created by the user and immediately before " +
+			"all the objects which are part of a Cluster's topology are going to be created.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- The call's request contains the Cluster object\n" +
+			"- This is a blocking hook; Runtime Extension implementers can use this hook to execute\n" +
+			"tasks before the objects which are part of a Cluster's topology are created",
 	})
 
 	catalogBuilder.RegisterHook(AfterControlPlaneInitialized, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called after the Control Plane is initialized for the first time.",
-		Description: "This non-blocking hook is called after the Control Plane for the Cluster is reachable for the first time.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook after the control plane is reachable for the first time",
+		Description: "Cluster API Runtime will call this hook after the control plane for the Cluster is reachable for the first time.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- This is a non-blocking hook",
 	})
 
 	catalogBuilder.RegisterHook(BeforeClusterUpgrade, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called before the Cluster is upgraded.",
-		Description: "This blocking hook is called after the Cluster object has been updated with a new spec.topology.version by the user, and immediately before the new version is propagated to the Control Plane.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook before the Cluster is upgraded",
+		Description: "Cluster API Runtime will call this hook after the Cluster object has been updated with a new spec.topology.version by the user, " +
+			"and immediately before the new version is propagated to the control plane.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- The call's request contains the Cluster object, the current Kubernetes version and the Kubernetes version we are upgrading to\n" +
+			"- This is a blocking hook; Runtime Extension implementers can use this hook to execute " +
+			"tasks before the new version is propagated to the control plane",
 	})
 
 	catalogBuilder.RegisterHook(AfterControlPlaneUpgrade, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called after the Control Plane is upgraded.",
-		Description: "This blocking hook is called after the Control Plane has been upgraded to the version specified in spec.topology.version, and immediately before the new version is propagated to the MachineDeployments.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook after the control plane is upgraded",
+		Description: "Cluster API Runtime will call this hook after the a cluster's control plane has been upgraded to the version specified " +
+			"in spec.topology.version, and immediately before the new version is going to be propagated to the MachineDeployments. " +
+			"A control plane upgrade is completed when all the machines in the control plane have been upgraded.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- The call's request contains the Cluster object and the Kubernetes version we upgraded to\n" +
+			"- This is a blocking hook; Runtime Extension implementers can use this hook to execute " +
+			"tasks before the new version is propagated to the MachineDeployments",
 	})
 
 	catalogBuilder.RegisterHook(AfterClusterUpgrade, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called after the Cluster is upgraded.",
-		Description: "This non-blocking hook is called after the Cluster, Control Plane and MachineDeployments have been upgraded to the version specified in spec.topology.version.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook after a Cluster is upgraded",
+		Description: "Cluster API Runtime will call this hook after a Cluster has been upgraded to the version specified " +
+			"in spec.topology.version. An upgrade is completed when all control plane and MachineDeployment's Machines have been upgraded.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- The call's request contains the Cluster object and the Kubernetes version we upgraded to \n" +
+			"- This is a non-blocking hook",
 	})
 
 	catalogBuilder.RegisterHook(BeforeClusterDelete, &runtimecatalog.HookMeta{
-		Tags:        []string{"Lifecycle Hooks"},
-		Summary:     "Called before the Cluster is deleted.",
-		Description: "This blocking hook is called after the Cluster deletion has been triggered by the user, and immediately before objects of the Cluster are going to be deleted.",
+		Tags:    []string{"Lifecycle Hooks"},
+		Summary: "Cluster API Runtime will call this hook before the Cluster is deleted",
+		Description: "Cluster API Runtime will call this hook after the Cluster deletion has been triggered by the user, " +
+			"and immediately before objects of the Cluster are going to be deleted.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- This hook will be called only for Clusters with a managed topology\n" +
+			"- The call's request contains the Cluster object \n" +
+			"- This is a blocking hook; Runtime Extension implementers can use this hook  to execute " +
+			"tasks before objects of the Cluster are deleted",
 	})
 }
diff --git a/exp/runtime/hooks/api/v1alpha1/topologymutation_types.go b/exp/runtime/hooks/api/v1alpha1/topologymutation_types.go
@@ -175,14 +175,26 @@ func ValidateTopology(*ValidateTopologyRequest, *ValidateTopologyResponse) {}
 
 func init() {
 	catalogBuilder.RegisterHook(GeneratePatches, &runtimecatalog.HookMeta{
-		Tags:        []string{"Topology Mutation Hook"},
-		Summary:     "GeneratePatches generates patches during topology reconciliation for the entire Cluster topology.",
-		Description: "A GeneratePatches call generates patches for the entire Cluster topology. Accordingly the request contains all templates, the global variables and the template-specific variables. The response contains generated patches.",
+		Tags:    []string{"Topology Mutation Hook"},
+		Summary: "Cluster API Runtime will call this hook when a Cluster's topology is being computed",
+		Description: "Cluster API Runtime will call this hook when a Cluster's topology is being computed " +
+			"during each topology controller reconcile loop. More specifically, this hook will be called " +
+			"while computing patches to be applied on top of templates derived from the Cluster's ClusterClass.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- The call's request contains all templates, the global variables and the template-specific variables required to compute patches\n" +
+			"- The response must contain generated patches",
 	})
 
 	catalogBuilder.RegisterHook(ValidateTopology, &runtimecatalog.HookMeta{
-		Tags:        []string{"Topology Mutation Hook"},
-		Summary:     "ValidateTopology validates the Cluster topology after all patches have been applied.",
-		Description: "A ValidateTopology call validates the Cluster topology after all patches have been applied. The request contains all templates of the Cluster topology, the global variables and the template-specific variables. The response contains the result of the validation.",
+		Tags:    []string{"Topology Mutation Hook"},
+		Summary: "Cluster API Runtime will call this hook after a Cluster's topology has been computed",
+		Description: "Cluster API Runtime will call this hook after a Cluster's topology has been computed " +
+			"during each topology controller reconcile loop. More specifically, this hook will be called " +
+			"after all patches have been applied to the templates derived from the Cluster's ClusterClass.\n" +
+			"\n" +
+			"Notes:\n" +
+			"- The call's request contains all templates, the global variables and the template-specific variables used while computing patches\n" +
+			"- The response must contain the result of the validation",
 	})
 }