# yam

**Repository Path**: code2life/yam

## Basic Information

- **Project Name**: yam
- **Description**: Yet Another Application Model - The Simpler Way of Continuous Delivery.
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-02-08
- **Last Updated**: 2022-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center"><a href="javascript:void(0);" target="_blank" rel="noreferrer"><img width="300" src="https://filecdn.code2life.top/yam-icon.png" alt="YAM logo"></a></p>

# YAM

[Yet Another Application Model](https://yam.plus) - The Simpler Way of Continuous Delivery.

- [YAM](#yam)
  - [What's YAM](#whats-yam)
        - [Documentation https://yam.plus](#documentation-httpsyamplus)
  - [Why YAM](#why-yam)
      - [Why separation of concerns is significant](#why-separation-of-concerns-is-significant)
  - [Getting Started](#getting-started)
    - [Prerequisites](#prerequisites)
    - [Step 1. Install YAM-CLI](#step-1-install-yam-cli)
    - [Step 2. Generate Operation Boilerplate](#step-2-generate-operation-boilerplate)
    - [Step 3. Release the App](#step-3-release-the-app)
    - [Other Commands](#other-commands)
  - [Basic Workflow](#basic-workflow)
  - [Comparisons](#comparisons)
    - [Compare to Helm/Kustomize](#compare-to-helmkustomize)
    - [Compare to Pulumi/Terraform](#compare-to-pulumiterraform)
    - [Compare to Open Application Model (OAM)](#compare-to-open-application-model-oam)
      - [What YAM & OAM have in common](#what-yam--oam-have-in-common)
      - [The Differences](#the-differences)
  - [Plugin Development](#plugin-development)

## 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**.

##### Documentation [https://yam.plus](https://yam.plus)

## Why YAM

YAM is inspired by [Open Application Model](https://oam.dev/)(OAM), however, the implementation is **Totally** different from OAM runtime [KubeVela](https://github.com/oam-dev/kubevela). Here are some highlights of YAM.

- ☸ **Operation Lifecycle as Code, EVERYTHING as Code**.
- :ok_person: Focus on **separation of concerns**, **app-centric**, hiding the complexity of the platform.
- :blush: **Extremely easy to use**, it won't take you one minute to bring your application on Kubernetes.
- :zap: **Lightweight and Fast**, NO need for [CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and [Operators](https://github.com/operator-framework)
- :sparkles: 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](https://minikube.sigs.k8s.io/docs/start/), [K3S](https://k3s.io/) 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](https://github.com/Code2Life/yam/releases?q=release&expanded=true).

- Or, **for Linux**

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

**Option 2**. Install by NPM

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

**Option 3**. Install VSCode Extension

Search and install "YAM Engine" in [VSCode marketplace](https://marketplace.visualstudio.com/items?itemName=code2life.yam-engine).

### Step 2. Generate Operation Boilerplate

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

```bash
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:

```yaml
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

```bash
# 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

![](packages/extension/screenshot-output.jpg)

### Other Commands

Rollback or remove the app.

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

Some built-in tools.

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

# portable UI
yam ui
```

## Basic Workflow

<p><a href="javascript:void(0);" target="_blank" rel="noreferrer"><img src="https://filecdn.code2life.top/yam-architecture.drawio.png" alt=""></a></p>

## Comparisons

### Compare to Helm/Kustomize

Limitations of Helm:
1. Helm allows us to customize template, but it can not customize operation workflow or integrate with non-kubernetes systems
2. Helm defines environment related parameters in separate "values" file, it's not flexible enough, especially when there are a dozen of environments
3. 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.
4. 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.

```yaml
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.

```yaml
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.

```bash
yam plugin create mysql-provisioner

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