CI/CD for Ilum Interactive Services with GitHub Actions

This guide demonstrates how to automate the deployment of Ilum Interactive ServicesUtilisant GitHub Actions with self-hosted runners running directly on your Kubernetes cluster. By combining the Ilum REST API with a CI/CD pipeline, you can deploy and update services automatically on every push or merge.

Conditions préalables ​

• A running Ilum instance on Kubernetes (with all pods healthy)
• kubectl et helm configured for your cluster
• A GitHub account with permissions to create repositories and personal access tokens
• cert-manager installed on the cluster

Step 1: Install cert-manager​

Actions Runner Controller requires cert-manager for TLS certificate management. Install it if not already present:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.2/cert-manager.yaml

Wait for all cert-manager pods to be ready:

kubectl wait --for=condition=Ready pods --all -n cert-manager --timeout=120s

Step 2: Create a GitHub Personal Access Token​

The self-hosted runner needs a GitHub token to register itself with your repository.

1. Navigate to GitHub → Settings → Developer Settings → Personal access tokens → Tokens (classic).
2. Cliquer Generate new token (classic).
3. Set a descriptive name (e.g., ServiceManagementToken).
4. Select the repo scope (full control of private repositories).
5. Cliquer Generate token and copy the value immediately — you won't see it again.

Step 3: Install Actions Runner Controller (ARC)​

3.1 Add the Helm Repository​

helm repo add actions-runner-controller \
  https://actions-runner-controller.github.io/actions-runner-controller

3.2 Create the Namespace and Secret​

# Create namespace for runners
kubectl create ns arc-runners

# Store the GitHub token as a Kubernetes secret
kubectl create secret generic github-token \
  --namespace arc-runners \
  --from-literal=github_token=<YOUR_GITHUB_TOKEN>

3.3 Install ARC via Helm​

helm install arc \
  actions-runner-controller/actions-runner-controller \
  --namespace arc-runners \
  --set authSecret.create=false \
  --set authSecret.name=github-token

Step 4: Create a Runner Deployment​

Créez un runner-deployment.yaml file that tells ARC to spawn a self-hosted runner for your repository:

apiVersion :  actions.summerwind.dev/v1alpha1
gentil :  RunnerDeployment
métadonnées : 
  nom : ilum - demo- runner
  Namespace :  arc- runners
Spec : 
  Répliques :  1 
  modèle : 
    Spec : 
      dépôt : <votre - org> /IlumServiceManagment
      Étiquettes : 
        - même - hosted
        -  linux

Apply it:

kubectl apply -f runner-deployment.yaml

The runner pod will register itself with GitHub and appear in your repository's Settings → Actions → Runners as an available self-hosted runner.

Step 5: Create the Service Repository​

Create a new GitHub repository (e.g., IlumServiceManagment) with the following structure:

IlumServiceManagment/
├── service.py                      # Ilum service implementation
└── .github/
    └── workflows/
        └── deploy.yml              # GitHub Actions workflow

5.1 Service Implementation (service.py) ​

This file contains the Ilum Interactive Service code. The service extends IlumJob and implements the Courir method:

De ilum . API importation IlumJob 
De Pyspark . SQL . functions importation  col,  sum comme  spark_sum


classe  SparkInteractiveExample( IlumJob ) : 
    Def  Courir ( même , étincelle , Configuration )  - >  str: 
table_name = Configuration . Avoir ( 'Table' ) 
        database_name = Configuration . Avoir ( 'database') 
        report_lines =  [ ] 

        si  non table_name : 
            raise ValueError( "Config must provide a 'table' key") 

        si  database_name: 
étincelle . catalogue . setCurrentDatabase( database_name) 
            report_lines. append( f"Using database: { database_name} " ) 

        si table_name non  dans  [ t . nom pour t dans étincelle . catalogue . listTables( ) ] : 
            raise ValueError( f"Table '{ table_name } ' not found in catalog") 

Df = étincelle . table ( table_name ) 

        report_lines. append( f"=== Details for table: { table_name }  ===") 

        total_rows = Df . compter ( ) 
        report_lines. append( f"Total rows: { total_rows} " ) 

        total_columns =  len( Df . columns) 
        report_lines. append( f"Total columns: { total_columns} " ) 

        report_lines. append( "Distinct values per column:") 
        pour c dans Df . columns: 
            distinct_count = Df . select( c ) . distinct( ) . compter ( ) 
            report_lines. append( f"  { c } : { distinct_count} " ) 

        report_lines. append( "Schema:") 
        pour f dans Df . schéma . fields: 
            report_lines. append( f"  { f . nom } : { f . dataType} " ) 

        report_lines. append( "Sample data (first 5 rows):") 
        sample_rows = Df . take( 5 ) 
        pour ramer dans  sample_rows: 
            report_lines. append( str( ramer . asDict( ) ) ) 

        report_lines. append( "Null counts per column:") 
        null_counts_df = Df . select( 
            [ spark_sum( col( c ) . isNull( ) . cast( "int") ) . alias( c )  pour c dans Df . columns] 
        ) 
        null_counts =  null_counts_df. collect( ) [ 0 ] . asDict( ) 
        pour c ,  v dans  null_counts. items( ) : 
            report_lines. append( f"  { c } : { v} " ) 

        rendre  "\n". join( report_lines) 

5.2 GitHub Actions Workflow (.github/workflows/deploy.yml) ​

This workflow runs on every push to principal and uses the Ilum REST API to deploy the service:

nom :  Deploy ILUM Group

on: 
  pousser : 
    branches:  [ principal ] 

Env : 
  ILUM_DEMO_SERVICE:  ILUM_DEMO_SERVICE

jobs: 
  deploy: 
    runs-on: même - hosted
    steps: 
      -  nom :  Checkout code
        Utilise :  actions/checkout@v4

      -  nom :  Check if group ILUM_DEMO_SERVICE exists
        id :  check_group
        Courir :  | 
          echo "Checking if group ILUM_DEMO_SERVICE exists..."

          RESPONSE=$(curl - s - X GET \
            - w "\nHTTP_STATUS: % { http_code} " \
            "http: ilum - core.ilum.svc.cluster.local: 9888/api/v1/group?name=$ILUM_DEMO_SERVICE")

          HTTP_STATUS=$(echo "$RESPONSE" |  grep HTTP_STATUS |  cut - d': ' - f2)
          BODY=$(echo "$RESPONSE" |  sed '/HTTP_STATUS/d')

          GROUP_ID=$(echo "$BODY" |  jq - r '.content[ 0 ] .groupId // empty')

si [  - n "$GROUP_ID" ]  &&  [  "$GROUP_ID" != "null" ] ; then
            echo "Group ILUM_DEMO_SERVICE found with ID:  $GROUP_ID"
            echo "GROUP_ID=$GROUP_ID" > >  $GITHUB_OUTPUT
            echo "GROUP_EXISTS=true" > >  $GITHUB_OUTPUT
autre 
            echo "Group ILUM_DEMO_SERVICE does not exist."
            echo "GROUP_EXISTS=false" > >  $GITHUB_OUTPUT
          fi

      -  nom :  Delete existing group
        si :  steps.check_group.outputs.GROUP_EXISTS == 'true'
        Courir :  | 
          GROUP_ID="${{ steps.check_group.outputs.GROUP_ID }}"
          echo "Stopping and deleting group ILUM_DEMO_SERVICE (ID: $GROUP_ID)..."

friser - s - X POST \
http : ilum - core.ilum.svc.cluster.local: 9888/api/v1/group/$GROUP_ID/stop

          RESPONSE=$(curl - s - X DELETE \
            - w "\nHTTP_STATUS: % { http_code} " \
http : ilum - core.ilum.svc.cluster.local: 9888/api/v1/group/$GROUP_ID)

          HTTP_STATUS=$(echo "$RESPONSE" |  grep HTTP_STATUS |  cut - d': ' - f2)

si [  "$HTTP_STATUS" - ne 200 ] ; then
            echo "Error:  Failed to delete group (Status:  $HTTP_STATUS)"
            exit 1
          fi

          echo "Group ILUM_DEMO_SERVICE deleted successfully."

      -  nom :  Create new group
        Courir :  | 
          echo "Creating group ILUM_DEMO_SERVICE with service.py..."

          RESPONSE=$(curl - s - X POST \
            - F "name=ILUM_DEMO_SERVICE" \
            - F "[email protected] " \
            - F "clusterName=default" \
            - F "language=PYTHON" \
            - w "\nHTTP_STATUS: % { http_code} " \
http : ilum - core.ilum.svc.cluster.local: 9888/api/v1/group)

          HTTP_STATUS=$(echo "$RESPONSE" |  grep HTTP_STATUS |  cut - d': ' - f2)
          BODY=$(echo "$RESPONSE" |  sed '/HTTP_STATUS/d')

          echo "HTTP Status:  $HTTP_STATUS"
          echo "Response Body:  $BODY"

si [  "$HTTP_STATUS" - ne 200 ] ; then
            echo "Error:  Failed to create group (Status:  $HTTP_STATUS)"
            exit 1
          fi

          GROUP_ID=$(echo "$BODY" |  jq - r '.groupId // empty')
          echo "Group ILUM_DEMO_SERVICE created successfully with ID:  $GROUP_ID"

Commit both files to the repository.

Step 6: Verify the Deployment​

Once the workflow completes successfully (visible in the Actions tab on GitHub), navigate to the Ilum UI:

1. Atteindre Services in the sidebar.
2. You should see the ILUM_DEMO_SERVICE service group with status Active.
3. Click on it and go to the Execute Jobonglet.
4. Set the Classe À service.SparkInteractiveExample.
5. Provide parameters as JSON:

{ 
    "database":  "ilum_example_product_sales", 
    "table":  "products"
} 

6. Cliquer Exécuter . The result will display table details including row count, schema, sample data, and null counts.

Step 7: Update the Service via Pull Request​

The key benefit of this CI/CD approach is that updating your service is as simple as modifying code and merging a pull request.

Example: Adding Table Listing Feature​

1. Create a new branch (e.g., feature/list-tables) from principal .
2. Éditer service.py to add functionality — for example, listing other tables in the database:

        # List other tables in the current database
        current_db = étincelle . catalogue . currentDatabase( ) 
        report_lines. append( f"Tables in database '{ current_db} ':") 
        tables = étincelle . catalogue . listTables( current_db) 
        other_tables =  [ t . nom pour t dans  tables si t . nom !=table_name ] 
        si  other_tables: 
            pour  tname dans  other_tables: 
                report_lines. append( f"  { tname} " ) 
        autre : 
            report_lines. append( "  (no other tables)") 

        rendre  "\n". join( report_lines) 

3. Commit the change and open a Pull RequestDe feature/list-tables into principal .
4. Merge the PR.
5. The GitHub Actions workflow triggers automatically, stops the old service, and deploys the updated version.
6. Execute the job again in Ilum — the result now includes the new "Tables in database" section.

Dépannage ​

Frequently Asked Questions (FAQ)​