From 2fc2a76bbfd66537daa19bb5a22541d9a3aef1a9 Mon Sep 17 00:00:00 2001 From: Stephen McCarthy Date: Thu, 6 Jun 2024 16:08:56 +0100 Subject: [PATCH 1/2] docs: fix root-level extn docs, clean up formatting --- doc/generate-kuadrant-rate-limit-policy.md | 56 +++++++++---------- doc/kuadrantctl-ci-cd.md | 64 +++++++++++----------- doc/openapi-kuadrant-extensions.md | 6 +- 3 files changed, 63 insertions(+), 63 deletions(-) diff --git a/doc/generate-kuadrant-rate-limit-policy.md b/doc/generate-kuadrant-rate-limit-policy.md index 05b0377..d76188c 100644 --- a/doc/generate-kuadrant-rate-limit-policy.md +++ b/doc/generate-kuadrant-rate-limit-policy.md @@ -1,20 +1,20 @@ ## Generate Kuadrant RateLimitPolicy object from OpenAPI 3 -The `kuadrantctl generate kuadrant ratelimitpolicy` command generates an [Kuadrant RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) -from your [OpenAPI Specification (OAS) 3.x](https://spec.openapis.org/oas/latest.html) powered with [kuadrant extensions](openapi-kuadrant-extensions.md). +The `kuadrantctl generate kuadrant ratelimitpolicy` command generates a [Kuadrant RateLimitPolicy](https://docs.kuadrant.io/kuadrant-operator/doc/rate-limiting/) +from your [OpenAPI Specification (OAS) 3.x document](https://spec.openapis.org/oas/latest.html) powered with [Kuadrant extensions](openapi-kuadrant-extensions.md). ### OpenAPI specification -An OpenAPI document resource can be provided to the cli by one of the following channels: +An OpenAPI document resource can be provided to the Kuadrant CLI in one of the following ways: * Filename in the available path. * URL format (supported schemes are HTTP and HTTPS). The CLI will try to download from the given address. -* Read from stdin standard input stream. +* Read from `stdin` standard input stream. ### Usage ```shell -Generate Kuadrant RateLimitPolicy from OpenAPI 3.0.X +Generate Kuadrant RateLimitPolicy from OpenAPI 3.0.x Usage: kuadrantctl generate kuadrant ratelimitpolicy [flags] @@ -28,31 +28,31 @@ Global Flags: -v, --verbose verbose output ``` -> Under the example folder there are examples of OAS 3 that can be used to generate the resources +> **Note**: The `kuadrantctl/examples` directory in GitHub includes sample OAS 3 files that you can use to generate the resources. -### User Guide +### Procedure -* Clone the repo +1. Clone the Git repository as follows: ```bash git clone https://github.com/Kuadrant/kuadrantctl.git cd kuadrantctl -``` -* Setup a cluster, Istio and Gateway API CRDs and Kuadrant + ``` +2. Set up a cluster, Istio and Gateway API CRDs, and Kuadrant as follows: -Use our single-cluster quick start script - this will install Kuadrant in a local `kind` cluster: https://docs.kuadrant.io/getting-started-single-cluster/ +* Use the single-cluster quick start script to install Kuadrant in a local `kind` cluster: https://docs.kuadrant.io/getting-started-single-cluster/. -* Build and install CLI in `bin/kuadrantctl` path +3. Build and install the CLI in `bin/kuadrantctl` path as follows: ```bash make install ``` -* Deploy petstore backend API +4. Deploy the Petstore backend API as follows: ```bash kubectl create namespace petstore kubectl apply -n petstore -f examples/petstore/petstore.yaml ``` -* Let's create Petstore's OpenAPI spec +5. Create the Petstore OpenAPI definition as follows:
```yaml @@ -129,46 +129,44 @@ paths: description: "invalid input" EOF ``` -
-> **NOTE**: `servers` base path not included. WIP in following up PRs. +> **Note**: The `servers` base path is not included. WIP in following up PRs. -| Operation | Applied config | +| Operation | Applied configuration | | --- | --- | -| `GET /cat` | It should return 200 Ok and be rate limited (1 req / 10 seconds) | -| `POST /cat` | Not added to the HTTPRoute. It should return 404 Not Found | -| `GET /dog` | It should return 200 Ok and be rate limited (3 req / 10 seconds) | -| `POST /dog` | It should return 200 Ok and NOT rate limited | +| `GET /cat` | Should return 200 OK and be rate limited (1 req / 10 seconds). | +| `POST /cat` | Not added to the HTTPRoute. Should return 404 Not Found. | +| `GET /dog` | Should return 200 OK and be rate limited (3 req / 10 seconds). | +| `POST /dog` | Should return 200 OK and NOT rate limited. | -* Create the HTTPRoute using the CLI +6. Create the HTTPRoute by using the CLI as follows: ```bash bin/kuadrantctl generate gatewayapi httproute --oas petstore-openapi.yaml | kubectl apply -n petstore -f - ``` -* Create the Rate Limit Policy +7. Create the rate limit policy as follows: ```bash bin/kuadrantctl generate kuadrant ratelimitpolicy --oas petstore-openapi.yaml | kubectl apply -n petstore -f - ``` -* Test OpenAPI endpoints - * `GET /cat` -> It should return 200 Ok and be rate limited (1 req / 10 seconds) +8. Test the OpenAPI endpoints as follows: + * `GET /cat` - Should return 200 OK and be rate limited (1 req / 10 seconds). ```bash curl --resolve example.com:9080:127.0.0.1 -v "http://example.com:9080/cat" ``` - * `POST /cat` -> Not added to the HTTPRoute. It should return 404 Not Found + * `POST /cat` - Not added to the HTTPRoute. Should return 404 Not Found. ```bash curl --resolve example.com:9080:127.0.0.1 -v -X POST "http://example.com:9080/cat" ``` - * `GET /dog` -> It should return 200 Ok and be rate limited (3 req / 10 seconds) + * `GET /dog` - Should return 200 OK and be rate limited (3 req / 10 seconds). ```bash curl --resolve example.com:9080:127.0.0.1 -v "http://example.com:9080/dog" ``` - - * `POST /dog` -> It should return 200 Ok and NOT rate limited + * `POST /dog` - Should return 200 OK and NOT rate limited. ```bash curl --resolve example.com:9080:127.0.0.1 -v -X POST "http://example.com:9080/dog" diff --git a/doc/kuadrantctl-ci-cd.md b/doc/kuadrantctl-ci-cd.md index 495ef1c..d9cf304 100644 --- a/doc/kuadrantctl-ci-cd.md +++ b/doc/kuadrantctl-ci-cd.md @@ -1,25 +1,27 @@ # kuadrantctl - CI/CD with Tekton and Argo CD -This guide demonstrates setting up a CI/CD pipeline using Tekton to deploy Kubernetes Gateway API and Kuadrant resources generated by `kuadrantctl`, from an OpenAPI specification. In this example, these resources are applied directly to the cluster where Tekton is running. +This guide demonstrates setting up a CI/CD pipeline by using Tekton to deploy Kubernetes Gateway API and Kuadrant resources generated by `kuadrantctl`, from an OpenAPI definition. In this example, these resources are applied directly to the cluster where Tekton is running. ## Prerequisites -- Kuadrant, and all of its pre-requisites, is installed onto a cluster -- [Tekton Pipelines](https://tekton.dev/) installed on your Kubernetes or OpenShift cluster. -- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) configured to communicate with your cluster (i.e you have a kubectl config available with access to your cluster) -- [Tekton CLI `tkn`](https://tekton.dev/docs/cli/) (optional) for easier interaction with Tekton resources. +- Kuadrant, and all of its prerequisites, installed on a Kubernetes or OpenShift cluster. +- [Tekton Pipelines](https://tekton.dev/) installed on your cluster. +- [`kubectl`](https://kubernetes.io/docs/reference/kubectl/) configured with access to communicate with your cluster. +- Optional: [Tekton CLI `tkn`](https://tekton.dev/docs/cli/) for easier interaction with Tekton resources. -## Setup +## Procedure -First, create a dedicated namespace: +### Step 1 - Set up your namespace + +Create a dedicated namespace as follows: ```bash kubectl create namespace petstore ``` -## Create a Persistent Volume Claim +### Step 2 - Create a Persistent Volume Claim -For this guide, to store associated Tekton build artifacts, we'll create a PVC in the `petstore` namespace: +For this example, to store associated Tekton build artifacts, create a Persistent Volume Claim (PVC) in the `petstore` namespace as follows: ```bash kubectl apply -n petstore -f - < **Note:** Important: While this guide uses a kubeconfig secret for simplicity, it is not recommended for production environments. Instead, use a Service Account for enhanced security. +> **Important:** While this guide uses a `kubeconfig` secret for simplicity, do not use this in production environments. Instead, use a service account for enhanced security. -In this guide, we use a `kubeconfig` secret coupled with role bindings to demonstrate how to provide access for pushing generated resources to a cluster. However, for production setups, employing a Service Account is advised. +This example uses a `kubeconfig` secret and role bindings to demonstrate how to provide access for pushing generated resources to a cluster. However, for production setups, employing a service account is best. -To proceed, create a kubeconfig secret in the `petstore` namespace to provide Tekton with access to your Kubernetes cluster: +To proceed, create a `kubeconfig` secret in the `petstore` namespace to provide Tekton with access to your Kubernetes cluster as follows: ```bash kubectl create secret generic kubeconfig-secret --from-file=kubeconfig=/path/to/.kube/config -n petstore ``` -Create an associated `ClusterRole` and `ClusterRoleBinding`: +Create an associated `ClusterRole` and `ClusterRoleBinding` as follows: ```bash kubectl apply -n petstore -f - < Date: Thu, 6 Jun 2024 17:48:25 +0100 Subject: [PATCH 2/2] docs: minor clean up --- doc/generate-kuadrant-rate-limit-policy.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/generate-kuadrant-rate-limit-policy.md b/doc/generate-kuadrant-rate-limit-policy.md index d76188c..711a938 100644 --- a/doc/generate-kuadrant-rate-limit-policy.md +++ b/doc/generate-kuadrant-rate-limit-policy.md @@ -62,7 +62,7 @@ openapi: "3.0.3" info: title: "Pet Store API" version: "1.0.0" -x-kuadrant: +x-kuadrant: ## Root-level Kuadrant extension route: name: "petstore" namespace: "petstore" @@ -75,7 +75,7 @@ servers: - url: https://example.io/v1 paths: /cat: - x-kuadrant: ## Path level Kuadrant Extension + x-kuadrant: ## Path-level Kuadrant extension backendRefs: - name: petstore port: 80 @@ -101,7 +101,7 @@ paths: description: "invalid input" /dog: get: # Added to the route and rate limited - x-kuadrant: ## Operation level Kuadrant Extension + x-kuadrant: ## Operation-level Kuadrant extension backendRefs: - name: petstore port: 80 @@ -118,7 +118,7 @@ paths: 405: description: "invalid input" post: # Added to the route and NOT rate limited - x-kuadrant: ## Operation level Kuadrant Extension + x-kuadrant: ## Operation-level Kuadrant extension backendRefs: - name: petstore port: 80 @@ -131,7 +131,7 @@ EOF ``` -> **Note**: The `servers` base path is not included. WIP in following up PRs. +> **Note**: The `servers` base path is not included. This is work-in-progress in follow-up PRs. | Operation | Applied configuration | | --- | --- |