Fieldctl CLI

DEPRECATED: This CLI is being deprecated since, in the end, it is just better to use vcluster cli directly. However, the architecture is still valid so I keep it here for anybody who might be interested.

This cli aims to help on operating a local environment. The intention is to wrap some complicated commands which are used to develop in local.

The first target is MacOS.

17 seconds to have a cluster up and running in local

Motivation

You, as a developer, usually need to create ephemeral environments quickly to develop, test and debug.

These actions can occur quite often. And, in some cases, you rather prefer a clean environment than an already used one.

Every time a new instance of the cluster is needed, you need to destroy the cluster and re-create it.

In a Linux OS with some flavours of k8s (kind, k3s, k0s), these actions can take a small period of time.

In a MacOS, you might need to create a VM, making the repetitive process a time consumer (a couple of minutes each time can kill your patience)

The solution can be to leverage several tools (lima VM, vcluster, metallb). But that is too much work.

This CLI helps on making easy to create a VM with a k8s cluster (k3s) and deploy vclusters.

Vcluster is a technology which allows to have multiple isolated k8s clusters within one "main" one.

Creating and deleting those vclusters is a matter of seconds. This helps on speeding up the development lifecycle.

Dependencies

The CLI requires you to have already installed:

• Lima VM

• vcluster

• kubectl

Important

When installing Lima do not forget to install vde_vmnet to enable the network

How to use

Download it and run to discover the commands:

fieldctl --help
fieldctl vm --help
fieldctl virtual --help

A folder will hold all the related files and persisted folders which are used within the VM. The folder is located at ~/.field

Note	Internally, the cluster deployed in the VM leverages some docker registry as mirrors. The data is persisted in your host at ~.field folder. Once you destroy the VM, you can recreate it and re-use the already downloaded images. This speeds up the installation time for your applications

Autocomplete

Autocomplete scripts are in autcomplete folder. There is support for bash, zsh and fish

• Bash

Source autocomplete/fieldctl-complete.bash script in ~/.bashrc.

• Zsh

Source autocomplete/fieldctl-complete.zsh script in ~/.zshrc.

• Fish

Save the autocomplete/fieldctl-complete.fish script to ~/.config/fish/completions/foo-bar.fish

Examples

# Create the Lima VM where to deploy the cluster.
# Notice that it will re-use your existing config file
# k3s is used as main cluster. Metallb is used to expose services as LoadBalancer to your host machine
fieldctl vm create --memory 8 --cpus 4 --disk 50

# To make the main cluster accessible from the host
fieldctl vm connect

Warning

If you have issues, go to Troubleshooting

# Create a virtual cluster (vcluster) with name: `demo-1`.
fieldctl virtual create -n demo-1

kubectl get ns

kubectl create ns test

kubectl create deployment nginx --image=nginx -n test

kubectl expose deployment nginx --port=80 --target-port=80 --type=LoadBalancer -n test

export APP_IP=$(kubectl -n test get svc nginx -o jsonpath='{.status.loadBalancer.ingress[0].*}')

curl $APP_IP
# You should be able to access nginx

fieldctl virtual create -n demo-2

kubectl get ns
# You should NOT see the test namespace because this is another environment

# Delete the first cluster
fieldctl virtual delete -n demo-1

DEV Notes

Why python? The CLI could have been developed using any other language. However, python is easy to read and develop even not having much experience.

As well, one of the packages is pyinstaller which facilitates the creation of the binary.

Why click? click is a python framework to develop CLIs. It is extremely friendly an intuitive making the development of your CLI quite easy to anybody to understand it and to collaborate.

The downside is on execution time. In order to run, the binary creates a temporary folder in your filesystem to deploy the embedded resources like the template. This creates a small latency the first time is executed.

Notice that:

• Work in progress. The cli is open to grow in any direction. For example: Add commands to test scenarios

• No tests created. Being first iterations, there are no test to cover the results.

• Code is not polished. Being firsts iterations, the code is still dirty

Troubleshooting

• When running fieldctl vm create --memory 8 --cpus 4 --disk 50, I get this error:

networks.yaml field `path.vdeSwitch` error: lstat /opt/vde/bin/vde_switch: no such file or directory

Then, you need to install vde_vmnet

• When installing vde_vmnet, the step: sudo make PREFIX=/opt/vde install fails

Then, you might be missing some packages required to build and install vde_vmnet

brew install autoconf automake libtool

• vd_vmnet is installed but Lima cannot find it

Then, run following commands to figure out the executable path to vde_vmnet and vde_switch

which vde_vmnet # i.e. /opt/vde/bin/vde_vmnet
which vde_switch # i.e. /opt/vde/bin/vde_switch

Include those paths into the $PATH environment variable:

# Having `/opt/vde/bin/vde_vmnet` in $HOME/.bashrc or $HOME/.zshrc add:
export PATH="/opt/vde/bin:$PATH"

Add lima to sudoers:

limactl sudoers | sudo tee /etc/sudoers.d/lima
/private/etc/sudoers.d/ # You should see `lima`

Verify that Lima links correctly to executables and sodoer:

cat ~/.lima/_config/networks.yaml

And you should see something similar to:

paths:
  vdeSwitch: /opt/vde/bin/vde_switch
  vdeVMNet: /opt/vde/bin/vde_vmnet
  varRun: /private/var/run/lima
  sudoers: /private/etc/sudoers.d/lima

Acknowledgements

Fieldctl is built upon other open source code projects. Without these projects Fieldctl would never have seen the light.

• Lima VM

• Vcluster

• k3s

• MetalLB