Configuration file structure

furyctl uses a configuration file (named furyctl.yaml by default) to define the complete configuration of a SIGHUP Distribution cluster.

The configuration file structure depends on the kind (alias for the Provider) of the cluster being created.

All configuration files share a common base structure though:

apiVersion: <version>
kind: <kind>
metadata:
  name: <name>
spec:
  infrastructure:
  kubernetes:
  distribution:
  plugins:

You can find the reference schemas for each Provider here

Spec

The .spec portion contains the phases that are exeucted by furyctl to provision a SD cluster.

.spec.infrastructure

The .spec.infrastructure portion will contain all the parameters needed to create the infrastructure that will host a Kubernetes cluster. For example, on AWS this will configure the VPC and VPN. Not all providers have this phase, see the Providers documentation for more details.

.spec.kubernetes

The .spec.kubernetes portion will contain the actual configuration for the Kubernetes cluster, options and nodepools. It is used to drive the creation of a Kubernetes cluster with a provider of your choice. Not all providers have this phase, see the Providers documentation for more details.

.spec.distribution

The .spec.distribution portion will contain all the configurations on the SIGHUP Distribution core modules that will be installed inside the Kubernetes cluster.

note

N.B.: the default values for the furyctl.yaml config file are set to provide you with a production-grade cluster, so the default configuration will install all modules with some default values. In consequence, if a module is not specified, it does not mean that it will be not installed. If you want to not install a module, you must set it explicitly in its configuration, for example:

spec:
  distribution:
    networking: # or any other module
      type: "none"

You can see the default values for each kind on the distribution GitHub repository.

.spec.distribution.customPatches

The .spec.distribution.customPatches section allows you to apply patches to the manifests generated during the distribution phase.

As furyctl uses Kustomize under the hood to generate the distribution's manifests, the .spec.distribution.customPatches is a hook to insert custom behavior during the execution of Kustomize.

You can specify:

• a patchesStrategicMerge array of files that follow Kustomize's patchesStrategicMerge spec.

  warning

  This field is not recommended anymore, as we switched to Kustomize v5 and it is deprecated there. Use patches instead, see more below.

• a patches array of objects that follow Kustomize's patches spec.

• a configMapGenerator array of objects that follow Kustomize's configMapGenerator spec.

• a secretGenerator array of objects that follow Kustomize's secretGenerator spec.

• a images array of objects that follow Kustomize's images spec.

warning

Custom patches can disrupt a cluster's configuration in unpredictable ways. This field can possibly make your cluster unavailable and it should be used only if you know exactly what you are doing.

Use with caution!

You can see how to use customPatches in some of the advanced use cases.

.spec.distribution.customResources

The .spec.distribution.customResources section adds your own resources to the manifests of the distribution phase.

furyctl appends each entry to the resources list of the Kustomization that builds the distribution. Kustomize applies these resources together with the SD core modules, in the same phase. All the providers support this field.

Each entry is a string that points to one of these:

• a manifest file.
• a directory that contains a Kustomize base.
• a remote resource, such as a Git repository or a URL. It uses Kustomize's remote target syntax.

furyctl resolves a local path against the directory that contains furyctl.yaml. Both ./my-base and my-base are correct.

If an entry does not match a local file or directory, furyctl passes the entry to Kustomize without a change. Remote resources work in this way.

note

A local path with a typo does not match a file, so furyctl passes it to Kustomize unchanged. When Kustomize builds the manifests, the distribution phase fails.

Keep your resources inside the project directory. If a path resolves outside the directory that contains furyctl.yaml, furyctl prints a warning. The generated manifests are then different on other machines.

For example:

...
spec:
  ...
  distribution:
    customResources:
      - "./manifests/storageclass.yaml"
      - "./manifests/csi-driver"
      - "github.com/example/repo//base?ref=v1.0.0"

warning

Use customResources only when furyctl must apply the resources in the distribution phase, together with the core modules.

For all the other resources, use plugins. Plugins are the preferred way to add resources to a cluster, and you can remove them with helm or kapp.

.spec.plugins

The .spec.plugins portion will contain all the additional Helm Charts/Kustomize projects that we want to install inside the Kubernetes cluster. This is intended to be the place where you add things that you consider to be part of the cluster's core components, which will be managed by furyctl and not by other means. It's not intended as a mean to place actual application workload inside the cluster.

As an example, you could install as a plugin the resources needed to use a CSI of your choice.

Phases

Each one of the aforementioned portions defines also a phase of furyctl's execution.

During creation, the phases will be executed in the following order: infrastructure -> kubernetes -> distribution -> plugins.

The phases can also be executed in standalone mode if necessary, using the flag --phase with furyctl.