Technical Deep Dive: Istio Developer Portal
Organizations with a mature microservices architecture run into challenges around service-to-service communication including things like resilience, observability, and security. A powerful service mesh solution, like the open-source Istio service mesh, can be used to solve these challenges. These microservices typically expose an API and get composed into higher-level business functionality that gets exposed to other parts of an organization, to mobile applications, or even to partners. At Solo.io, we’ve announced a solution that layers on top of Istio to help document, expose, and compose APIs called the Istio Developer Portal.
With the Istio Developer Portal, teams can publish their APIs running in Istio into a customizable portal that enables authentication/authorization, usage plans/policy, self-service documentation, sign up and more. In this blog, we take a look at how this works, what components get added to Istio to enable this, and what the main API resources are.
How it Works
Istio Developer Portal works as a typical Kubernetes-native application with Custom Resources and controllers to reconcile state intentions. There are no additional databases or custom configuration formats. The core Custom Resource Definitions (CRDs) that drive the developer portal are the
ApiDoc, ApiProduct, and
Portal resources. Other supporting custom resources help facilitate user management, routing, and grouping.
Understanding Istio Developer Portal Concepts
A user will start by creating an
ApiDoc resource which is made up of an Open API Spec (OAS) doc or gRPC schema. This
ApiDoc resource captures the interface or contract for an existing service or API. The API operations contained in this specification are then used to help automate the creation of the routing rules and matchers that will be specified in Istio configuration and automatically generated. Before we can generate this configuration to wire up Istio resources, we need to define an API Product which aggregates multiple
ApiDoc resources into a single unified API that then gets exposed to users.
ApiProduct resource, we can logically group and organize a set of
ApiDoc resources, whether specified as Open API Spec or gRPC into a single unified API that we can expose to users through a Portal. Another important role of the
ApiProduct is to map Usage Plans which include rate limiting and authentication policies to specific APIs. The Istio Developer Portal ships with a powerful rate limit server and external auth server that plugs into Istio’s ingress-gateway component. Istio Developer Portal uses Istio’s EnvoyFilter resource to wire all of this up, which alleviates the need for a custom proxy. You can use the baked in Istio ingress-gateway as a sort of lightweight API Gateway. For a more full-featured, powerful API Gateway see the Gloo API Gateway which is also built on Envoy and plugs into Istio.
At this point, the Istio Developer Portal will translate our ApiProduct into the necessary Istio VirtualService resources and tie them to the Istio Gateway resource. This means by defining our API specs and aggregating them into an ApiProduct, we can automatically expose these APIs on the Istio ingress gateway and get automatic rate-limiting and authentication. All of this is driven by the spec! Now, this doesn’t mean people will be able to access it yet. We need to document it, and expose it in a curated catalog or portal.
Enabling developers with an API portal
After we’ve defined the ergonomics of our externally facing API with the
ApiProduct resource, we can expose it in a custom
Portal that allows users to browse the APIs, view their documentation, and test them locally. Defining the
Portal consists of adding custom branding, additional static pages, and selecting the
ApiProducts we wish to expose.
Once you publish the Portal, it will be available through a web browser and display your APIs accordingly:
You can also specify optional access control which will constrain which users can view the APIs and whether or not they need API keys to call the APIs.
What the Istio Developer Portal means for Istio users
Istio is a powerful solution for solving service-to-service communication challenges and helping to operate microservices at scale. However, once you’ve deployed a large graph of microservices, not only do you need to operate it, but you need to enable others to harness the power of the services and APIs you’ve deployed. To date, this has been very haphazard and ad-hoc. The Istio Developer Portal enables Istio users to have the characteristics of a decentralized mesh along with the power of a unified strategy for sharing and discovering APIs. The Istio Developer Portal offers these features for Istio users:
- API management: Curate, document, and expose APIs running in your Istio mesh to others in your organization or to external partners/users and secure them with API keys and rate limiting
- Developer Onboarding: A clean and intuitive user experience makes it easy for developers to quickly search and browse the APIs they are authorized to use, get detailed information, and easily test them
- OpenAPI Spec and gRPC Support: Automatically drive Istio configuration using gRPC and OpenAPI/Swagger specs. Auto-create Istio Gateway, VirtualService, Destination Rules and Envoy Filter resources to configure Istio ingress and to handle API security
- Declarative Configuration: Use custom resources in Kubernetes to describe all elements of the developer portal system including portals, APIs, policies, and more
- Enhanced Security: A pluggable auth service allows integration of external auth systems – including OIDC, JWT, and Single Sign-On (SSO) – to your Istio environment
- API Rate Limiting: Enforce Global Rate limiting on your APIs with the Istio Rate Limit extension.
- Custom Branding: Organizations can create customized web-based portals with their company logo, images, colors, and content in addition to the published APIs.