Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

🌱 Improve open API docs #6878

Merged
merged 1 commit into from
Jul 8, 2022
+98 −34
Merged

🌱 Improve open API docs #6878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions exp/runtime/catalog/openapi.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this statement implies that if handlers do not serve the same hook they can share the same name but any two handlers of a single external component irrespective of if they serve the same hook should have different names. If not there will be a collision in the registry.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If not there will be a collision in the registry.

I think the discovery would already fail before we add anything to the registry as we validate that the Names have to be unique there.

Independent of that. I think you're right. Can you open a PR to improve this description?

Copy link
Contributor

@ykakarap ykakarap Jul 12, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the discovery would already fail before we add anything to the registry as we validate that the Names have to be unique there.

You are right. It would not pass the discovery response validation.

Independent of that. I think you're right. Can you open a PR to improve this description?

PR: #6896

Required: true,
Schema: &spec.Schema{
SchemaProps: spec.SchemaProps{
Type: []string{"string"},
Expand Down Expand Up @@ -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),
},
}
Expand Down
13 changes: 9 additions & 4 deletions exp/runtime/hooks/api/v1alpha1/discovery_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
})
}
75 changes: 57 additions & 18 deletions exp/runtime/hooks/api/v1alpha1/lifecyclehooks_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
})
}
24 changes: 18 additions & 6 deletions exp/runtime/hooks/api/v1alpha1/topologymutation_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
})
}