Skip to main content

Advanced Usage

Cluster creation​

Create the PKI for on-premises and immutable clusters​

The OnPremises and the Immutable kinds need a set of certificate authorities and certificate files to work as a prerequisite. Both for the Kubernetes control plane and for the etcd database. The OnPremises kind reads the folder that holds them from .spec.kubernetes.pkiFolder, and the Immutable kind from .spec.kubernetes.pkiPath.

furyctl provides a command that allows the creation of this PKI:

furyctl create pki

The command supports some additional options, like --etcd to create only the PKI for etcd, or creating the files in a different path.

See all the additional options with the --help flag:

furyctl create pki --help

Create the secrets that the configuration file needs​

Some fields of the cluster configuration file need a random secret. For example, Pomerium needs four secrets when the auth module type is sso. Gangplank needs a client secret and a session security key.

furyctl creates all of them for you:

furyctl create secrets

The command writes one file for each secret, in ./secrets/<component>/, and prints the fields to add to your furyctl.yaml. The fields read the files with the {file://<path>} notation.

With the --update-config flag furyctl writes those fields in the configuration file for you. It edits only the lines of those fields. Thus each comment, each empty line and each multi-line value, for example a certificate in oidcTrustedCA, stay as they are. furyctl writes the configuration file one time, and a configuration file that is a symbolic link keeps the link.

A field that already holds a value stays as it is, and furyctl writes no secret for it: the cluster can run with that value, and a new one would be a different secret. The command names each such field. To get a new value, take the field out of the configuration file and run the command again.

On the OnPremises and Immutable kinds the command also asks whether the cluster encrypts the secrets of etcd at rest. With an answer of yes, furyctl writes an EncryptionConfiguration object with a new secretbox key, and the spec.kubernetes.advanced.encryption.configuration field reads that file. The command asks nothing with the --no-tty flag. To write that configuration with no question, name the component:

furyctl create secrets etcd-encryption
caution

The API server reads the encryption at rest configuration when it starts. To give it the new configuration, apply the kubernetes phase with furyctl apply --phase kubernetes. The playbooks write the file to each control plane node and reconfigure the API server.

The secrets that etcd holds stay in clear text until something writes them again. Write again only the secrets that you must: a command that writes each secret of the cluster also writes the secrets of the infrastructure and of the plugins, and a tool such as kapp or a GitOps controller owns those.

Keep the file safe: without it, etcd holds secrets that nothing can read. A new key needs the old one in the same file until each secret is written again, thus never replace the key of a cluster that runs.

With no argument, furyctl creates only the secrets that your configuration file needs and that your cluster can hold. The kind of the cluster and the version of the distribution decide which fields the cluster has, thus an older version of the distribution gets fewer secrets. If you name a component that your cluster cannot hold, furyctl creates the secrets of the other names and then stops with an error.

furyctl reads those fields from the schema of the distribution, thus the command downloads it the first time for each version. Use --distro-location to read it from a local copy. With no configuration file furyctl reads no schema, and creates the secrets of every component.

Name the components to create only some of them:

furyctl create secrets pomerium gangplank

A file that is already there keeps its value. Thus you can run the command again after you add a module to the configuration file. The secrets that are already there stay the same. A path that holds no secret that furyctl can read is a fault: a folder, a file with no value in it, or a file that furyctl has no permissions for. furyctl creates the other secrets, names that path, and the run ends with an error. It writes no reference to that path, and it changes nothing in it.

caution

The command stops when it cannot read the value of a field, for example when a {file://} path is not there or an environment variable holds no value. It then names each such field. furyctl cannot tell an empty field from a field that holds a secret that it cannot see, and a new value would be a second secret.

See all the additional options with the --help flag:

furyctl create secrets --help
caution

The files hold private keys and passwords in clear text. Give access to these files only to the persons that must use them. Keep a safe copy of them. If you put these files in a git repository, encrypt them first, for example with git-crypt or SOPS.

Create a cluster in an already existing infrastructure​

Same steps described in the Basic usage guide, but you can skip the infrastructure creation phase by not filling the section infrastructure in the furyctl.yaml file and running furyctl create cluster --start-from kubernetes.

Deploy a cluster step by step​

The cluster creation process can be split into three phases:

  1. Infrastructure
  2. Kubernetes
  3. Distribution

The furyctl create cluster command will execute all the phases by default, but you can limit the execution to a specific phase by using the --phase flag.

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 --vpn-auto-connect.

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

Legacy vendor download​

The new furyctl still embeds some legacy features, for example the command furyctl legacy vendor to download SD dependencies from a deprecated Furyfile.yml.

This can be still used to manually manage all the components of the distribution.

tip

You can also use --furyfile to point to a Furyfile.yaml in a different folder

Plugins​

furyctl supports Helm and Kustomize plugins. The following sections will help you getting started with them.

Find out more in the Plugins section of the SD documentation.

Helm plugins​

To install a Helm plugin (chart), follow these steps:

  1. Add the repository to the spec.plugins.helm.repositories section of your furyctl.yaml file.
  2. 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 spec.plugins.helm.releases[].values section.

For example to install the Prometheus Helm chart you have to add the following to your furyctl.yaml:

...
spec:
  ...
  plugins:
    helm:
      repositories:
        - name: prometheus-community
          url: https://prometheus-community.github.io/helm-charts
      releases:
        - name: prometheus
          namespace: prometheus
          chart: prometheus-community/prometheus
          version: "24.3.0"
          set:
            - name: server.replicaCount
              value: 3
          values:
            - path/to/values.yaml

Kustomize plugins​

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.

For example:

...
spec:
  ...
  plugins:
    kustomize:
      - name: kustomize-project
        folder: path/to/kustomize/project

Advanced Tips​

Using a custom distribution location​

furyctl comes with the flag --distro-location, allowing you to use a local copy of SD instead of downloading it from the internet. This allows you to test changes to the SD without having to push them to the repository, and might come in handy when you need to test new features or bug fixes.

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 release candidate 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: pre-infrastructure, infrastructure, post-infrastructure, pre-kubernetes, kubernetes, post-kubernetes, pre-distribution, distribution, post-distribution, plugins.

Setting command flags via environment variables​

The flags for furyctl commands can also be set via environment variables additionally to passing them in the command itself. furyctl will pick up the flags from environment variables that have the following format:

FURYCTL_<flag name with underscores instead of spaces>

For example, for setting the --outdir and --distro-location flags you can set the following environment variables instead of passing the flags in each command:

export FURYCTL_OUTDIR=$PWD
export FURYCTL_DISTRO_LOCATION=/home/myuser/src/sd-vX

Now, you can run for example furyctl apply and the --outdir and --distro-location flags will be set based on the environment variables values even if not specified in the command.