diff --git a/exp/runtime/catalog/openapi.go b/exp/runtime/catalog/openapi.go index eb8b2279db8b..8e3dbf44434b 100644 --- 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 index 24796745e67a..3a18b3de2ee3 100644 --- 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 index 9e373c7e675c..ae3a6e516ab5 100644 --- 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 index 88d6a16958d7..a5db2ca021d4 100644 --- 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", }) }