Declarative APIs or declarative models are popular in k8s cloud native apps. This post shares the experience and thoughts on learning and building a declarative interface prototype.
Declarative Model
A declarative software model, usually compared to imperative interface, includes a concept model of northbound scheme or DSL which describes a desired state of system and a southbound provider as a controller of async reconciliations.
Model Overview
- Northbound:
- A scheme or DSL to describe desired state of system
- From users' view, it's the state being requested to declarative API, not the ways to do it
- Usually the request is processed in an async way, e.g. ordering way
- Southbound
- One or more southbound providers in backend
- The app could carry a default provider in most of cases, e.g. to call a traditional RESTful API in backend
- The provider would reconcile the in scope object states towards desired states by:
- Calculate the state diff, usually in top to bottom or state tree model
- The processing could be distributed and usually in async with workers
- Once the calculated diff is empty, stop reconciliation
- Generate requests to reconcile the targeted objects
- It's up the system dependencies but the experience is to reconcile one step at a time
- If there are still more steps to go, complete current reconciliation step and requeue the request
- Take care of low level requirements on the generated downstream requests
- Auth-n and auth-z with tenancies
- Rate-limit with tenancies and cloud service provider
- Charging or order management and traceabilities
- Payload formats
- Related east-west interactions, e.g. provider dependencies
A typical example is the Terraform with providers.
Benifits or Problems To Resolve
- Reduce Human Error
Reports show around 1/5 outage incidents occur because of human error. In an imperative model, users need to consider each detail API request, version, phased validation and usually programmatically manage the intermediate states in sequence or async ways. From another point of view, the user end implements a work-flow implicitly. It increases the chances to introduce human errors due to the conflicts between humanity and complexity.
- Better and Earlier Validation
(TBC)
- Hide the Technical Details
With declarative interface, users don't deal with number of versions for all the APIs. There could still be version of scheme, which is an universal version or grouped versions in a relatively simpler way. The backend services could evolve without user end impacts.
Provider Design
(TBC)
Open Questions
- Benifits and examples of manifest model
(TBC)
Change Log
Nov24, 2021: Continue drafting the model overview section. Mar15, 2021: Initial post draft.