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 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

OpenShift with Helm¶

Install Jumpstarter on an OpenShift cluster 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=route \
          --version=0.6.0

OpenShift with ArgoCD¶

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 with Minikube¶

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’s jmp admin install command simplifies installation in your Kubernetes cluster.

Use the minikube IP address when installing with the CLI:

$ jmp admin install --ip $(minikube ip)

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=$(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

Local cluster with kind¶

To try the Jumpstarter Controller on your local machine, run a local Kubernetes cluster for development purposes.

kind is a tool for running local Kubernetes clusters using Podman or Docker container “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

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.

Install Jumpstarter with default options:

$ jmp admin install

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

Install Jumpstarter with Helm¶

If you prefer manual installation with Helm, use the following commands:

$ export IP="X.X.X.X"
$ 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