discovery

Knative Discovery API

This is Work in Progress. It is based on the Discovery API design doc.

Install

TODO: instructions on installing nightly and a release.

Development

Install,

ko apply -f ./config

If you modify the ClusterDuckType definition, you may have to update the ClusterDuckType's OpenAPI Schema. Refer to hack/schema to help generate the schema definition.

ClusterDuckType:discovery.knative.dev/v1alpha1

The goal is to have a custom type that is user installable to help a developer, cluster admin, or tooling to better understand the duck types that are installed in the cluster. This information could be used to understand which Kinds could fulfill a role for another resource.

demos.example.com.yaml

apiVersion: discovery.knative.dev/v1alpha1
kind: ClusterDuckType
metadata:
  name: demos.example.com
spec:
  # selectors is a list of CRD label selectors to find CRDs that have been
  # labeled as the given duck type.
  selectors:
    - labelSelector: "example.com/demo=true"

  # Names allows us to give a short name to the duck type.
  names:
    name: "Demo"
    plural: "demos"
    singular: "demo"

  # Versions are to allow the definition of a single duck type with multiple
  # versions, useful if the duck type API shape changes.
  versions:
    - name: "v1"
      # refs allows for adding native types, or crds directly as the ducks via
      # Group/Version/Kind/Resource
      refs:
        - group: "demo.example.com"
          version: "v1"
          kind: "Demo"
      # additionalPrinterColumns is intended to understand what printer columns
      # should be used for the custom objects.
      additionalPrinterColumns:
        - name: Ready
          type: string
          jsonPath: ".status.conditions[?(@.type=='Ready')].status"
        - name: Reason
          type: string
          jsonPath: ".status.conditions[?(@.type=='Ready')].reason"
        - name: Demo
          type: string
          jsonPath: .status.demo
      # schema is the partial schema of the duck type.
      schema:
        openAPIV3Schema:
          properties:
            status:
              type: object
              properties:
                address:
                  type: object
                  properties:
                    demo:
                      type: string

  # Role holds an Aggregating Role used by the duck type to manage the ducks.
  # If not specified, the Selectors are used to find a Role with an aggregation rule that matches a selector
  role:
    roleRef:
      kind: ClusterRole
      name: view
      apiGroup: rbac.authorization.k8s.io
  group: example.com

Demo

Using addressables.duck.knative.dev.yaml, we will apply it,

kubectl apply -f ./config/knative/addressables.duck.knative.dev.yaml

clusterducktype.discovery.knative.dev/addressables.duck.knative.dev created

After applying this, you can fetch it:

kubectl get cducks addressables.duck.knative.dev

NAME                            SHORT NAME    DUCKS   READY   REASON
addressables.duck.knative.dev   addressable   6       True

And get the full DuckType addressables.duck.knative.dev resource:

kubectl get clusterducktypes addressables.duck.knative.dev -oyaml

apiVersion: discovery.knative.dev/v1alpha1
kind: ClusterDuckType
metadata:
  generation: 1
  name: addressables.duck.knative.dev
spec: ...
status:
  conditions:
    - lastTransitionTime: "2021-04-06T01:19:42Z"
      status: "True"
      type: Ready
  clusterRoleAggregationRule:
    clusterRoleSelectors:
      - matchLabels:
          duck.knative.dev/addressable: "true"
  duckCount: 7
  ducks:
    v1:
      - accessibleByClusterRole: true
        apiVersion: eventing.knative.dev/v1
        kind: Broker
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: eventing.knative.dev/v1beta1
        kind: Broker
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: flows.knative.dev/v1
        kind: Parallel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: flows.knative.dev/v1
        kind: Sequence
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: flows.knative.dev/v1beta1
        kind: Parallel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: flows.knative.dev/v1beta1
        kind: Sequence
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: messaging.knative.dev/v1
        kind: Channel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: messaging.knative.dev/v1
        kind: InMemoryChannel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: messaging.knative.dev/v1beta1
        kind: Channel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: messaging.knative.dev/v1beta1
        kind: InMemoryChannel
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: serving.knative.dev/v1
        kind: Route
        scope: Namespaced
      - accessibleByClusterRole: true
        apiVersion: serving.knative.dev/v1
        kind: Service
        scope: Namespaced
  observedGeneration: 1

Knative Duck Types

If the ./config/knative directory is applied (via kubectl apply -f config/knative), a quick view of the duck types used by Knative in this cluster becomes easier to find:

kubectl get clusterducktypes

NAME                            SHORT NAME    DUCKS   READY   REASON
addressables.duck.knative.dev   Addressable   6       True
bindings.duck.knative.dev       Binding       1       True
channelables.duck.knative.dev   Channelable   0       True
podspecables.duck.knative.dev   PodSpecable   7       True
sources.duck.knative.dev        Source        4       True

Note: there is also a short name: cducks

kubectl get cducks