Skip to content

MetaCell/cloud-harness

Repository files navigation

drawing

CloudHarness is a base infrastructure facilitator for microservice based applications deployed primarily on Kubernetes. Can scaffold and maintain your cloud solution on top of Cloudharness without writing Kubernetes templates, with in place common utilities and applications already configured for you.

What building your cloud solution with CloudHarness gives to you:

  • Common framework and utilities to develop and deploy micro-service application
    • Helm chart automatic generation
      • deployments
      • services
      • ingress configuration
      • databases
      • backup cron jobs
      • access gatekeepers configuration
      • secrets
      • templated config maps from files
    • Docker compose configuration generation
      • services
      • traefik configuration
      • databases (postgreql)
      • access gatekeepers configuration
      • secrets and configmaps
    • Automatic build and push of images
    • REST-API scaffolding building based on OpenApi
    • Continuous deployment script generation
    • Debug backend applications running on Kubernetes
    • Python cluster access utilities
  • Prebuilt support applications and shared library to:
    • Log in and user management - based on Keycloak
    • Submit batch and asynchronous workflows - based on Argo
    • Orchestrate microservices - based on Kafka
    • Assign compute workspaces to users - based Jupyterhub
  • Testing framework to help you write and run tests
    • Unit tests
    • API integration tests
    • End to End tests (with Puppeteer)
  • CI/CD pipelines generation

Why CloudHarness?

The microservice architecture is a great to get code separation and flexible development, but may not be of easy implementation, especially for small development teams/projects. In particular, these questions may rise:

  • How do I create a deployment for my microservices?
  • How do I orchestrate my microservices?
  • How to create consistent api documentation?
  • Do I need to be an experienced devops to create a micro-service based application?
  • Wouldn't it be nice to develop a plain database/backend/frontend application without infrastructure boilerplate but still be able to configure everything I want when needed?
  • How to run batch operations like ETL processes easily and efficiently in a cloud environment?
  • How to manage databases without being locked to a specific vendor solution?
  • How to perform database backups?
  • How to manage secret data?
  • What about having a precounfigured account management application?
  • Sooner rather than later I'll need an orchestration queue. Why not have that just ready to use?

Command line tools

CloudHarness provides the following command line tools to help application scaffolding and deployment.

  • harness-deployment - generate the helm chart to deploy on Kubernetes.
  • harness-application - create a new CloudHarness REST application.
  • harness-generate - generates server and client code for all CloudHarness REST applications.
  • harness-test - run end to end tests

Get started

Prerequisites

Operative system

Cloudharness can be used on all major operative systems.

  • Linux: supported and tested
  • MacOS: supported and tested
  • Windows/WSL2: supported and tested
  • Windows native: mostly working, unsupported

Python

Python 3.9 must be installed.

It is recommended to setup a virtual environment. With conda:

conda create --name ch python=3.12
conda activate ch

Docker

Docker is required to build locally.

Kubernetes command line client

kubectl allows you to connect to your Kubernetes cluster or local environment.

Helm

Helm is required to deploy to your Kubernetes cluster or local environment.

Skaffold

Skaffold is the way to go to build and debug your application in your local development environment.

Docker compose

Docker Compose is required if the docker compose system is the target (instead of Kubernetes).

Node environment

A node environment with npm is required for developing web applications and to run end to end tests.

Recommended:

  • node >= v14.0.0
  • npm >= 8.0.0

Java Runtime Environment

A JRE is needed to run the code generators based on openapi-generator.

For more info, see here.

CloudHarness command line tools

To use the cli tools, install requirements first:

bash install.sh

Generate deployment

To generate a deployment, run harness-deployment. See below for more.

Create new REST application

To create a new REST application, run harness-application from the root of your solution.

Generate server and client code from openapi

To (re)generate the code for your applications, run harness-generate from the root. The script will look for all openapi applications, and regenerate the Flask server code and documentation. Note: the script will eventually override any manually modified file. To avoid that, define a file openapi-generator-ignore.

Extend CloudHarness to build your project

CloudHarness is born to be extended.

The quickest way to start is to install Cloud Harness, copy the blueprint folder and build from that with the cli tools, such as harness-application, harness-generate, harness-deployment.

See the developers documentation for more information.

Build and deploy

The script harness-deployment scans your applications and configurations to create the build and deploy artifacts. Created artifacts include:

  • Helm chart (or docker compose configuration file)
  • Skaffold build and run configuration
  • Visual Studio Code debug and run configuration
  • Codefresh pipeline yaml specification (optional)

With your project folder structure looking like

applications
deployment-configuration
infrastructure
cloud-harness

run

harness-deployment cloud-harness . [PARAMS]

to create the build and deployment artifacts for your solution. See the dedicated Build and deploy document for more details and examples.

Add and manage applications

Any Dockerfile added in a subfolder below the applications directory is interpreted as an application part of the deployment. The harness-application cli tool creates new applications from predefinite code templates. See the dedicated Applications documents for more details and examples.

Configure the deployment

First, create the folder deployment-configuration on project level.

Then, you can selectively add files related to configuration that you want to personalize:

  • values-template.yaml: base for helm/<chart-name>/values.yaml. Modify this file to add values related to new infrastructure elements not defined as an application
  • value-template.yaml: cloud-harness application configuration inside values.yaml. Prefer adding a custom values.yaml to your application over changing this file.
  • codefresh-template-dev.yaml: base for codefresh/codefresh-dev.yaml. Modify this file if you want to change the build and deploy steps in the codefresh dev pipeline
  • codefresh-template-prod.yaml: base for codefresh/codefresh-prod.yaml. Modify this file if you want to change the deploy and publish steps in the codefresh production pipeline. The production pipeline is meant to reause the same set of images from a previously completed dev pipeline.
  • codefresh-build-template.yaml: base for a single build entry in codefresh.yaml

For more information about how to configure a deployment, see here

Codefresh build status