kmoberg/okctl

Opinionated and effortless infrastructure and application management

okctl - Opinionated and effortless infrastructure and application management

Installation

To download the latest release, run the command matching your operating system:

# Linux
curl --silent --location "https://github.com/oslokommune/okctl/releases/latest/download/okctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/okctl /usr/local/bin

# macOS
brew tap oslokommune/tap
brew install oslokommune/tap/okctl

Getting started

The following is a guide for how to create an environment that contains the elements described in Compare and contrast.

1. Create a new GitHub repository

Go to github.com/oslokommune and create a new private or internal git repository. No credentials are stored in this repository, we want it private as a precaution until we are certain it is safe to have it set as public.

ℹ️ This repository will be used by okctl to store infrastructure-as-code, which means files containing various configuration for your up-and-coming cluster.

Now, run:

# Clone the repository you just made
$ git clone [email protected]:oslokommune/<the new repository>.git
$ cd <the new repository>

2. Create a cluster

A "cluster" is a Kubernetes cluster with many addons and integrations, creating a production grade environment as described in Functionality.

You will soon be running okctl apply cluster, which will ask you for the following information:

• Username and password: This is your Oslo Kommune AD organization username (e.g., oooXXXXX) and its password.
• Multi factor token (MFA): The same one you use to login to AWS. If you haven't set up MFA yet, you can do that here.
• AWS account ID: This identifies which account you want to use. You can see which accounts you have access to just after logging in to AWS:

# Scaffold a cluster. Format:
okctl scaffold cluster -f cluster.yaml
# <edit cluster.yaml>
okctl apply cluster -f cluster.yaml

Follow the instructions.

When done, verify that you have a working cluster by running

$ okctl venv -c cluster.yaml
$ kubectl get service

The last command should show something like

NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.100.0.1   <none>        443/TCP   1h

Common commands

# Get help for any command
$ okctl --help

# Show credentials for cluster
$ okctl show credentials -c cluster.yaml

# Run a sub shell with environment variables from the above command and a custom command prompt (PS1)
$ okctl venv -c cluster.yaml

# Delete the cluster
$ okctl delete cluster -c cluster.yaml

Functionality

The core cluster is up and running, and we are currently working on building a seamless experience on top of this cluster with integrations for common functionality:

Core cluster

• ExternalSecrets for storing secrets securely
• AWS Load Balancer Controller creates load balancers for incoming traffic
• ExternalDNS ensures humane DNS hostnames
• Autoscaler for adjusting the size of pods and nodes
• Argo CD gives us continuous delivery
• Kubernetes Prometheus for prometheus and grafana
• Amazon Elastic Block Store (EBS) CSI driver for block storage
• Loki for processing logs
• Tempo for processing traces
• Promtail for collecting logs

Application lifecycle

• Postgres for creating and integrating a postgres database with your application
• Amazon Elastic Container Registry for creating and assisting with the publication of container images for use in the cluster
• Reference application that demonstrates how to use the cluster and its integrations

Compare and contrast

The intended purpose of okctl is to be an opinionated solver of infrastructure problems, this includes setting up CI/CD pipelines et al.

The following table is not present to determine what tool is better or worse, but rather how these tools compare to okctl and the problems we are focused on solving.

	okctl	eksctl	kubectl	serverless.tf
Defines a CI/CD scheme	✅	❌	❌	❌
Creates a Kubernetes cluster	✅	✅	❌	❌
Facilitates with application creation	✅	❌	❌	✅
Integrates with Github (actions, packages, oauth)	✅	❌	❌	❌
Sets up monitoring	✅	❌	❌	❌

Inspiration

We have begged, borrowed and stolen various ideas from the following CLIs:

• https://github.com/deislabs/porter
• https://github.com/weaveworks/eksctl
• https://github.com/kubernetes/kops
• https://kubernetes.io/docs/tasks/tools/install-kubectl/
• https://github.com/go-kit/kit
• https://github.com/Versent/saml2aws/