Weave Kubernetes Subscription Control - wksctl

The wksctl command allows simple creation of a Kubernetes cluster given a set of IP addresses and an SSH key. It can be run in a standalone environment but is best used via a GitOps approach in which cluster and machine descriptions are stored in Git and the state of the cluster tracks changes to the descriptions.

Install wksctl binary

1. Download the OS specific wksctl release package from the release page
2. Unpack and add the wksctl binary to your path

For example:

cd <download dir>
tar xfz wksctl-0.7.0-linux-x86_64.tar.gz
chmod +x wksctl
sudo mv wksctl /usr/local/bin/

Quick start

The examples folder (also included in the release package download) contains guides to get you up and running with Footloose, Vagrant and others!

Modes of use

In standalone mode, wksctl builds a static cluster based on the contents of cluster.yaml and machines.yaml files passed on the command line; in GitOps mode, changes to cluster.yaml and machines.yaml files stored in Git will cause updates to the state of the live cluster.

Standalone mode

Run wksctl apply and pass in the paths to cluster.yaml and machines.yaml

wksctl apply \
  --cluster cluster.yaml \
  --machines machines.yaml

GitOps mode

We will create a cluster by pulling the cluster and machine yaml from git.

The following are new commandline arguments to wksctl apply which will result in a cluster being created.

• git-url The git repo url containing the cluster.yaml and machine.yaml
• git-branch The branch within the repo to pull the cluster info from
• git-deploy-key The deploy key configured for the GitHub repo
• git-path Relative path to files in Git (optional)

The git command line arguments will be passed instead of --cluster and --machines.

wksctl apply \
  --git-url git@github.com:meseeks/config-repo.git \
  --git-branch dev \
  --git-deloy-key-path ./deploy-key

Using the url, branch, and deploy key, we will clone the repo - if we can't clone the repo we will error out.

These --git arguments are then used to set up and configure flux to automate cluster management.

We will rely on the user installing fluxctl to interact with flux directly instead of trying to replicate the functionality within wksctl

To see a more detailed example combining Wksctl, GitOps, Ignite also know as FireKube see Firekube

Development

Build

make

Upgrading the build image

• Update build/Dockerfile as required.
• Test the build locally:

rm build/.uptodate
make !$

• Push this change, get it reviewed, and merge it to master.
• Run:

git checkout master ; git fetch origin master ; git merge --ff-only master
rm build/.uptodate
make !$
> [...]
> Successfully built deadbeefcafe
> Successfully tagged quay.io/wksctl/build:latest
> docker tag quay.io/wks/build quay.io/wksctl/build:master-XXXXXXX
> touch build/.uptodate
docker push quay.io/wksctl/build:$(tools/image-tag)

• Update .circleci/config.yml to use the newly pushed image.
• Push this change, get it reviewed, and merge it to master.

Checkpoint

wksctl contacts Weaveworks servers for available versions. When a new version is available, wksctl will print out a message along with a URL to download it.

The information sent in this check is:

• wksctl version
• Machine Architecture
• Operating System
• Host UUID hash

To disable this check, run the following before executing wksctl:

export CHECKPOINT_DISABLE=1

Contributing

Please see CONTRIBUTING.md and our Code Of Conduct.

Other interesting resources include:

• The issue tracker

Getting Help

If you have any questions about, feedback for or problems with wksctl:

• Invite yourself to the Weave Users Slack.
• Ask a question on the #general slack channel.
• File an issue.

Your feedback is always welcome!

License

Apache 2.0