Fix "kubectl explain" output for Agones CRDs

[aLekSer]

Is your feature request related to a problem? Please describe. Currently there is no option to see the description of fields using standard kubectl functionality:

kubectl explain gameservers.agones.dev
error: Couldn't find resource for "agones.dev/v1, Kind=GameServer"

Describe the solution you'd like Output should be similar to this:

kubectl explain pods

KIND:     Pod
VERSION:  v1

DESCRIPTION:
     Pod is a collection of containers that can run on a host. This resource is
     created by clients and scheduled onto hosts.

It seems that we could update apiserver.go code to serve requests of this kind. Describe alternatives you've considered

Additional context

[roberthbailey]

I think this is an issue of openapi spec not existing for CRDs. Based on https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/00xx-publish-crd-openapi.md it looks like once we update to 1.14 (or maybe later) this should "just work." It would be worth testing against a later k8s cluster to see what the behavior is.

[aLekSer]

Partially fixed in Kubernetes 1.16:

kubectl explain fleet
KIND:     Fleet
VERSION:  agones.dev/v1

DESCRIPTION:
     <empty>

So what left is to understand where to put a description.

[aLekSer]

I was able to fix output of kubectl explain for gameserverallocationpolicies.multicluster.agones.dev.

CRD extension has been promoted to v1. We have some changes to consider, e.g spec.validation is removed; use spec.versions[*].schema instead

spec.validation was switched to spec.versions.schema and apiextensions.k8s.io to v1 and added type: object root element in validation schema field.

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  creationTimestamp: null
  labels:
    controller-tools.k8s.io: "1.0"
    component: crd
    app: agones
    chart: agones-1.8.0
    release: agones-manual
    heritage: Helm
  name: gameserverallocationpolicies.multicluster.agones.dev
spec:
  group: multicluster.agones.dev
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          apiVersion:
            description: 'APIVersion defines the versioned schema of this representation
              of an object. Servers should convert recognized schemas to the latest
              internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#resources'
            type: string
          kind:
            description: 'Kind is a string value representing the REST resource this
              object represents. Servers may infer this from the endpoint the client
              submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds'
            type: string
          metadata:
            type: object
          spec:
            properties:
              connectionInfo:
                properties:
                  secretName:
                    type: string
                  serverCa:
                    type: string
                    format: byte
                  allocationEndpoints:
                    items:
                      type: string
                    type: array
                    minItems: 1
                  clusterName:
                    type: string
                  namespace:
                    type: string
                required:
                - namespace
                type: object
              priority:
                format: int32
                minimum: 0
                type: integer
              weight:
                format: int64
                minimum: 0
                type: integer
            required:
            - priority
            - weight
            type: object
  - name: v1alpha1
    # Disable the v1alpha1 version, but include it for inplace upgrade.
    served: false
    storage: false
    schema:
      openAPIV3Schema:
        type: object
  names:
    kind: GameServerAllocationPolicy
    plural: gameserverallocationpolicies
  scope: Namespaced
status:
  acceptedNames:
    kind: ""
    plural: ""
  conditions: []
  storedVersions: []

[markmandel]

We have schemas now for everything - I wonder what the output is now. Could be good to test.

[eminguyen]

The output appears to be good! All of the descriptions are still <empty> though, with the exception of lists.

$ kubectl explain fleets.agones.dev
KIND:     Fleet
VERSION:  agones.dev/v1

DESCRIPTION:
     <empty>

FIELDS:
   apiVersion   <string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

   kind <string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

   metadata     <Object>
     Standard object's metadata. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

   spec <Object>

   status       <Object>

$ kubectl explain gameserver
KIND:     GameServer
VERSION:  agones.dev/v1

DESCRIPTION:
     <empty>

FIELDS:
   apiVersion   <string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

   kind <string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

   metadata     <Object>
     Standard object's metadata. More info:
     https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

   spec <Object> -required-

   status       <Object>

[roberthbailey]

As per https://github.com/googleforgames/agones/issues/1194#issuecomment-686437406 it seems like we are still missing the description, not just for the top level resource but also for the spec and status.