The SolSA library for Node.js makes it possible to specify the architecture of Kubernetes applications as programs.
SolSA enables developers to configure Kubernetes-managed resources by writing JavaScript or TypeScript code instead of YAML. SolSA automatically translates the developer written code to the required lower-level YAML. SolSA integrates with IDEs such as Visual Studio Code to provide online validation, code completion, and documentation of the various resources and configuration parameters. SolSA enables the definition of architectural patterns (bundles of resources) that can be used across many applications.
Thanks to Kubernetes operators, Kubernetes applications can include not only containerized services but also managed cloud services (using for instance the IBM Cloud Operator), cloud functions (using the IBM Cloud Functions Operator), Knative services and events, etc.
While SolSA is meant to facilitate application development and deployment on the IBM Cloud and supports a few IBM-specific services out of the box, the SolSA programming model and library implementation is intended to work with any Kubernetes cluster and any cloud. No IBM Cloud account required.
SolSA is an open-source project with an Apache 2.0 license. We welcome contributions!
Kubernetes is becoming the de facto standard for managing applications in the cloud. While YAML is a fine language to perform some basic configuration, we believe application developers need to reason about applications at a higher-level of abstraction using the languages and tools they are familiar with.
Developers can use SolSA to configure Kubernetes resources using JavaScript or
TypeScript instead of YAML. But SolSA is not just a syntax. SolSA supports
bundling together resources into reusable abstractions that expose curated
configuration parameters. For instance, SolSA offers a ContainerizedService
bundle that combines a Deployment and a Service, automatically bridging the
two by means of auto-generated labels and selectors.
SolSA bundles can be smart and vary their content based on context. In
particular, SolSA leverages
Kustomize to permit targeting
multiple environments, e.g., a local development cluster, a Red Hat OpenShift on
IBM Cloud cluster, or an IBM Cloud Kubernetes Service cluster. SolSA
automatically tailors resource bundles such as Ingress to the specifics of
each targeted environment.
SolSA can synthesize all the YAML needed to deploy an application. But it does not have to do so. SolSA supports easy configuration to select which resources should be unique to an application instance and which resources should be shared across multiple instances.
SolSA facilitates the configuration of related resouces for instance a Kafka instance, a Kafka topic, and a Knative Kafka event source, by automatically reusing relevant configuration information. SolSA can not only inject configuration information from one resource into another during YAML generation but also, if necessary, during deployment using the Composable Operator. Using this operator, SolSA can for example configure a Kafka source to dynamically obtain a list of broker urls from a Kafka instance deployed at the same time.
SolSA generates pure Kubernetes YAML that can be deployed at once, i.e., with a
single kubectl apply command. SolSA does not need a server-side
component.
SolSA includes an optional capability to containerize Node.js code. This facilitates the integration of components that require a little bit of glue code to interface properly, e.g., to align schemas or match protocols. This glue code can leverage Node.js frameworks such as Express or KafkaJS. SolSA builds and pushes the container image in addition to synthesizing the YAML to instantiate the image with the proper configuration.
SolSA consists of:
- A
solsaNode.js module that makes it possible to configure using JavaScript or TypeScript:- all the standard Kubernetes resources,
- custom resources supported by a growing set of operators,
- resource bundles that provide high-level abstractions of key architectural patterns.
- A
solsacommand-line interface (CLI):solsa buildbuilds container images for SolSA-defined services (if any).solsa pushpushes container images for SolSA-defined services (if any).solsa yamlsynthesizes YAML for deploying SolSA solutions on Kubernetes.
SolSA supports Node.js 8 and above, Kubernetes 1.14 and above.
The easiest way to use SolSA is to install it globally. Run the following command:
npm install -g solsaThis will add the SolSA CLI to your PATH. This will also download kustomize on
supported platforms (darwin x86_64 and linux x86_64). On other platforms,
please install kustomize per Kustomize's install
instructions
and adjust your PATH to include it.
Try the CLI:
solsaUsage:
solsa <command> [flags]
Available commands:
build <solution.js> build container images
push <solution.js> push container images to registries for current kubernetes context
yaml <solution.js> synthesize yaml for current kubernetes context
Global flags:
--cluster <cluster> use <cluster> instead of current kubernetes cluster
--config <config> use <config> file instead of default
-c, --context <context> use <context> instead of current kubernetes context
-d, --debug output a stack trace on error
Flags for "yaml" command:
-o, --output <file> output base yaml and context overlays to <file>.tgz
While a global install is enough to use the SolSA CLI, we recommend you also link SolSA from your home directory:
cd
npm link solsaThis will ensure that IDEs such as Visual Studio Code can locate the SolSA module and provide an optimal developer experience with code completion and hover help.
Install SolSA locally for use in a single project.
npm install solsaThis will install SolSA as a dependency to your current project
(package.json). This will also download kustomize on supported platforms
(darwin x86_64 and linux x86_64). On other platforms, please install
kustomize per Kustomize's install
instructions
and adjust your PATH to include it.
Typically, a local install does not add the SolSA CLI to the PATH. To run the CLI use:
$(npm bin)/solsaUsage:
solsa <command> <solution> [flags]
Available commands:
build <solution> build container images
push <solution> push container images to registries for current kubernetes context
yaml <solution> synthesize yaml for current kubernetes context
Global flags:
--cluster <cluster> use <cluster> instead of current kubernetes cluster
--config <config> use <config> file instead of default
-c, --context <context> use <context> instead of current kubernetes context
-d, --debug output a stack trace on error
Flags for "yaml" command:
-o, --output <file> output base yaml and context overlays to <file>.tgz
-a, --appname <name> add the label solsa.ibm.com/app=<name> to all generated resources
To contribute to the development of SolSA, you will need to clone this repository, install, build, and link SolSA:
git clone https://github.com/IBM/solsa.git
cd solsa
npm install
npm run build
npm linkTo use your local SolSA checkout in other projects run in each project:
npm link solsaWe assume that you have already configured kubectl or oc to be able to
access each Kubernetes cluster you will be using with SolSA.
We assume that you have already installed kustomize. If not, please install it
per Kustomize's install
instructions
and adjust your PATH to include it.
Proper configuration of kubectl/oc and kustomize is sufficient to enable
you to use SolSA to generate YAML for all core Kubernetes resource types.
If you intend to use SolSA to define solutions that include advanced features such as configuring cloud services or Knative resources, you will need to install the necessary Operators. On each cluster, do the following:
-
Install the Composable Operator from https://github.com/IBM/composable.
-
Install the IBM Cloud Operator from https://github.com/IBM/cloud-operators.
-
Install the IBM Event Streams Topic Operator from https://github.com/IBM/event-streams-topic.
-
Install the IBM Cloud Functions Operator from https://github.com/IBM/cloud-functions-operator.
If you intend to use SolSA to define solutions that include Knative resources, you will need a cluster with Knative installed. For example, if you are using a cluster provisioned via the IBM Cloud Kubernetes Service, follow the instructions at https://knative.dev/docs/install/knative-with-iks.
You can optionally create a .solsa.yaml file in your home directory that
describes each Kubernetes context for which you want SolSA to generate a
specialized Kustomize overlay. Just like kubectl, solsa supports both
cluster-level and context-level specification.
The configuration information in sosla.yaml enables cluster-specific and/or
context-specific generation of Ingress resources and container image rewrites
such as switching default registries or image tags.
Please refer to the full
documentation of
.solsa.yaml for full details, including ingress specifications for a variety
of kinds of Kubernetes clusters. Shown below is a basic .solsa.yaml file that
enables sosla to target the Kubernetes v1.14 cluster included in Docker
Desktop v2.1.
clusters:
- name: 'docker-desktop'
ingress:
nodePort: trueWe will assume this configuration file in the following example.
A sample SolSA solution is provided in helloWorld.js.
const solsa = require('solsa')
module.exports = new solsa.ContainerizedService({ name: 'hello-world', image: 'docker.io/ibmcom/kn-helloworld', port: 8080, ingress:true })It consists of a single containerized service which when deployed will be exposed via an ingress.
This solution can be deployed to the current Kubernetes context using the
solsa CLI and either kubectl or oc as follows.
solsa yaml helloWorld.js | kubectl apply -f -The YAML synthesized by SolSA for this example depends on the SolSA configuration file used. If no configuration file is used, the ingress request is ignored and the CLI outputs a warning message.
Assuming the configuration file provided in the previous section, the YAML
synthesized when targeting cluster docker-desktop is
helloWorld.yaml.
In this configuration, SolSA synthesizes Service objects with type NodePort
for all the exposed service. Moreover, port numbers are assigned dynamically. We
can obtain the port number for the deployed hello-world service using command:
kubectl get service hello-world -o jsonpath={.spec.ports[0].nodePort}31509
Assuming 1.2.3.4 is the public IP of one of the worker node of the targeted
Kubernetes cluster, we can then query the deployed containerized service using
curl:
curl 1.2.3.4:31509Hello World!
To undeploy the solution, use the command:
solsa yaml helloWorld.js | kubectl delete -f -The solsa-examples repository contains other examples of cloud-native applications, services, and architectural patterns defined using SolSA.
In order to build and deploy solutions that include SolSA-defined services, run:
solsa build mySolution.js
solsa push mySolution.js
solsa yaml mySolution.js | kubectl apply -f -The build command builds images for the SolSA-defined services. The push
command tags and pushes these images according to the SolSA configuration for
the current Kubernetes context.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent