Quickstart

This quickstart walks through the core Kupe Cloud workflow from end to end: create a cluster, connect to it, deploy an application with Argo CD, and confirm that routing, logs, and metrics are all working.

It uses kupecloud/hello-kupe, the official Kupe Cloud quickstart app. The repo is intentionally small, but it exercises the main platform paths that new users should see on day one: GitOps, HTTP routing, structured logs, and scrapeable metrics.

What you will do

1. Create a managed cluster in the Kupe Cloud console.
2. Download kubeconfig and verify access with kubectl.
3. Deploy hello-kupe with Argo CD from GitHub.
4. Confirm the generated HTTPRoute and open the app.
5. Validate health, logs, and metrics.

Before you start

• Kupe Cloud account access.
• kubectl installed locally.
• kubelogin installed if you plan to use the recommended OIDC kubeconfig flow.
• Your tenant name and the slug of the cluster you create in this guide.

Step 1: Create your cluster

In the console:

1. Open Clusters.
2. Select Create Cluster.
3. Set:
   • Cluster Name
   • Kubernetes Version
   • Resource Limits for CPU, memory, and storage
4. Leave workload placement on Shared Nodes.
5. Create the cluster and wait for the lifecycle to progress to Running.

The current self-service create flow uses a generated slug from your cluster name and defaults to a shared cluster. That is the right path for a first deployment.

Tip: The default starting values in the create form are a sensible first cluster. You can scale resource limits later once you have a workload running.

Step 2: Download kubeconfig and verify access

Once the cluster is Running:

1. Open the cluster in the console.
2. Open CLI Access.
3. Download the OIDC kubeconfig if you are working interactively, or a token kubeconfig if you need a non-interactive flow.
4. Verify access:

kubectl --kubeconfig ./<cluster>-oidc.kubeconfig get ns

If you prefer the OIDC flow, make sure kubelogin is installed locally first. For more details, see CLI Access.

Step 3: Deploy hello-kupe with Argo CD

Kupe Cloud uses a central Argo CD control plane. Each tenant gets an AppProject named after the tenant, and each managed cluster is registered as a tenant-prefixed Argo destination.

If your cluster slug is prod, use:

• project: <tenant>
• destination.name: <tenant>-<cluster-slug>

Use the registered Argo destination name here, not the cluster API server URL. Kupe registers each managed cluster in Argo CD under the tenant-prefixed name.

Apply this Application in the argocd namespace of your managed cluster:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hello-kupe
  namespace: argocd
spec:
  project: <tenant>
  source:
    repoURL: https://github.com/kupecloud/hello-kupe.git
    targetRevision: main
    path: chart/hello-kupe
    helm:
      releaseName: hello-kupe
      values: |
        tenant: <tenant>
  destination:
    name: <tenant>-<cluster-slug>
    namespace: hello-kupe
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Replace <tenant> and <cluster-slug> with your actual tenant and cluster values.

The chart deploys a Deployment, Service, and HTTPRoute, and it annotates the pod for metrics scraping automatically.

Step 4: Confirm the generated HTTPRoute

You do not need to create an HTTPRoute separately for this quickstart. The hello-kupe chart creates one for you with the default hostname pattern hello-kupe.<tenant>.kupe.cloud.

This is the route the chart creates by default:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: hello-kupe
  namespace: hello-kupe
spec:
  parentRefs:
    - name: external-gateway
      namespace: kube-system
  hostnames:
    - hello-kupe.<tenant>.kupe.cloud
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: hello-kupe
          port: 80

If you want to use a different hostname, override httpRoute.hostname in the Helm values. If you want to use your own domain, follow Custom Domains.

Step 5: Validate success

Use both the console and the cluster itself to confirm the deployment is healthy:

• Cluster lifecycle is Running.
• Argo CD reports the app as Synced and Healthy.
• kubectl get deploy,svc,httproute -n hello-kupe shows the expected resources.
• The HTTPRoute is accepted and serving traffic on hello-kupe.<tenant>.kupe.cloud.
• Grafana shows logs and metrics for the workload.

For a quick cluster-side check:

kubectl --kubeconfig ./<cluster>-oidc.kubeconfig get deploy,svc,httproute -n hello-kupe

Then open:

https://hello-kupe.<tenant>.kupe.cloud

hello-kupe emits structured background logs continuously, so you should see log data in Grafana even before you start sending real traffic to it.

Start with Grafana Dashboards for the default cluster and workload views.

Step 6: View centralised logs

hello-kupe continuously emits structured JSON logs, so it is a good first workload for checking that tenant log collection is working correctly.

In Grafana:

1. Open Explore.
2. Select the Loki datasource.
3. Run a query like:

{namespace="hello-kupe", container="hello-kupe"}

You should see both:

• request logs when you open hello-kupe.<tenant>.kupe.cloud
• synthetic background logs emitted by the app every few seconds

If you want a guided view first, open the default Logs dashboard and filter to the hello-kupe namespace before switching to Explore.

Step 7: View metrics

hello-kupe also exposes a Prometheus-style /metrics endpoint, and the chart annotates the pod so Kupe Cloud scrapes it automatically.

In Grafana:

1. Open Explore.
2. Select the Prometheus datasource.
3. Run a query like:

up{namespace="hello-kupe"}

That confirms the workload is being scraped. Then try:

hello_kupe_http_requests_total{namespace="hello-kupe"}

Open the app a few times and rerun the query to watch the counter increase.

For more on working with the default dashboards and Grafana Explore, see:

• Grafana Dashboards
• Logs
• Metrics

Next steps

• Custom Domains
• Secrets
• Notifications
• Upgrade Clusters

Further reading

• Platform Overview
• Applications Overview
• Observability Overview