Skip to main content
Version: 3.0.0-alpha (Diátaxis)

🚀 Quick Start with Hikube

Welcome! This guide will walk you through creating your first project on Hikube. By the end of this tutorial, you will have deployed your first application in a completely secure environment.

Prerequisites​

Platform Access​

If you don't have a Hikube account yet, contact our team at sales@hidora.io to get your access.

Required Tools Installation​

kubectl (required)​

macOS

# Homebrew
brew install kubectl

Linux

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y kubectl

# RHEL/CentOS/Fedora
sudo dnf install kubectl
# or for older versions
sudo yum install kubectl

# Alpine Linux
sudo apk add kubectl

Windows

# Chocolatey
choco install kubernetes-cli

# winget
winget install Kubernetes.kubectl

📖 Official documentation : Install kubectl

kubelogin (required for OIDC authentication)​

kubelogin is a kubectl plugin for OpenID Connect (OIDC) authentication.

macOS / Linux (Homebrew)

brew install kubelogin

Krew (macOS, Linux, Windows)

kubectl krew install oidc-login

Windows (Chocolatey)

choco install kubelogin

📖 Official documentation: int128/kubelogin

Warning

Do not use the Azure kubelogin (Azure/kubelogin). Hikube uses standard OIDC authentication and requires the int128/kubelogin plugin.

For a better Kubernetes management experience:

  • Lens - Modern graphical interface for Kubernetes
  • K9s - Interactive terminal interface for Kubernetes
  • Helm - Package manager for Kubernetes
  • kubectx + kubens - Tools to quickly switch context and namespace

Step 1: Access Your Tenant​

kubectl Configuration​

  1. Retrieve your kubeconfig from your Hikube administrator
  2. Configure kubectl with your configuration file: 
    # Option 1: Environment variable
    export KUBECONFIG=/path/to/your/hikube-kubeconfig.yaml

    # Option 2: Copy to default directory
    cp hikube-kubeconfig.yaml ~/.kube/config
  3. Verify the connection: 
    kubectl get pods
Multiple Configuration

You can manage multiple clusters with kubectl config get-contexts and kubectl config use-context <context-name>

Tenant Verification​

Your tenant is your isolated workspace. Verify that you are in the correct context:

kubectl config current-context
Do not use -A / --all-namespaces

The -A (--all-namespaces) flag performs a cluster-scoped request, which is forbidden for tenant users. Always run commands without -A: your kubeconfig already targets your namespace.

Step 2: Create Your First Kubernetes Cluster​

Deployment via kubectl​

  1. Create a YAML file for your Kubernetes cluster
  2. Customize the configuration according to your needs
  3. Deploy with kubectl:
apiVersion: apps.cozystack.io/v1alpha1
kind: Kubernetes
metadata:
  name: kube
spec:
  addons:
    certManager:
      enabled: true
      valuesOverride: {}
    fluxcd:
      enabled: false
      valuesOverride: {}
    ingressNginx:
      enabled: true
      hosts:
      - my-app.example.com
      valuesOverride: {}
    monitoringAgents:
      enabled: false
      valuesOverride: {}
    verticalPodAutoscaler:
      valuesOverride: {}
  controlPlane:
    replicas: 3
  host: k8s-api.example.com
  kamajiControlPlane:
    addons:
      konnectivity:
        server:
          resources: {}
          resourcesPreset: small
    apiServer:
      resources: {}
      resourcesPreset: small
    controllerManager:
      resources: {}
      resourcesPreset: small
    scheduler:
      resources: {}
      resourcesPreset: small
  nodeGroups:
    md0:
      ephemeralStorage: 30Gi
      instanceType: u1.large
      maxReplicas: 6
      minReplicas: 3
      roles:
      - ingress-nginx
  storageClass: replicated
  1. Deploy the cluster: 
    # Save the configuration in a file
    kubectl apply -f my-kubernetes-cluster.yaml

⏳ Deployment Monitoring​

  • The cluster will be ready in 1-3 minutes
  • Monitor the status with kubectl: 
    kubectl get kubernetes
    kubectl describe kubernetes kube
  • Status "Ready" = Cluster operational ✅

DNS Configuration​

Required DNS Records​

For your cluster to be accessible, you must create the following DNS records with your DNS provider:

# Retrieve the public IP of your cluster via Ingresses
kubectl get ingress

Expected output:

NAME                            CLASS           HOSTS                 ADDRESS        PORTS   AGE
kubernetes-kube                 tenant-myco     k8s-api.example.com   91.x.x.x      80      2m
kubernetes-kube-ingress-nginx   tenant-myco     my-app.example.com    91.x.x.x      80      2m

Create the DNS records with your DNS provider:

Type A: k8s-api.example.com → <ADDRESS>
Type A: my-app.example.com → <ADDRESS>
DNS Configuration
  • k8s-api.example.com : Kubernetes API access point
  • my-app.example.com : Domain for your applications via Ingress
  • Replace example.com with your actual DNS zone

Step 3: Retrieve the Kubeconfig​

Cluster Kubeconfig Extraction​

Once your cluster is deployed and ready, retrieve its credentials with this command:

# Retrieve the kubeconfig of the created cluster (adjust the cluster name)
kubectl get secret kubernetes-<clusterName>-admin-kubeconfig \
  -o go-template='{{ printf "%s\n" (index .data "admin.conf" | base64decode) }}' > admin.conf

# Concrete example with the "kube" cluster:
kubectl get secret kubernetes-kube-admin-kubeconfig \
  -o go-template='{{ printf "%s\n" (index .data "admin.conf" | base64decode) }}' > admin.conf
Variable to Customize
  • <clusterName> : Replace with your cluster name (e.g., kube according to the YAML manifest)

Local Configuration​

# Use the new cluster's kubeconfig
export KUBECONFIG=./admin.conf

# Verify connection to the created cluster
kubectl get nodes
note

This command will only work after you have configured the DNS records (previous section). Worker nodes may take a few additional minutes to appear.

Congratulations!

Your Kubernetes cluster is now operational with native high availability!

Summary​

You have created:

  • A high-availability Kubernetes cluster
  • A completely secure environment (network isolation)
  • Resilient storage (automatic replication)

Need Help?​

Documentation​

Support​

  • Email: support@hidora.io
  • Documentation: This platform
  • Community: Forums and real-time chat
Well Done! 🎊

You've just taken your first steps on Hikube. Your infrastructure is now ready to host all your most ambitious projects!

Recommended next step: 📖 Key Concepts → Master Hikube fundamentals