Psykube    a faster way to deploy to Kubernetes!  

What is Psykube? | Installation | The Psykube YAML | Cluster Assumptions | Getting Started | Playground | Commands

What is Psykube?

Kubernetes is a powerful system, but it comes with its own learning curve. To deploy a single application you have to come familiar with a set of concepts. For example a single hello world application may be comprised of a Deployment, Service, and Ingress manifest file. Psykube aims to make that simpler by unifying your applications configuration into a single file.

For the above example you may expect something like this in the .psykube.yml file.

psykube.yml

name: hello-world
registry_user: johndoe
ports:
  http: 8080
  ingress:
    tls: true
    host: hello-world.example.com

Installation

Pre-requirements

• kubectl installed on your system.
• docker installed on your system.
• git installed on your system.

Using Homebrew for OSX

You can install psykube on OSX using homebrew by running:

brew install commercialtribe/tools/psykube

Binaries

You can also download the pre-built binaries.

Versions

The Major, Minor, and Patch components of the version match the kubectl version used by Pyskube. The fourth component tracks the Psykube specific release. Click here for a list of versions.

The Psykube YAML

A .psykube.yml is required in the root for each app. This can be overridden with the -f or --file flag on any command.

Template Variables

The .psykube.yml allows for expanding variables using the {{var.name}} template syntax. The following variables are available within the template:

Var	Description
metadata.namespace	The namespace provided with the --namespace flag on the command.
metadata.cluster_name	The name of the cluster.
metadata.name	The name of the application.
env.{name}	An environment variable referenced by name.
git.branch	The current git branch.
git.tag	The current git tag.
git.sha	The current git sha.

Example Variable Usage

ingress:
  host: {{metadata.namespace}}.k8s.example.com

Reference

You can find a detailed example of the .psykube.yml in reference/.psykube.yml More examples can be found in the example dir.

Cluster Assumptions

Psykube works best with a certain kubernetes setup.

1. A cluster running that latest kubernetes.
2. An ingress controller.
3. kube-lego controller installed for automatic TLS.

Getting Started

Before you start...
We make reference to Kubernetes documentation in this README, this is only for reference, Psykube's main purpose is to abstract away the complexity of writing and maintaining the file manifests needed to deploy applications to Kubernetes. As you start learning about the Kubernetes objects we reference you can be rest assured that psykube will be generating all these files for you. (you can see how .psykube.yml files translate by checking our the playground)

Generating the .psykube.yml file

To get started with psykube you can run the psykube init command. You can then edit the .psykube.yml file generated in the current directory.

name: hello-world
registry_user: johndoe

If an application (without exposing it as a service) is all you need, you can stop here and go straight to deploying-an-application, or continue for more detail.

Exposing an application as a service

While it's great to have an application deployed to Kubernetes, you cannot actually interact with it unless it exposes a Kubernetes Service. In order to do this all we have to do is assign ports, the port you specify will become both the container port and the service port. Once you add a port your .psykube.yml should now look like this:

name: hello-world
registry_user: johndoe
ports:
  http: 8080

More advanced service customization.

You also have the option of doing more advance service customization by using the service object. For example, you may want to change the type of the service to be a LoadBalancer or Headless service rather than the default ClusterIP. For example, if you wanted to make the service a LoadBalancer, which exposes it with an external IP, you would do the following.

name: hello-world
registry_user: johndoe
service:
  type: LoadBalancer
ports:
  http: 8080

If an application and service is all you need, you can stop here and go straight to deploying-an-application, or continue for more detail.

Allocating an application's ingress records

Sometimes you want more than an internal service, and you may not want to just expose your service as a LoadBalancer. This is where ingress comes into play. If your cluster has an ingress controller, then it will make use of the Kubernetes Ingress records generated by the global and cluster ingress objects. Ingress, requires for the application to have an exposed service. The simplest ingress may just include a single hostname:

name: hello-world
registry_user: johndoe
service:
  type: LoadBalancer
ports:
  http: 8080
ingress:
  host: my-app.com

Ingress TLS

In addition to a hostname you may want to add TLS/HTTPS to your ingress. By setting tls: true in your ingress object, psykube will auto-generate a secret_name for your certificate and add an annotation to allow for kube-lego to generate a free SSL certificate using Let's Encrypt.

Advanced ingress rules

If the ingress of your application requires more customization you can use the hosts and tls objects:

name: hello-world
registry_user: johndoe
service:
  type: LoadBalancer
ports:
  http: 8080
ingress:
  tls:
    secret_name: my-app-cert
  hosts:
    my-app.com:
      path: /

Deploying an application

Once you have generated the .psykube.yml you should be able to immediately be able to deploy using the psykube apply <cluster_name> command. Invoking the command will build your docker container, push it up to the specified registry, generate the kubernetes manifests and apply them to the proper Kubernetes environment.

Playground

Psykube's main purpose is to abstract away much of the complexity involved in deploying and managing an application on Kubernetes. A primary component to this is how the .psykube.yml file translates into the files we generate for kubernetes. You can boot up the playground using the psykube playground command or by visiting psykube.commercialtribe.ninja.

Commands

psykube init

Generates a .psykube.yml in the current directory.

Usage:

psykube init [flags...] [arg...]

Flags:

long	short	default	description
--help			Displays help for the current command.
--env	-e		Set an environment variable.
--file	-f	./.psykube.yml	The location of the psykube manifest yml file.
--host	-h		Set a host for ingress.
--image	-i		Set the image, this takes precedence over --registry-host and --registry-user.
--name	-N	current directory name	Set the name of the application used for deployment.
--namespace	-n		Set the namespace.
--overwrite	-o	false	Overwrite the file if it exists.
--port	-p		Set a port. (can be in the format of --port 1234 or --port http=1234).
--registry-host	-R		The hostname for the registry. (use if not hosting on docker hub)
--registry-user	-U	current docker user	The username for the registry.
--tls	-t	false	Enable TLS for ingress.

psykube generate

Generate the kubernetes manifests.

Usage:

psykube generate [flags...] <cluster> [arg...]

Arguments

name	description
cluster_name	the name of the cluster to generate the manifests for.

Flags:

long	short	default	description
--help			Displays help for the current command.
--file	-f	./.psykube.yml	The location of the psykube manifest yml file.
--namespace	-n		The namespace to use when invoking kubectl.
--image	-i		Overrides the docker image.

psykube apply

Apply the kubernetes manifests.

Usage:

psykube apply [flags...] <cluster> [arg...]

Arguments

name	description
cluster_name	the name of the cluster to generate the manifests for.

Flags:

long	short	default	description
--help			Displays help for the current command.
--file	-f	./.psykube.yml	The location of the psykube manifest yml file.
--namespace	-n		The namespace to use when invoking kubectl.
--image	-i		Overrides the docker image.
--build-args			The build args to add to docker build.
--context	-c	The current context set for kubectl	The context to use when invoking kubectl.
--copy-namespace			Copy the specified namespace if the target namespace does not exist.
--force-copy		false	Copy the namespace even the destination already exists.
--push		true	Build and push the docker image.
--resources	-r		The resource types to copy for copy-namespace.

psykube push

Build and push the docker image.

Usage:

psykube push [flags...] [arg...]

Flags:

long	short	default	description
--help			Displays help for the current command.
--file	-f	./.psykube.yml	The location of the psykube manifest yml file.
--build-args			The build args to add to docker build.
--tag	-t		Additional tags to push.

psykube playground

Start the playground.

Usage:

psykube generate [flags...] [arg...]

Flags:

long	short	default	description
--help			Displays help for the current command.
--bind	-b	127.0.0.1	The address to bind to.
--port	-p	8080	The port to bind to.