📖 Add APIBindings example

[SimonTheLeg]

Summary

Adds an APIBinding example to fit with the example previously on the page and adds some more information on APIBindings/turns some of the bullets into full text.

The asciiflow link did not resolve for me and is also not rendered in the documentation at the moment, so I removed it.

Related issue(s)

Fixes #

Release Notes

NONE

[kcp-ci-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign embik for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[kcp-ci-bot]

Hi @SimonTheLeg. Thanks for your PR.

I'm waiting for a kcp-dev member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[sttts]

/ok-to-test

[SimonTheLeg]

addressed all comments. Ready for review again

[embik]

Some small changes I would suggest.

[embik]

Suggested change

	`APIBindings` are used to import API resources. They contain a reference to an `APIExport` using the namespace and workspace path of an `APIExport` and will bind all APIs defined in the `APIExport`. The reference path needs to be provided to you by the provider of the API or an external catalog solution.
	`APIBindings` are used to import API resources. They contain a reference to an `APIExport` using the name and workspace path of an `APIExport` and will bind all APIs defined in the `APIExport`. The reference path needs to be provided to you by the provider of the API or an external catalog solution if you don't have direct access to the workspace containing the `APIExport`.

I think the "namespace" part here is wrong, APIExports are cluster-level resources. Maybe "name" was meant? In addition, I suggest a little clarification on how to get the APIExport path (if you have access directly, you don't need someone to give you the path; it's entirely possible that people make this choice).

[embik]

Nit: I think we shouldn't put permission claims in backticks, they aren't a standalone resource type. It would be more useful to put the JSONpath references to where permission claims are configured in APIExport and APIBindings.

[embik]

Suggested change

	It should be noted that `APIBindings` do not create `CRDs` or `APIResourceSchemas`. Instead APIs are directly bound.
	It should be noted that `APIBindings` do not create `CRDs` or `APIResourceSchemas` in the workspace. Instead APIs are directly bound.

Strictly speaking (as far as I know), CRDs are created somewhere in the shadows, so let's make this sentence a little more precise.

[embik]

Suggested change

	Furthermore, you can use the `APIBinding.Status.BoundResources` field to precisely identify which `APIResourceSchemas` have been imported.
	Furthermore, you can use the `.status.boundResources` field of an `APIBinding` to precisely identify which `APIResourceSchemas` have been imported.

I would say we should reference via JSONpath, not Go structs. That only makes sense if you develop a controller, and you usually don't write controllers that check an APIBinding status.

[janwillies]

Instead APIs are directly bound.

What does this mean?

[jmcshane]

How are these permissions granted? Need an example in line with the APIExport sample above.