Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

📖 Add APIBindings example #3207

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

📖 Add APIBindings example #3207

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7ac5005
Add APIBindings example
SimonTheLeg Dec 6, 2024
e6ad9ac
Apply suggestions from code review
SimonTheLeg Dec 10, 2024
d10b444
add info on PermissionClaim on ApiExport update
SimonTheLeg Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 31 additions & 10 deletions docs/content/concepts/apis/exporting-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Exporting APIs
# Exporting and Binding APIs

If you're looking to provide APIs that can be consumed by multiple workspaces, this section is for you!

Expand Down Expand Up @@ -374,12 +374,33 @@ TODO
## Bind to Exported APIs

### APIBinding
TODO
- "imports" all the `APIResourceSchemas` defined in an `APIExport` into its workspace
- Also provides access to the group/resources defined in an `APIExport`'s `PermissionClaims` slice
- APIs are "imported" by accepting `PermissionClaims` within the `APIBinding` for each of the `APIExport`'s group/resources
- The consumer of the `APIExport` must be granted permission to the `bind` verb on that `APIExport` in order to create an `APIBinding`
- An `APIBinding` is bound to a specific `APIExport` and associated `APIResourceSchema`s via the `APIBinding.Status.BoundResources` field, which will hold the identity information to precisely identify relevant objects.
- how do I correctly reference an APIExport?

[diagram1]: https://asciiflow.com/#/share/eJyrVspLzE1VssorzcnRUcpJrEwtUrJSqo5RqohRsrI0NdGJUaoEsozMzYCsktSKEiAnRkmBGPBoyh5qoZiYPGKtVFBwzs8rLs1NLVIIzy%2FKLi5ITE6FyJBgyIC4G5cMEYZgtVwhPDMlPbWkWMExwNMpMy8lMy%2BdFAOp5C44BXGNgiMWY6gY4igBgNUBTtgdAGQDw0khoCi%2FLDMFNfHgNMp5gPxCxeSJO4YR8YeqEilVuVYU5BeVKDya3kKCDdj5ONROw68WyS1BqcX5pUXJqcHJGam5iehx1vNoSgM10AT6xHATzlKsiZRcN4dKvl5C1xIDS9DgKMmICQyoqU24ZUgyBEcpRpYh6CURWYagl0EkGDKFSsljRoxSrVItAH%2FrdL4%3D

`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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

using the name of the APIExport and path to the workspace, where an APIExport is located
something like that maybe

Furthermore, `APIBindings` provide access to the groups/resources defined in an `APIExport's` `PermissionClaims` list.

SimonTheLeg marked this conversation as resolved.
Show resolved Hide resolved
Returning to our previous example, we can use the following `APIBinding` to import the widgets api.

```yaml
apiVersion: apis.kcp.io/v1alpha1
kind: APIBinding
metadata:
name: example.kcp.io
spec:
reference:
export:
name: example.kcp.io
path: "root:api-provider" # path of your api-provider workspace
```

It should be noted that `APIBindings` do not create `CRDs` or `APIResourceSchemas`. Instead APIs are directly bound. This means you can query for imported APIs using `kubectl api-resources`. Additionally you can use `kubectl explain` to get a detailed view on all fields of the API.

SimonTheLeg marked this conversation as resolved.
Show resolved Hide resolved
```sh
# inside consumer workspace
kubectl api-resources --api-group='example.kcp.io'

NAME SHORTNAMES APIVERSION NAMESPACED KIND
widgets example.kcp.io/v1alpha1 false Widget
```

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