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 all commits
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
44 changes: 34 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,36 @@ 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).

Furthermore, `APIBindings` provide the `APIExport` owner access to additional resources defined in an `APIExport`'s `PermissionClaims` list. `PermissionClaims` must be accepted by the user explicitly, before this access is granted. The resources can be builtin Kubernetes resources or resources from other `APIExports`.
When an `APIExport` is changed after workspaces have bound to it, new or changed APIs are automatically propagated to all `APIBindings`. New `PermissionClaims` on the other hand are NOT automatically accepted.
Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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


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.

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

Copy link

@janwillies janwillies Dec 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Instead APIs are directly bound.

What does this mean?

Bound APIs are like any other resources in kcp or Kubernetes. 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.

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