The next generation of
furyctl, called "furyctl next", has been officially released. It is now in a stable state and available starting from version v0.25.0. The previous version, furyctl 0.11, is considered legacy and will only receive bug fixes. It will be maintained under the v0.11 branch.
What is Furyctl?
furyctl is the command line companion for the Kubernetes Fury Distribution to manage the full lifecycle of your Kubernetes Fury clusters.
EKSCluster: Provides comprehensive lifecycle management for an EKS cluster on AWS. It handles the installation of the VPC, VPN, EKS using the installers, and deploys the Distribution onto the EKS cluster.
KFDDistribution: Dedicated provider for the distribution, which installs the Distribution (modules only) on an existing Kubernetes cluster.
OnPremises: Provider to install a KFD Cluster on VMs.
Installing from binaries
You can find
furyctl binaries on the Releases page.
To download the latest release, run:
curl -L "https://github.com/sighupio/furyctl/releases/latest/download/furyctl-$(uname -s)-amd64.tar.gz" -o /tmp/furyctl.tar.gz && tar xfz /tmp/furyctl.tar.gz -C /tmp
chmod +x /tmp/furyctl
sudo mv /tmp/furyctl /usr/local/bin/furyctl
Alternatively, you can install
furyctl using the asdf plugin.
Add furyctl asdf plugin:
asdf plugin add furyctl
Check that everything is working correctly with
$ furyctl version
Installing from source
make >= 4.1
go >= 1.21
goreleaser >= v1.22
You can install
goreleaserwith the following command once you have Go in your system:
go install email@example.com
Once you've ensured the above dependencies are installed, you can proceed with the installation.
- Clone the repository:
git clone firstname.lastname@example.org:sighupio/furyctl.git
# cd into the cloned repository
- Build the binaries by running the following command:
- You will find the binaries for Linux and Darwin (macOS) for your current architecture inside the
$ tree dist/furyctl_*/
- Check that the binary is working as expected:
darwinwith your OS and
amd64with your architecture in the following commands.
- (optional) move the binary to your
binfolder, in macOS:
sudo mv ./dist/furyctl_darwin_amd64_v1/furyctl /usr/local/bin/furyctl
See all the available commands and their usage by running
Enable command tab autocompletion for
furyctlon your shell (
fishare supported). See the instruction on how to enable it with
furyctl completion --help
Check KFD Compatibility matrix for the Furyctl / KFD versions to use.
Basic usage of
furyctl for a new project consists on the following steps:
- Creating a configuration file defining the prequired infrastructure, Kubernetes cluster details, and KFD modules configuration.
- Creating a cluster as defined in the configuration file.
- Destroying the cluster and its related resources.
1. Create a configuration file
furyctl provides a command that outputs a sample configuration file (by default called
furyctl.yaml) with all the possible fields explained in comments.
Furyctl configuration files have a kind that specifies what type of cluster will be created, for example the
EKSCluster kind has all the parameters needed to create a KFD cluster using the EKS managed clusters from AWS.
You can also use the
KFDDistribution kind to install the KFD distribution on top of an existing Kubernetes cluster or
OnPremises kind to install a KFD cluster on VMs.
Additionaly, the schema of the file is versioned with the
apiVersion field, so when new features are introduced you can switch to a newer version of the configuration file structure.
To scaffold a configuration file to use as a starter, you use the following command:
furyctl create config --version v1.27.1 --kind "EKSCluster"
You can pass some additional flags, like the schema (API) version of the configuration file or a different configuration file name.
furyctl create config --helpfor more details.
Open the generated configuration file with your editor of choice and edit it according to your needs. You can follow the instructions included as comments in the file.
Once you have filled your configuration file, you can check that it's content is valid by running the following comand:
furyctl validate config --config /path/to/your/furyctl.yaml
--configflag is optional, set it if your configuration file is not named
2. Create a cluster
- AWS CLI
- OpenVPN (when filling the
vpnfield in the configuration file)
In the previous step, you have created and validated a configuration file that defines the Kubernetes cluster and its sorroundings, you can now proceed to actually creating the resources.
Furyctl divides the cluster creation in four phases:
- The first phase,
infrastructure, creates all the prerequisites needed to be able to create a cluster. For example, the VPC and its networks.
- The second phase,
kubernetes, creates the actual Kubernetes clusters. For example, the EKS cluster and its node pools.
- The third phase,
distribution, deploys KFD modules to the Kubernetes cluster.
- The fourth phase,
plugins, installs Helm and Kustomize plugins into the cluster.
You will find these four phases when editing the furyctl.yaml file.
Just like you can validate that your configuration file is well formed,
furyctl let you check that you have all the needed dependencies (environment variables, binaries, etc.) before starting a cluster creation process.
To validate that your system has all the dependencies needed to create the cluster defined in your configuration file, run the following command:
furyctl validate dependencies
Last but not least, you can launch the creation of the resources defined in the configuration file by running the following command:
You are about to create cloud resources that could have billing impact.
The cluster creation process, by default, will create a VPN in the
infrastructurephase and connect your machine to it automatically before proceeding to the
furyctl create cluster --config /path/to/your/furyctl.yaml
You can use the alias
furyctl applyinstead of
furyctl create cluster.
The creation process will take a while.
🎉 Congratulations! You have created your production-grade Kubernetes Fury Cluster from scratch and it is now ready to go into battle.
3. Upgrade a cluster
Upgrading a cluster is a process that can be divided into two steps: upgrading the fury version and running the migrations(if present).
The first step consist in bringing the cluster up to date with the latest version of the Kubernetes Fury Distribution. This is done by running the following command:
furyctl apply --upgrade --config /path/to/your/furyctl.yaml
Once that is done, if you were also planning to move to a different provider (e.g.:
loki), you can run the following command to run the migrations:
furyctl apply --config /path/to/your/furyctl.yaml
You must first upgrade the cluster using the old provider(e.g.:
opensearch), update the configuration file to use the new provider(e.g.:
loki) and then run the command above.
4. Destroy a cluster
Destroying a cluster will run through the four phases mentioned above, in reverse order, starting from
To destroy a cluster created using
furyctl and all its related resources, run the following command:
You are about to run a destructive operation.
furyctl delete cluster --dry-run
Check that the dry-run output is what you expect and then run the command again without the
--dry-run flag to actually delete all the resources.
--dry-runflag, used to check what the command would do. This flag is available for other commands too.
The following steps will guide you through the process of creating a Kubernetes Fury cluster from zero.
- Follow the previous steps to generate a
furyctl.yamland download the modules.
- Edit the
furyctl.yamlto customize the cluster configuration by filling the sections
- Check that the configuration file is valid by running
furyctl validate config.
furyctl create clusterto create the cluster.
- (Optional) Watch the logs of the cluster creation process with
tail -f ~/.furyctl/furyctl.<timestamp>-<random>.log.
Create a cluster in an already existing infrastructure
Same as the previous section, but you can skip the infrastructure creation phase
by not filling the section
infrastructure in the
furyctl.yaml file and
furyctl create cluster --start-from kubernetes.
Deploy a cluster step by step
The cluster creation process can be split into three phases:
furyctl create cluster command will execute all the phases by default,
but you can limit the execution to a specific phase by using the
To create a cluster step by step, you can run the following command:
furyctl create cluster --phase infrastructure
If you choose to create a VPN in the infrastructure phase, you can automatically connect to it by using the flag
furyctl create cluster --phase kubernetes
After running the command, remember to export the
KUBECONFIG environment variable to point to the generated kubeconfig file or
to use the flag
--kubeconfig in the following command.
furyctl create cluster --phase distribution
The new furyctl still embed some of the legacy features, for example the command
furyctl legacy vendor to download KFD dependencies from a deprecated
This can be still used to manually manage all the components of the distribution.
you can also use
--furyfileto point to a
Furyfile.yamlin a different folder
Furyctl supports Helm and Kustomize plugins.
To install an Helm plugin (chart), first you have to add the repository to the
spec.plugins.helm.repositories section of your
furyctl.yaml file and then you can add the release to the
spec.plugins.helm.releases section, specifying the chart name, the namespace, the chart version and the values to override. To override the values you can use the
spec.plugins.helm.releases.set or the
For example to install the Prometheus Helm chart you have to add the following to your
- name: prometheus-community
- name: prometheus
- name: server.replicaCount
To install a Kustomize plugin (project) you have to configure the
spec.plugins.kustomize section of your
furyctl.yaml file, specifying a name and the path to the folder.
- name: kustomize-project
Using a custom distribution location
Furyctl comes with the flag
--distro-location, allowing you to use a local copy of KFD instead of downloading it from the internet. This allows you to test changes to the KFD without having to push them to the repository, and might come in handy when you need to test new features or bugfixes.
Using a custom upgrade path location
On the same note, the tool comes with the
--upgrade-path-location flag, too, allowing you to test changes to the upgrade path without having to push them to the repository, and to support cases that are not covered by the official release, such as upgrading from a beta or rc release to a stable one.
Restarting the cluster creation or update process from a specific (sub-)phase
If, for any reason, the cluster creation or update process fails, you can restart it from a specific (sub-)phase by using the
--start-from flag. Starting from v0.27.0 we introduced the support for sub-phases, to give the operator more control over the process. The supported options are: