Skip to main content

MonkOS in 10 Minutes

This is a super-quick guide to get some containers running within your own MonkOS cluster, from start to finish.

Prerequisites​

  • A computer with Linux or macOS installed (+ Homebrew on macOS)
  • An account with your favorite cloud provider
  • 10 minutes of your time

Getting Monk​

Install Monk for your OS. For more detailed instructions see Getting Monk.

brew install monk-io/monk/monk

Running Monk​

warning

You always need to have monkd running in order to use MonkOS CLI. Fire it up to continue this guide.

Ensure that Docker or Podman is running on your system. Both of either Docker or Podman and monkd have to be running when using Monk.

Initialize a new monk VM that will run monkd in the background:

monk machine init

Monk machine is a lightweight Linux VM that runs monkd on your mac. After this step you don't have to start monkd by hand.

Creating Your MonkOS Account​

Setting up the account takes 10 seconds. We use accounts to securely match users with their Monk clusters and for licensing and analytics purposes.

Use this command to create your MonkOS account:

monk register

You will be asked to verify your email address before logging in. Check your email!

Signing In​

Once monkd is running and you have confirmed your email address do:

monk login

Use your MonkOS account email and password:

? Email [email protected]
? Password ***** ***
✔ Logged in.
tip

MonkOS is 100% ready to roll at this point. You will not be asked to log in very often but some commands will require your MonkOS account credentials.

Creating a MonkOS Cluster​

Now to the exciting part! MonkOS cluster is where your workloads will run. Clusters are created once and they serve as a runtime environment that can be grown or shrunk on demand. Let's create a cluster with 3 short commands.

You'll need your service account credentials handy. Here's a reminder on how to get them:

  1. Create a new project in your GCP console,
  2. In the new project, go to IAM → Service Accounts → CREATE SERVICE ACCOUNT,
  3. Assign the Admin role on the project to the account,
  4. On the account list, click three dots and create a JSON Key for the account,
  5. Save the file on your machine eg. in key.json
warning

Make sure that Compute Engine is enabled on your project. See https://cloud.google.com/apis/docs/getting-started#enabling_apis if you're not sure how.

Make sure that your account has compute resources admin access.

note

It's alright if you want to skip cluster creation for now. You can run things locally and create a cluster later. You can still follow this guide but remember that stuff will happen on your machine and not in the cloud. To skip ahead, head to Running Kits locally.

To create a new cluster:

monk cluster new

You'll be asked to choose a name for the new cluster. Now we'll attach your cloud credentials to the new cluster:

In order to add your Service Account key to MonkOS do:

monk cluster provider add -p gcp -f <<path/to/your-key.json>>

where <<path/to/your-key.json>> is an absolute path to your Service Account JSON Key.

For example:

monk cluster provider add -p gcp -f ~/myproject/key.json

Successful invocation will result in:

✔ Provider added successfully
note

If you have more cloud accounts you can add all of them. MonkOS is great at managing singular clusters across cloud providers out of the box.

info

You don't need to touch, or even have your gcloud or aws CLI installed locally. MonkOS will work without them being present.

tip

That's it! We now have a brand new cluster. Its only member is your own machine at the moment.

Growing Your New Cluster​

The cluster is there logically. Now we have to expand it physically. Fortunately, we don't have to go back to the cloud console or resort to other tools like Terraform. We will just tell MonkOS to bootstrap it for us:

monk cluster grow

This command, like all monk commands, can either take arguments or prompt interactively. You will be asked about how many instances you want to spin up - we went with three n1-standard-1. It's generally a good idea to have at least two in your cluster in order to ensure that the cluster remains stable in case of failure of a single node.

Next up, you will be prompted for some information. All fields are required:

? Cloud provider gcp
? Name for the new instance foobar
? Tag <your-cluster-tag>
? Instance region (gcp) us-central1
? Instance type (gcp) n1-standard-1
? Disk Size (GBs) 20
? Number of instances (or press ENTER to use default = 1) 3
⠏ Creating a new instance(s) on gcp...

Tag is important – replace <your-cluster-tag> with a name of your choice and write it down. MonkOS requires all machines in the cluster to be tagged with at least one tag. We will be referring to the new machines by their tag shortly.

warning

Your cloud account may have some quotas on CPU and instance types depending on the region. You may see an error if you hit a quota or choose an unavailable instance-region combination. Try choosing a different region or machine type.

It should take 1–3 minutes to bootstrap all 3 instances. After grow is done, check with:

monk cluster peers

You should get a similar output:

ID     Name      Tag  Cloud ID  Provider  Containers  IP         Started At  Active
local  local                    unknown   0           127.0.0.1  52m 3s      true
...    foobar-1                 gcp       0           ...        2m 3s       true
...    foobar-2                 gcp       0           ...        2m 53s      true
...    foobar-3                 gcp       0           ...        3m 1s       true
note

Sometimes, depending on your network conditions, the peers might appear on the list with a slight delay. Repeat monk cluster peers if you don't see all 3 instances immediately.

tip

You now have a fully operational 3 machine MonkOS cluster running in your cloud 🎉

Deploying a Kit​

Now that we have a working cluster, it's high time to run something on it.

Use the following command to see what's immediately available:

monk list

Then just pick one of those Kits, or just try with mongodb/mongodb:

monk run -t <your-cluster-tag> mongodb/mongodb

Remember to replace <your-cluster-tag> with the one you've chosen during monk cluster new!

note

Skip -t <your-cluster-tag> if you skipped the cluster creation step. The invocation will look like this:

monk run mongodb/mongodb

MonkOS will work for a moment and then display a summary showing the current workload layout and some useful hints.

tip

That's it! You're now running stuff, in the cloud, with MonkOS 🎉

Cleaning Up​

If you don't want to use the cluster anymore just do:

monk cluster nuke

This will destroy the cluster and all associated resources. Be careful! MonkOS will not back up the storage of the instances it terminates.

In case you'd like to create another cluster, follow this guide again or see: Creating a cluster.

What's Next?​

Our newly formed cluster has 3 machines and can do much more than just running one simple workload. Having your cluster up and running is enough to start trying everything that Monk has to offer.

If you'd like to try a more advanced setup including a database, HTTP server, and a self-made service, continue to our first A-Z tutorial: Running a small system.

Rate this page