Merge pull request #310 from jumpstarter-dev/docs/operator-install-and-release-workflow

docs: document operator install flow and release installer workflow

Author: mangelajo

.github/workflows/release-operator-installer.yaml

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

python/docs/source/getting-started/configuration/authentication.md

@@ -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
 
@@ -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
@@ -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
@@ -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:
 
@@ -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'
 ```

python/docs/source/getting-started/installation/service/index.md

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

python/docs/source/getting-started/installation/service/service-local.md

@@ -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
@@ -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
@@ -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
@@ -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.
 
 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
 ```