From 7ac50052605c12dbba255ab883afd5ae0e2af49f Mon Sep 17 00:00:00 2001 From: Simon Bein Date: Fri, 6 Dec 2024 14:35:10 +0100 Subject: [PATCH 1/3] Add APIBindings example On-behalf-of: SAP simon.bein@sap.com Signed-off-by: Simon Bein --- docs/content/concepts/apis/exporting-apis.md | 41 +++++++++++++++----- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/content/concepts/apis/exporting-apis.md b/docs/content/concepts/apis/exporting-apis.md index bd552dc48b0..b340ec3231f 100644 --- a/docs/content/concepts/apis/exporting-apis.md +++ b/docs/content/concepts/apis/exporting-apis.md @@ -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! @@ -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. + +Furthermore, `APIBindings` provide access to the groups/resources defined in an `APIExport's` `PermissionClaims` list. + +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. + +```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. From e6ad9acd4667488746a5b56bf1653a52ae39f189 Mon Sep 17 00:00:00 2001 From: Simon Bein Date: Tue, 10 Dec 2024 16:09:09 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Dr. Stefan Schimanski On-behalf-of: SAP simon.bein@sap.com Signed-off-by: Simon Bein --- docs/content/concepts/apis/exporting-apis.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/content/concepts/apis/exporting-apis.md b/docs/content/concepts/apis/exporting-apis.md index b340ec3231f..631cc30ee37 100644 --- a/docs/content/concepts/apis/exporting-apis.md +++ b/docs/content/concepts/apis/exporting-apis.md @@ -377,7 +377,7 @@ TODO `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. -Furthermore, `APIBindings` provide access to the groups/resources defined in an `APIExport's` `PermissionClaims` list. +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`. Returning to our previous example, we can use the following `APIBinding` to import the widgets api. @@ -393,7 +393,9 @@ spec: 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. +It should be noted that `APIBindings` do not create `CRDs` or `APIResourceSchemas`. Instead APIs are directly bound. + +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 From d10b44428c91f7daaea73dbf5fa194337d7bdd9f Mon Sep 17 00:00:00 2001 From: Simon Bein Date: Tue, 10 Dec 2024 16:16:28 +0100 Subject: [PATCH 3/3] add info on PermissionClaim on ApiExport update On-behalf-of: SAP simon.bein@sap.com Signed-off-by: Simon Bein --- docs/content/concepts/apis/exporting-apis.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/content/concepts/apis/exporting-apis.md b/docs/content/concepts/apis/exporting-apis.md index 631cc30ee37..0687e02acb4 100644 --- a/docs/content/concepts/apis/exporting-apis.md +++ b/docs/content/concepts/apis/exporting-apis.md @@ -378,6 +378,7 @@ TODO `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. 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. Returning to our previous example, we can use the following `APIBinding` to import the widgets api.