Self-Serve 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

CLI quick reference for clusters and namespaces

This page shows how to manage clusters and namespaces, generally using the UI. Here is a quick reference to the equivalent CLI commands:

Task	Command
List clusters	wf get cluster
Access a cluster	wf access cluster CLUSTER-NAME See also Access a cluster
Create a cluster	wf create cluster See also Create a cluster using the CLI
Create a namespace	wf create namespace
Delete a cluster	wf delete cluster CLUSTER-NAME
Delete a namespace	wf delete namespace NAMESPACE-NAME

Access a cluster

Important

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:

• NGINX ingress (optional)
• Flux Helm Controller
• ExternalDNS
• cert-manager
• Auto-scalers: Installed for EKS, and enabled in GKE and AKS
• AKS: AAD Pod Identity
• EKS: Kubernetes metrics-server (available by default in GKE and AKS)
• EKS: Calico networking

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.

   

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.

   note

   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.

   

   Field	Description
   Description	Select an appropriate description for the cluster.
   Region	Select a region for the cluster
   Version	Accept the default Kubernetes version (recommended) or select a different one.
   Auto-upgrade	You can enable auto-upgrade of Kubernetes on the cluster.
   Maintenance window	Enter 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 cluster	You can enable this as a private cluster. For details, see How to set up private clusters for your cloud provider.
   Authorized master networks	Configure the networks allowed to speak to the control plane. If left blank, this defaults to all networks.
   Authorized networks	Configure 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.
   Addons	Enable additional features.
   Node pools	Add, edit, or delete node pool configurations as needed.
   Enable quota limits	For 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 settings	The rest of the settings are dependent on the cloud provider–configure as needed.

   important

   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.

   

   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:

   wf create cluster CLUSTERNAME -w WORKSPACEID -p PLAN-NAME -a ACCOUNT

   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='["1.1.1.1/32","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.

Make a cluster ephemeral (temporary)

Ephemeral clusters are deleted after a set time. You can make a cluster ephemeral when creating it, or afterward.

To make a cluster ephemeral:

1. Set an expiry time for the cluster in one of these two ways:

   • When creating the cluster
     After entering the basic information on the cluster, click Show advanced options, set Expiry (TTL) to Yes, and then enter the cluster's time to live (TTL) in the fields provided.

   • After creating the cluster
     In the Resources > Clusters page, click the cluster name, click Settings, and then click Edit. Set Expiry (TTL) to Yes, and then enter the cluster's time to live (TTL) in the fields provided.

     

   After this time interval the cluster is deleted.

Create and manage namespaces

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

Edit a namespace

To edit a namespace:

1. In the Wayfinder UI, navigate to Resources > Clusters, and then click the name of the cluster where you want to edit the namespace.
2. Find and expand the namespace you want to edit, click the Actions tab, and then click Edit.
3. Complete your edits and save the namespace.

CLI: wf edit namespace

Delete a namespace

caution

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 and expand the namespace you want to delete, click the Actions tab, and then click Delete.
3. Verify the deletion by typing the name of the namespace, and then click Delete.

CLI: wf delete namespace

Deploy an app into a namespace

Follow these steps to get the Kubernetes manifest details that you'll need to deploy your app into a namespace.

To get the manifest details:

1. In the UI, navigate to Resources > Clusters, click the name of the cluster you want to deploy into, and then click the Namespaces tab.

   A list of namespace in this cluster is displayed.

2. Expand the namespace you want to deploy into, and then click the Deployment Info tab.

   The Kubernetes manifest details are displayed.

Expose a deployed app via ingress

See Exposing Apps via Ingress.

Manage clusters

Edit cluster settings

To edit cluster settings:

1. In the Wayfinder UI, navigate to Resources > Clusters, and then click the name of the cluster you want to edit.
2. Click the Settings tab for this cluster, and then click the Edit button.
3. Make your changes, and then click Save.

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. You can also use labels to automate software package installations across multiple clusters. For more information on these use cases, see:

• Creating Access Policies
• Package Installation

To manage labels for a cluster:

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

   

   note

   All clusters also have the internal labels shown above. You can use these as well as your own labels to filter clusters as needed.

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.

Enable/disable cluster capabilities

Wayfinder comes with some default global packages and other capabilities that are available to clusters, for example:

• Nginx Ingress—Provides the ability to expose applications via Nginx Ingress
• Pod Security Admission (PSA) Controller—Enforces Kubernetes pod security standards. Installed and enabled on all clusters, and cannot be disabled
• Appvia Terranetes—Open source controller that manages the life-cycle of terraform resources defined and built inside Kubernetes. For details, see Appvia Terranetes.

This list will grow as Appvia adds more cluster capabilities, and the Wayfinder administrator applies more global packages and capabilities.

To enable/disable installed cluster capabilities:

1. In the UI, navigate to Resources > Clusters, click the name of a cluster, and then click the Capabilities tab.

   

2. For any capability, toggle the Enabled switch on or off.

   Some capabilities, like the PSA controller, cannot be disabled.

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:

• GCP documentation
• Azure documentation

To add a spot nodepool:

1. In the Wayfinder UI navigate to Resources > Clusters, and then click 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.

   

3. Scroll down to 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.

   caution

   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:

Cloud	Supported network types
EKS	Nodes
AKS	Nodes, Services
GKE	Nodes, Services, Pods

important

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.

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