From 86a0d35445a58b564949aceddb9d080befbdd5ec Mon Sep 17 00:00:00 2001 From: Stephen McCarthy Date: Wed, 22 May 2024 12:21:37 +0100 Subject: [PATCH] docs: add numbering and headers for navigation, minor edits --- doc/openapi-apicurio.md | 63 +++++++------ doc/openapi-kuadrant-extensions.md | 37 ++++---- doc/openapi-openshift-dev-spaces.md | 135 ++++++++++++++-------------- 3 files changed, 124 insertions(+), 111 deletions(-) diff --git a/doc/openapi-apicurio.md b/doc/openapi-apicurio.md index 9dbdbb2..5558ad7 100644 --- a/doc/openapi-apicurio.md +++ b/doc/openapi-apicurio.md @@ -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). + + diff --git a/doc/openapi-kuadrant-extensions.md b/doc/openapi-kuadrant-extensions.md index 3f2ca70..cc8b763 100644 --- a/doc/openapi-kuadrant-extensions.md +++ b/doc/openapi-kuadrant-extensions.md @@ -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 diff --git a/doc/openapi-openshift-dev-spaces.md b/doc/openapi-openshift-dev-spaces.md index d579ef1..8f48dd5 100644 --- a/doc/openapi-openshift-dev-spaces.md +++ b/doc/openapi-openshift-dev-spaces.md @@ -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//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//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)