Skip to main content
Version: 1.2


This page details the prerequisites you need in place before and after install in order for Wayfinder to run successfully.

Summary of prerequisites

Tools on your workstation:



Cloud access for install

Wayfinder is installed into a cloud account that you have access to. See the instructions below for the cloud you want to install Wayfinder in.


Follow these steps to configure your console for access to an AWS Account using the aws tool:

  1. Install the AWS CLI.


    If you are using ~/.aws/credentials in your environment, it will take precedent over the SSO profile. Either remove this credentials file or make sure it is set to the right account.

  2. Configure AWS profile, and then run export AWS_PROFILE=<profile_name>.

  3. Use an AWS role for upgrade or re-install.


Set up access to an Azure Subscription in your console using the az tool:

  1. Install the Azure CLI.
  2. Sign in with Azure CLI.


The gcloud tool is part of the GCP SDK and is required for console access to a GCP project:

  1. Install gcloud CLI (SDK)
  2. Authorizing gcloud CLI (SDK)

Access to create public DNS records

Wayfinder is required to be installed securely with valid DNS records that can be trusted for secure web access (HTTPS).

Two DNS names in the same DNS zone are required for a Wayfinder install, for example:

  • (Wayfinder API)
  • (Web UI)

You can use any public-facing DNS zone for these records.

The Wayfinder install reserves public IP addresses with your cloud provider during install and waits for these names to resolve before continuing.

Identity provider

Wayfinder uses your existing identity provider to grant access to the UI, CLI, and the infrastructure provisioned for team workspaces.

Wayfinder uses Open ID Connect (OIDC) for integrating with identity providers, and you must provide the following details when installing Wayfinder:

  • Issuer URL
  • Client ID
  • Client Secret

The installer:

  • Requests all these values during install.
  • Provides you the call-back URL to complete OIDC setup during install.
  • Validates the issuer URL only during install.

See User authentication providers for more information and help setting up specific providers.

Use an AWS role for upgrade or re-install


This prerequisite is needed only when upgrading or re-installing Wayfinder on an AWS EKS cluster.

When Wayfinder is installed on an AWS EKS cluster, the installer automatically adds a reference to a default AWS role to EKS. The following shows the installer message with the default role wf-wayfinder:

✔ Successfully validated AWS API access

An AWS role is required if you need another user to re-install Wayfinder
This may be created after the initial installation
✔ Role ARN which will have admin access to the EKS cluster outside Wayfinder: arn:aws:iam::12345678910:role/wf-wayfinder

The user that installs Wayfinder for the first time can either override the default role with an existing AWS role, or create the Wayfinder default role in AWS. This original user is then the kubernetes IAM entity given access to the install cluster, via this role.

Subsequently, if a different user needs to upgrade or re-install Wayfinder, that user must use the AWS role used in the original install in order to upgrade or re-install.

To use the original Wayfinder install role on upgrade or reinstall:

  1. Find the name of the role used for the original Wayfinder install in the wf-install.yaml file:

    grep awsClusterAdminRoleARN wf-install.yaml 
    awsClusterAdminRoleARN: arn:aws:iam::149353100611:role/wf-wayfinder

    In this example, the role name returned is wf-wayfinder.

  2. If the above role doesn't exist in AWS after the original install, create this role in AWS with the relevant user access policy. For instructions, see the following AWS documenation:

  3. Before running the Wayfinder install, assume the above AWS role using the AWS CLI:

    aws sts assume-role

    See the AWS documentation.

For more information, see the AWS documentation on Creating a role to delegate permissions to an IAM user.