YAM

Yet Another Application Model - The Simpler Way of Continuous Delivery.

What's YAM

YAM is an easy-to-use and powerful platform to deliver apps on Kubernetes:

It allows platform engineers defining standardized application model that maintains COMPLETE OPERATION LIFECYCLE metadata.
It allows developers/operators declaring how to operate their cloud native apps with A FEW LINES OF CODES.

Why YAM

YAM is inspired by Open Application Model(OAM), however, the implementation is Totally different from OAM runtime KubeVela. Here are some highlights of YAM.

☸ Operation Lifecycle as Code, EVERYTHING as Code.
🙆 Focus on separation of concerns, app-centric, hiding the complexity of the platform.
😊 Extremely easy to use, it won't take you one minute to bring your application on Kubernetes.
⚡ Lightweight and Fast, NO need for CRDs and Operators
✨ Extensible, YAM leverages JavaScript ecosystem to develop plugins to strengthen application model, by using JSON Schema, TypeScript, and Tons of NPM packages.

Why separation of concerns is significant

The concerns of different roles varies a lot:

Platform Engineer: how to provide an easy to use, scalable, stable, secure, cloud native platform?
Developer: how to run, access, observe my app ?
Operator: how to operate the app, is capacity enough ?

Traditional way:

Developers need to learn TOO MUCH platform related things to get onboard, like Kubernetes Resources, CRD, Helm, Cloud Services...
Platform engineer loses control of running workloads when team grows.

YAM/OAM way:

From developer/operator's perspective, they only need to fill in a few blanks that defined by the Application Model, then, type ONE simple command(YAM - "yam apply" / OAM - "vela up"), the whole app stack magically works !
From platform engineer's perspective, app-centric and standardized models LINK whole platform holistically. All complex things, like IaC, Kubernetes Resources and CRs, Helm Charts, are hidden for developers, but easily controlled by platform engineer team.

Getting Started

Prerequisites

Just a Kubernetes cluster, you could run one by Minikube, K3S or any Kubernetes cloud provider.

Step 1. Install YAM-CLI

Option1. Download and Install binary executable

For Windows/MacOS/Linux: Download from https://github.com/Code2Life/yam/releases.
Or, for Linux

curl -sfL https://get.yam.plus | sh -
# takes maybe 10 seconds
yam version

Option 2. Install by NPM

npm i yam-cli -g
# takes maybe 5 seconds
yam version

Option 3. Install VSCode Extension

Search and install "YAM Engine" in VSCode marketplace.

Step 2. Generate Operation Boilerplate

The following command will generate an 'app.yaml' file for maintaining the whole operation lifecycle, as code.

yam init <your-team>/<your-app>

or execute "YAM: Create New Application Model" command in VSCode.

Afterwards, complete the application model. Here is an example:

metadata:
  app: your-app
  namespace: your-team

# declare dependencies
prepare:
- type: helm
  name: redis
  chartName: bitnami/redis
  values:
    requests:
      cpu: 20m
      memory: 128Mi

# declare app configs
config:
- type: configMap
  name: my-config
  mount: /path/to/config
  from: 
  - application.yml

# declare deploy metadata
deploy:
  type: Deployment
  replicas: 2
  version: ''
  containers:
    - name: my-app
      image: 'busybox'
      command:
        - sleep
        - infinity

# declare access rules
access:
  - protocol: https
    host: some-domain.corp.com
    cert: your-cert
    paths: ['/']
    ingressEnabled: true

# declare monitoring/alerting rules
observe:
  monitor:
    enable: true
    path: /metrics
  alert:
    rules:
    - condition: absent(process_uptime_seconds{service="your-app"})
      keep: 5s
      severity: critical
      description: "Service Unavailable !"

# declare auto-scaling rules
scale:
  minReplicaCount: 1
  maxReplicaCount: 10
  triggers:
  - type: cpu
    metadata:
      value: "60"

Step 3. Release the App

# 1. plan a release of your app, on a group of environments
yam plan --version v1.0.0 --clusters dev,qa
# 2. apply the changes previously planned
yam apply -f release-plan-<timestamp>.rpz

# or, plan-and-apply directly
yam apply --version v1.0.1 --clusters dev,qa

Also, you could apply the app model through VSCode Extension

Other Commands

Rollback or remove the app.

yam rollback team/app --rev 1/2 --clusters 
yaml remove team/app --clusters

Some built-in tools.

# port-forwarding tool
yam forward team/app --from-to 8080:8089

# portable UI
yam ui

Basic Workflow

Comparisons

Compare to Helm/Kustomize

Limitations of Helm:

Helm allows us to customize template, but it can not customize operation workflow or integrate with non-kubernetes systems
Helm defines environment related parameters in separate "values" file, it's not flexible enough, especially when there are a dozen of environments
Helm exposes not only values files but also templates definitions to developers and operators, namely, it's not app centric, but more like a template engine.
Helm can't validate the generated files util applied to kubernetes

YAM is app-centric, also leverages existing Helm ecosystem, 'helm-operator' is a built-in plugin, you could specify dependent Helm Chart in prepare stage.

metadata:
  app: your-app
  namespace: your-team
prepare:
- type: helm
  name: redis
  chart: bitnami/redis
  values:
    key: value
deploy:
  # ......

Compare to Pulumi/Terraform

Both Pulumi and Terraform are focused on IaC, they are designed to used by Platform Engineers and Operators, NOT for Developers.

YAM leverages Pulumi/Terraform, Platform Engineer could develop customized, SIMPLE application models, while using those two IaC tools to implement the Model. Here is an example.

metadata:
  app: your-app
  namespace: your-team
prepare:
- type: terraform
  provider: aws
  variables:
    route53.domain: my-app.my-corp.com
deploy:
  # ...

Compare to Open Application Model (OAM)

What YAM & OAM have in common

Since YAM is inspired by OAM, they share a lot in common.

Both are built for separation of concerns.
Both are app centric.
Both leverage existing cloud-native ecosystem, Pulumi/Terraform/Helm/CRD Operators/CrossPlane...
Both are easily integrated to ANY CI/CD system.

The Differences

OAM introduces the concept "Trait", while YAM focuses on defining streamlined, concise, holistic application model, no additional concepts are introduced.
OAM runtime KubeVela uses Cuelang to define, validate and extend the model, while YAM glued plugins together by a more programmable approach: JSON Schema + TypeScript
OAM Runtime KubeVela is actually an Kubernetes Operator, needs to be deployed into cluster, while YAM is a Lightweight Tool written by Node.js/TypeScript, no requirements on Kubernetes.
YAM introduces flexible environment hierarchy and fantastic parameterization mechanism, it's designed for both simple workloads and large scale, multiple region deployments.
YAM split operation workflow to two stages, plan & apply (inspired by terraform).
Benefit from NPM, YAM plugin is more powerful, you could send HTTP requests , or, do anything you want inside plugins, composing YAML is just a piece of cake.

Plugin Development

Define subset of JSON Schema + Handler Function, publish to https://yam.plus marketplace.

yam plugin create mysql-provisioner

# npm install -g pnpm
# pnpm i
# pnpm run build

butlerwang / yam

YAM