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".
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install seira
gem install seira option may be preferred for shorter typing, or generating a binstub is also an option.
This library only currently works with
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.
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
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.
- 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
tierlabel 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_URLto connect and authenticate to the database
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.
All functionality is targeted to be a platform on top of Kubernetes that has a Heroku-like experience.
- Bootstrap new applications
- Apply new configurations to an application
- Scale app tiers
- Restart an application
- 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
- List pods for a given app
- Connect to a running pod to run commands
- Run a one-off command such as
- List, set, unset secrets
Running Proxy UI
Easily run a proxy UI (
kubectl proxy) by using
seira staging proxy shorthand.
Applying New Manifest Files
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
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 can be listed and also exec'd into.
seira staging app-name pods list
seira staging app-name pods connect --pod=<POD-NAME>
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/joinhandshake/seira.
Future roadmap has plans for:
- Create CLI help commands and improve general CLI usability
- More functionality for managing pods
- More seamless
The gem is available as open source under the terms of the MIT License.