From be1e6a8d66a68804041f4fa8818b67fc6a111ffb Mon Sep 17 00:00:00 2001 From: James Peach Date: Thu, 4 Jun 2020 14:19:19 +1000 Subject: [PATCH] Document root CRD objects as API resource types. When finding the set of root CRD types, the documentation generator checks for the `+genclient` annotation, ratherd than the newer `+kubebuilder:object:root`. Adding `+genclient` makes the root CRD type objects appear in the resource list at the head of the API documentation, which improves their visibility. Signed-off-by: James Peach --- api/v1alpha1/gateway_types.go | 2 + api/v1alpha1/httproute_types.go | 2 + api/v1alpha1/tcproute_types.go | 2 + api/v1alpha1/trafficsplit_types.go | 2 + docs-src/spec.md | 487 ++++++++++++++++------------- 5 files changed, 280 insertions(+), 215 deletions(-) diff --git a/api/v1alpha1/gateway_types.go b/api/v1alpha1/gateway_types.go index d025668366..237ee1ae77 100644 --- a/api/v1alpha1/gateway_types.go +++ b/api/v1alpha1/gateway_types.go @@ -20,6 +20,8 @@ import ( metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" ) +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/httproute_types.go b/api/v1alpha1/httproute_types.go index 10e8df6865..e290accfb6 100644 --- a/api/v1alpha1/httproute_types.go +++ b/api/v1alpha1/httproute_types.go @@ -315,6 +315,8 @@ type HTTPRoute struct { Status HTTPRouteStatus `json:"status,omitempty" protobuf:"bytes,4,opt,name=status"` } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // HTTPRouteList contains a list of HTTPRoute diff --git a/api/v1alpha1/tcproute_types.go b/api/v1alpha1/tcproute_types.go index 07460ebf90..503055bf74 100644 --- a/api/v1alpha1/tcproute_types.go +++ b/api/v1alpha1/tcproute_types.go @@ -34,6 +34,8 @@ type TcpRouteStatus struct { // Important: Run "make" to regenerate code after modifying this file } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // TcpRoute is the Schema for the tcproutes API diff --git a/api/v1alpha1/trafficsplit_types.go b/api/v1alpha1/trafficsplit_types.go index 6a4a7a7a67..522f5c4d6b 100644 --- a/api/v1alpha1/trafficsplit_types.go +++ b/api/v1alpha1/trafficsplit_types.go @@ -34,6 +34,8 @@ type TrafficSplitStatus struct { // Important: Run "make" to regenerate code after modifying this file } +// +genclient +// +genclient:Namespaced // +kubebuilder:object:root=true // TrafficSplit is the Schema for the trafficsplits API diff --git a/docs-src/spec.md b/docs-src/spec.md index 030ee4bb2d..480fbb89f9 100644 --- a/docs-src/spec.md +++ b/docs-src/spec.md @@ -10,8 +10,132 @@

Resource Types: +

Gateway +

+

+

Gateway represents an instantiation of a service-traffic handling infrastructure.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +networking.x-k8s.io/v1alpha1 + +
+kind
+string +		Gateway
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +GatewaySpec + + +		 +
+
+ + + + + + + + + + + + + +
+class
+ +string + +		 +

Class used for this Gateway. This is the name of a GatewayClass resource.

+
+listeners
+ + +[]Listener + + +		 +

Listeners associated with this Gateway. Listeners define what addresses, +ports, protocols are bound on this Gateway.

+
+routes
+ + +RouteBindingSelector + + +		 +

Routes specifies a schema for associating routes with the Gateway using +selectors. A route is a resource capable of servicing a request and allows +a cluster operator to expose a cluster resource (i.e. Service) by +externally-reachable URL, load-balance traffic and terminate SSL/TLS. +Typically, a route is a “httproute” or “tcproute” in group +“networking.x-k8s.io”. However, an implementation may support other resources.

+

Support: Core

+
+
+status
+ + +GatewayStatus + + +		 +

GatewayClass

@@ -180,6 +304,154 @@ GatewayClassStatus +

TcpRoute +

+

+

TcpRoute is the Schema for the tcproutes API

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +networking.x-k8s.io/v1alpha1 + +
+kind
+string +		TcpRoute
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +TcpRouteSpec + + +		 +
+
+ +
+
+status
+ + +TcpRouteStatus + + +		 +
+

TrafficSplit +

+

+

TrafficSplit is the Schema for the trafficsplits API

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +networking.x-k8s.io/v1alpha1 + +
+kind
+string +		TrafficSplit
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +TrafficSplitSpec + + +		 +
+
+ +
+
+status
+ + +TrafficSplitStatus + + +		 +

AddressType (string alias)

@@ -321,107 +593,6 @@ surfaced in status.

-

Gateway -

-

-

Gateway represents an instantiation of a service-traffic handling infrastructure.

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -GatewaySpec - - -		 -
-
- - - - - - - - - - - - - -
-class
- -string - -		 -

Class used for this Gateway. This is the name of a GatewayClass resource.

-
-listeners
- - -[]Listener - - -		 -

Listeners associated with this Gateway. Listeners define what addresses, -ports, protocols are bound on this Gateway.

-
-routes
- - -RouteBindingSelector - - -		 -

Routes specifies a schema for associating routes with the Gateway using -selectors. A route is a resource capable of servicing a request and allows -a cluster operator to expose a cluster resource (i.e. Service) by -externally-reachable URL, load-balance traffic and terminate SSL/TLS. -Typically, a route is a “httproute” or “tcproute” in group -“networking.x-k8s.io”. However, an implementation may support other resources.

-

Support: Core

-
-
-status
- - -GatewayStatus - - -		 -

GatewayClassCondition

@@ -2105,63 +2276,6 @@ construct.

TargetPort specifies the destination port number to use for a TargetRef.

-

TcpRoute -

-

-

TcpRoute is the Schema for the tcproutes API

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -TcpRouteSpec - - -		 -
-
- -
-
-status
- - -TcpRouteStatus - - -		 -

TcpRouteSpec

@@ -2180,63 +2294,6 @@ TcpRouteStatus

TcpRouteStatus defines the observed state of TcpRoute

-

TrafficSplit -

-

-

TrafficSplit is the Schema for the trafficsplits API

-

- - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-metadata
- - -Kubernetes meta/v1.ObjectMeta - - -		 -Refer to the Kubernetes API documentation for the fields of the -metadata field. -
-spec
- - -TrafficSplitSpec - - -		 -
-
- -
-
-status
- - -TrafficSplitStatus - - -		 -

TrafficSplitSpec