Skip to main content
Version: 2.3

Overview of Private Clusters

A private cluster is one where the Cloud Kubernetes API is not associated with any public network and has no direct public network connectivity. Workloads in private clusters run on instances located on private subnets, and have no direct public ingress. All connectivity to the Kubernetes API or the Wayfinder agent is via private networks and internal load balancers, and all traffic between the management plane (Wayfinder) and the remote cluster is via private networks.

Private clusters do not exclude public ingress, but the entry points are specific, for example, there is an ingress controller or an application gateway.


We recommend you read up on peering rules first since private cluster support relies heavily on peering mechanics.

Private cluster support in Wayfinder

Support in Wayfinder is tied to how network connectivity is established using peering rules. Once a cluster is provisioned as private, the cluster is no longer accessible by Wayfinder. So connectivity must be achieved via either direct peering or hub and spoke. Before allowing workspaces to provision private clusters, platform administrators must define how they want those networks to be connected.

Here's an example network topology showing two Wayfinder workspaces with two clusters in a private network. Wayfinder itself runs in the management cluster.

Private Clusters

Setting up private clusters

Setting up private clusters on Wayfinder includes three high-level tasks:

  • Use peering rules to define the manner in which connectivity is established to the Wayfinder instance.

  • When creating the cluster (or cluster plan), enable the private cluster setting using one of the following methods:

    • If using yaml, set spec.enablePrivateCluster to true.
    • If using Wayfinder's web interface enable Private cluster in the cluster settings.

  • (Highly recommended) Set up IP Management for the cloud provider, otherwise the users that define clusters will be responsible for ensuring no network conflict exist.


If you don't configure IP Management and accidentally create an overlapping network range, don't worry. In that case, the cluster and network build, but peering is actively refused. The cluster is left in limbo and has to be deleted.

For detailed instructions on using private clusters in your cloud provider, see:

Using authorized networks instead of private clusters


This is currently supported for AWS and GCP.

As an alternative to setting up private clusters and related networking, you can use the cloud vendors' support for locking down the Kubernetes API via firewall rules.

In Wayfinder this is exposed via the networking options in cluster plans:

  • Authorized master networks–IP ranges allowed to speak to the control plane
    (spec.networking.authorizedMasterNetworks in examples below)

  • Authorized networks–IP ranges allowed to speak to a cluster
    (spec.networking.authorizedNetworks in examples below)

Using these authorized networks, you can lock down the Kubernetes API exposed by the cloud vendor's external addresses for Wayfinder, and lock down the networks that can access the authentication module (the proxy that users and access token accounts go through). Authorized networks are configured in the cluster definition, and can be enforced by the cluster plan.

Configure authorized networks in AWS

Authorized networks are configured in cluster plans (or cluster settings). This procedure is focused on using yaml for cluster plans. You can also configure cluster plans in Wayfinder's web interface: Click Settings, then navigate to Developer Self-Service > Cluster plans.

To configure authorized networks in AWS:

  1. Get Wayfinder's external addresses from the management cluster:

    wf get networkfabric management -workspace admin -o yaml

    The addresses are listed in

  2. Disable the default EKS cluster plan shipped with Wayfinder:

    wf disable clusterplan PLAN-NAME

  3. Copy the disabled cluster plan as the new default plan.

  4. Plug the addresses from Step 1 into spec.networking.authorizedMasterNetworks in your new default plan.

    This ensures that only the Wayfinder instance can access the Kubernetes API.

    These are CIDR blocks, so ensure you use the correct notation, for example: ADDRESS/32. See this example AWS cluster plan.

    If using Wayfinder's web interface: In the cluster plan, set the Authorized master networks values (see image in Step 5 below).

  5. Update the ranges of the spec.networking.authorizedNetworks to only those address ranges you wish to have access.

    Here you are locking down where users and access token accounts can source from.

    If using Wayfinder's web interface: In the cluster plan, set the Authorized networks values (see image in step 5 below).

  6. In the cluster plan, ensure that these values cannot be changed.

    If using YAML:

    Set editable to false for the authorized networks, under policies in the cluster plan:

    - editable: false
    path: spec.networking.authorizedMasterNetworks
    - editable: false
    path: spec.networking.authorizedNetworks

    For a more detailed yaml cluster plan, see this example.

    If using Wayfinder's web interface:

    In the cluster plan, uncheck the checkboxes that allow workspaces to change Authorized master networks and Authorized networks:

    Authorized networks

Configure authorized networks in GCP

To configure authorized networks in GCP:

  1. Get Wayfinder's external addresses from the management cluster:

    wf get networkfabric management -workspace admin -o yaml

    The addresses are listed in status.gcp.gateways.

  2. Follow the same flow as above, except disable the default GKE cluster plan and create a new one for GKE private clusters.