Skip to content

docs: document operator install flow and release installer workflow #310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mangelajo merged 2 commits into from
Mar 12, 2026
Merged

docs: document operator install flow and release installer workflow #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c28d7fe
docs: switch service installation guidance to operator flow
mangelajo Mar 11, 2026
292923f
docs: fix auth validation text and platform-specific verify commands
mangelajo Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/release-operator-installer.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: Release operator installer

on:
release:
types: [published]

permissions:
contents: write

jobs:
publish-operator-installer:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Set up Go
uses: actions/setup-go@v5
with:
go-version-file: controller/deploy/operator/go.mod

- name: Build operator installer manifest
env:
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
VERSION="${RELEASE_TAG#v}"
IMG="quay.io/jumpstarter-dev/jumpstarter-operator:${VERSION}"
make -C controller/deploy/operator build-installer IMG="${IMG}"
cp controller/deploy/operator/dist/install.yaml operator-installer.yaml

- name: Upload installer to release assets
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
RELEASE_TAG: ${{ github.event.release.tag_name }}
run: |
gh release upload "${RELEASE_TAG}" operator-installer.yaml --clobber
185 changes: 94 additions & 91 deletions python/docs/source/getting-started/configuration/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,15 @@ Jumpstarter uses internally issued JWT tokens to authenticate clients and
exporters by default. You can also configure Jumpstarter to use external OpenID
Connect (OIDC) providers.

When installing with the operator, authentication is configured directly on the
`Jumpstarter` custom resource, under `spec.authentication`.

For operator installation context, see
[Install with Operator](../installation/service/service-operator.md).

To use OIDC with your Jumpstarter installation:

1. Set the helm value `jumpstarter-controller.authenticationConfiguration` to a
valid `AuthenticationConfiguration` yaml configuration
1. Set `spec.authentication.jwt` on your `Jumpstarter` resource
2. Configure your OIDC provider to work with Jumpstarter
3. Create users with appropriate OIDC usernames

Expand All @@ -22,22 +27,21 @@ Set up Keycloak for Jumpstarter authentication:
- `Valid redirect URIs`: `http://localhost/callback`
- Leave remaining fields as default

2. Use this configuration for
`jumpstarter-controller.authenticationConfiguration` during installation:
2. Configure `spec.authentication.jwt` on your `Jumpstarter` resource:

```yaml
apiVersion: jumpstarter.dev/v1alpha1
kind: AuthenticationConfiguration
jwt:
- issuer:
url: https://<keycloak domain>/realms/<realm name>
certificateAuthority: <PEM encoded CA certificates>
audiences:
- jumpstarter-cli
claimMappings:
username:
claim: preferred_username
prefix: "keycloak:"
spec:
authentication:
jwt:
- issuer:
url: https://<keycloak domain>/realms/<realm name>
certificateAuthority: <PEM encoded CA certificates>
audiences:
- jumpstarter-cli
claimMappings:
username:
claim: preferred_username
prefix: "keycloak:"
```

Note, the HTTPS URL is mandatory, and you only need to include
Expand Down Expand Up @@ -172,20 +176,20 @@ $ helm install --namespace dex --wait -f values.yaml dex dex/dex
`jumpstarter-controller.authenticationConfiguration` during installation:

```yaml
apiVersion: jumpstarter.dev/v1alpha1
kind: AuthenticationConfiguration
jwt:
- issuer:
url: https://dex.dex.svc.cluster.local:5556
audiences:
- jumpstarter-cli
audienceMatchPolicy: MatchAny
certificateAuthority: |
<content of pki/ca.crt>
claimMappings:
username:
claim: "name"
prefix: "dex:"
spec:
authentication:
jwt:
- issuer:
url: https://dex.dex.svc.cluster.local:5556
audiences:
- jumpstarter-cli
audienceMatchPolicy: MatchAny
certificateAuthority: |
<content of pki/ca.crt>
claimMappings:
username:
claim: "name"
prefix: "dex:"
```

4. Create clients and exporters with appropriate OIDC usernames. Prefix the full
Expand Down Expand Up @@ -225,9 +229,8 @@ $ jmp login --exporter <exporter alias> \

## Reference

The reference section provides a complete example of an
`AuthenticationConfiguration` resource with detailed comments. Use this as a
template for creating your own configuration.
The reference section provides a complete example of `spec.authentication.jwt`
with detailed comments. Use this as a template for your `Jumpstarter` resource.

Key components include:

Expand All @@ -237,62 +240,62 @@ Key components include:
- User validation rules

```yaml
apiVersion: jumpstarter.dev/v1alpha1
kind: AuthenticationConfiguration
# JWT authenticators for OIDC-issued tokens
jwt:
- issuer:
# URL of the OIDC provider (must use https://)
url: https://example.com
# Optional: override URL for discovery information
discoveryURL: https://discovery.example.com/.well-known/openid-configuration
# Optional: PEM encoded CA certificates for validation
certificateAuthority: <PEM encoded CA certificates>
# List of acceptable token audiences
audiences:
- my-app
- my-other-app
# Required when multiple audiences are specified
audienceMatchPolicy: MatchAny
# rules applied to validate token claims to authenticate users.
claimValidationRules:
# Validate specific claim values
- claim: hd
requiredValue: example.com
# Alternative: use CEL expressions for complex validation
- expression: 'claims.hd == "example.com"'
message: the hd claim must be set to example.com
- expression: 'claims.exp - claims.nbf <= 86400'
message: total token lifetime must not exceed 24 hours
# Map OIDC claims to Jumpstarter user properties
claimMappings:
# Required: configure username mapping
username:
# JWT claim to use as username
claim: "sub"
# Prefix for username (required when claim is set)
prefix: ""
# Alternative: use CEL expression (mutually exclusive with claim+prefix)
# expression: 'claims.username + ":external-user"'
# Optional: configure groups mapping
groups:
claim: "sub"
prefix: ""
# Alternative: use CEL expression
# expression: 'claims.roles.split(",")'
# Optional: configure UID mapping
uid:
claim: 'sub'
# Alternative: use CEL expression
# expression: 'claims.sub'
# Optional: add extra attributes to UserInfo
extra:
- key: 'example.com/tenant'
valueExpression: 'claims.tenant'
# validation rules applied to the final user object.
userValidationRules:
- expression: "!user.username.startsWith('system:')"
message: 'username cannot used reserved system: prefix'
- expression: "user.groups.all(group, !group.startsWith('system:'))"
message: 'groups cannot used reserved system: prefix'
spec:
authentication:
# JWT authenticators for OIDC-issued tokens
jwt:
- issuer:
# URL of the OIDC provider (must use https://)
url: https://example.com
# Optional: override URL for discovery information
discoveryURL: https://discovery.example.com/.well-known/openid-configuration
# Optional: PEM encoded CA certificates for validation
certificateAuthority: <PEM encoded CA certificates>
# List of acceptable token audiences
audiences:
- my-app
- my-other-app
# Required when multiple audiences are specified
audienceMatchPolicy: MatchAny
# rules applied to validate token claims to authenticate users.
claimValidationRules:
# Validate specific claim values
- claim: hd
requiredValue: example.com
# Alternative: use CEL expressions for complex validation
- expression: 'claims.hd == "example.com"'
message: the hd claim must be set to example.com
- expression: 'claims.exp - claims.nbf <= 86400'
message: total token lifetime must not exceed 24 hours
# Map OIDC claims to Jumpstarter user properties
claimMappings:
# Required: configure username mapping
username:
# JWT claim to use as username
claim: "sub"
# Prefix for username (required when claim is set)
prefix: ""
# Alternative: use CEL expression (mutually exclusive with claim+prefix)
# expression: 'claims.username + ":external-user"'
# Optional: configure groups mapping
groups:
claim: "sub"
prefix: ""
# Alternative: use CEL expression
# expression: 'claims.roles.split(",")'
# Optional: configure UID mapping
uid:
claim: 'sub'
# Alternative: use CEL expression
# expression: 'claims.sub'
# Optional: add extra attributes to UserInfo
extra:
- key: 'example.com/tenant'
valueExpression: 'claims.tenant'
# validation rules applied to the final user object.
userValidationRules:
- expression: "!user.username.startsWith('system:')"
message: 'username cannot use reserved system: prefix'
- expression: "user.groups.all(group, !group.startsWith('system:'))"
message: 'groups cannot use reserved system: prefix'
```
3 changes: 3 additions & 0 deletions python/docs/source/getting-started/installation/service/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,13 @@ For most users, we recommend starting with a **local installation** to get famil

service-local.md
service-production.md
service-operator.md
```

## Quick Start

**New to Jumpstarter?** Start with the [Local Installation](service-local.md) guide to get up and running quickly on your development machine.

**Ready for production?** See the [Production Deployment](service-production.md) guide for Kubernetes and OpenShift clusters with proper security, monitoring, and ingress configurations.

**Installing with the Kubernetes operator?** Use [Install with Operator](service-operator.md) for `Jumpstarter` CR examples using Kubernetes Ingress or OpenShift Routes.
56 changes: 2 additions & 54 deletions python/docs/source/getting-started/installation/service/service-local.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ Before installing locally, ensure you have:

- Docker or Podman installed (for kind)
- `kubectl` installed and configured to access your cluster
- [Helm](https://helm.sh/docs/intro/install/) (version 3.x or newer)
- Administrator access to your cluster (required for CRD installation)

## Install with Jumpstarter CLI
Expand Down Expand Up @@ -56,7 +55,6 @@ Additional options for cluster creation:

- Custom cluster name: Specify as the first argument (default: `jumpstarter-lab`)
- `--kind <PATH>`: Path to the kind binary to use for cluster management
- `--helm <PATH>`: Path to the Helm binary to install the Jumpstarter service with
- `--force-recreate`: Force recreate the cluster if it already exists (destroys all data)
- `--kind-extra-args`: Pass additional arguments to kind cluster creation
- `--skip-install`: Create the cluster without installing Jumpstarter
Expand All @@ -72,7 +70,6 @@ Additional options for cluster creation:

- Custom cluster name: Specify as the first argument (default: `jumpstarter-lab`)
- `--minikube <PATH>`: Path to the minikube binary to use for cluster management
- `--helm <PATH>`: Path to the Helm binary to install the Jumpstarter service with
- `--force-recreate`: Force recreate the cluster if it already exists (destroys all data)
- `--minikube-extra-args`: Pass additional arguments to minikube cluster creation
- `--skip-install`: Create the cluster without installing Jumpstarter
Expand Down Expand Up @@ -211,61 +208,12 @@ $ minikube start --extra-config=apiserver.service-node-port-range=8000-9000
```
````

### Install Local Jumpstarter with Helm
### Install Local Jumpstarter with Operator

For manual installation with Helm, use these commands:

````{tab} kind
```{code-block} console
:substitutions:
$ 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={{controller_version}}
```
````

````{tab} minikube
```{code-block} console
:substitutions:
$ 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={{controller_version}}
```
````
For manual installation after creating the local cluster, follow [Install with Operator](service-operator.md). Use a `baseDomain` and endpoint addresses appropriate for your local environment (for example, `nip.io` based hostnames), then apply your `Jumpstarter` CR.
Comment thread
mangelajo marked this conversation as resolved.

To check the status of the installation, run:

```{code-block} console
$ 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:

```{code-block} console
$ helm uninstall jumpstarter --namespace jumpstarter-lab
```
Loading
Loading