Skip to main content
Version: 1.2

Provisioning Kubernetes Clusters in Wayfinder

To get your application running on Wayfinder, you need a cluster. A cluster represents a dedicated, isolated Kubernetes cluster available for your workspace. It can be hosted in AWS, Google Cloud, or Microsoft Azure. Once you are in a Wayfinder workspace, you can access a cluster, and create one if needed.

This topic contains information on accessing existing clusters and creating new clusters, followed by information on more advanced cluster settings.

See also:

Managing Multi-tenant Clusters

Access a cluster


You must assume a role to access a cluster for any purpose. Role assumption is time-limited to one hour by default. After an hour you must re-assume the role, as described below, to continue working with your cluster. For more information, see Assuming Roles.

If you have one or more clusters available to your workspace, you can get kubectl access to them using the wf access cluster command.

wf access cluster does two operations (which you can also run separately):

  • Sets your kubectl context to access a cluster that your workspace owns—see wf kubeconfig
  • Performs a role assumption to grant you temporary permissions on that cluster—see wf assume and Assume a Role

You can provide all details directly, or run the command with no parameters to be prompted for details.

To access a cluster:

  1. Run the following command:

    wf access cluster CLUSTER NAMESPACE --role ROLE

    For example:

    $ wf access cluster eks-dev project-namespace --role cluster.viewer
    ◉ Waiting for role to be applied
    ✔ Access to cluster eks-dev with role cluster.viewer granted until: 30 Apr 21 19:48 BST
    ✔ Current kubectl context set to devs.eks-dev
  2. Use kubectl to access your cluster. For example:

    $ kubectl get pods -n project-namespace
    No resources found in project-namespace namespace.

Create a cluster

To create a cluster, you will need to have access to a cloud allocated to your workspace by your Wayfinder administrator, as discussed in the Cloud Accounts section.

A cluster is associated with a plan, chosen when creating the cluster. A plan represents a set of parameters that define how the cluster should be built: which features are enabled, what size it should be, etc.

Cluster plans:

  • Provide sane default settings out of the box that reflect best practices for production and nonproduction environments.
  • Remove the need for domain knowledge in development teams. They can focus on deploying their applications to staging, dev, and production environments, rather than on Kubernetes cluster types.
  • Provide guard rails for the environment options workspace members can select to keep infrastructure in line with the organization's requirements.
  • Include policies on whether various cluster settings can be edited by members of the workspace(s) the plans are allocated to.

You can customise certain cluster parameters. Depending on the policy applied by your Wayfinder administrator, you can change certain parameters to meet your workspace's requirements.

Services included in each cluster

Clusters created in Wayfinder come with the following pre-provisioned services:

If you're using multi-tenant clusters

For details on multi-tenancy in Wayfinder, see Managing Multi-tenant Clusters.

Create a cluster using the UI

To create a cluster using the UI:

  1. In the UI, ensure the correct workspace is selected in the dropdown list at the top, navigate to the Resources > Clusters page, and then click Add cluster.

    Create new cluster

  2. Select the cloud you wish to use.

    If you don't see the cloud you wish to use, contact your Wayfinder administrator to have one allocated to you.

  3. Select a Cluster stage, based on whether you're using this cluster for production or other purpose.

  4. Select whether to use a new account managed in Wayfinder (preferred), or to use an existing account.

    If there is only one account option, it will be prepopulated in the form.

  5. Select a cluster plan. You can click View plan details to learn more about the plan.

    If the Wayfinder administrator has enabled cost estimates, you see a breakdown of estimated costs for this cluster as configured.


    If a GKE cluster is set to Private cluster, you see an additional cost estimate for GKE cloudNAT.

  6. Change the cluster name if you wish.

  7. (Optional) If you select Show advanced options you see advanced options that you are permitted to adjust. Otherwise, default options are used.

    Show advanced options button

    DescriptionSelect an appropriate description so that developers can easily choose the right plan for them when creating a cluster.
    RegionSelect a region for the cluster
    VersionAccept the default Kubernetes version (recommended) or select a different one.
    Auto-upgradeYou can enable auto-upgrade of Kubernetes on the cluster.
    Maintenance windowEnter a time of day for maintenance operations (includes auto-upgrade).
    Expiry (TTL)Select whether you want this cluster to be deleted after an amount of time. If yes, enter a time interval. The expiry time is displayed on the Clusters page.
    Private clusterYou can enable this as a private cluster. For details, see How to set up private clusters for your cloud provider.
    Authorized master networksConfigure the networks allowed to speak to the Wayfinder control plane. If left blank, this defaults to all networks.
    Authorized networksConfigure the networks allowed to connect to the cluster.
    • Node network
    • Services network
    • Pod network
    Enter network ranges for these networks. Supported network types depend on the cloud provider, and whether or not you have allocated IP address ranges for this cloud provider. If you have allocated IP address ranges, you can auto-assign the network range(s), or use a custom range. For more information, see Add a network allocation.
    AddonsEnable additional features.
    Node poolsAdd, edit, or delete node pool configurations as needed.
    Enable quota limitsFor multi-tenant clusters. When enabled, this lets you add resource quota templates for tenant namespaces. These templates are similar on both the cluster plan and the cluster settings, except that as a Wayfinder administrator, you can decide whether to allow workspaces to change the template settings. For details, see Set resource quotas and constraints in the Multi-Tenancy topic.
    Remaining settingsThe rest of the settings are dependent on the cloud provider–configure as needed.

    Network settings for the cluster are not changeable once the cluster is created. To set these, see Configure cluster network settings below.

  8. Once you have selected a plan, and adjusted any advanced options if desired/permitted, click Next.

    At this point the cluster creation process begins.

  9. (Optional) To create a namespace, enter its name, and then click Next.

    Create a namespace

    Otherwise, click Cancel to create a namespace later.

Once you're finished, the Clusters page is displayed, where you can see the progress of the cluster creation.

Create a cluster using the CLI

When building a cluster with the CLI you must specify a cloud account to use, and the account must be allocated to your workspace. You must also provide a cluster plan.

To view available cloud accounts and cluster plans:

  1. To see your workspace's cloud accounts, run:

    wf get cloudaccounts -w WORKSPACEID

    Contact your Wayfinder administrator if you do not have an allocated cloud account for the cloud you wish to use, and they can allocate one.

  2. To see the available cluster plans, run

    wf get plans

    If you wish to understand all of the parameters included in a plan, run:

    wf get plan plan-name -o yaml

To create a cluster:

  1. Run wf create cluster as follows:


    For example:

    wf create cluster mycluster -w workspace1 -p gke-development -a my-gcporg-name

    If you need to specify any parameters, use the --param argument. For example:

    wf create cluster mycluster -w workspace1 -p gke-development -a my-gcporg-name --param authProxyAllowedIPs='["","2,2,2,2"]'

    Only parameters that are permitted to be edited by the policies set up by the Wayfinder administrator can be set.

  2. To list all of your workspace's clusters, run wf get clusters -w WORKSPACEID.

    If you wish to see more details about a specific cluster, run wf get cluster -w WORKSPACEID CLUSTERNAME -o yaml.

Create a namespace

A namespace is the environment within a cluster where you will deploy your apps.

To create a namespace:

  1. In the Wayfinder UI, navigate to Resources > Clusters, and then click the name of the cluster where you want to create the namespace.

    The Namespaces page is displayed.

  2. Click Add namespace, enter a name, and then click Save.

    Your new namespace is listed.

CLI: wf create namespace

Delete a namespace


Deleting a namespace deletes any deployed apps and resources in that namespace. We recommend that before you delete a namespace you run kubectl get services and kubectl get pods to see what is currently in the namespace. For more information on these commands, see the Kubernetes documentation.

To delete a namespace:

  1. In the Wayfinder UI, navigate to Resources > Clusters, and then click the name of the cluster where you want to delete the namespace.
  2. Find the namespace you want to deletle, and then click Delete for that namespace.
  3. Verify the deletion by typing the name of the namespace, and then click Delete.

CLI: wf delete namespace

Manage cluster labels

Labels are key:value pairs in Kubernetes. You can use cluster labels in user access policies to constrain the policies to include/exclude clusters with specific labels. For more information, see Creating Assumption Policies.

To manage labels for a cluster:

  1. In the Wayfinder UI, navigate to Resources > Clusters, find your cluster, and then click Labels.


  2. You can do the following:

    • Enter a new Label name and Label value in the fields provided.
    • To add more labels, for each one, click Add label, and then enter the name and value.
    • To remove a label, click the minus sign next to it.
  3. When done, click Save.

Create spot/preemptible node pools

Spot or preemptible VMs provide a cost-saving way to run workloads that can tolerate interruption, because spot instances are not guaranteed to be available from the cloud provider. For example, they are appropriate for use with batch processing jobs, or fault-tolerant testing environments.

Currently, you can add spot or preemptible node pools on GCP and Azure clusters.

For more information, see:

To add a spot nodepool:

  1. In the Wayfinder UI navigate to Resources > Clusters, and then click View on the cluster you want to add the nodepool to.

  2. Click Settings > Edit.

  3. Click Add node pool and fill out the form provided:

    • For Azure, in the Mode field, you must select User, and turn on the Spot button.
    • For GCP, turn on the Preemptible button.
  4. Click OK, and then click Save on the Settings page.

Control which IPs can access your cluster

An IP whitelist may already be in place at the cluster plan level. However, if the Wayfinder admin allows it, you can create an IP whitelist to specify that only specific IPs can access your cluster and its resources. An IP whitelist may already be in place at the cluster plan level.

To create an IP whitelist:

  1. In the Wayfinder UI, navigate to Resources > Clusters.

  2. Create or edit a cluster, and in the cluster settings, toggle to Show advanced options.

    Advanced Settings

  3. Scroll down to Authorized networks.

    Authorized Networks

    The existing default setting lets all networks access the cluster.

  4. For every IP permitted to access your cluster, click Add network, and then enter a name and the IP address.


    Be sure to remove the default setting.

  5. Save your settings when done.

Configure cluster network settings

There are two factors that determine your options for network settings on a cluster:

  • You can change default network settings if the cluster plan allows it.
  • Your Wayfinder administrator can configure network IP range allocations. If these have been configured, the cluster network ranges can be auto-assigned, or you can provide a custom IP range.

The network types for which you can provide IP ranges are:

CloudSupported network types
AKSNodes, Services
GKENodes, Services, Pods

The cluster network settings below cannot be changed once the cluster is created.

To configure network settings:

  1. In the Wayfinder UI, navigate to Resources > Clusters.

  2. Create or edit a cluster, and in the cluster settings, toggle to Show advanced options.

  3. Scroll down to Cluster network.

    Depending on your Wayfinder admin network allocations, and if permitted, you can set the following to Auto-assign or Custom:

    • Cluster network–This is the node network. Available for all clouds. Optionally, you can provide a Network CNI provider.
    • Service network–This is the network for services. Available for AKS and GKE.
    • Pod network–This is the network for pods. Available for GKE.

Upgrade Kubernetes on a cluster

If the Wayfinder admin allows it, you can select whether to upgrade the Kubernetes version on a cluster either automatically or manually. The option to enable Auto-upgrade is available when you create or edit a cluster.

Enable cluster auto-upgrade

You can enable auto-upgrade on a cluster if your cluster plan allows it.

To enable auto-upgrade on a cluster:

  1. In the Wayfinder UI, navigate to Resources > Clusters.
  2. Create or edit a cluster, and in the cluster settings, toggle to Show advanced options.
  3. Scroll down to Auto-upgrade, and then click Enabled.
  4. In the Maintenance window field, enter a time of day when maintenance (upgrade) should occur.
  5. Save your settings.

See available upgrades

You can see whether an upgrade is available in the Wayfinder UI, on the Clusters page.

Upgradable Cluster

When there's a Kubernetes update available for a cluster, it is displayed as upgradable.

  • If you enabled auto-upgrade
    The message displayed when there is an upgrade is Upgrade available: Scheduled. Hover over this message with your mouse to see the next scheduled maintenance window.

  • If you have not enabled auto-upgrade
    The message displayed when there is an upgrade is Upgrade available: Not scheduled. To upgrade manually, edit the cluster settings and select the latest version of Kubernetes.

Delete a cluster

Deleting a cluster also deletes namespaces on that cluster, including tenant namespaces if it's a multi-tenant cluster.

To delete a cluster:

  1. In the UI, navigate to Resources > Clusters.
  2. Find the cluster you want to delete, and then click Delete cluster.

CLI: wf delete cluster CLUSTER-NAME