Installation Guide
This guide provides detailed instructions for installing KubeOsprey in a Kubernetes environment.
Prerequisites
kubectlwith cluster administrator privileges- Helm v4, or Helm v3.8+ for OCI chart installation
- MySQL/PostgreSQL database, or local storage for sqlite
Installation Methods
Method 1: Helm Chart (Recommended)
Using Helm provides flexibility for configuration and upgrades:
Install from OCI registry:
helm install kube-osprey oci://ghcr.io/fadewalk/charts/kube-osprey -n kube-osprey-system --create-namespaceInstalling under the release name kube-osprey names every deployed resource kube-osprey.
Or pin a chart version for reproducible installs:
helm install kube-osprey oci://ghcr.io/fadewalk/charts/kube-osprey --version <chart-version> -n kube-osprey-system --create-namespaceCustom Installation
You can adjust installation parameters by customizing the values file:
For complete configuration, refer to Chart Values.
Install with custom values:
helm install kube-osprey oci://ghcr.io/fadewalk/charts/kube-osprey -n kube-osprey-system -f values.yamlMethod 2: YAML Manifest
For quick deployment, you can directly apply the official installation YAML:
WARNING
This method is not suitable for production environments, as it does not include any configuration related to persistence. You need to manually mount the persistence volume and set the environment variable DB_DSN=/data/db.sqlite to ensure that data is not lost. Alternatively, you can use an external database.
see Persistence Issues for more details.
kubectl apply -f https://raw.githubusercontent.com/fadewalk/kube-osprey/main/deploy/install.yamlThis method will install KubeOsprey with default configuration. For advanced customization, it's recommended to use the Helm Chart.
Accessing KubeOsprey
Port Forwarding (Testing Environment)
During testing, you can quickly access KubeOsprey through port forwarding:
kubectl port-forward -n kube-osprey-system svc/kube-osprey 8080:8080LoadBalancer Service
If the cluster supports LoadBalancer, you can directly expose the KubeOsprey service:
kubectl patch svc kube-osprey -n kube-osprey-system -p '{"spec": {"type": "LoadBalancer"}}'Get the assigned IP:
kubectl get svc kube-osprey -n kube-osprey-systemIngress (Recommended for Production)
For production environments, it's recommended to expose KubeOsprey through an Ingress controller with TLS enabled:
WARNING
KubeOsprey's log and web terminal features require websocket support. Some Ingress controllers may require additional configuration to handle websockets correctly.
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: kube-osprey
namespace: kube-osprey-system
spec:
ingressClassName: nginx
rules:
- host: kube-osprey.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: kube-osprey
port:
number: 8080
tls:
- hosts:
- kube-osprey.example.com
secretName: kube-osprey-tlsServing under a subpath (basePath)
If you want to serve KubeOsprey under a subpath (for example https://example.com/kube-osprey), use the Helm chart basePath value.
How to set it:
- In
values.yaml:
basePath: "/kube-osprey"- Or with Helm CLI:
helm install kube-osprey oci://ghcr.io/fadewalk/charts/kube-osprey -n kube-osprey-system --create-namespace --set basePath="/kube-osprey"Important notes:
- Ingress configuration: make sure your Ingress
pathsmatch the subpath and use a matching pathType (e.g.,Prefix). Example:
ingress:
enabled: true
hosts:
- host: kube-osprey.example.com
paths:
- path: /kube-osprey
pathType: Prefix- OAuth / redirects: if you enable OAuth (or any external redirect flows), update the redirect URLs in your OAuth provider to include the base path, e.g.
https://kube-osprey.example.com/kube-osprey/oauth/callback. - Environment overrides: if you provide environment variables via
extraEnvsor an existing secret, ensureKUBE_OSPREY_BASEis set consistently with thebasePathvalue (otherwise behavior may differ).
Verifying Installation
After installation, you can access the dashboard to verify that KubeOsprey is deployed successfully. The expected interface is as follows:
TIP
If you need to configure KubeOsprey through environment variables, please refer to Environment Variables.


You can complete cluster setup according to the page prompts.
Quick Setup with In-Cluster Mode
For the simplest setup, select in-cluster as the cluster type. This option automatically uses the service account credentials that KubeOsprey is running with inside the cluster, requiring no additional configuration:
- No kubeconfig needed: KubeOsprey will use its own service account to access the Kubernetes API
- Automatic authentication: Works out of the box with the default RBAC permissions
- Ideal for single-cluster deployments: Perfect when KubeOsprey is managing the same cluster it's running in
This is the recommended option for getting started quickly, especially in development or when KubeOsprey only needs to manage its own cluster.
Uninstalling KubeOsprey
Helm Uninstall
helm uninstall kube-osprey -n kube-osprey-systemYAML Uninstall
kubectl delete -f https://raw.githubusercontent.com/fadewalk/kube-osprey/main/deploy/install.yamlNext Steps
After KubeOsprey installation is complete, you can continue with: