Seira
An opinionated library for building applications on Kubernetes.
This library builds a framework for doing deployments, secrets management, managing and accessing pods, bootstraping new apps and clusters, and more. It makes decisions about how to run the apps and cluster to make managing the cluster easier.
The vision for Seira is to produce a CLI and set of guidelines that makes deploying apps on Kubernetes as easy as Heroku.
What does the name mean?
Following Kubernetes naming pattern, Seira (Seirá) is greek for "order" or "the state of being well arranged".
Installation
Add this line to your application's Gemfile:
gem 'seira'
And then execute:
$ bundle
Or install it yourself as:
$ gem install seira
The gem install seira
option may be preferred for shorter typing, or generating a binstub is also an option.
Usage
This library only currently works with gcloud
and kubectl
, meaning Google Cloud Platform and Kubernetes.
All commands follow a pattern:
seira <cluster> <app> <category> <param1> <param2> <..>
The only exception is commands on the cluster itself, which does not take an <app>
. By making sure to take in a cluster as the first parameter to every command, the intent is to reduce mistake commands on the wrong cluster.
Configuration File
A configuration file is expected at .seira.yml
relative path. Below is an example file.
seira:
organization_id: "11111"
clusters:
internal:
project: org-internal
cluster: gke_org-internal_us-central1-a_internal
region: us-central1
zone: us-central1-b
aliases:
- "i"
staging:
project: org-staging
cluster: gke_org-staging_us-central1-a_staging
region: us-central1
aliases:
- "s"
demo:
project: org-demo
cluster: gke_org-demo_us-central1-a_demo
region: us-central1
aliases:
- "d"
production:
project: org-production
cluster: gke_org-production_us-central1-a_production
region: us-central1
aliases:
- "p"
applications:
- name: app1
golden_tier: "web"
- name: app2
golden_tier: "web"
This specification is read in and used to determine what gcloud
context to use and what kubectl
cluster to use when operating commands. For example, seira internal
will connect to org-internal
gcloud configuration and gke_org-internal_us-central1-a_internal
kubectl cluster. For shorthand, seira i
shorthand is specified as an alias.
Application Configuration Files
Each app can also define configuration files. These files specify details that allow seira to execute commands with minimal user input, and declare aspects of the application. This file lives in the app folder with the name .seira.app.yaml
. An example configuration file:
# The name of the sql instance as it shows in GCP Cloud SQL UI
primary_sql_instance: app-database-name
Regions and Zones
All clusters should have a region
option specified. For zonal clusters (clusters that are NOT regional) should also specify their zone
.
Manifest Files
Seira expects your Kubernetes manifests to exist in the "kubernetes/cluster-name/app-name" directory. When a deploy is run on foo
app in staging
cluster, it looks to kubernetes/staging/foo
directory for the manifest files.
Assumptions
- Each app has all its objects contained in a namespace, named after the app
- Each app has one or more deployments, and a deployment and all pods created by that deployment have a
tier
label matching the name of the deployment - If using a SQL database (currently only postgresql is supported), pgbouncer is used for connection pooling, and the app uses the secret
DATABASE_URL
to connect and authenticate to the database
Initial Setup
In order to use Seira, an initial setup is needed. Use the seira setup
command to set up each of your clusters in your configuration file.
Current Functionality
All functionality is targeted to be a platform on top of Kubernetes that has a Heroku-like experience.
App
- Bootstrap new applications
- Apply new configurations to an application
- Scale app tiers
- Restart an application
Database (Postgres)
- List postgres instances
- Create new primary and automatically set the right secrets with configurability such as HA, CPU, Memory.
- Create a new replica on the primary
- Pgbouncer yaml generation for all new instances
- Delete an instance
Pods
- List pods for a given app
- Connect to a running pod to run commands
- Run a one-off command such as
rails db:migrate
Secrets
- List, set, unset secrets
Example Usage
Running Proxy UI
Easily run a proxy UI (kubectl proxy
) by using seira staging proxy
shorthand.
Applying New Manifest Files
By using seira staging app-name app apply
, Seira will find/replace the string "REVISION" in your manifests with the value in the REVISION
environment variable and apply the new configs to the cluster. If REVISION
is nil, it will ask to use the tag currently being used by the current web
deployment.
Setting Secrets
All secrets are stored in appname-secrets
Secret object. They are expected to be used via envFrom
in manifest files.
seira staging app-name secrets list
seira staging app-name secrets set KEY=value
seira staging app-name secrets get KEY
Pods
Pods can be listed and also exec'd into.
seira staging app-name pods list
seira staging app-name pods connect --pod=<POD-NAME>
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Packages
A Github acions workflow will build and push a new release to Github packages on on new tags. You can cut a new release using ./bin/release
to push a new tag and trigger a release.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/joinhandshake/seira.
Roadmap
Future roadmap has plans for:
- Create CLI help commands and improve general CLI usability
- More functionality for managing pods
- More seamless
seira setup
script
License
The gem is available as open source under the terms of the MIT License.