Skip to content

Commit

Permalink
docs: add numbering and headers for navigation, minor edits
Browse files Browse the repository at this point in the history
@smccarthy-ie @david-martin
smccarthy-ie authored and david-martin committed Jun 5, 2024
1 parent 2187ca0 commit 86a0d35
Showing 3 changed files with 124 additions and 111 deletions.
63 changes: 37 additions & 26 deletions doc/openapi-apicurio.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,26 @@
## Using Apicurio with Kuadrant OAS extensions
# Using Apicurio Studio with Kuadrant OAS extensions

[OpenAPI Extensions](https://swagger.io/docs/specification/openapi-extensions/) can
be used to describe extra functionality beyond what is covered by the standard OpenAPI
specification. They typically start with `x-`. Kuadrant OpenAPI extensions start with
`x-kuadrant`, and allow you to configure Kuadrant policy information along side
your API.
You can use [OpenAPI extensions](https://swagger.io/docs/specification/openapi-extensions/) to define extra functionality beyond what is covered by the standard OpenAPI specification. Extensions typically start with the `x-` prefix, for example, `x-codegen`. Kuadrant OpenAPI extensions start with the `x-kuadrant` prefix, and allow you to configure Kuadrant policy information alongside your API.

Apicurio Studio is a UI tool for visualising and editing OpenAPI specifications.
It has support for visualising security and extensions defined in your spec.
[Apicurio Studio](https://www.apicur.io/studio) is a UI tool for visualizing and editing OpenAPI designs and definitions, which can visualize security details and custom extensions specified in your OpenAPI definition.

This guide assumes you have Apicurio Studio already running.
See https://www.apicur.io/studio/ for info on how to install Apicurio Studio.
## Prerequisites

### Adding extensions to the spec
- You have Apicurio Studio installed and running. For more information, see the [Apicurio Studio documentation](https://www.apicur.io/studio/docs).

Open or import your OpenAPI spec in the Apicurio Studio UI.
You can modify the source of the spec from the UI.
There are a few different configuration and extension points supported by Apicurio Studio, and also supported by the `kuadrantctl` cli.
## Procedure

To generate a [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) for the API, add the following `x-kuadrant` block to your spec in the UI, replacing values to match your APIs details and the location of your Gateway.
### Step 1 - Access your OpenAPI definition in Apicurio Studio

Open or import your OpenAPI definition in Apicurio Studio. On the **Design** tab, select the **VENDOR-EXTENSiONS** section to add an extension. Alternatively, you can use the **Source** tab to edit the API definition directly.

### Step 2 - Add Kuadrant extensions to your API definition

The following configuration and extension points are supported by Apicurio Studio and the `kuadrantctl` CLI:

#### Generate an HTTP route

To generate an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) for the API, add the following `x-kuadrant` block to your API definition in Apicurio Studio, replacing values to match your API details and the location of your Gateway:

```yaml
info:
@@ -34,11 +36,11 @@ info:
kind: Gateway
```
See [this guide](./generate-gateway-api-httproute.md) for more info on generating a HTTPRoute.
For more details, see [Generate Gateway API HTTPRoute object from OpenAPI 3](./generate-gateway-api-httproute.md).
#### Generate an AuthPolicy
To generate an [AuthPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/auth/), add a `securityScheme` to the components block.
This `securityScheme` requires that an API key header is set.
Although securityScheme is not an OpenAPI extension, it is used by `kuadrantctl` like the other extensions mentioned here.
To generate an [AuthPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/auth/), add a `securityScheme` to the `components` block in your API definition. The following `securityScheme` requires that an API key header is set:

```yaml
securitySchemes:
@@ -48,14 +50,17 @@ Although securityScheme is not an OpenAPI extension, it is used by `kuadrantctl`
in: header
```

When added, the UI will display this in the security schemes section:
Although `securityScheme` is not an OpenAPI extension, it is used by `kuadrantctl` like the other extensions mentioned in this document.

When added, Apicurio Studio will display the following update in the **SECURITY SCHEMES** section:

![Apicurio security requirements](./images/apicurio-security-scheme-apikey.png)

See [this guide](./generate-kuadrant-auth-policy.md) for more info on generating an AuthPolicy.
For more details, see [Generate Kuadrant AuthPolicy object from OpenAPI 3](./generate-kuadrant-auth-policy.md).

#### Generate a RateLimitPolicy

To generate a [RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) for the API, add the following `x-kuadrant` block to a path in your spec,
replacing values to match your APIs details.
To generate a [RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) for the API, add the following `x-kuadrant` block to a path in your API definition, replacing values to match your API details.

```yaml
paths:
@@ -74,9 +79,15 @@ paths:
unit: second
```

When added, the UI will show this in Vendor Extensions section for that specific path:
When added, Apicurio Studio will display the following update in the **VENDOR-EXTENSiONS** section for that specific path:

![Apicurio RateLimitPolicy Vendor Extension](./images/apicurio-vendor-extension-backend-rate-limit.png)

See [this guide](./generate-kuadrant-rate-limit-policy.md) for more info on generating a RateLimitPoliicy.
There is also the full [kuadrantctl guide](./openapi-kuadrant-extensions.md).
For more details, see [Generate Kuadrant RateLimitPolicy object from OpenAPI 3](./generate-kuadrant-rate-limit-policy.md).

## Additional resources

- [OpenAPI 3.0.x Kuadrant Extensions in the kuadrantctl documentation](./openapi-kuadrant-extensions.md).
- [Apicurio Studio - Now with OpenAPI Vendor Extensions](https://www.apicur.io/blog/2024/05/10/studio-vendor-extensions).


37 changes: 19 additions & 18 deletions doc/openapi-kuadrant-extensions.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
## OpenAPI 3.0.X Kuadrant Extensions
# OpenAPI 3.0.x Kuadrant extensions

### Info level kuadrant extension
This reference information shows examples of how to add Kuadrant extensions at the `info`, path, and operation level in an OpenAPI 3.0.x definition.

Kuadrant extension that can be added at the info level of the OpenAPI spec.
## Info-level Kuadrant extension

You can add a Kuadrant extension at the `info` level of an OpenAPI definition. The following example shows an extension added for a `petstore` app:

```yaml
info:
x-kuadrant:
x-kuadrant: ## Info-level Kuadrant extension
route: ## HTTPRoute metadata
name: "petstore"
namespace: "petstore"
@@ -19,23 +21,23 @@ info:
namespace: gateways
```
### Path level kuadrant extension
## Path-level Kuadrant extension
Kuadrant extension that can be added at the path level of the OpenAPI spec.
This configuration at the path level
is the default when there is no operation level configuration.
You can add a Kuadrant extension at the path level of an OpenAPI definition.
This configuration at the path level is the default when there is no operation-level configuration.
The following example shows an extension added for a `/cat` path:

```yaml
paths:
/cat:
x-kuadrant: ## Path level Kuadrant Extension
x-kuadrant: ## Path-level Kuadrant extension
disable: true ## Remove from the HTTPRoute. Optional. Default: false
pathMatchType: Exact ## Specifies how to match against the path Value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
pathMatchType: Exact ## Specifies how to match against the path value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
backendRefs: ## Backend references to be included in the HTTPRoute. []gateway.networking.k8s.io/v1beta1.HTTPBackendRef. Optional.
- name: petstore
port: 80
namespace: petstore
rate_limit: ## Rate limit config. Optional.
rate_limit: ## Rate limit configuration. Optional.
rates: ## Kuadrant API []github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
- limit: 1
duration: 10
@@ -48,23 +50,22 @@ paths:
value: alice
```

### Operation level kuadrant extension
## Operation-level Kuadrant extension

Kuadrant extension that can be added at the operation level of the OpenAPI spec.
Same schema as path level kuadrant extension.
You can add a Kuadrant extension at the operation level of an OpenAPI definition. This extension uses the same schema as the path-level Kuadrant extension. The following example shows an extension added for a `get` operation:

```yaml
paths:
/cat:
get:
x-kuadrant: ## Path level Kuadrant Extension
disable: true ## Remove from the HTTPRoute. Optional. Default: path level "disable" value
pathMatchType: Exact ## Specifies how to match against the path Value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact
x-kuadrant: ## Operation-level Kuadrant extension
disable: true ## Remove from the HTTPRoute. Optional. Default: path level "disable" value.
pathMatchType: Exact ## Specifies how to match against the path value. Valid values: [Exact;PathPrefix]. Optional. Default: Exact.
backendRefs: ## Backend references to be included in the HTTPRoute. Optional.
- name: petstore
port: 80
namespace: petstore
rate_limit: ## Rate limit config. Optional.
rate_limit: ## Rate limit configuration. Optional.
rates: ## Kuadrant API github.com/kuadrant/kuadrant-operator/api/v1beta2.Rate
- limit: 1
duration: 10
135 changes: 68 additions & 67 deletions doc/openapi-openshift-dev-spaces.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,75 @@
# Integrating Kuadrant OAS Extensions with Red Hat OpenShift Dev Spaces
# Integrating Kuadrant OAS extensions with Red Hat OpenShift Dev Spaces

[OpenAPI Extensions](https://swagger.io/docs/specification/openapi-extensions/) enhance the standard OpenAPI specification by adding custom functionality. Kuadrant OpenAPI extensions, identified by the prefix `x-kuadrant`, allow the integration of Kuadrant policies directly within your API specs.
[OpenAPI extensions](https://swagger.io/docs/specification/openapi-extensions/) enhance the standard OpenAPI specification by adding custom functionality. Kuadrant OpenAPI extensions are identified by the `x-kuadrant` prefix. You can use OpenAPI extensions to integrate Kuadrant policies directly into your API definitions.

[Red Hat OpenShift Dev Spaces](https://developers.redhat.com/developer-sandbox/ide) offers a browser-based, cloud-native IDE that supports rapid and decentralized development within container-based environments. This tutorial demonstrates how to use OpenShift Dev Spaces to modify an OpenAPI specification by incorporating Kuadrant policies and then employ `kuadrantctl` to create Kubernetes resources for both Gateway API and Kuadrant.
[Red Hat OpenShift Dev Spaces](https://developers.redhat.com/developer-sandbox/ide) provides a browser-based, cloud-native IDE that supports rapid and decentralized development in container-based environments. This tutorial demonstrates how to use OpenShift Dev Spaces to modify an OpenAPI definition by incorporating Kuadrant policies, and then use the `kuadrantctl` CLI to create Kubernetes resources for both Gateway API and Kuadrant.


To follow along, you'll need access to a Dev Spaces instance. This can be either:
## Prerequisites

- A self-hosted instance.
- An instance provided through the [Red Hat Developer Sandbox](https://developers.redhat.com/developer-sandbox/ide).
- You must have access to one of the following Dev Spaces instances:

- A self-hosted OpenShift Dev Spaces instance.
- An OpenShift Dev Spaces instance provided by the [Red Hat Developer Sandbox](https://developers.redhat.com/developer-sandbox/ide).

## Setting up your Workspace
## Procedure

First, create a Workspace in Dev Spaces for your project:
### Step 1 - Setting up your workspace

Create a workspace in Dev Spaces for your project as follows:

1. Fork the following repository: [https://github.com/Kuadrant/blank-petstore](https://github.com/Kuadrant/blank-petstore).
2. In Dev Spaces, select `Create Workspace`, enter the URL of your forked repository (e.g., `https://github.com/<your-username>/blank-petstore.git`), and then click `Create & Open`.
2. In Dev Spaces, select **Create Workspace**, and enter the URL of your forked repository. For example: `https://github.com/<your-username>/blank-petstore.git`.
3. Click **Create & Open**.

## Configuring VSCode in Dev Spaces
### Step 2 - Configuring VS Code in Dev Spaces

For this tutorial, we'll:
For this tutorial, you will perform the following tasks:

- Install `kuadrantctl` within your workspace to demonstrate Kubernetes resource generation from your modified OpenAPI spec.
- (Optionally) Configure `git` with your username and email to enable pushing changes back to your repository.
- Install `kuadrantctl` in your workspace to demonstrate Kubernetes resource generation from your modified OpenAPI definition.
- Optional: Configure Git with your username and email to enable pushing changes back to your repository.


### `kuadrantctl` installation
#### Install the kuadrantctl CLI

To install `kuadrantctl` in your Dev Spaces workspace, execute the following command:
To install `kuadrantctl` in your Dev Spaces workspace, enter the following command:

```bash
curl -sL "https://github.com/kuadrant/kuadrantctl/releases/download/v0.2.3/kuadrantctl-v0.2.3-linux-amd64.tar.gz" | tar xz -C /home/user/.local/bin
```

This will place `kuadrantctl` in `/home/user/.local/bin`, which is included in the container's `$PATH` by default.
This command installs `kuadrantctl` in `/home/user/.local/bin`, which is included in the container's `$PATH` by default.

### Configuring Git (Optional)
#### Optional: Configuring Git

If you plan to push changes back to your repository, configure your git username and email:
If you plan to push changes back to your repository, configure your Git username and email as follows:

```bash
git config --global user.email "foo@example.com"
git config --global user.name "Foo Example"
```

## Editing Your OpenAPI Spec

Upon creating your workspace, Dev Spaces will launch VSCode loaded with your forked repository. Navigate to the `openapi.yaml` file within the sample app to begin modifications.
### Step 3 - Adding Kuadrant policies to your OpenAPI definition

### Kuadrant Policies Introduction
After creating your workspace, Dev Spaces will launch VS Code loaded with your forked repository. Navigate to the `openapi.yaml` file in the sample app to begin modifications.

We'll enhance our API spec by applying Kuadrant policies to the following endpoints:
#### Kuadrant policies overview

`/pet/findByStatus`
`/user/login`
`/store/inventory`
You will enhance your API definition by applying Kuadrant policies to the following endpoints:

In this tutorial, we're going to introduce some Kuadrant policies via this OAS. We will:
- `/pet/findByStatus`
- `/user/login`
- `/store/inventory`

- Generate a `HTTPRoute` to expose these three routes for an existing Gateway API `Gateway`
- Add API key authentication for the `/user/login` route, using Kuadrant's `AuthPolicy` API and OAS' `securitySchemes`
- Add a Kuadrant `RateLimitPolicy` to the `/store/inventory` endpoint, to limit the amount of requests this endpoint can receive
In this tutorial, you will add Kuadrant policies to your API definition as follows:

### Defining a Gateway
- Generate an `HTTPRoute` to expose these three routes for an existing `Gateway`.
- Add API key authentication for the `/user/login` route, using a Kuadrant `AuthPolicy` and OAS `securitySchemes`.
- Add a Kuadrant `RateLimitPolicy` to the `/store/inventory` endpoint, to limit the amount of requests this endpoint can receive.

Utilize the `x-kuadrant` extension in the `info` block to specify a `Gateway`. This information will be used to generate `HTTPRoute`s at the path level:
#### Defining a Gateway

For example:
Use the `x-kuadrant` extension in the `info` block to specify a `Gateway`. This information will be used to generate `HTTPRoute`s at the path level. For example:

```yaml
info:
@@ -83,13 +86,9 @@ info:
namespace: gateways
```
Add this extension to the `info` section.


### Specifing `HTTPRoute`'s for each Path

For each path, add an `x-kuadrant` extension with `backendRefs` to link our routes to our paths:
#### Specifying HTTPRoutes for each path
For each path, add an `x-kuadrant` extension with `backendRefs` to link your routes to your paths as follows:

```yaml
/pet/findByStatus:
@@ -124,10 +123,10 @@ For each path, add an `x-kuadrant` extension with `backendRefs` to link our rout
# ...
```

**Note:** The `x-kuadrant` extension at the path level applies to all HTTP methods defined within. For method-specific policies, move the extension inside the relevant HTTP method block (e.g., `get`, `post`).
**Note:** The `x-kuadrant` extension at the path level applies to all HTTP methods defined in the path. For method-specific policies, move the extension inside the relevant HTTP method block, for example, `get` or `post`.


### Implementing `AuthPolicy` and Security Schemes
#### Implementing AuthPolicy and security schemes

To secure the `/user/login` endpoint with API key authentication, use the following configuration:

@@ -139,7 +138,6 @@ To secure the `/user/login` endpoint with API key authentication, use the follow
- api_key: []
```


```yaml
components:
schemas:
@@ -166,12 +164,10 @@ stringData:
api_key: secret
type: Opaque
```
For simplicity, this example uses a simple, static API key for your app.

We don't recommend using a simple, static API key for your app, but will do so for this tutorial for the sake of simplicity.


### Applying a `RateLimitPolicy` to an Endpoint

#### Applying a RateLimitPolicy to an endpoint

To enforce rate limiting on the `/store/inventory` endpoint, add the following `x-kuadrant` extension:

@@ -189,23 +185,26 @@ To enforce rate limiting on the `/store/inventory` endpoint, add the following `
unit: second
```

This limits requests to 10 every 10 seconds for the `/store/inventory` endpoint.
This limits to 10 requests every 10 seconds for the `/store/inventory` endpoint.


### Step 4 - Generate Kubernetes resources by using kuadrantctl

## `kuadrantctl` and Kubernetes resource generation
With your extensions in place, you can use `kuadrantctl` to generate the follollowing Kubernetes resources:

With our extensions in place, let's use `kuadrantctl` to generate some Kubernetes resources, including:
- An `HTTPRoute` for your `petstore` app for each of your endpoints.
- An `AuthPolicy` with a simple, static API key from a secret for the `/user/login` endpoint.
- A `RateLimitPolicy` with a rate limit of 10 requests every 10 seconds for the `/store/inventory` endpoint.

- An `HTTPRoute` for our petstore app for each of our endpoints
- An `AuthPolicy` with a simple, static API key from a secret for the `/user/login` endpoint
- A `RateLimitPolicy` with a rate limit of 10 requests every 10 seconds for the `/store/inventory` endpoint
In Dev Spaces, select **☰ > Terminal > New Terminal**, and run the following commands:

Open a new terminal in Dev Spaces (`☰` > `Terminal` > `New Terminal`), and run the following:
##### Generate an HTTPRoute

```bash
kuadrantctl generate gatewayapi httproute --oas openapi.yaml
```

Outputs:
This command outputs the following `HTTPRoute`:

```yaml
kind: HTTPRoute
@@ -254,12 +253,13 @@ status:
parents: null
```

##### Generate an AuthPolicy

```bash
kuadrantctl generate kuadrant authpolicy --oas openapi.yaml
```

Outputs:
This command outputs the following `AuthPolicy`:

```yaml
apiVersion: kuadrant.io/v1beta2
@@ -301,12 +301,13 @@ spec:
status: {}
```

##### Generate a RateLimitPolicy

```bash
kuadrantctl generate kuadrant ratelimitpolicy --oas openapi.yaml
```

Outputs:
This command outputs the following `RateLimitPolicy`:

```yaml
apiVersion: kuadrant.io/v1beta2
@@ -338,11 +339,11 @@ spec:
status: {}
```

## Applying resources
### Step 5 - Applying resources to the app

> **Note:** by default, `oc` and `kubectl` in Dev Spaces will target the cluster running Dev Spaces. If you want to apply resources to another cluster, you will need to login with `oc` or `kubectl` to another cluster, and pass a different `--context` to these to apply resources to another cluster.
> **Note:** By default, the `oc` and `kubectl` commands in Dev Spaces target the cluster running Dev Spaces. If you want to apply resources to another cluster, you must log in with `oc` or `kubectl` to another cluster, and pass a different `--context` to these commands to apply resources to another cluster.

You can now apply these policies to a running app via `kubectl` or `oc`. If Dev Spaces is running on a cluster where Kuadrant is also installed, you can apply these resources:
You can now apply these policies to a running app by using `kubectl` or `oc`. If Dev Spaces is running on a cluster where Kuadrant is also installed, you can apply these resources as follows:


```bash
@@ -351,16 +352,16 @@ kuadrantctl generate kuadrant authpolicy --oas openapi.yaml | kubectl apply -f -
kuadrantctl generate kuadrant ratelimitpolicy --oas openapi.yaml | kubectl apply -f -
```

Alternatively, `kuadrantctl` can be used as part of a CI/CD pipeline. See the [kuadrantctl CI/CD guide](./kuadrantctl-ci-cd.md) for more details.
Alternatively, you can use `kuadrantctl` as part of a CI/CD pipeline. For more details, see the [kuadrantctl CI/CD guide](./kuadrantctl-ci-cd.md).

If you've completed the optional `git` configuration step above, you can now `git commit` the changes above and push these to your fork.
If you completed the optional Git configuration step, you can enter `git commit` to commit the these changes and push them to your fork.

# Next
## Additional resources

Here are some extra documentation on using `x-kuadrant` OAS extensions with `kuadrantctl`:
For more details, see the following documentation on using `x-kuadrant` OAS extensions with `kuadrantctl`:

- [Guide to `kuadrantctl` and OAS extensions](./openapi-kuadrant-extensions.md)
- [Generating Gateway API HTTPRoutes with `kuadrantctl`](./generate-gateway-api-httproute.md)
- [Generating Kuadrant AuthPolicy with `kuadrantctl`](./generate-kuadrant-auth-policy.md)
- [OpenAPI 3.0.x Kuadrant extensions](./openapi-kuadrant-extensions.md)
- [Generate Gateway API HTTPRoutes with `kuadrantctl`](./generate-gateway-api-httproute.md)
- [Generate Kuadrant AuthPolicy with `kuadrantctl`](./generate-kuadrant-auth-policy.md)
- [Generate Kuadrant RateLimitPolicy with `kuadrantctl`](./generate-kuadrant-rate-limit-policy.md)
- [`kuadrantctl` CI/CD guide](./kuadrantctl-ci-cd.md)
- [kuadrantctl CI/CD guide](./kuadrantctl-ci-cd.md)

0 comments on commit 86a0d35

Please sign in to comment.