anemos

Anemos

Anemos is a single-binary CLI tool written in Go and designed to simplify the management of Kubernetes manifests. It bundles Goja JavaScript runtime and lets you define your manifests using JavaScript and TypeScript, enabling you to leverage the full power of the language to generate and manipulate Kubernetes YAML manifests.

Anemos uses JavaScript package management system. You can distribute your libraries as npm packages, use other Anemos packages, or any other JavaScript library, and take advantage of the vast ecosystem of tools available in the JavaScript community.

Anemos provides you an SDK for both template based and programmatic generation of Kubernetes manifests. JavaScript's template literals allow you to write clean and readable templates and libraries such as kubernetes-models provide type safety and better IDE experience. You can also mix and match templates and programmatic generation, use the best approach for each part of your manifest.

Anemos also supports node based modification of YAML manifests. This powerful feature enables you to modify any YAML manifest without waiting for the package maintainers to add support for your use case or fix a bug in the package. It also allows you to modify manifests in bulk, making it easy to apply changes across multiple manifests.

Installation

Anemos is a single binary that can be downloaded from the GitHub releases page. Get the latest version and place it in your PATH and you are ready to go.

Docs

You can visit documentation for more information on how to use Anemos, including examples, tutorials, and API references.

Quick Start

Simplest way to get started with Anemos is to create an index.js file and run it with anemos build index.js:

const anemos = require("@ohayocorp/anemos");
const helloWorld = require("https://anemos.sh/examples/hello-world.js");

const builder = new anemos.Builder("1.31", anemos.KubernetesDistribution.Minikube, anemos.EnvironmentType.Development);

helloWorld.add(builder, {
    replicaCount: 2,
});

builder.addDocument(
    `pod.yaml`,
    `
    apiVersion: v1
    kind: Pod
    metadata:
      name: nginx
    spec:
      containers:
        - name: nginx
          image: nginx
          ports:
            - containerPort: 80
    `);

builder.build();

This will generate an output directory containing the Kubernetes manifests generated by the package from https://anemos.sh/examples/hello-world.js and pod.yaml that we defined in the code.

Using Anemos Packages

Following example will use the @ohayocorp/anemos-hello-world package to generate a simple deployment:

const anemos = require("@ohayocorp/anemos");
const helloWorld = require("@ohayocorp/anemos-hello-world");

const builder = new anemos.Builder("1.32", anemos.KubernetesDistribution.Minikube, anemos.EnvironmentType.Development);

helloWorld.add(builder, {
    name: "custom-hello-world",
    autoScaling: {
        minReplicas: 1,
        maxReplicas: 3,
    },
    ingress: {
        host: "hello-world.local",
    },
});

builder.build();

Run following command to install the package and generate the manifests:

anemos package add @ohayocorp/anemos-hello-world
anemos build index.js

It is also possible to use local JavaScript files and URLs for easy sharing. See the documentation for more details.

Applying Manifests

Anemos can apply the generated manifests to a Kubernetes cluster. You can use the anemos apply <package> command to apply a package directly. This command will compute the diff between the current state of the cluster and the manifests generated by the package, print the changes, and apply them if you confirm. It can also take a YAML file as input to override the default values in the package.

anemos apply --yes https://anemos.sh/examples/hello-world.js -f - <<EOF
replicaCount: 3
EOF

Example output:

[09:44:11.880] INFO: Starting to build documents
[09:44:11.881] INFO: Applying actions for step: '2' - Sanitize
[09:44:11.881] INFO: Applying actions for step: '5' - Generate resources
[09:44:11.883] INFO: Applying actions for step: '100' - Apply
[09:44:11.883] INFO: Summary of changes:
[09:44:11.883] INFO: OP  NAMESPACE  RESOURCE
[09:44:11.883] INFO: A   default    deployments/anemos-hello-world
[09:44:11.883] INFO: A   default    services/anemos-hello-world
[09:44:11.948] INFO: Successfully applied Kubernetes manifests

Or use the anemos build --apply <js-file> command to build and apply all manifests defined in the JavaScript file:

anemos build --apply index.js

There are also commands to list the apply sets and delete them:

anemos apply list
anemos apply delete <apply-set-id>

See the documentation for more details on how to apply manifests.

Contributing

We welcome contributions to Anemos! If you have an idea for a new feature, a bug fix, or an improvement, please open an issue or a pull request on our GitHub repository.

To build Anemos from source, clone the repository and run the following commands:

./download-bun.sh
go build ./cmd/anemos