Skip to content

Install in an existing Kubernetes cluster

This advanced route installs cluster components only. It does not install Ubuntu, K3s, host mDNS, systemd workers or the physical setup console.

Before you start

  • You administer the cluster and have a working cluster-admin kubeconfig.
  • kubectl, Helm and the Flux CLI are installed; use Bash/Python 3 or PowerShell 7.
  • A default StorageClass can provision persistent volumes.
  • A LoadBalancer can assign Envoy a reachable private address, with ports 443 and temporary 9443 available.
  • You have reviewed the cluster, container-runtime and GPU-provider compatibility for this release. Existing Kubernetes is not upgraded by these scripts.

Do not remove a shared gateway/controller just to install Magic Stick. Allocate a separate address when necessary. Back up cluster state and confirm the kubeconfig context before proceeding.

Install with the wrapper

curl -fsSL https://raw.githubusercontent.com/QualityMinds/AIppliance-Magic-Stick/main/deploy-on-k8s.sh \
  -o /tmp/deploy-on-k8s.sh
less /tmp/deploy-on-k8s.sh
bash /tmp/deploy-on-k8s.sh --context "$(kubectl config current-context)" --preflight-only
bash /tmp/deploy-on-k8s.sh --context "$(kubectl config current-context)"

Or with PowerShell 7:

Invoke-WebRequest https://raw.githubusercontent.com/QualityMinds/AIppliance-Magic-Stick/main/deploy-on-k8s.ps1 -OutFile $env:TEMP\deploy-on-k8s.ps1
Get-Content $env:TEMP\deploy-on-k8s.ps1
pwsh $env:TEMP\deploy-on-k8s.ps1 -Context (kubectl config current-context) -PreflightOnly
pwsh $env:TEMP\deploy-on-k8s.ps1 -Context (kubectl config current-context)

Use --ref <release-tag> or -Ref <release-tag> for a selected release. The wrapper checks existing appliance/Flux ownership and stops rather than overwriting another source tree. It installs the matching Gateway CRDs without forcing field ownership. Resolve any conflict with the platform owner; do not bypass it with --force-conflicts.

Complete setup

The bootstrap terminal prints a one-time code and setup address. Kubernetes stores the claim hash, not its plaintext. Connect over your private administration network, verify the certificate fingerprint, then follow first administrator setup. Do not open 9443 publicly. mDNS is optional and often unavailable in routed networks.

If bootstrap is interrupted, rerun the same wrapper with the same source/version options. Its bounded resume state preserves the installation identity. Do not manually regenerate setup state on a completed installation.

Verify and troubleshoot

kubectl get nodes
kubectl -n flux-system get gitrepositories,kustomizations,helmreleases
kubectl -n identity-system get appliancesetup local
kubectl get svc -A

Continue with installation verification. Host-only controls may be unavailable: that is expected when your platform does not run the Magic Stick host worker. For optional user-facing cluster access, follow Kubernetes SSO access.

The reviewed manual implementation lives in deploy-on-k8s.sh and deploy-on-k8s.ps1. For custom source ownership, use advanced GitOps integration.

Removal

Plan data retention and review generated resources with the cluster owner before removal. Do not delete shared CRDs, Flux, namespaces or storage as a generic uninstall step. See backup and recovery.