Document our resources schema / yaml

[carolynvs]

It would be incredibly helpful to have a document that outlines the entire set of acceptable yaml that can be sent to Service Catalog, which fields are required, when you would set an optional value, etc.

For example:

manifest-schema.md

apiVersion: servicecatalog.k8s.io/v1beta1
kind: ServiceInstance
metadata:
  name: ups-instance
  namespace: test-ns
spec:
  clusterServiceClassExternalName: user-provided-service # Required
  clusterServiceClassName: user-provided-service-uuid # Required (but explain that one must be set)
  clusterServicePlanExternalName: default # Required
  clusterServicePlanName: default-uuid #Required (but explain again when)
  parameters: # Optional
    param-1: value-1
    param-2: value-2
...

Maybe a full set to of values and a table explaining each one?

[jeremyrickard]

#dibs

[MHBauer]

I feel like the best place for this is types.go, as it is the ultimate source of truth.

Can we generate docs off of the existing comments? Another code-generator to run.

[carolynvs]

Another code-generator to run

😝 Yes, I think that's a good idea.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.