Skip to main content

Installation Methods & Steps

You can install Wayfinder using:

  • Appvia's installer
  • Via the AWS Marketplace
  • Via the Azure Marketplace

Please read the installation prerequisites before continuing with the installation process.

The installation process using Appvia's installer


Wayfinder runs on Windows, however, the installer is currently supported only for Unix and Linux systems. Please contact us on Slack for help using the installer on windows.

The Wayfinder installer is built into the Wayfinder CLI, and configures the Wayfinder server and all its dependencies in a cluster in your cloud provider.

Simplfied install option

The installer gives you the option to do a simplified installation for testing Wayfinder. If you select this option, the installer uses default values for:

  • Networking
  • Availablity Zones
  • DNS Hostnames for Wayfinder Web UI and API addresses
  • Basic Authentication (identity provider can be set up later in the Web UI)

To change the networking defaults used in simplified install, you must do a new installation. Therefore, if you're building a production instance of Wayfinder do not do a simplified install, and review all configuration values during installation.

Installation stages

The installation procedure has two stages:

1. Interactive stage

  • Requests and validates all options
  • Creates ingress IPs required for valid DNS

This stage creates two files in your install directory, which contain the values you choose in response to prompts:

wf-install.yaml wf-install-secrets.yaml

If you want to automate installation, you can run the interactive stage alone, and use these generated files to do the automated installs. For details, see Prepare for an automated install and Use non-interactive install in your automation below.

2. Non-interactive stage

Installs Wayfinder and all dependencies, including:

  • Cloud Networking
  • Cloud Kubernetes
  • TLS Certificates
  • Ingress


During the interactive stage of the installer, there are three possibilities for licensing:

  • Use existing license key–The installer detects an existing license key, and you confirm you want to use it.
  • Use a different license key–The installer detects an existing license key, and you want to use a different one. You are prompted to paste in the license key.
  • Use the free version–There are no existing licenses, and you request a new one. The new license key unlocks Wayfinder's free version. To upgrade contact Appvia to get a full license.

Install Wayfinder

This procedure does a complete installation of Wayfinder. For detailed options see wf install.


Review and implement the Prerequisites before installing Wayfinder, including cloud access for install for your cloud provider.

To install Wayfinder:

  1. Ensure you are logged in to the cloud provider in which you want to install Wayfinder.

  2. Create a directory, for example wf-install, for Wayfinder to create install files:

    mkdir wf-install
    cd wf-install
  3. Run the installer:

    wf install
    • In the first stage, the installer prompts you for all configuration options including simplified install, and generates the files wf-install.yaml and wf-install-secrets.yaml.

    • The second stage completes the installation, which can take between 10 and 40 minutes depending on your cloud provider.


    Keep the wf-install.yaml and wf-install-secrets.yaml files to reinstall if necessary.

  4. If necessary, create an AWS role for accessing the install cluster.

    The installer adds a reference to a default AWS role, wf-wayfinder, which you can override with an existing role. If you accept the default role, you must then create the wf-wayfinder role in AWS with the appropriate user (STS) access permissions. See the following AWS documentation:

  5. Important: If this is a re-install, you must follow the procedure in Update Wayfinder's cloud access.

For troubleshooting the installation, see Troubleshooting.

Automate your installs

To automate your installs, you prepare for it by generating the required files, then use a non-interactive install in your automation. These steps are described below.

Prepare for an automated install

This procedure runs the first, interactive, stage of the installer only. This generates two files needed to do an automated/non-interactive install using your automation script.

For detailed options, see wf install.

To prepare files for an automated install:

  1. Run the first stage of the installer only:

    wf install --init-only

    You are prompted for all configuration options. At the end of this stage, two files are created:

    • wf-install.yaml—you can commit this into a source control system.
    • wf-install-secrets.yaml—do NOT commit this to source control. Instead, ensure this file is encrypted or provided from a secrets management system.

    Keep the wf-install.yaml and wf-install-secrets.yaml files to reinstall if necessary.

    To automate your installs, you can use these files in your automation using the non-interactive install procedure below.

Use non-interactive install in your automation

The non-interactive install is appropriate for use in your automated installs. The non-interactive install does a complete installation and takes between 10 and 40 minutes depending on cloud vendor.

For detailed options see wf install.

To run a non-interactive install:

  1. Ensure you have these files in your current directory:


    See Prepare for an automated install above.

  2. Use this command in your automation script to run the installer with no prompts:

    wf install --non-interactive

Set up cloud accounts for Wayfinder

After successfully installing Wayfinder, but before using it, you must provide it with one or more cloud accounts that you want it to use. For more information, see Cloud Accounts.

Configure identity provider

We strongly recommend that you configure an identity provider when using Wayfinder. This is done after the initial installation is complete - see User authentication providers for more information and help setting up specific providers.

Accessing the Management cluster

Once provisioned you can access the Kubernetes cluster for management like any other workspace one. A predefined workspace admin is created on installation and used for administrative resources.

# Access the management cluster
$ wf access cluster management -w admin

Uninstall Wayfinder

The uninstall command removes the Wayfinder management Kubernetes cluster and dependent network. However, all remaining cloud resources in Wayfinder are orphaned after the uninstall, and remain in the cloud. These include clusters, DNS zones, other networks, or anything you used Wayfinder to create. Since these resources are not removed by the uninstall, you can still keep using them without using Wayfinder.


Any orphaned cloud resources remaining in the cloud after uninstall incur ongoing costs.

To uninstall Wayfinder:

  1. (Recommended) Do either of the following:

    • In Wayfinder, delete cloud resources you used Wayfinder to create, such as clusters.
    • If you plan to re-install Wayfinder, back up the Wayfinder database and any cloud resources you created in Wayfinder. See Backup and Restore.
  2. Go to the directory where you first installed Wayfinder.

    This is the directory where the wf-install.yaml and wf-install-secrets.yaml files reside.


    If you no longer have the wf-install.yaml file, you can generate it by running the following command (providing the Wayfinder Instance ID, Cloud and Management Cluster name):

    wf install --non-interactive --instance-identifier ${WF_INSTANCE_IDENTIFIER} --cloud ${WF_CLOUD} --disable-idp --cluster-name ${WF_MANAGEMENT_CLUSTER} --init-only
  3. Run wf install --remove.

    The management cluster and dependent network are removed. Remaining resources that you did not delete are orphaned and remain in the cloud.

  4. If you did not delete resources in Wayfinder in Step 1 above, and don't plan to keep using them, then manually delete them in your cloud provider to avoid incurring costs.