Connect Foyre to Your Kubernetes Cluster

What Foyre does with this access

When a requester creates a validation sandbox, Foyre uses the configured host-cluster credentials to create Kubernetes resources for a new vcluster. The requester gets a scoped kubeconfig for that virtual cluster, deploys their application, and marks the request ready for review. Reviewers can then inspect a running workload instead of approving from a description alone.

Foyre does not run the requester application itself. It orchestrates sandbox infrastructure on a cluster you own.

Prerequisites

• A Kubernetes cluster that will host validation sandboxes
• kubectl configured with admin-level access for setup
• Permission to create namespaces, service accounts, cluster roles, and cluster role bindings
• A reachable API server URL for the host cluster
• A default StorageClass, or permission to install one

1. Install a StorageClass if one is missing

vcluster needs persistent storage. First check whether your cluster already has a default StorageClass:

kubectl get sc

If no default StorageClass is present, and you are using a simple test cluster, install Rancher’s local-path provisioner:

kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml
kubectl patch storageclass local-path -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

2. Create the Foyre namespace and RBAC

This creates a service account with the permissions Foyre needs to create and remove validation environments.

kubectl create namespace foyre-system
kubectl apply -f - <<'EOF'
apiVersion: v1
kind: ServiceAccount
metadata:
  name: foyre-provisioner
  namespace: foyre-system
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: foyre-provisioner
rules:
  - apiGroups: [""]
    resources: [nodes]
    verbs: [get, list]
  - apiGroups: [authorization.k8s.io]
    resources: [selfsubjectaccessreviews]
    verbs: [create]
  - apiGroups: [""]
    resources: [namespaces, pods, services, configmaps, secrets,
                serviceaccounts, persistentvolumeclaims, events]
    verbs: ["*"]
  - apiGroups: [apps]
    resources: [statefulsets, deployments, replicasets]
    verbs: ["*"]
  - apiGroups: [batch]
    resources: [jobs]
    verbs: ["*"]
  - apiGroups: [rbac.authorization.k8s.io]
    resources: [roles, clusterroles]
    verbs: [get, list, watch, create, update, patch, delete, escalate, bind]
  - apiGroups: [rbac.authorization.k8s.io]
    resources: [rolebindings, clusterrolebindings]
    verbs: [get, list, watch, create, update, patch, delete]
  - apiGroups: [networking.k8s.io]
    resources: [networkpolicies, ingresses]
    verbs: ["*"]
  - apiGroups: [storage.k8s.io]
    resources: [storageclasses]
    verbs: [get, list]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: foyre-provisioner
subjects:
  - { kind: ServiceAccount, name: foyre-provisioner, namespace: foyre-system }
roleRef:
  { kind: ClusterRole, name: foyre-provisioner, apiGroup: rbac.authorization.k8s.io }
EOF

These permissions let Foyre manage the resources vcluster needs for each sandbox, including namespaces, workloads, services, secrets, events, jobs, RBAC resources, node lookup, access reviews, and persistent volume claims.

3. Generate a kubeconfig for Foyre

Run the command below from a shell where kubectl is already pointed at the host cluster. It reads the cluster API server and CA certificate from your current context, creates a service-account token, and prints a complete kubeconfig for Foyre.

SA_NS=foyre-system
SA_NAME=foyre-provisioner
CTX=$(kubectl config current-context)
CLUSTER=$(kubectl config view -o jsonpath="{.contexts[?(@.name==\"$CTX\")].context.cluster}")
SERVER=$(kubectl config view --raw -o jsonpath="{.clusters[?(@.name==\"$CLUSTER\")].cluster.server}")
CA=$(kubectl config view --raw --flatten -o jsonpath="{.clusters[?(@.name==\"$CLUSTER\")].cluster.certificate-authority-data}")
TOKEN=$(kubectl -n $SA_NS create token $SA_NAME --duration=8760h)

cat <<EOF
apiVersion: v1
kind: Config
clusters:
- name: foyre-host
  cluster:
    server: $SERVER
    certificate-authority-data: $CA
users:
- name: foyre-provisioner
  user:
    token: $TOKEN
contexts:
- name: foyre-host
  context:
    cluster: foyre-host
    user: foyre-provisioner
current-context: foyre-host
EOF

Copy the YAML output from the terminal. You will paste that full kubeconfig into Foyre in the next step.

4. Connect the cluster in Foyre

In the Foyre UI, go to the admin area for validation environments or host clusters. Paste the kubeconfig you created, then click Test connection before saving.

A successful connection confirms that Foyre can authenticate to the host cluster and use the kubeconfig to manage sandbox infrastructure.

5. Configure external access for requesters

Foyre exposes each validation cluster through a NodePort service. Set External node host to the hostname or IP where your cluster’s worker nodes are reachable from the requester’s machine.

Examples:

• k8s.internal.example.com
• A reachable worker node IP address
• An internal load balancer hostname that routes to worker nodes

If left blank, Foyre will use the node’s InternalIP. That may work inside the cluster network, but it may not be reachable from a requester’s laptop or workstation.

Security note

Treat this kubeconfig as infrastructure credentials. Store it only in Foyre and in your team’s approved secret management process.

Verify the connection

After saving the host cluster in Foyre, create a test validation sandbox from a submitted request.

On the host cluster, watch for namespaces and workloads created by vcluster:

kubectl get namespaces
kubectl get pods --all-namespaces

Expected result: Foyre should report the sandbox as provisioned, and you should see Kubernetes resources for the validation environment in the host cluster.