Skip to content

Commit

Permalink
Fix doc structure
Browse files Browse the repository at this point in the history
  • Loading branch information
szwedm committed Dec 12, 2024
1 parent a612fac commit a8f7822
Showing 1 changed file with 19 additions and 22 deletions.
41 changes: 19 additions & 22 deletions docs/user/05-60-kyma-bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,63 +28,60 @@ The creation process is divided into three parts: configuration check, request v

### Configuration Check

If a feature flag for Kyma bindings is enabled, KEB first checks if the Kyma instance exists. If the instance is found and the plan it has been provisioned with is bindable, KEB proceeds to the validation phase.
If a feature flag for Kyma bindings is enabled, KEB does the following:
1. Checks if the Kyma instance exists.
2. If the instance is found and the plan it has been provisioned with is bindable, KEB proceeds to the validation phase.

### Request Validation

Now, the unmarshalled request is validated, and the correctness of its structure is checked. See the table for the data that you can pass to the request:
The unmarshalled request is validated, and the correctness of its structure is checked. See the table for the data that you can pass to the request:

| Name | Default | Description |
|------------------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **expiration_seconds** | `600` | Specifies the duration (in seconds) for which the generated kubeconfig is valid. If not provided, the default value of `600` seconds (10 minutes) is used, which is also the minimum value that can be set. The maximum value that can be set is `7200` seconds (2 hours). |

After unmarshaling, the data is validated against the allowed parameter values, which includes checks of the expiration value range, database record existence, parameter mutations verification, expiration of existing bindings, and binding number limits.
The first check verifies the expiration value. The minimum and maximum limits are configurable and, by default, set to 600 and 7200 seconds, respectively.
Next, KEB checks the status of the instance. The instance must be provisioned for the binding creation.
After checking the instance, KEB checks if the binding already exists. The binding in the database is identified by the Kyma instance ID and the binding ID, which are passed as a path query parameter. If the binding exists, KEB checks the mutation of the parameters of the existing binding.
The OSB API requires a request to create a binding to fail if an object has already been created and the request contains different parameters.
If the found binding is not expired, KEB returns it in the response. If the found binding is expired and exists in the database, KEB responds with an error and the Bad Request status.
This check is done in an implicit database insert statement. The query fails for expired but existing bindings because the primary key is defined on the instance and binding IDs, not the expiration date. This is the case until the cleanup job removes the expired binding from the database.
If the binding does not exist, the flow returns to the process's execution path, where no bindings exist in the database.
Whether the binding exists or not, the last step in the request validation is to verify the number of bindings.
Every instance is allowed to create a limited number of active bindings. The limit is configurable and, by default, set to 10 non-expired bindings.
If the limit is not exceeded and the binding does not exist in the database, KEB proceeds to the next phase of the process - binding creation.

After unmarshaling, the following actions take place:
1. The first check verifies the expiration value. The minimum and maximum limits are configurable and, by default, set to 600 and 7200 seconds, respectively.
2. KEB checks the status of the instance. The instance must be provisioned for the binding creation.
3. KEB checks if the binding already exists. The binding in the database is identified by the Kyma instance ID and the binding ID, which are passed as a path query parameter. If the binding exists, KEB checks the values of the parameters of the existing binding. The OSB API requires a request to create a binding to fail if an object has already been created and the request contains different parameters.
4. If the found binding is not expired, KEB returns it in the response. If the found binding is expired and exists in the database, KEB responds with an error and the Bad Request status. This check is done in an implicit database insert statement. The query fails for expired but existing bindings because the primary key is defined on the instance and binding IDs, not the expiration date. This is the case until the cleanup job removes the expired binding from the database. If the binding does not exist, the flow returns to the process's execution path, where no bindings exist in the database.
5. Whether the binding exists or not, the last step in the request validation is to verify the number of bindings. Every instance is allowed to create a limited number of active bindings. The limit is configurable and, by default, set to 10 non-expired bindings. If the limit is not exceeded and the binding does not exist in the database, KEB proceeds to the next phase of the process - binding creation.

### Binding Creation

In the binding creation phase, KEB creates a service binding object and generates a kubeconfig file with a JWT token. The kubeconfig file is valid for a specified period, defaulted or set in the request body.
Binding creation part consists of the following steps:
1. KEB creates a service binding object and generates a kubeconfig file with a JWT token. The kubeconfig file is valid for a specified period, defaulted or set in the request body.

> [!NOTE]
> Expired bindings do not count towards the bindings limit. However, as long as they exist in the database, they prevent creating new bindings with the same ID. Only after they are removed by the cleanup job or manually can the binding be recreated again.
After the insert has been done, KEB creates ServiceAccount, ClusterRole (administrator privileges), and ClusterRoleBinding, all named `kyma-binding-{{binding_id}}`. You can use the ClusterRole to modify permissions granted to the kubeconfig.

The created resources are then used to generate a [TokenRequest](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/). The token is then wrapped in a kubeconfig template and returned to the user. The encrypted credentials are then stored as an attribute in the previously created database binding.
2. KEB creates ServiceAccount, ClusterRole (administrator privileges), and ClusterRoleBinding, all named `kyma-binding-{{binding_id}}`. You can use the ClusterRole to modify permissions granted to the kubeconfig.
3. The created resources are used to generate a [TokenRequest](https://kubernetes.io/docs/reference/kubernetes-api/authentication-resources/token-request-v1/). The token is wrapped in a kubeconfig template and returned to the user.
4. The encrypted credentials are stored as an attribute in the previously created database binding.

> [!NOTE]
> Creation of multiple and unused TokenRequest resources is not recommended.
> It is not recommended to create multiple and unused TokenRequest resources.

## The Process of Fetching a Kyma Binding

![Get Binding Flow](../assets/bindings-get-flow.drawio.svg)

The diagram shows a flow of fetching a Kyma binding in KEB. The process starts with a GET request sent to the KEB API.
The process starts with a GET request sent to the KEB API.
The first instruction in the process is to check if a Kyma instance exists. If a Kyma instance exists, it must not be deprovisioned or suspended.
The endpoint doesn't return bindings for such instances. Existing bindings are retrieved by instance ID and binding ID. If any bindings exist, they are filtered by expiration date. KEB returns only non-expired bindings.

## The Process of Deleting a Kyma Binding

![Delete Binding Flow](../assets/bindings-delete-flow.drawio.svg)

The diagram shows the flow of removing a Kyma binding. The process starts with a DELETE request sent to the KEB API. The first instruction is to check if the Kyma instance that the request refers to exists.
The process starts with a DELETE request sent to the KEB API. The first instruction is to check if the Kyma instance that the request refers to exists.
Any bindings of non-existing instances are treated as orphaned and are removed. The next step is to conditionally delete the binding's ClusterRole, ClusterRoleBinding, and ServiceAccount, given that the cluster has been provisioned and not marked for removal. In case of deprovisioning or suspension of the Kyma cluster, this is unnecessary because the cluster is removed either way.
In case of errors during the resource removal process, the binding database record should not be removed, which is why the resource removal happens before the binding database record removal.
Finally, the last step is to remove the binding record from the database.

> [!WARNING]
> Removing the ServiceAccount invalidates all tokens generated for that account, revoking access to the cluster for all clients using the kubeconfig from the binding.
> Do not remove the ServiceAccount because the removal invalidates all tokens generated for that account and thus revokes access to the cluster for all clients using the kubeconfig from the binding.
## Cleanup Job

Expand Down

0 comments on commit a8f7822

Please sign in to comment.