Skip to main content


This section provides a high-level overview of Wayfinder's architecture and key concepts. Along with the elements described below, Wayfinder also uses industry standard tools and frameworks such as OPA and OIDC, and open source projects such as flux, ingress-nginx, external-dns, and cert-manager.

Wayfinder elements

Wayfinder is hosted by the customer, and can run on Kubernetes in AWS, GCP, and Azure public clouds. At a high level, Wayfinder consists of these elements:

  • Controllers implement the logic that is the Wayfinder control plane.
  • Webhooks validates and mutates all calls to Wayfinder resources.
  • API that allows users and tools to interact with WF controllers in automated, programmatic and interactive ways. The API is structured around Kubernetes Custom Resource Definitions (CRDs).
  • Command Line Interface (CLI) that allows users to trigger operations in WF and inspect resources in clusters managed by WF.
  • Web interface is a portal that allows users to explore actions and resources in Wayfinder.
  • Cache that stores cloud metadata for fast retrieval
  • Database stores audit information
  • Terranetes which is an open source project that we use to deliver cloud resource plans and provision cloud resources.
  • Other open source projects. Wayfinder makes use of several open source Kubernetes projects, including controller-runtime, cert-manager, flux, ingress-nginx, external-dns, kyverno.

Once configured, the Wayfinder platform handles:

  • Cloud access management (including cloud account automation if enabled)
  • Kubernetes cluster provisioning and autoscaling
  • Networking policy
  • Ingress
  • Certificate management
  • DNS and HTTPS
  • Generating manifests to deploy to clusters
  • Access to clusters

Wayfinder automation allows a single admin to support many teams/workspaces. Behind the scenes, the platform:

  • Creates isolated cloud accounts following least privilege best practices
  • Sets up role-based access control (RBAC) for both Wayfinder itself and the Kubernetes clusters created using Wayfinder
  • Turns off insecure options when creating Kubernetes clusters, adds network and pod security policies, and turns on auto-scaling, using Appvia's best practices. This ensures that the public cloud Kubernetes services are configured correctly for enterprise security needs.

Wayfinder concepts

The following diagram shows a more detailed view of how Wayfinder interacts and with the Kubernetes clusters it manages.

  • Wayfinder is deployed into a Kubernetes cluster. The installation creates Wayfinder's Management Cluster, shown on the right side of this diagram.

  • The Management Cluster acts as the control plane, and interacts with the Kubernetes (k8s) clusters created by your developers using Wayfinder.

  • Wayfinder is organized around developer workspaces, the cloud infrastructure available to them, and the access policies and permissions they have. So in addition to other components, Wayfinder's Management Cluster has a namespace for each workspace created in Wayfinder.

lower level architecture

You can use Wayfinder on multiple clouds. For example, you can install Wayfinder/Management Cluster on one public cloud, and have workspace members provision their Kubernetes clusters in a different public cloud.

Regardless of this choice, we recommend the following cloud configuration:

  • Use a dedicated cluster to host Wayfinder because it creates and manages namespaces as workspaces are created.
  • Install Wayfinder into a cluster that is not running other workloads.
  • Install only a single instance of Wayfinder into a cluster.
  • Set up Wayfinder to run using credentials managed entirely by AWS on EKS.

For more information, see the installation prerequisites.