Cluster.dev is an open-source system delivered as GitHub Action or Docker Image for creating and managing Kubernetes clusters with simple manifests by GitOps approach.
Designed for developers that are bored to configure Kubernetes stuff and just need: kubeconfig, dashboard, logging and monitoring and deployment systems out-of-the-box.
GitOps infrastructure management with Terraform and continuous deployment with ArgoCD. Easily extendable by pre-configured applications and modules. Quick integration with Jenkins, GitLab or other CI/CD systems. Supports multiple Cloud Providers and Kubernetes versions.
Principle diagram ↑
Small and understandable yaml definition:
cluster:
installed: true
name: develop
cloud:
provider: aws
region: eu-central-1
vpc: default
domain: cluster.dev
provisioner:
type: minikube
instanceType: m5.large
modules:
nginx-ingress: true
cert-manager: true
apps:
- /kubernetes/apps/samples
cluster.dev
turns into powerful ready to use infrastructure in code:
How it works ↑
In background:
- Terraform creates a "state bucket" in your Cloud Provider account where all infrastructure objects will be stored. Typically it is defined on Cloud Object Storage like AWS S3.
- Terraform modules create Minikube/EKS/GKE/etc.. cluster, VPC and DNS zone within your Cloud Provider.
- ArgoCD Continuous Deployment system is deployed inside Kubernetes cluster. It enables you to deploy your applications from raw manifests, helm charts or kustomize yaml's.
- GitHub CI runner is deployed into your Kubernetes cluster and used for your apps building CI pipelines with GitHub Actions.
You receive:
- Automatically generated kubeconfig, ssh-access, and ArgoCD UI URLs
- Configured: Ingress Load Balancers, Kubernetes Dashboard, Logging(ELK), Monitoring(Prometheus/Grafana)
Installation ↑
Quick Start on AWS ↑
normally it takes 15 minutes
- Dedicate a separate repository for the infrastructure code that will be managed by
cluster.dev
.
This repo will host code for your clusters, deployments, applications and other resources.
Clone the repo locally:
$ git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY
$ cd YOUR-REPOSITORY
Next steps should be done in that repo.
- Create credentials for your non-root cloud user account.
In AWS you need to use the existing or create the new ones "Programmatic Access user".
Required Managed policies: AmazonEC2FullAccess, AmazonS3FullAccess, AmazonRoute53FullAccess, AmazonDynamoDBFullAccess, IAMFullAccess, AmazonEC2ContainerRegistryReadOnly, ElasticLoadBalancingFullAccess, or you can add permissions using this iam-json.
Resulting access pair should look like:
aws_access_key_id = ATIAAJSXDBUVOQ4JR
aws_secret_access_key = SuperAwsSecret
-
Add credentials to you repo Secrets under GitHub's repo setting:
Settings → Secrets
: -
In your repo, create a Github Workflow file: .github/workflows/main.yml and
cluster.dev example manifest: .cluster.dev/minikube-one.yaml with cluster definition.
Or download example files to your local repo clone using the next commands:
# Sample with Minikube cluster
export RELEASE=v0.1.5
mkdir -p .github/workflows/ && wget -O .github/workflows/main.yml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/docs/quick-start/aws/github-workflow.yaml"
mkdir -p .cluster.dev/ && wget -O .cluster.dev/minikube-one.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/docs/quick-start/aws/minikube-cluster-definition.yaml"
-
In cluster definition yaml you should set your own Route53 DNS zone. If you don't have any hosted public zone you can create it manually with instructions from AWS Website.
-
You can change all other parameters or leave default values in cluster.yaml .
Leave github workflow file as is. -
Copy sample ArgoCD applications from /kubernetes/apps/samples and Helm chart samples from /kubernetes/charts/wordpress to the same paths into your repo.
Or download application samples directly to local repo clone with commands:
export RELEASE=v0.1.5
# Create directory and place ArgoCD applications inside
mkdir -p kubernetes/apps/samples && wget -O kubernetes/apps/samples/helm-all-in-app.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/apps/samples/helm-all-in-app.yaml"
wget -O kubernetes/apps/samples/helm-dependency.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/apps/samples/helm-dependency.yaml"
wget -O kubernetes/apps/samples/raw-manifest.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/apps/samples/raw-manifest.yaml"
# Download sample chart which with own values.yaml
mkdir -p kubernetes/charts/wordpress && wget -O kubernetes/charts/wordpress/Chart.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/charts/wordpress/Chart.yaml"
wget -O kubernetes/charts/wordpress/requirements.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/charts/wordpress/requirements.yaml"
wget -O kubernetes/charts/wordpress/values.yaml "https://raw.githubusercontent.com/shalb/cluster.dev/${RELEASE}/kubernetes/charts/wordpress/values.yaml"
Define path to ArgoCD apps in cluster manifest:
apps:
- /kubernetes/apps/samples
-
Commit and Push files to your repo and follow the Github Action execution status.
In GitHub action output you'll receive access instructions to your cluster and services:
-
Voilà! You receive GitOps managed infrastructure in code. So now you can deploy applications, create more clusters, integrate with CI systems, experiment with the new features and everything from Git don't leaving your IDE.
Cleanup ↑
For shutdown cluster and remove all associated resources:
- Open
.cluster.dev/
directory in your repo. - In each manifest set
cluster.installed
tofalse
- Commit and push changes
- Open Github Action output for see removal status
After successful removal, you can safely delete cluster manifest file from .cluster.dev/
directory.
Technical diagram ↑
Roadmap ↑
The project is in Alpha Stage. Roadmap details: docs/ROADMAP.md
Contributing ↑
If you want to spread the project with your own code, you could start contributing with this quick guide: docs/CONTRIBUTING.md