DEV Community: Abdallah Abedraba

The Three Steps of Building Design-First APIs in Kubernetes

Abdallah Abedraba — Tue, 13 Dec 2022 05:42:59 +0000

Every time your organization needs to create a new API from scratch on Kubernetes, you’re faced with a decision: Are we going to create and follow a process to get this job done, or are we just going to stumble our way into a deployment that we hope gets the job done?

If your organization is mature enough to follow a process, which is a great first step, you also need to decide which route to go. There are a few popular approaches to API design and development, but we’re going to hone in on the design-first approach because it means you’re generating the API’s specifications from the design of your API, not your code. It’s the best way to create APIs that are developer-friendly, go to market faster, and solve everyone’s problems the right way, the first time.

There are big steps to get the job done.‍

1. Determine what business problem you’re trying to solve

You start by getting the people from technical and business units in the same room (or Zoom call) together to discuss and iterate on how the API should work and validate the design decisions you’re making before anyone even opens up an IDE.

You’ll ask questions like:

What do we need to get buy-in from customers, leadership, developers, QA testers, and IT operation?
What kinds of naming conventions or code quality guides should we enforce?
Which security, authentication, and authorization standards do we need?

2. Codify your API in a human- and machine-readable document

Once you know exactly what your team is trying to accomplish, you can start translating the business requirements and goals into an API definition using OpenAPI, which is the most broadly adopted specification for new APIs. The YAML syntax makes it approachable for technical and business folks alike.

Your goal in this step is to convert your agreed-upon design into an OpenAPI definition, a single document that details exactly how the API works, like the path(s) it responds to, what structure and type those responses should be, what security schemes the API will need, what kind of validation is required, and more.

In the end, this definition becomes your API contract: A single source of truth for how your API works on the frontend, backend, and from the end user’s perspective.

3. Convert the API design into code, tests, and other artifacts using generators… like Kusk!

With your OpenAPI definition in Git, your teams can start writing client- and server-side code that meets those requirements. Or you can use other tools that convert your API into other valuable resources or knowledge:

With openapi-generator, you can generate client- and server-side code in a variety of languages.
Tools like portman automatically create tests from your OpenAPI definition
Complete, up-to-date, and exhaustive documentation that can be generated with Stoplight Elements
Security verification against known vulnerabilities and remediation advice using tools like 42Crunch

And when it comes to taking an OpenAPI definition to a live Kubernetes deployment, there’s Kusk, an API Gateway that helps you validate, deploy, and monitor your APIs using the open-source and much-loved Envoy Proxy.

With Kusk, developers can annotate existing OpenAPI definitions to add any gateway-related configurations, like CORS rules, cache controls, rate limiting, and much more. Kusk automatically turns that under the hood into an Envoy Proxy configuration, plus the rest of the OpenAPI definition, into a functional gateway that can validate requests and consolidate your error handling.

There’s more — once you’re using Kusk, your frontend developers can use gateway-level mocking to start building the end-user experience while their peers in the backend team work on implementing the API, getting your API to production way faster.

Ready to build your next API with a design-first strategy? Install Kusk and get involved on Discord to learn from others at this exciting intersection between OpenAPI and Kubernetes. The power of the API community awaits…!

Kusk + Cloudentity - Fine-Grained Authorization for your APIs

Abdallah Abedraba — Tue, 18 Oct 2022 04:48:37 +0000

The Kusk team is glad to announce it has partnered with Cloudentity, an authorization-as-a-service platform, to enable users to leverage Cloudentity's robust centralized policy management and distributed Authorizer frameworks in combination with Kusk's OpenAPI extensions.

Security and infrastructure teams at organizations across the world rely on Cloudentity to keep their applications safe and secure. We're excited to join their team of trusted partners like Okta, Amazon Web Services (AWS), Azure, Google, and Axway.

This is part of our main effort in helping companies create better and more resilient APIs.

OpenAPI for Open Standards

Cloudentity embraces open standards and open-source in its journey to enable developers to implement scalable security from day one. Cloudentity users achieve security compliance faster and with less effort in ecosystems like Open Banking, which heavily rely on standards like OpenAPI.

Kusk allows users to extend their OpenAPI definitions to include API gateway configuration rules so developers can have less complexity in their path to production. The configuration of the API gateway by use of OpenAPI enables developers to include features like response mocking and request body validation, among many others, out-of-the-box from day one.

Control the Authorization of APIs

Kusk allows users to create their own authorization logic with Custom Auth Upstreams. But dealing with authorization rules is complicated and doesn’t easily scale.

With Cloudentity added as an authorizer to Kusk Gateway, API requests are now protected with rules that developers can create using Cloudentity’s Visual Policy Editor or REGO policies built on Open Policy Agent. These rules are then orchestrated in Cloudentity allowing developers to tailor the authorization of their APIs easily and scale it at the same time their API grows.

This is a great step for developers that use Kusk Gateway with their APIs, enabling more out-the-box working API self-service solutions, while still maintaining flexibility and control over the gateway in their Kubernetes clusters.

How does this integration work?

To use Cloudentity as the authorizer of your API requests with Kusk Gateway, you need to add the auth extension to your OpenAPI spec:

Kusk then configures the gateway to use a Cloudentity Authorizer that will filter requests using Cloudentity’s powerful and highly customizable authorization rules that API developers can create using Cloudentity’s platform.

You can see the full instructions on how to use Cloudentity with Kusk in our guides.

Try it out now!

We are very excited to add more integrations that enable our users to build great APIs. Check on how to use Cloudentity with Kusk in our guides. If you have any issues or questions about Kusk Gateway with Cloudentity, reach out to the team on the Discord channel or open an issue in the GitHub repository).

Setup Ingress Controller with CORS configuration

Abdallah Abedraba — Tue, 04 Oct 2022 16:43:48 +0000

Configuring CORS in Kubernetes is not easy, let alone debugging issues with it. In a microservices architecture, leaving CORS to be managed by each backend could lead to non-standardized CORS rules throughout your APIs. So how can we solve these issues?

First things first, what is CORS?

CORS is a mechanism implemented by browsers to ensure that requests are not sent to the server when the request is made by a domain the server does not expect to receive a request from (for example, malicious.com).

It’s a security feature implemented for browsers mainly because when using CORS acts on the Origin header of a request (which an attacker can easily set if they’re running the request outside of the browser), it’s no good for the server to protect against these types of requests. But, if the request is made through a browser, the Origin header cannot be overridden by an attacker because the browser controls this header. So CORS becomes a browser’s responsibility as it’s the browser that should block the malicious requests.

How to configure your Ingress Controller for CORS?

For this example, we will be using Kusk Gateway, an open-source OpenAPI-driven Ingress Controller. The reasons we want to use Kusk Gateway is that firstly it simplifies the configuration of Envoy, a very sophisticated proxy, and it allows users to configure it using an OpenAPI definition, so the developers don’t need to learn yet another Kubernetes annotations (the case with Nginx Ingress for example), and they can leverage the OpenAPI ecosystem for code-generation, API mocking, testing, and more.

Let’s see how that looks in practice. We will deploy a simple hello-world example.

1- Install Kusk in your Kubernetes cluster

First, let’s install the Kusk CLI:

# MacOS
brew install kubeshop/kusk/kusk

# Linux
curl -sSLf https://raw.githubusercontent.com/kubeshop/kusk-gateway/main/cmd/kusk/scripts/install.sh | bash

# Windows (go binary needed)
go install -x github.com/kubeshop/kusk-gateway/cmd/kusk@latest

Once the CLI is installed, proceed to install Kusk in your cluster:

kusk cluster install

2- Deploy a sample application to your clusterYou can deploy this example application:

kubectl create deployment hello-world --image=kubeshop/kusk-hello-world:v1.0.0

And we now wrap it in a service:

kubectl expose deployment hello-world --type=ClusterIP --port=8080

3- Configure your OpenAPI definition for Kusk

Create a file openapi.yaml with the following content:

As you can see this is a standard OpenAPI definition. This API exposes a single /hello path.

We also have the x-kusk extension, this is a standard way to make annotations in OpenAPI, we’ve added there the CORS rules for our API and also the upstream details of the application we deployed in the first step.

4- Apply the changes to the cluster

The following command will configure Kusk Gateway with the new rules:

kusk deploy -i openapi.yaml

5- Connect to Kusk Gateway

One way of testing CORS rules is by trying to access the website from the browser through a different domain than the one we have defined in CORS. The other way of testing it is through the CLI with curl. Let’s explore both.

But first, let’s get the External IP of our Ingress Controller:

kusk ip

6- How to test CORS?

As you’ve seen in the step earlier, we have configured CORS to expect requests from example.com and we will now make our requests from example.org to test that the requests are blocked.

Open https://example.org in your browser, and access the developer console, then run the following Javascript snippet (make sure your change the EXTERNAL-IP):

(function() {
  fetch("http://EXTERNAL-IP/hello")
    .then(res => console.log(res))
})()

Given that our CORS configuration expects requests from example.com and not example.org, the browser should fail the request with the following error:

What is happening under the hood is that the browser makes a preflight request (a request before the actual request is made) which essentially asks the server for the origins that it expects to be called from. This happens by making an HTTP request using the OPTIONS method.

The server checks the origin header that the browser has set and it then can decide between either adding the Access-Control-Allow-Origin: https://example.com\ or not adding it. In case it’s not added (meaning the server does not recognize the origin it’s being called from), the browser blocks the actual request.

CORS through your Ingress Controller made easy

With Kusk, it’s really easy to configure CORS in your APIs from a single place and using a standard like OpenAPI, which is essential for any modern REST API developer.

Check out how to configure CORS, rate-limiting and authentication in your Ingress Controller in our guides and let us know about your experience in our Discord channel, and we are more than happy to see issues raised and PRs opened in our Github repository :)

Thank you for reading!

Kusk v1.3 Release - Updated CLI and dashboard experience!

Abdallah Abedraba — Tue, 04 Oct 2022 16:29:03 +0000

The Kusk team is proud to announce the v1.3 release of Kusk Gateway, which adds OAuth support, mocking of the API directly from the CLI and improved developer experience of the CLI!

CLI improvements

New kusk deploy that allows you to deploy your OpenAPI definition to Kusk directly without needing to pipe it to kubectl. It also adds a watched that looks for changes in your OpenAPI file and re-applies them to the LoadBalancer.
New kusk ip command that returns the IP address of the default Kusk LoadBalancer so you can now pipe it to your favorite commands. curl $(kusk ip)/api
kusk install and kusk upgrade have now moved to kusk cluster install/upgrade. We have also removed the dependency on helm and we install Kusk directly using kubectl under-the-hood, this has vastly improved the speed of installation and upgrade of Kusk Gateway!
New kusk cluster uninstall command that uninstalls Kusk and all of its components from your Kubernetes clusters.

Dashboard Overhaul

We have redesigned Kusk Dashboard to make it easier to use and more familiar with the entire Kusk ecosystem. There are new guides and recommendations added that will help you navigate easier.

Improved Documentation

We’ve improved the experience and design of the documentation because we like amazing experiences everywhere 😎 Check out the new docs.kusk.io

Try it out!

Try and download the new version of Kusk here! If you have any questions or ideas please feel free to join our Discord server and get in touch. Kusk is fully open source, so you can always help us by starring the project on github, opening issues or a PR!

Thank you!

Kusk on the Road - Our September ‘22 Schedule

Abdallah Abedraba — Thu, 08 Sep 2022 21:12:06 +0000

The Kusk team is hitting the road to meet users and industry friends face-to-face across the US in September.

We (Ole Lensmar, CTO of Kubeshop, Abdallah Abedraba Developer Advocate and Christopher Jones, PM for Kusk) would like to say hi to you if you’re around the conferences from the list below, or just in the area of Michigan and San Francisco; to talk about APIs, and everything Kubernetes!

What are we doing in these conferences

We will be discussing mainly about APIs, how to develop them in Kubernetes and great API development workflows!We will give presentations on scaling API teams and GitOps-ing APIs in Kubernetes.

Conferences we are attending

Deserted Island DevOps Conf - Sept 14-15 Mackinac Island

Can You GitOps Your API? - Sept 14 | 11am ET | Abdallah Abedraba

Description of the presentation:

”One of the major trends in contemporary cloud-native application development is the adoption of GitOps; managing the state of your Kubernetes cluster(s) in Git - with all the bells and whistles provided by modern Git platforms like GitHub and GitLab in the regards to workflows, auditing, security, tooling, etc.

Let’s dive into how your teams can leverage it for a faster and safer road to production!”

API Specification Conference - Sept 19-21
San Francisco
Key Note - Retrospective Panel - Wed Sept 21

Presentation - Boosting your Kubernetes API development workflows with OpenAPI | Sept 19 | Virtual Session

Description of the presentation:

”Achieving a productive workflow for API development under Kubernetes is a challenge, especially for developers who are new to Kubernetes and related constructs like manifests, Ingress controllers, GitOps, etc. Adopting an OpenAPI-centric approach to API development can bring many benefits in this regard; the metadata contained in OpenAPI can be used to automate many of the tasks related to building and deploying APIs to Kubernetes - both in manual and CI/CD workflows - helping your team to keep up the pace while transitioning to Kubernetes.

This talk will show you how to leverage OpenAPI to accelerate your API development workflow for Kubernetes. Both design-first and code-first approaches are covered, with both manual and automated CI/CD/GitOps processes.”

API Days Australia - Sept 14-15 Online

Scale Your API teams with a Design-First Approach | Sept 14

Description of the presentation:

“Kubernetes scales APIs from a workload perspective, but teams have a long way to go to find a good workflow that includes simplifying development, prototyping, iteration, stakeholder collaboration, and much more.

In this talk, we will explore how Kusk Gateway helps bridge the gap of a productive API workflow in Kubernetes with APIOps and OpenAPI at its core.”

Come talk to us

We having a booth at API Specification Conference, where will be more than happy to talk to you about:- Adopting API-first approach in your development teams- Achieving a productive API workflow in Kubernetes- Creating a robust API experience starting from the gateway all the way back to the microservices

Can’t wait to meet you there!

Kusk Gateway 1.2.0 Release - OAuth, Local Mocking and more!

Abdallah Abedraba — Thu, 08 Sep 2022 08:36:55 +0000

Intro

The Kusk team is proud to announce the v1.2.0 release of Kusk Gateway! For the unfamiliar, what makes Kusk Gateway unique is that it uses the ubiquitous OpenAPI specification file as a single source of truth for making an API available to consumers, which includes routing configuration, request validation, timeouts, etc.

Kusk will especially resonate with developers and teams like ours, who have adopted a design-first approach to API development.

Thanks to Kusk Gateway and industry-standard OpenAPI (f.k.a Swagger), you can quickly publish your APIs deployed in Kubernetes without having to add any additional configuration resources, which plays nicely with both manual and automated/GitOps-based development workflows. Kusk Gateway enables you to design and deploy your APIs from a single OpenAPI definition, allowing you to:

Rapidly prototype your REST APIs by mocking your API responses, allowing your teams to instantly start building on top of your APIs without your services being implemented
Protect your endpoints with automatic request and response validations
Configure critical policies like authentication and CORS with no coding required
Centrally control your APIs from an Open Source dashboard
Enable automation of the entire deployment process of your API without requiring manual DevOps intervention

What’s new?

Since the 1.1.0 release we have been focusing on making the core of Kusk Gateway production ready - but have also managed to squeeze in some new functionality.

OAuth Authentication (Experimental)

OAuth2 ensures that your applications (upstreams) don’t get requests which are not authenticated and authorized. It effectively helps to protect your API. Kusk now allows you to add simple configuration and use it with your favorite auth provider, taking away the headache of setting up complex OAuth flows.

Learn more about implementing OAuth in Kusk at https://docs.kusk.io/guides/oauth2

Local auto-mocking from schema

Spin up a local mocking server that generates responses from your content schema or returns your defined examples. No need to have Kusk running in a cluster anymore to take advantage of OpenAPI mocking!

kusk mock -i <path to openapi file>

Learn more at https://docs.kusk.io/reference/cli/mock-cmd.

Public OpenAPI Path

The openapi-path field takes a path name and will expose your OpenAPI definition in the defined path.

...x-kusk: openapi-path: openapi.json...

This will expose your entire OpenAPI definition, without the Kusk extensions, on yourdomain.com/openapi.json.

ARM64 support

Kusk Gateway now supports being deployed to clusters running on ARM64.

Misc Enhancements

Improved CLI developer experience
Authentication now happens before Mocking to allow for use of both polcies together.
Ability to disable telemetry during installation
Improving overall experience with developing Restful APIs

The roadmap post 1.2.0

The main areas for improvement we are planning after this 1.2.0 release include:

Upgraded Envoy to the newest version 1.23.0
Onboarding and Help improvements, especially on the CLI
An new and improved Dashboard experience- Packaging for APT, Chocolatey and an improved Brew experience
Hot Deploy (Deploy to a target from the CLI when the OpenAPI spec file changes)
… and more enhancements and bug fixes.For more about future enhancements, you’re welcome to check out the 1.3.0 Release project on GitHub to see how things are going, don’t hesitate to jump in with comments, suggestions or a Pull Request!

Try it out!

Head over to the Kusk Gateway GitHub repository to download the latest release - installation instructions and documentation are available there as well. If you have any questions or ideas please feel free to join our Discord server and get in touch.

Thank you!

Rapidly prototype your APIs on Kubernetes with Kusk Gateway

Abdallah Abedraba — Sun, 26 Jun 2022 12:09:20 +0000

OpenAPI (f.k.a Swagger) has introduced a set of standardized specifications for REST APIs that, among many things, allows producers and consumers of APIs to work together in designing an API before even writing a single line of code!

This design-first approach has improved the experience of API developers by giving them the opportunity to use tools like OpenAPI generator which takes an OpenAPI definition and generates scaffolding code for backenders, making the development of APIs much faster.

But consumers of APIs still didn’t have a way of really taking advantage of this design-first approach as they still depended on the backend teams to implement and deploy APIs.

How could consumers of APIs then take advantage of OpenAPI and the design-first approach? By making the API gateway aware of the OpenAPI definition. Let me explain how!

An API gateway sits in front of your microservices routing incoming traffic that your Kubernetes cluster receives to the corresponding microservice. By having the API gateway be aware of your OpenAPI definition it can then see what a response would look like and generate a mock (or fake) response for the consumers instead.

This approach would allow API consumers to start using the API with mocked results and meanwhile (in parallel!) the backend team can start implementing the actual API; it essentially loses the dependency between consumer and producer teams and allows for quicker prototyping of the API. With no code whatsoever, just your run-of-the-mill OpenAPI definition.

In this tutorial, you will learn how to use Kusk Gateway, an open-source OpenAPI-driven API gateway, to enable this rapid prototyping development! Let’s make a simple example of how to achieve this:

Walkthrough

1. Install Kusk Gateway CLI

brew install kubeshop/kusk/kusk

For other installation methods, check the installation docs.

2. Install Kusk Gateway in your Kubernetes cluster

kusk install

3. Create an OpenAPI definitionCreate the file `openapi.yaml` with the content:

This is a simple common OpenAPI definition for a single /hello route that accepts a GET method. There are a couple of important details here:

1. The `x-kusk` extension

This section is an extension to the OpenAPI specification. We use it to configure Kusk Gateway to enable in this case CORS access and mocking of the API. This approach makes OpenAPI the definition of your API and your gateway configuration(!) essentially having a single source of truth.

2. The `example` field

To allow Kusk Gateway to generate mock responses, you'll need to define examples of your responses under OpenAPI's example field. In this case we have an example message "Hello from a mocked response!".

4. Apply the API configuration to the cluster

kusk api generate -i openapi.yaml --envoyfleet.name kusk-gateway-envoy-fleet | kubectl apply -f -

This applies the configuration to the gateway and deploys the API.

5. Test your mocked API

Now you are ready to test the API and build against mocked responses!

First, you need to get the External IP of the gateway, i.e. the entry point of your APIs. For that run:

kubectl get -n kusk-system svc/kusk-gateway-envoy-fleet

Note: if you're running a local cluster with Minikube, the ExternalIP might be in pending state; in case it is, you can port-forward to the gateway by running kubectl port-forward -n kusk-system svc/kusk-gateway-envoy-fleet 8080:80, so your external IP becomes localhost:8080.

And now test the /hello path:

curl $EXTERNAL_IP/hello{"message": "Hello from a mocked response!"}

And that's it! You can see that this is the same response that was defined in our OpenAPI definition. Now your API consumer teams can already start working with the mocked API!

Once the API team has implemented the service, you will stop mocking your endpoint and connect it to a microservice in your cluster. That's what we'll cover in the next sections.

6. Deploy your application to the cluster

Deploy this example application that we will connect with the API gateway:

kubectl apply -f https://gist.githubusercontent.com/aabedraba/e9e7a48c7bc48386f4dadd0d9fe3b7df/raw/9048bcae0675dade44a2cd4b091e752acafaf960/hello-kubernetes.yaml

7. Connect your application to Kusk Gateway

Now, you will need to disable the mocking for your API and connect the upstream. Update your openapi.yaml file with the following changes:

8. Test your implemented application

With the same External IP from step 5, run

curl $EXTERNAL_IP/hello{"message": "Hello from an implemented service!"}

Voilá! You've just implemented and connected a service to your gateway!

You can find the code for the article on Github.

Conclusions

Kusk Gateway enabled you to take advantage of OpenAPI and a design-first approach to allow your teams to work in parallel once they've agreed on a specific API design. Nothing should have be stopping them anyway!

Having an OpenAPI-aware gateway allows you to reap more advantages of the OpenAPI lifecycle, like for example automatic validation of your APIs and more!

Head over to the Kusk Gateway documentation to try it out and explore all the benefits of an OpenAPI-driven gateway! We would love to hear your thoughts and ideas in our Discord server or just drop by if you to say hi :)

Thank you!

From Design-First to Automated Deployment with OpenAPI

Abdallah Abedraba — Tue, 26 Apr 2022 07:19:40 +0000

Being an API-first organization is becoming a must as organizations need to build APIs to enable consumers (internal or external) to extend the functionality of their systems, share data across organizations and build customized experiences.

The microservices architecture — building services that perform only one function, as opposed to covering an entire area of functionality — provides the agile and efficient building workflows needed to deliver seamless customer experiences.

Finally, Kubernetes, a container orchestration system, has been an extremely popular choice for orchestrating those microservices. It has helped adopt the organizational agile structure into the API development process, but has inherently introduced a new set of challenges.

Current API development processes require developers to adhere to an organizational set of best practices — if they even exist and assuming that developers have read those best practices and are implementing them — that can only recommend, but not enforce the best practices, giving turn to inconsistent API quality, (slow) developer experience and configuration control.

In this article we will discuss how you can address these challenges by implementing a design-first approach in your APIs and automating their deployment.

Design-First

Most developers have been following a code-first approach to build their APIs. That is, implement the API first, and everything from documentation — usually code-generated OpenAPI specifications used with Swagger — to the organization’s policy requirements (security, etc) have come after the fact.

The code-first approach has increased the speed of the development itself, but it has compromised the consistent experience between the organization’s APIs and their quality.

To introduce consistency and quality to a code-first approach, organizations have usually introduced blockers in the deployment process (for example, requiring an API team approval) and in turn slowing down going to production.

Going design-first means you start by designing your API — writing how your APIs should behave and translating that to the OpenAPI specification — and, once it has been agreed upon, you would then start writing the code to implement the designed behavior of the API.

Design-first approach enables you to include multiple stakeholders from your organization early in the API design process. Additionally, there are tools that can validate the designed specification, which reduces risks of failure, improves consistency and enforces required aspects of the APIs.

Design-First in Practice

A lot of companies have tried design-first methodologies, but have failed to maintain them after a while because they either could not set up the right process, or it was extremely time consuming or tedious.

In the following walkthrough, we will use three tools to help us set up the process required to go from design to implementation with little overhead. Our design-first approach will be the following:

We’ll use SwaggerHub to create our OpenAPI document which allows us to automatically validate the designed API against our standardization rules. The design-time validation ensures that the new API will be consistent with other APIs across the organization. Additionally, we can specify validation rules, to ensure operational consistency across our microservices landscape.
After that, the designed spec would go into a git repository that will help having a single source of truth of our APIs. This git repository will be connected to ArgoCD, which can then ensure that the cluster is up-to-date with the repository.
Finally, ArgoCD will use Kusk-gateway, an OpenAPI driven Kubernetes gateway, to deploy the API so developers can start implementing the services.

The process would look like the following diagram:

Walkthrough

Enough talk — let’s see this in action — here comes a step-by-step walkthrough to get this in place for the automated deployment and execution of OpenAPI specifications in your cluster of choice!

Let’s start with setting things up for our APIOps-powered development!

1. Setting up a Github repository

Create a Github repository that we will use to put our OpenAPI specifications in and synchronize them with the deployed API in the cluster.

After the repository is created, create a new folder in the repository with the name api. This is where we will put our OpenAPI spec.

For that, run the following commands

mkdir api # folder where the OpenAPI spec will go to
touch api/.gitkeep
git add . git commit -m “Initial commit”
git push origin main

2. Create a new API in SwaggerHub

In SwaggerHub, on the top left menu, click on “Create New API”

Fill in the form as shown below:

Once the API is created, let’s write an example API to deploy. Copy the spec below and paste it in your SwaggerHub editor.

OpenAPI allows extending the spec by use of decorators. To extend the OpenAPI specification, you just need to create a new section in the spec that starts with “x-”. In the spec above, you can see that we have used x-kusk to add Kusk-gateway’s configurations.

3. Connect SwaggerHub to your Github repository

To deploy it to our Github repository you will need to hover on the Sync button as seen below and click on Setup Integration.

Choose the Github Sync integration and click on Next.

In the next window, click on Connect to Github and follow the procedure to connect it. Remember to choose the right repository (the one we just created in the first step).

Now fill out the rest of the form as seen below. After that click on the Create and Execute button and click on Done in the next window.

To check if the integration works, click on the Sync button as seen below, Push the changes and you should see the updates in your Github repository!

4. Install Kusk-gateway in your Kubernetes cluster

Follow the Kusk-gateway installation guide.

5. Install ArgoCD in your Kubernetes cluster

Follow the ArgoCD installation guide.

6.Configure ArgoCD to use Kusk-gateway

ArgoCD allows the use of plugins that we will use to install Kusk’s CLI tool with, so that when our Github repository is updated, ArgoCD can run the CLI tool to generate the YAML manifests from the OpenAPI specification and apply them to the cluster.

Create a deployment patch manifest patch.yaml, this will be of type JSON-patch:

And apply it with the following command:

kubectl patch deployments.apps -n argocd argocd-repo-server --type json --patch-file patch.yaml

Now let’s add Kusk CLI to ArgoCD’s plugin ConfigMap. Create the file
argocd-plugins.yaml

As you can see here, we’re using the command kgw api generate which creates the Custom Resources (manifests) that ArgoCD will then add to our cluster. Apply the patch with the command:

kubectl patch -n argocd configmaps argocd-cm --patch-file argocd-plugin.yaml

Finally, create the ArgoCD application that will manage your API’s gateway deployment.

Create the file kusk-gateway-application.yaml

Notice that we have defined path: api which is the folder in the Github repository with the api-spec.yaml from the steps earlier. We have also defined the .destination.namespace to be default, which is where the gateway should be deployed in the cluster. And apply it with

kubectl apply -f kusk-gateway-application.yaml

7. Run the initial ArgoCD sync and check your cluster

On ArgoCD’s dashboard, we will now see the newly created application. Let’s click to get into it and sync our API.

And now click on Sync to create the gateway for the first time‍.

And voilà, there’s our newly created gateway created and managed by ArgoCD with every new update on the OpenAPI spec in the Github repository!

8. Consuming the Deployed API

In our API we have configured Kusk-gateway to mock our single endpoint, so we can have a testable endpoint before implementing the service. It uses OpenAPIs example section to use as a response mock of the API.

For that we will have to get the Kusk-gateway API endpoint, which you can find by running

kubectl get svc -l "app.kubernetes.io/component=envoy-svc" --namespace kusk-system

Copy the External IP from the result and query the /hello path defined in our OpenAPI spec:

$ curl 127.0.0.1/hello
“Hello world!”

And we are set to start implementing the API!

Wrapping up

This flow of programmatic API design we call it the APIOps, which combined with GitOps philosophy (having your repository as a single source of truth, combining it with CI/CD pipeline) provide a powerful alternative to a more traditional code-first approach not so closely aligned with the lifecycle of Kubernetes applications.

Let us know what you think about this method, we’re open to hearing your feedback in our Discord server!

Check Kusk-gateway on GitHub and SwaggerHub!

You can also check the webinar on this article if you want to see the action yourself!

Thank you!

A GitOps-Powered Kubernetes Testing Machine with ArgoCD and Testkube — Kubeshop

Abdallah Abedraba — Thu, 21 Apr 2022 08:51:23 +0000

One of the major trends in contemporary cloud native application development is the adoption of GitOps; managing the state of your Kubernetes cluster(s) in Git — with all the bells and whistles provided by modern Git platforms like GitHub and GitLab in regard to workflows, auditing, security, tooling, etc. Tools like ArgoCD or Flux are used to do the heavy lifting of keeping your Kubernetes cluster in sync with your Git repository; as soon as difference is detected between Git and your cluster it is deployed to ensure that your repository is the source-of-truth for your runtime environment.

Don’t you agree that it’s time to move testing and related activities into this paradigm also? Exactly! We at Kubeshop are working hard to provide you with the first GitOps-friendly Cloud-native test orchestration/execution framework — Testkube — to ensure that your QA efforts align with this new and shiny approach to application/cluster configuration management. Combined with the GitOps approach described above, Testkube will include your test artifacts and configuration in the state of your cluster and make git the source of truth for these test artifacts. And it’s Open-Source too.

Key wins achieved with this approach:

Since your tests are included in the state of your cluster you are always able to validate that your application components/services work as required.
Since tests are executed from inside your cluster there is no need to expose services under test externally purely for the purpose of being able to test them.
Tests in your cluster are always in sync with the external tooling used for authoring
Test execution is not strictly tied to CI but can also be triggered manually for ad-hoc validations or via internal triggers (Kubernetes events)
You can leverage all your existing test automation assets from Postman, or Cypress, or through executor plugins.

From a conceptual perspective this can be illustrated as follows:

Walkthrough

Enough talk - let’s see this in action - here comes a step-by-step walkthrough to get this in place for the automated deployment and execution of Postman collections in a local Minikube cluster to test.

Let’s start with setting things up for our GitOps-powered testing machine!

Installations

1. Install Minikube

You can follow the minikube installation for your operating system here.

2. Install ArgoCD

Follow the ArgoCD installation guide.

Note: For step 3 “ Access The Argo CD API Server”, choose the “Port Forwarding” method, as that is the easiest way to connect to it with a Minikube cluster.

3. Install Testkube

Follow the installation guide for Testkube here. Make sure to install the CLI client and the components in your cluster.

Setting up application and tests

Install a “Hello Kubernetes!” application in your cluster
We will create a YAML file for a simple “Hello Kubernetes” application that we will then create our integration tests against.

Create the file hello-kubernetes.yaml

And deploy the Hello Kubernetes deployment with:

kubectl apply -f hello-kubernetes.yaml‍

You can test that your application has been correctly installed by running:

minikube service hello-kubernetes-service

5. Set up a Git Repository containing some Postman collections

We are going to use tests created by Postman and exported in a Postman collections file.

We can upload this to the same Git Repository as our application, but in practice the repository could be the same repository hosting the application or it could also be in a separate repository where you manage all your test artifacts.

So let’s create our postman-collections.json and push it to the repository.

You can see an example of how the repository should look like here.

Configure ArgoCD to work with Testkube

6. Configure ArgoCD to use the Testkube plugin

To get ArgoCD to use Testkube, we need to add Testkube as a plugin. For that we have built a customized argocd-repo-server container image that will include Testkube as a binary.

Patch the ArgoCD repo-server pod image.

Create a deployment patch manifest patch.yaml, this will be of type JSON-patch:

And apply it with the following command:

kubectl patch deployments.apps -n argocd argocd-repo-server — type json — patch-file patch.yaml

7. Define Testkube as a plugin in ArgoCD’s Configuration Management Plugin

Create the file argocd-plugins.yaml

‍As you can see here, we’re using the command testkube crd which creates the Custom Resources (manifests) that ArgoCD will then add to our cluster. Apply the patch with the command:

kubectl patch -n argocd configmaps argocd-cm — patch-file argocd-plugin.yaml

8. Configure an ArgoCD application to manage test collections in your cluster

Create the file testkube-application.yaml

Notice that we have defined path: postman-collections which is the test folder with our Postman collections from the steps earlier. With Testkube you can use multiple test executors like curl for example, so it is convenient to have a folder for each. We have also defined the .destination.namespace to be testkube, which is where the tests should be deployed in our cluster.‍

Now let’s create the application with:

kubectl apply -f testkube-application.yaml

9. Run the initial ArgoCD sync and check your cluster

On ArgoCD’s dashboard, we will now see the newly created application. Let’s click to get into it and sync our tests.

And now click on Sync to see your tests created.

And voilà, there’s our test collection created and managed by ArgoCD with every new test created and updated in the Github repository containing the tests!

Run your tests!

10. Run ad-hoc tests from the CLI

Now that we’re all set - let’s try some ad-hoc test execution using Testkube’s CLI

List the tests in your cluster with:

kubectl-testkube tests list

You should see your deployed test artifacts

To run those tests execute the following command:

kubectl-testkube tests run hello-kubernetes

The test execution will start in the background, you now need to copy the command from the image below to check the result of the execution of the test

kubectl testkube tests execution EXECUTION_ID

And you should see that the tests have run successfully, just like in the image below.

11. See test results in the Testkube dashboard

You can also see the results of your tests in a nice dashboard. Just open the Testkube dashboard with the following command

kubectl-testkube dashboard

‍

And you will be able to see the results of the execution in the Executions tab as seen in the image below.

12. Test the flow: update the test and deploy the updated test with ArgoCD

Let’s add an additional test to our collection. Replace the content our existing test in hello-kubernetes.json with the following:

As you can see, we have added a request status check. Now commit this change to the Github repository.

If you now go to ArgoCD’s dashboard you’ll see that your tests are out of sync with the deployed artifacts.

Click on Sync again and apply the changes. With that, your test artifacts are back in sync!

Wow - that was quite a lot to get through but we ended up with something really neat - an automated test deployment and execution pipeline based on GitOps principles!

Wrapping up

Once fully realized - using GitOps for testing of Kubernetes applications as described above provides a powerful alternative to a more traditional approach where orchestration is tied to your current CI/CD tooling and not closely aligned with the lifecycle of Kubernetes applications.

Would love to get your thoughts on the above approach - over-engineering done right? Waste of time? Let us know!

Check Testkube on GitHub — and let us know if you’re missing something we should be adding to make your k8s resource testing easier.

Download the latest release on GitHub
Check out the documentation
Get in touch with us on our Discord server

Thank you!

How to Create a YAML Manifest Template in Monokle

Abdallah Abedraba — Wed, 02 Mar 2022 08:29:18 +0000

Monokle is a great tool to inspect your Kubernetes manifests with an easy and intuitive interface showing you how your manifests are connected to each other and how they translate to your existing cluster. It also allows your team to avoid drifts between your manifests and clusters as you keep adding more and more components.

Apart from inspecting your existing manifests, Monokle allows you to create manifests both from scratch and from templates. These templates help you gain speed while creating new components, but more importantly, they reduce grounds for errors from wrongly misconfiguring them.

For example, if your team has a policy of adding a specific property to every component, you can enforce the correct creation of these properties in your template instead of having the developer manually create the manifest and forgetting to add the required property.

When you create your templates with Monokle, you will be able to have a form that developers will fill out to create the resources they need, as seen in the example below.

Monokle comes with a number of default templates to get you started with Kubernetes, and in this tutorial, you will learn how to make your own template for a simple Kubernetes Pod.

Setting up the project

Templates are installed through a plugin in Monokle. A plugin is basically a Github repository with a valid Monokle package.json.

So, first of all, let’s go ahead and create a Github repository -you can call it monokle-templates-plugin - and connect the repository to your local machine.

We will create now the package.json for our template plugin in the root of our repository:

Template configuration

a Monokle template configuration
a Form configuration
and a Kubernetes YAML manifest with placeholders

We will expand on those in the next section while we are creating them.

1. Monokle template configuration

We will need a specific folder for each template. Let’s create a folder and call it basic-pod-template, just like we have defined it in the path section of our package.json:

$ mkdir basic-pod-template && cd basic-pod-template

Let’s now create the template configuration, which is Monokle-specific and defines what type of template you are creating. There are two types of templates in Monokle for now: vanilla and helm-charts; we will be creating a simple vanilla type template.

Create the file monokle-template-json with following content:

In the code above, we have defined the fields forms.schema and forms.uiSchema. Both of these fields define files that will be used by Monokle to provide users of our template with a nice input form. The form-schema.json file will contain the form fields that we will request the user to input, and the form-ui-schema.json defines how the form is going to appear (titles for the fields, descriptions, etc).

Let’s go ahead and create our form-schema.json defining the basic fields that we will request from the user to create a Pod:

This is a standard JSON schema format, which you can read more about in the json-schema website. JSON schema is used in most projects to define custom forms like the one we are creating now, where you can define, among other things, the required fields of your form, as seen in the required section.

Monokle uses the react-json-schema-form frontend component to render the forms for these templates. It takes the form fields definition which we just created, and a UI form definition, which we will build next.

Create the file the file form-ui-schema.json with the following content:

Notice that we are using a custom widget, internally defined for Monokle, called namespaceSelection. This widget provides the user with a dropdown of available namespaces.

3. YAML manifest template

Finally, we’ll define the YAML manifest template with the placeholders that we will update the form data with. Note that we are using forms as an array because we can define multiple successive forms in our monokle-template.json, instead of having one huge form. In our case, as we have only one form, we will use forms[0] to access it.

Create the template.yaml file and populate it with:

As you can see, we have been able to enforce a specific type of property, by marking the form field as required and formatting it in a specific way in our template. You can also see that Monokle uses [[,..]] as the syntax for interpolation of form values and simple scripts written in javascript.

Upload your project to Github

Let us wrap up with the creation of the template and upload the package.json and our template folder to the Github repository that we created at the beginning of this tutorial.

Importing your template in Monokle

Now that we have defined our template configuration, the form definition and our manifest with its placeholders, we need to import the template to Monokle in our configured project.

Click on the plugin section, on the top right of Monokle’s interface

Click on install, and add your Github repository link on the prompted field.

You will now find your brand new plugin in the Plugin Manager, as shown below

If you check the Templates section, you’ll now find your new template available to use.

Using your template

Let’s create a basic pod by using the template and filling the form:

Now that the Manifest is created, we can save it and deploy it!

And just like that, you’ve created a template! 🥳

Next Steps

All the steps from this tutorial can be found in this Github repository – feel free to clone it, make your own changes and use it as a starting point to your new templates. You can also read and learn more in the Monokle documentation about plugins and templates.

Check Monokle on GitHub — and let us know if you’re missing something we should be adding to make your everyday life with k8s manifests and resources easier.

Download the latest release on GitHub
Check out the documentation
Get in touch with us on our Discord server

DEV Community: Abdallah Abedraba

The Three Steps of Building Design-First APIs in Kubernetes

1. Determine what business problem you’re trying to solve

2. Codify your API in a human- and machine-readable document

3. Convert the API design into code, tests, and other artifacts using generators… like Kusk!

Kusk + Cloudentity - Fine-Grained Authorization for your APIs

OpenAPI for Open Standards

Control the Authorization of APIs

How does this integration work?

Try it out now!

Setup Ingress Controller with CORS configuration

First things first, what is CORS?

How to configure your Ingress Controller for CORS?

1- Install Kusk in your Kubernetes cluster

2- Deploy a sample application to your clusterYou can deploy this example application:

3- Configure your OpenAPI definition for Kusk

4- Apply the changes to the cluster

5- Connect to Kusk Gateway

6- How to test CORS?

CORS through your Ingress Controller made easy

Kusk v1.3 Release - Updated CLI and dashboard experience!

CLI improvements

Dashboard Overhaul

Improved Documentation

Try it out!

Kusk on the Road - Our September ‘22 Schedule

What are we doing in these conferences

Conferences we are attending

Come talk to us

Kusk Gateway 1.2.0 Release - OAuth, Local Mocking and more!

Intro

What’s new?

OAuth Authentication (Experimental)

Local auto-mocking from schema

Public OpenAPI Path

ARM64 support

Misc Enhancements

The roadmap post 1.2.0

Try it out!

Rapidly prototype your APIs on Kubernetes with Kusk Gateway

How could consumers of APIs then take advantage of OpenAPI and the design-first approach? By making the API gateway aware of the OpenAPI definition. Let me explain how!

Walkthrough

1. Install Kusk Gateway CLI

2. Install Kusk Gateway in your Kubernetes cluster

3. Create an OpenAPI definitionCreate the file openapi.yaml with the content:

1. The x-kusk extension

2. The example field

4. Apply the API configuration to the cluster

5. Test your mocked API

6. Deploy your application to the cluster

7. Connect your application to Kusk Gateway

8. Test your implemented application

Conclusions

From Design-First to Automated Deployment with OpenAPI

Design-First

Design-First in Practice

Walkthrough

Wrapping up

A GitOps-Powered Kubernetes Testing Machine with ArgoCD and Testkube — Kubeshop

Walkthrough

Installations

Setting up application and tests

Configure ArgoCD to work with Testkube

Run your tests!

Wrapping up

How to Create a YAML Manifest Template in Monokle

Setting up the project

Template configuration

1. Monokle template configuration

3. YAML manifest template

Upload your project to Github

Importing your template in Monokle

Using your template

Next Steps

3. Create an OpenAPI definitionCreate the file `openapi.yaml` with the content:

1. The `x-kusk` extension

2. The `example` field