Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

Service

This section explains how to install and configure the Jumpstarter service in your Kubernetes cluster. The service enables centralized management of your Jumpstarter environment. Before installing, ensure you have:

  • A Kubernetes cluster available

  • kubectl installed and configured to access your cluster

  • Helm (version 3.x or newer)

  • Administrator access to your cluster (required for CRD installation)

  • Domain name for service endpoints (or use nip.io for local testing)

Note

global.baseDomain creates these service hostnames with jumpstarter.example.com:

  • grpc.jumpstarter.example.com

  • router.jumpstarter.example.com (for router endpoints)

Kubernetes with Helm

Install Jumpstarter on a standard Kubernetes cluster or OpenShift using Helm:

$ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
        --create-namespace --namespace jumpstarter-lab \
        --set global.baseDomain=jumpstarter.example.com \
        --set global.metrics.enabled=true \
        --set jumpstarter-controller.grpc.mode=ingress \
        --version=0.6.0

$ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
        --create-namespace --namespace jumpstarter-lab \
        --set global.baseDomain=jumpstarter.example.com \
        --set global.metrics.enabled=true \
        --set jumpstarter-controller.grpc.mode=route \
        --version=0.6.0

Install with OpenShift and ArgoCD

You can also use ArgoCD to install Jumpstarter in your OpenShift cluster:

First, create and label a namespace for Jumpstarter:

$ kubectl create namespace jumpstarter-lab
$ kubectl label namespace jumpstarter-lab argocd.argoproj.io/managed-by=openshift-gitops

For ArgoCD to manage Jumpstarter CRDs, create this ClusterRole and ClusterRoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
    argocds.argoproj.io/name: openshift-gitops
    argocds.argoproj.io/namespace: openshift-gitops
  name: openshift-gitops-argocd-appcontroller-crd
rules:
- apiGroups:
  - 'apiextensions.k8s.io'
  resources:
  - 'customresourcedefinitions'
  verbs:
  - '*'
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    argocds.argoproj.io/name: openshift-gitops
    argocds.argoproj.io/namespace: openshift-gitops
  name: openshift-gitops-argocd-appcontroller-crd
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: openshift-gitops-argocd-appcontroller-crd
subjects:
- kind: ServiceAccount
  name: openshift-gitops-argocd-application-controller
  namespace: openshift-gitops

Create an ArgoCD Application to deploy Jumpstarter:

Warning

The secrets jumpstarter-controller.controllerSecret and jumpstarter-controller.routerSecret must be unique for each installation. While Helm can auto-generate these, ArgoCD cannot - you must manually create these in your Jumpstarter namespace.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: jumpstarter
  namespace: openshift-gitops
spec:
  destination:
    name: in-cluster
    namespace: jumpstarter-lab
  project: default
  source:
    chart: jumpstarter
    helm:
      parameters:
      - name: global.baseDomain
        value: devel.jumpstarter.dev
      - name: global.metrics.enabled
        value: "true"
      - name: jumpstarter-controller.controllerSecret
        value: "pick-a-secret-DONT-USE-THIS-DEFAULT"
      - name: jumpstarter-controller.routerSecret
        value: "again-pick-a-secret-DONT-USE-THIS-DEFAULT"
      - name: jumpstarter-controller.grpc.mode
        value: "route"
    repoURL: quay.io/jumpstarter-dev/helm
    targetRevision: "0.6.0"

Local Cluster

If you want to test our Jumpstarter locally, you can create a local cluster using tools such as minikube and kind.

Kind is a tool for running local Kubernetes clusters using Podman or Docker containerized “nodes”.

Tip

Consider minikube for environments requiring untrusted certificates.

Find more information on the kind website.

Create a kind cluster

First, create a kind cluster config that enables nodeports to host the Services. Save this as kind_config.yaml:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
kubeadmConfigPatches:
- |
  kind: ClusterConfiguration
  apiServer:
    extraArgs:
      "service-node-port-range": "3000-32767"
- |
  kind: InitConfiguration
  nodeRegistration:
    kubeletExtraArgs:
      node-labels: "ingress-ready=true"
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 5080
    protocol: TCP
  - containerPort: 30010
    hostPort: 8082
    protocol: TCP
  - containerPort: 30011
    hostPort: 8083
    protocol: TCP
  - containerPort: 443
    hostPort: 5443
    protocol: TCP

Next, create a kind cluster using the config you created:

$ kind create cluster --config kind_config.yaml

Minikube runs local Kubernetes clusters using VMs or container “nodes”. It works across several platforms and supports different hypervisors, making it ideal for local development and testing.

Find more information on the minikube website.

Create a minikube cluster

Expand the default NodePort range to include the Jumpstarter ports:

$ minikube start --extra-config=apiserver.service-node-port-range=8000-9000

Install Jumpstarter with the CLI

The Jumpstarter CLI provides the jmp admin install command to automatically run Helm with the correct arguments, simplifying installation in your Kubernetes cluster.

Warning

Sometimes the automatic IP address detection for will not work correctly, to check if Jumpstarter can determine your IP address, run jmp admin ip. If the IP address cannot be determined, use the --ip argument to manually set your IP address.

Install Jumpstarter with default options:

$ jmp admin install --kind

$ jmp admin install --minikube

Uninstall Jumpstarter with the CLI:

$ jmp admin uninstall

To check the status of the installation, run:

$ kubectl get pods -n jumpstarter-lab --watch
NAME                                    READY   STATUS      RESTARTS   AGE
jumpstarter-controller-cc74d879-6b22b   1/1     Running     0          48s
jumpstarter-secrets-w42z4               0/1     Completed   0          48s

For complete documentation of the jmp admin install command and all available options, see the MAN pages.

Install Jumpstarter with Helm

For manual installation with Helm, use these commands:

$ export IP="X.X.X.X" # Enter the IP address of your computer on the local network
$ export BASEDOMAIN="jumpstarter.${IP}.nip.io"
$ export GRPC_ENDPOINT="grpc.${BASEDOMAIN}:8082"
$ export GRPC_ROUTER_ENDPOINT="router.${BASEDOMAIN}:8083"
$ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
    --create-namespace --namespace jumpstarter-lab \
    --set global.baseDomain=${BASEDOMAIN} \
    --set jumpstarter-controller.grpc.endpoint=${GRPC_ENDPOINT} \
    --set jumpstarter-controller.grpc.routerEndpoint=${GRPC_ROUTER_ENDPOINT} \
    --set global.metrics.enabled=false \
    --set jumpstarter-controller.grpc.nodeport.enabled=true \
    --set jumpstarter-controller.grpc.mode=nodeport \
    --version=0.6.0

$ export IP=$(minikube ip)
$ export BASEDOMAIN="jumpstarter.${IP}.nip.io"
$ export GRPC_ENDPOINT="grpc.${BASEDOMAIN}:8082"
$ export GRPC_ROUTER_ENDPOINT="router.${BASEDOMAIN}:8083"
$ helm upgrade jumpstarter --install oci://quay.io/jumpstarter-dev/helm/jumpstarter \
    --create-namespace --namespace jumpstarter-lab \
    --set global.baseDomain=${BASEDOMAIN} \
    --set jumpstarter-controller.grpc.endpoint=${GRPC_ENDPOINT} \
    --set jumpstarter-controller.grpc.routerEndpoint=${GRPC_ROUTER_ENDPOINT} \
    --set global.metrics.enabled=false \
    --set jumpstarter-controller.grpc.nodeport.enabled=true \
    --set jumpstarter-controller.grpc.nodeport.port=8082 \
    --set jumpstarter-controller.grpc.nodeport.routerPort=8083 \
    --set jumpstarter-controller.grpc.mode=nodeport \
    --version=0.6.0

To check the status of the installation, run:

$ kubectl get pods -n jumpstarter-lab --watch
NAME                                    READY   STATUS      RESTARTS   AGE
jumpstarter-controller-cc74d879-6b22b   1/1     Running     0          48s
jumpstarter-secrets-w42z4               0/1     Completed   0          48s

To uninstall the Helm release, run:

helm uninstall jumpstarter --namespace jumpstarter-lab