Troubleshooting

If you run into any issues while deploying vCluster Platform or troubleshooting vCluster instances, this page contains some information that may help. If you're still stuck, join the Slack #vCluster channel where you can ask questions.

vCluster Platform

Flag --reset

If you need a clean vCluster Platform installation, you can use the --reset flag to tell vCluster CLI to purge any previous vCluster Platform installs:

vcluster platform start --reset    # --insecure  ...add any other `vcluster platform start` flags if needed

Debug ImageErr + ImagePullBackOff

If your vCluster Platform pods are not starting because the vCluster Platform images cannot be pulled, you may need to use a private image registry rather than pulling vCluster Platform images from over the internet.

Use port-forwarding

You can always try to connect to vCluster Platform directly and circumvent any potential networking issues introduced at the load balancer and ingress controller level.

To start port-forwarding, either use vcluster platform start or run:

kubectl port-forward deploy/loft -n vcluster-platform 8080:10443

After that you can access vCluster Platform at https://localhost:8080. You can even login with the vCluster CLI to this URL with:

vcluster platform login localhost:8080 --insecure

If you can access vCluster Platform via port-forwarding only, this is usually an indicator that the problem might be related to a misconfigured LoadBalancer or Ingress Controller.

vCluster

Debug shell

The Debug Shell opens a terminal in an ephemeral container attached to a vCluster control plane pod. When a debug shell already exists for that pod, the existing ephemeral container is reused. The debug shell container runs for up to 60 minutes and then exits. If embedded etcd is detected, environment variables and endpoints for etcdctl are automatically configured.

info

By default, Global Admins, Management Admins, and Project Admins can access Debug Shell.

Administrators can grant additional access by allowing the virtualclusterinstances/debug-shell and virtualclusterinstances/debug-shell-pods subresources. This role should be assigned to users who already have access to the virtual cluster. For example, the following project role grants access:

apiVersion: management.loft.sh/v1
kind: ClusterRoleTemplate
metadata: {}
spec:
  access:
  - users:
    - '*'
    verbs:
    - get
  clusterRoleTemplate:
    metadata: {}
    rules:
    - apiGroups:
      - management.loft.sh/v1
      resources:
      - virtualclusterinstances/debug-shell
      - virtualclusterinstances/debug-shell-pods
      verbs:
      - get
      - create
  description: |-
    Allows the user or team to access the vCluster Debug Shell without granting
    create/delete permissions on the vClusterInstance itself.
  displayName: vCluster Debug Shell
  management: true
status: {}