Microservices & Kubernetes: Achieving functional and operational consistency with OpenAPI

Overcoming Microservice & Kubernetes Challenges with OpenAPI. APIs power modern-day organizations

Overcoming Microservice & Kubernetes Challenges with OpenAPI

APIs power modern-day organizations.

API-first development strategies are increasing to meet the digital needs of today’s tech-enabled consumer. Why? Because organizations must react quickly to market changes. To become more agile, many have moved towards more consumable architectural approaches.

Microservices architecture, a method of developing software focused on single-function modules with well-defined interfaces, supports an agile and decentralized workflow for delivering smaller consumable capabilities.

In tandem, container-based technology is being widely adopted to deploy and host microservices. Kubernetes, the container orchestration system, is a popular choice to deal with management, scaling, and deployment of microservices.

But adopting these patterns and technologies doesn’t guarantee a successful API strategy. It’s not easy to achieve sufficient scale while delivering consistent quality. It can even take time for investments to bear fruit – see SoundCloud’s eight-year migration journey from monolithic architecture using the strangler pattern.

That being said, let’s go over a few aspects that will put you in the best position to control your destiny.

Challenges with APIs, Microservices, Kubernetes

Fragmented approaches to API delivery lead to API chaos and paralyze digital evolution.

A common theme in many organizations is a scourge of undocumented APIs propping up system integrations. This leads to inconsistent API quality, poor developer experience, and the potential for security issues.

Kubernetes reins in API sprawl, but brings its own challenges. The declarative nature of Kubernetes Ingress means it’s configuration driven. An Ingress Specification describes these configurations, but the specification lacks many features needed to confidently expose APIs in a production setting. To overcome limitations, many controllers in the Kubernetes landscape have their own approach to specifying the feature configuration options.

Because of these challenges, organizations struggle to deliver optimal developer experience, maintain API quality, and keep consistency of their Kubernetes configurations under control. Some challenges are caused by workflow contention in the delivery process as well as team structures. For example, operational configuration of the ingress controllers is often performed by Ops personnel, yet the functional evolution of the API is done by Devs. The coordination overhead can cause bottlenecks or production issues.

Design-First Functional and Operational Consistency with OpenAPI

Applying a design-first approach can improve your API program. By encompassing both the functional and operational aspects of your services, and leveraging the OpenAPI specification, teams can progress from design through deployment in a quality-centered collaborative API workflow.

Before jumping into the benefits of the approach, let’s explore its terminology.

What Is OpenAPI?

The OpenAPI Specification (OAS), formerly known as the Swagger specification, defines a standard, language-agnostic interface to HTTP-based APIs. The OAS allows humans and computers to understand the capabilities of the service without access to source code, documentation, or network traffic inspection.

API specifications like OpenAPI do more than document what an API looks like. A consumer can understand and interact with the remote service with a minimal amount of implementation logic. The same is true on the provider side of an API, as stakeholders can communicate more effectively on the value proposition offered by any service.

Using an API definition can help automate many stops along the API lifecycle, including client and server code generation, mocking an API’s implementation, test automation, and telling the story of the API. This automation potential reduces waste from the DevOps cycles on both the producer and consumer sides of the API.

APIs and Microservices – What’s the Difference?

The terms are often used interchangeably, but they aren’t the same.

API stands for Application Program Interface. An API is an interface to a service, capability, or data. The programmable interface facilitates connections and communication between software applications and components, while hiding the implementation details. APIs are the language of software.

Microservices are all about implementation. A microservices architecture is an implementation pattern which promotes the delivery of self-contained components. These can be updated and evolved independently. APIs can exist without microservices! Most organizations don’t have the luxury of starting from scratch, so their API strategy includes the evolution from monolith to microservices approaches for API delivery.

Microservices are a major catalyst for the rise in API numbers.

What Is Kubernetes?

Kubernetes, also known as K8s, is a portable, extensible, and open-source platform for managing containerized workflows and services. It groups the containers that make up an application, using the concept of “pods” and “labels,” into logical units for ease of management and discovery.

Kubernetes was developed by Google, which donated it to the Cloud Native Computing Foundation (CNCF).

What Is an API Gateway?

An API gateway is a component used as part of an API management strategy. It acts as a front door to your API estate. Gateways intercept request and response traffic between clients and an API, and execute many common activities. The exact functionality varies, but routing, mapping, rate-limiting, authentication, transformation, validation, analytics, and billing are all possible.

What Is Ingress and Ingress Controllers?

Typically, services and pods have IPs which are only routable by the internal cluster network. All traffic that ends up at an edge router is either dropped or forwarded elsewhere.

Kubernetes Ingress is an API object that describes the external access routing rules for incoming traffic (typically HTTP or HTTPS) into the services running within a Kubernetes cluster. Ingress was created to make it easy for external clients (residing outside of a cluster) to access an application within the cluster, via a stable and externally addressable URL.

An Ingress Controller provides the actual Ingress implementation, and a running controller is required for the Ingress resource to work. Ingress controllers are pods, just like any other application in the cluster, and can see other pods. The controllers can inspect the incoming requests and perform certain rule fulfillment, like routing, as specified in the Ingress manifest. Ingress controllers resemble API Gateways.

The Cloud Makes API Standards Necessary – and Tricky

Industry research shows that standardization, governance, and security are significant challenges. With the adoption of cloud native environments, enforcing standardization of the operational aspect of API product is equally important to functional elements for the guaranteeing overall developer experience while keeping oversight across a distributed organizational landscape. It can lead to an exceptional developer experience while maintaining oversight across a distributed organizational landscape.

SmartBear recently teamed up with our friends at Kubeshop to showcase how combining SwaggerHub and Kusk promotes a single source of truth for your APIs.

Enabling fast, collaborative, and standardized API design is what SwaggerHub does best. It makes compliance with OpenAPI and your organization custom rules (or style guide) simple and intuitive. Combining SwaggerHub and the x-kusk extension from Kubeshop gives teams a single source of truth for operating and managing access to APIs running in Kubernetes.

The x-kusk extension supports declaring various run-time specifics of an API directly with an OpenAPI definition, in a unified manner agnostic of the cluster technology chosen.

It’s possible to specify the following directly with the definitions:

• Timeouts / retries
• CORS
• Disabling paths / operations (e.g., hide admin paths before exposing externally)
• Mocking
• Validation
• Cluster-specific properties

Using the same SwaggerHub API editor, teams can configure Ingress routes and other operational specifics from within a familiar tool. Additionally, SwaggerHub lets you apply standardization on operational configuration during design, and lays the foundation for features such as validation, mocking, and route-level settings.

When an API is ready for publishing to the Kusk gateway, teams know the runtime settings will match what was validated in earlier phases.

A typical SwaggerHub and Kusk Gateway workflow is:

1. Design your APIs in SwaggerHub collaboratively with all relevant stakeholders
2. Use the SwaggerHub standards enforcement to ensure x-kusk extensions are in place correctly
3. Use the SwaggerHub GitHub integration to sync/push your validated definitions (to GitHub)
4. Use CI/CD to automate the deployment of the API definition to Kusk Gateway and ensure implementations are in place
5. Publish and consume your APIs from mobile/web/3rd party applications

Embrace API Standards to Ensure Consistency Across Your Org

With APIs consuming the world of software, and microservices conquering the land of monoliths, staying in control of the functional and operational aspects of your API and microservices estate has never been more crucial.

See for yourself for free: Try SwaggerHub to get your standards in place and agile strategy in motion.

Why API Standards? Organizational benefits:

• Central representation (source of truth) for functional and operational aspects
• Collaborative design across the entire team (Business, Dev, Testers, Security, Ops)
• Outside-in approach for microservices – focus on consumer experience and consistency
• Standardization and governance – ensuring discoverability and consistency across the organization; the ability to validate/assert operational aspects early in the cycle
• Embracing iterative development – supporting automated workflows from design to deployment; reduced bottlenecks

To learn more:

• On-Demand Webinar – Ole Lensmar, CTO at Kubeshop and former OpenAPI chair, and Frank Kilcommins, API Technical Evangelist at SmartBear, explore the challenges of scaling API programs with microservices and Kubernetes, and the role OpenAPI can play in calming the chaos.
• Step-by-Step Walkthrough blog from the Kubeshop team – Design-First to Automate Deployment of APIs using SwaggerHub, Kusk, and OpenAPI with your Kubernetes cluster of choice.