⚠️ This is a work in progress. Don't attempt to use it for anything except developing Exekube (or inspiration).

Exekube

Exekube is a declarative "Infrastructure as Code" framework for administering Kubernetes clusters and deploying containerized software onto them. Exekube offers you full control over your infrastructure and container orchestration while also having a great default state with a one-click experience.

Here is a quick example of how you'd deploy CI tools using Exekube:

# ------------------------------------------------------------------------------
# live/prod/kube-ci/inputs.tfvars | HCL (HashiCorp Configuration Language) / Terraform
#
# modules/kube-ci v0.1.0 (Exekube built-in Terraform module)
#
# This is the "client side" of a Terraform module. You simply supply values for a Kubernetes Helm chart and pick a domain name for your app.
# ------------------------------------------------------------------------------

jenkins = {
  enabled     = true
  values_file = "values/jenkins.yaml"
  domain_name = "ci.example.com"
}

chartmuseum = {
  enabled     = true
  values_file = "values/chartmuseum.yaml"
  domain_name = "charts.example.com"

  # export TF_VAR_chartmuseum='{ username = "$()", password = "$()" }'
}

docker_registry = {
  enabled     = true
  values_file = "values/docker-registry.yaml"
  domain_name = "r.example.com"

  # export TF_VAR_docker_registry='{ username = "$()", password = "$()" }'
}

Introduction

You only need Docker CE and Docker Compose on your local machine to begin using Exekube. The framework is a thin layer on top of several open-source DevOps tools:

Docker Compose (for our local development environment)
Terraform, Terragrunt, and HCL (HashiCorp Language)
Kubernetes
Helm

Exekube allows you to manage both cloud infrastructure resources and Kubernetes resources using a git-based workflow with a continuous integration (CI) pipeline.

📘 Read the companion guide: https://github.com/ilyasotkov/learning-kubernetes/

Introduction
Design principles
Setup and usage
Feature tracker

Design principles

Everything on client side runs in a Docker container
Infrastructure (cloud provider) objects and Kubernetes API objects are expressed as declarative code, using HCL (HashiCorp Language) and Helm packages (YAML + Go templates)
Modular design
Git-based workflow with a CI pipeline [TBD]
No vendor lock-in, choose any cloud provider you want [only GCP for now]
Test-driven (TDD) or behavior-driven (BDD) model of development [TBD]

Setup and usage

Requirements starting from zero

The only requirements, depending on your local OS:

Linux

macOS

Docker for Mac

Windows

Docker for Windows

Usage step-by-step

Cloud provider setup: do it once

Create xk (stands for "exekube") alias for your shell session (or save to ~/.bashrc):
```
alias xk=". .env && docker-compose run --rm exekube"
```
Set up a Google Account for GCP (Google Cloud Platform), create a project named ${TF_VAR_gcp_project}, and enable billing.
Create a service account in GCP Console GUI, give it project owner permissions.
Download JSON credentials ("key") to repo root directory and rename the file to credentials.json.

Use JSON credentials to authenticate our gcloud client tool:

xk gcloud auth activate-service-account --key-file credentials.json

Create Google Cloud Storage bucket (with versioning) for our Terraform remote state:

xk gsutil mb \
        -p ${TF_VAR_gcp_project} \
        gs://${TF_VAR_gcp_remote_state_bucket} \
&& xk gsutil versioning set on \
        gs://${TF_VAR_gcp_remote_state_bucket}

Cluster setup: do it as often as you need

Edit code in live and modules directories:

[TODO] Guide to Terraform / Terragrunt, HCL, and Exekube directory structure

Deploy all live modules (the cluster and all Kubernetes resources):

# Edit $XK_LIVE_DIR environmental variable in docker-compose.yaml to change the what the `apply` command deploys
xk plan
xk apply

# To make the cluster dashboard available at localhost:8001/ui, run
docker-compose up -d
# To disable local dashboard, run `docker-compose down`

Cleanup

xk destroy

Workflows

Legacy imperative workflow (CLI)

⚠️ These tools are relatively mature and work well, but are considered legacy here since this framework aims to be declarative

Command line tools kubectl and helm are known to those who are familiar with Kubernetes. gcloud (part of Google Cloud SDK) is used for managing the Google Cloud Platform.

xk gcloud
xk kubectl
xk helm

Examples:

xk gcloud auth list

xk kubectl get nodes

xk helm install --name custom-rails-app \
        -f live/prod/kube-custom/values/rails-app.yaml \
        charts/rails-app

Declarative workflow (.tf and .tfvars files)

xk apply
xk destroy

Declarative tools are exact equivalents of the legacy imperative (CLI) toolset, except everything is implemented as a Terraform provider plugin and expressed as declarative HCL (HashiCorp Language) code. Instead of writing CLI commands like xk helm install --name <release-name> -f <values> <chart> for each individual Helm release, we install all releases simultaneously by running xk apply.

Feature tracker

Features are marked with ✔️ when they enter the alpha stage, meaning a minimum viable solution has been implemented

Cloud provider and local environment setup

Create GCP account, enable billing in GCP Console (web GUI)
Get credentials for GCP (credentials.json)
Authenticate to GCP using credentials.json (for gcloud and terraform use)
Enable terraform remote state in a Cloud Storage bucket

Cloud provider config

Create GCP Folders and Projects and associated policies
Create GCP IAM Service Accounts and IAM Policies for the Project

Cluster creation

Create the GKE cluster
Get cluster credentials (/root/.kube/config file)
Initialize Helm

Cluster access control

Add cluster namespaces (virtual clusters)
Add cluster roles and role bindings
Add cluster network policies

Supporting tools

Install cluster ingress controller (cloud load balancer)
Install TLS certificates controller (kube-lego)
Install Continuous Delivery tools
- Continuous delivery service (Drone / Jenkins)
- Helm chart repository (ChartMuseum)
- Private Docker registry
- Git service (Gitlab / Gogs)
Monitoring and alerting tools (Prometheus / Grafana)

User apps and services

Install "hello-world" apps like static sites, Ruby on Rails apps, etc.

alexxnica / exekube Goto Github PK

exekube's Introduction