Quick Start

Clone the repository

$ git clone https://github.com/modusintegration/moduskube

Note

You must be part of the modusintegration organization on GitHub to access this repository.

Build the ModusKube Docker image

$ cd moduskube
$ make

Verify cloud credentials

ModusKube will do its best to find your AWS credentials in the environment and in common locations like $HOME/.aws/credentials. At minimum you will need to define AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

You can also use temporary security credentials via the AWS_SESSION_TOKEN and AWS_SECURITY_TOKEN environment variables which is the recommended way to use ModusKube with AWS.

Tip

We strongly recommend keeping your AWS credentials out of plaintext files on your computer. Use a tool like AWS Vault to encrypt your credentials and generate temporary security credentials when needed. Tools like this also greatly simplify switching between multiple AWS accounts or roles.

Run ModusKube

Run moduskube without options to show the available commands:

$ ./moduskube
Usage: moduskube [OPTIONS] COMMAND [ARGS]...

...

Note

The moduskube command is just a lightweight shell script that calls the docker run command. Whenever you run the moduskube command you are running the ModusKube container image in Docker.

Important

The steps below assume that the moduskube script is located somewhere in your shell’s PATH. You should continue to use ./moduskube if this is not the case.

Set environment variables

ModusKube automatically reads environment variables for many of its settings. While these settings can be specified as command-line options, we’ll save some typing by defining them here for later steps:

$ export MODUSKUBE_CLUSTER=<my-cluster>
$ export MODUSKUBE_REGION=<my-region>
$ export MODUSKUBE_STATE_BUCKET=<my-bucket>

ModusKube relies on an S3 bucket to store cluster state, and most commands that work with clusters will require this option. We’re setting it here with the MODUSKUBE_STATE_BUCKET environment variable. We’ll be creating this bucket in the next step if it doesn’t already exist.

Tip

The help text for each command will show you which options can be set via environment variables.

Initialize cloud resources

Important

This is only required the first time ModusKube is used with a new cloud account.

$ moduskube cloud aws init

This will create the following resources in the active AWS account:

• A new VPC (called ModusKube Clusters by default)

• A set of IAM roles and policies for cluster nodes

• The S3 state bucket defined in the previous step

• An SSH keypair used for connecting to cluster nodes

• An encrypted secret stored in Systems Manager Parameter Store that holds the SSH keypair’s private key

Create the cluster

$ moduskube cluster create

Connect to the cluster

$ moduskube cluster kubeconfig run

This launches a shell in the ModusKube container with an active Kubernetes configuration and cluster connection. You can run any of the Kubernetes tools included with ModusKube to work with your cluster. For example:

$ kubectl get node
NAME                                       STATUS   ROLES    AGE    VERSION
ip-10-0-1-103.us-west-2.compute.internal   Ready    node     182d   v1.10.7
ip-10-0-1-16.us-west-2.compute.internal    Ready    node     182d   v1.10.7
ip-10-0-1-166.us-west-2.compute.internal   Ready    master   182d   v1.10.7
ip-10-0-1-43.us-west-2.compute.internal    Ready    node     182d   v1.10.7

Exit the shell by pressing Ctrl + D or running exit.

Tip

You can add your own tools to ModusKube by copying binaries into shared/bin, using ModusKube as a base image for your own container or by writing plugins that extend the CLI.

Destroy the cluster

$ moduskube cluster destroy ${MODUSKUBE_CLUSTER}

Note

As a precaution, the destroy command requires that the cluster be specified directly on the command line, which is why this looks different from previous commands.