Customer Onboarding

This tutorial walks through the complete journey for a new KubeOpera customer: from account creation through first app deployment in their isolated CloudSpace.

Prerequisites

• A KubeOpera account invitation or access to the sign-up page at /auth/sign-up
• An email address for verification
• No Kubernetes experience required for the onboarding steps themselves

Step 1 — Create your account

Open /auth/sign-up and fill in:

Field	Notes
Email	Used for verification and login
Username	Unique, 3+ characters
First / Last name	Used in the AI Advisor greeting
Password	Minimum 8 characters

Click Create Account. KubeOpera sends a 6-digit OTP to your email.

Google OAuth

Click Continue with Google to skip the form entirely. After OAuth, you land directly on the onboarding wizard (Step 3).

Step 2 — Verify your email

Open /auth/verify-otp. Enter the 6-digit code from your email.

• Codes expire after 10 minutes. Click Resend verification email if yours has expired.
• After a successful verification you are redirected to /auth/sign-in.

Step 3 — First login and workspace setup

Log in with your credentials. As a new Customer user:

1. KubeOpera detects that your JWT carries no tenant_id yet (CloudSpace not provisioned).
2. You are redirected to /onboarding automatically.

The onboarding wizard runs three steps:

Step 3a — Provisioning

The wizard immediately calls POST /api/kubeopera/onboarding/provision. Behind the scenes:

• A CloudSpace record is created in the auth-service database (space-{userId[:8]}).
• The CloudSpace is marked as your default workspace.
• A Tenant CR is created in the host cluster — tenant-controller picks it up and begins installing a vCluster via Helm.

You see a spinner. The CloudSpace status changes from provisioning → active once the vCluster is running (typically 60–120 seconds).

Step 3b — Confirm your space

Once provisioning completes, the wizard shows your space name and a summary. You can rename it later from /cloudspaces.

Step 3c — Go to your dashboard

Click Go to Dashboard to land on /home — your personal tenant workspace.

Step 4 — Explore your workspace

Your home dashboard (/home) shows:

• Health cards — app counts by status (healthy / degraded / stopped)
• CloudSpaces — your provisioned spaces (one by default)
• AI Advisor CTA — quick link to domain-aware recommendations

The sidebar contains only the features relevant to you as a Customer:

Section	Path	Purpose
Home	/home	Workspace overview
Cloud Spaces	/cloudspaces	Manage your vCluster environments
Monitoring → Performance	/monitoring/app-performance	App-level latency, error rate
Monitoring → Cost	/monitoring/app-cost	Your apps' resource cost
AI Advisor	/advisor	Domain-aware recommendations
Settings	/settings/profile	Profile, API keys, team
Support	/support/create	Open a support ticket

SuperAdmin is different

If you have been granted the SuperAdmin role (by a platform operator), you land on /dashboard instead — the global cluster-monitoring view. The customer workspace is not accessible to SuperAdmin accounts.

Step 5 — Deploy your first app

From the /home page, click Add App or navigate to your CloudSpace at /cloudspaces/{id}.

The app creation flow is identical to the standard App Creation Flow. All apps you create are scoped to your CloudSpace and invisible to other tenants.

Once an app is deployed:

• It appears in your CloudSpace app list
• AI Advisor begins profiling it within 10 minutes (the app-advisor discovery loop runs every 10 minutes by default)
• You can open a chat session with the AI Advisor from /advisor

Step 6 — AI Advisor first look

Navigate to /advisor. The AI Advisor:

1. Auto-detects your app's domain type from its image, labels, and environment variable names (ecommerce, ml_training, api_service, data_pipeline, auth, analytics)
2. Generates initial advice within minutes of first discovery — practical recommendations tied to your specific domain
3. Answers questions via streaming chat — ask about performance, scaling, reliability, or cost for any of your apps

The AI Advisor chat is scoped to your CloudSpace and calls only get_app_profile and get_app_advice — it has no access to cluster-wide tools. A third tool, get_app_live_metrics, is referenced in the same allowlist but isn't implemented yet, so it's currently a silent no-op rather than a real capability.

One honest caveat worth stating plainly rather than glossing over: the tenant isolation on get_app_profile/get_app_advice is enforced today only by the fact that you'd need to already know another tenant's exact namespace/name app identifier to query it — the backend doesn't yet check the caller's own tenant against the requested app. A fix moving this enforcement to the network layer (each tenant reaching only their own vCluster's advisor instance, so there's no cross-tenant app identifier reachable at all, regardless of what's asked) is designed but not yet shipped.

Common questions

My CloudSpace is stuck on "provisioning". Check the Tenant CR status in the host cluster (ask a SuperAdmin):

kubectl get tenant -n kubeopera-system

If phase is Failed, the SuperAdmin can reset it:

kubectl patch tenant <name> --type=merge \
  -p '{"status":{"phase":"Pending"}}' -n kubeopera-system

I want to rename my CloudSpace. Go to /cloudspaces, click the space, and use the rename option. Note that the underlying vCluster name (used internally) is fixed at provision time.

I want to invite a team member. Go to /settings/team and enter their email. Team members share your CloudSpace but receive their own login credentials.

My app is classified as the wrong domain type. Open /advisor, find the app, and click Override next to the domain label. Select the correct type and save. Future advice will use your selection (it takes priority over the auto-detected classification).

I need a second isolated environment (e.g., staging). Go to /cloudspaces → New Space. Each additional CloudSpace provisions a separate vCluster with independent compute, networking, and secrets.