Installing iQ Studio

The installer script automates the full installation of iQ Studio. It uploads component images to your registry, configures namespaces and secrets, installs the iQ Studio operator by using Helm, and applies the ProductRelease manifest to deploy all components. The installation takes 60 to 90 minutes, depending on network bandwidth and cluster performance.

Make sure the following requirements are met before you start the installation:

Tools

The installer script checks for these tools and installs them if they are not present on the node:

kubectl
helm
skopeo

Bundle files

Confirm that these bundle files are in the parent working directory:

iqstudio-v<version>-operator.tar.gz: iQ Studio operator bundle
iqstudio-v<version>-FullStack.tar.gz: Full-stack component bundle

Required information

Have the following information ready before you run the installer. The script prompts you for these values during installation. If any value is not available, exit the script and obtain the required information before you continue.

Required value	Description	Example
Registry endpoint	Hostname of your container registry.	`registry.example.com`
Registry username	Username for registry authentication.	`username`
Registry password	Password for registry authentication.	`password`
TLS certificate file path	Path to the `.crt` file for TLS.	`../samurai.crt`
TLS key file path	Path to the `.key` file for TLS.	`../samurai.key`
Registry CA certificate file path	Path to the `.crt` file for the registry CA.	`../registry-ca.crt`
Default FQDN	Fully qualified domain name for deployed applications.	`samurai.hitachivantara.com`
Load balancer IP address	External IP address of your load balancer.	`172.23.12.241`
Installation bundle SHA256 checksum	The cryptographic hash value that verifies the integrity of the installer bundle.	`2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824`

Run the installer script to start the installation.
```
./iqstudio-installer.sh --install
```
When prompted, confirm whether you have already run the preflight check. If you have not run it, enter no and run the preflight check before you continue. For more information, see Performing a preflight check.
```
Have you already run this script with the --preflight-check option? (yes/no): yes
Do you have all the required information ready? (yes/no): 
```
Enter the expected SHA256 checksum when the script prompts you.
```
Enter expected SHA256 checksum:
```
The script locates the installer bundle, calculates its SHA256 checksum, and compares it with the value you provide. It then verifies that the required tools are installed and displays the active Kubernetes context. For information about the checksum to use, see the iQ Studio release notes.
```
[SUCCESS] Checksum validation PASSED
[SUCCESS] Installer bundle integrity verified successfully
[SUCCESS] Step completed in 37s

[SUCCESS] kubectl is already installed: Client Version: v1.33.0
[SUCCESS] helm is already installed: v3.16.1
[SUCCESS] skopeo is already installed: skopeo version 1.16.1
[SUCCESS] Step completed in 1s

[SUCCESS] Using Kubernetes context: kubernetes-admin@kubernetes
[SUCCESS] Step completed in 0s
```
Important: If multiple Kubernetes contexts are available, the script prompts you to select one. In environments with a single context, the script selects it automatically.

Enter your registry credentials.

Enter Registry Endpoint [registry.example.com]: <yourregistry-endpoint>
Enter Registry Username: <your-username>
Enter Registry Password: <your-password>

Review the configuration summary, then confirm the values are correct.

Are these values correct? (yes/re-enter/exit): yes
[SUCCESS] Registry configuration confirmed and set successfully
[SUCCESS] Step completed in 2m 20s

The script identifies and validates the bundle files, and then sets run permissions on the upload script.

[INFO]    - Operator Bundle: iqstudio-v0.1.5-operator.tar.gz (91M)
[INFO]    - Component Bundle: iqstudio-v0.1.5-FullStack.tar.gz (18G)
[SUCCESS] Bundle files identified and validated successfully
[SUCCESS] Step completed in 0s
[SUCCESS] Execute permissions set on iqstudio-bundle-upload.sh
[SUCCESS] Step completed in 0s

Monitor the image upload process until both uploads complete successfully.

[INFO]    2026-02-24 05:10:27 - =====================================================
[INFO]    2026-02-24 05:10:27 - UPLOAD SCRIPT COMPLETED - Control returned to installer
[INFO]    2026-02-24 05:10:27 - Upload exit code: 0
[INFO]    2026-02-24 05:10:27 - =====================================================
[SUCCESS] 2026-02-24 05:10:27 - Component bundle uploaded successfully in 26m 33s
[SUCCESS] 2026-02-24 05:10:27 - ✓ Step completed in 26m 33s
------------------------------------------------------------
STEP 9/20: Logging into Helm registry
------------------------------------------------------------
[INFO]    2026-02-24 05:10:27 - Helm registry login attempt 1/3...
WARNING: Kubernetes configuration file is group-readable. This is insecure. Location: /root/.kube/config
WARNING: Kubernetes configuration file is world-readable. This is insecure. Location: /root/.kube/config
Login succeeded
[SUCCESS] 2026-02-24 05:10:27 - Logged into Helm registry successfully on attempt 1
[SUCCESS] 2026-02-24 05:10:27 - ✓ Step completed in 0s

The script extracts and pushes all container images and Helm charts from both the operator bundle and the full-stack bundle to the configured registry. When both uploads complete, the script displays a bundle upload summary.

[SUCCESS] All operator images pushed to registry
[SUCCESS] Step completed

BUNDLE STATISTICS:
  Total Bundles: 37
  Processed Successfully: 37
  Skipped (Already Uploaded): 0
  Failed: 0

IMAGE STATISTICS:
  Total Image References Found: 59
  Unique Images Uploaded: 59
  Image References Skipped: 0
  Actual Upload Failures: 0

[SUCCESS] All bundles uploaded successfully!
[SUCCESS] Upload completed!

CAUTION:

This phase takes about 35 to 65 minutes depending on your network bandwidth. Do not interrupt the process.

The script then automatically authenticates with the Helm OCI registry, creates the iqstudio-operator namespace, and sets up the Docker registry secret (regcred). You will be prompted to provide an optional ca.crt file for the registry, which you can use to create a trusted CA secret in the iqstudio-operator namespace.

[SUCCESS] Logged into Helm registry successfully on attempt 1
[SUCCESS] Step completed in 0s

[SUCCESS] Namespace iqstudio-operator created
[SUCCESS] Docker registry secret created
[SUCCESS] Step completed in 0s

Enter your TLS certificate and key file paths when the script prompts you.
The script creates the istio-system namespace and then prompts you for TLS certificate files that are required for secure service-to-service communication.
1. Enter the path to your TLS certificate file and TLS key file. You can use a relative or absolute path.
```
Enter path to TLS certificate file (e.g., changeme.crt or /path/to/changeme.crt): ../samurai.crt
Enter path to TLS key file (e.g., changeme.key or /path/to/changeme.key): ../samurai.key
```
1. Review the TLS configuration summary and confirm that the values are correct.
```
Are these values correct? (yes/re-enter/exit): 
```
```
[SUCCESS] Namespace istio-system created
[SUCCESS] TLS secret created
[SUCCESS] Step completed
```

Enter the default FQDN.

The script creates the iqstudio-config ConfigMap that is used by Kubernetes DNS. Enter the FQDN that will serve as the default domain for all deployed applications.

Enter the default FQDN.

Enter default FQDN for deployed applications [iqstudio.example.com]: samurai.hitachivantara.com

Confirm the value before continuing.

Are these values correct? (yes/re-enter/exit):

[SUCCESS] ConfigMap iqstudio-config created/updated
[INFO]      • FQDN: samurai.hitachivantara.com
[SUCCESS] Step completed in 40s

Enter the load balancer IP address and DNS configuration when the script prompts you.
1. Enter the load balancer IP address.
```
Enter LoadBalancer IP address [changeme]: <172.23.12.241>
```
2. Confirm the load balancer IP address.
```
Are these values correct? (yes/re-enter/exit):
```
3. Specify whether a wildcard DNS for your domain is configured at the central DNS level.
```
Is wildcard DNS (*.samurai.hitachivantara.com) configured at the central DNS level? (yes/no):
```
  - If you enter yes, the script performs nslookup resolution tests against central DNS for all required service endpoints.
  - If you enter no, the script creates a custom CoreDNS ConfigMap to handle local DNS resolution.
  Important: The DNS must be configured before the operator installs. Endpoint resolution failures at this step prevent the installation from completing successfully.
When all endpoints resolve correctly, the script reports success and automatically installs the iQ Studio operator and verifies the ProductRelease CRD.
```
[SUCCESS] All DNS endpoints resolved successfully!
[SUCCESS] Step completed in 1m 45s

[SUCCESS] iQ Studio operator installed/upgraded successfully on attempt 1
NAME: iqstudio-operator
NAMESPACE: iqstudio-operator
STATUS: deployed
REVISION: 1

Operator pods:
NAME                                READY   STATUS    RESTARTS   AGE
iqstudio-operator-7fbfcb7766-26dwn  1/1     Running   0          11s

[SUCCESS] Step completed in 11s

[SUCCESS] ProductRelease CRD is established
[SUCCESS] Step completed in 0s
```

Specify the Gitea registry IP address.

After the load balancer and DNS configuration completes, the installer detects the Gitea registry endpoint. The installer resolves the Gitea endpoint using DNS and displays the detected IP address. When prompted, enter the resolved IP address, or specify a different IP address if your Gitea registry uses a custom configuration.

[INFO]    2026-03-27 07:41:00 - ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[INFO]    2026-03-27 07:41:00 - GITEA REGISTRY DETECTED IN ENDPOINT
[INFO]    2026-03-27 07:41:00 - ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[INFO]    2026-03-27 07:41:00 - Gitea registry endpoint detected: giteatest.iq.idc.coe.hv
[INFO]    2026-03-27 07:41:00 - Gitea is typically exposed on a separate IP (not through Istio ingress)
[INFO]    2026-03-27 07:41:00 - Testing DNS resolution for Gitea endpoint...
[SUCCESS] 2026-03-27 07:41:15 - ✓ Gitea endpoint resolves to: 192.168.23.40
Enter IP address for Gitea registry (giteatest.iq.idc.coe.hv) [changeme]:

Select the storage classes.

The script lists all available storage classes and prompts you to select two for iQ Studio.

[INFO] Current default storage class: local-path
[INFO] You will be prompted for TWO storage classes:
[INFO] 1. Shared storage class (non-retain) - for general workloads
[INFO] 2. Shared storage retention class (retain) - for persistent data

Select or type the name of the shared storage class for general non-retaining workloads.
```
Select shared storage class (non-retain) [1–12] or type name: <storage class name>
```

Select or type the name of the shared storage retention class for persistent data.

Select shared storage retention class (retain) [1–12] or type name: <storage retention class name>

Review the storage configuration summary and confirm.

  STORAGE CONFIGURATION
   • Default Storage Class: local-path
   • Shared Storage Class (non-retain): nfs-client
   • Shared Storage Retention Class (retain): nfs-client-retain

   Are these values correct? (yes/re-enter/exit): yes
   [SUCCESS] Storage configuration confirmed successfully
   [SUCCESS] Step completed in 1m 59s

The script automatically detects the Kubernetes DNS service, patches the product release YAML, and verifies that cert-manager is installed.

[SUCCESS] Found kube-dns service in kube-system namespace
[INFO]    • Detected DNS Service: kube-dns
[INFO]    • DNS FQDN: kube-dns.kube-system.svc.cluster.local
[SUCCESS] Patched DNS_RESOLVER from 'coredns.kube-system.svc.cluster.local'
          to 'kube-dns.kube-system.svc.cluster.local'
[SUCCESS] Step completed in 0s

[SUCCESS] cert-manager namespace already exists
[SUCCESS] cert-manager is already installed and running
[SUCCESS] Step completed in 0s

Review the configuration patches and apply the ProductRelease manifest.
1. The script patches all configuration values into the product release YAML file and runs a kubectl dry-run syntax validation.
```
[INFO] Patches applied:
[INFO] ✓ DNS service patching
[INFO] ✓ Storage class replacements
[INFO] ✓ LoadBalancer IP update
[SUCCESS] YAML syntax validation passed
```
  The script applies the manifest using kubectl apply and triggers the full component deployment.
2. Review the confirmation prompt and enter yes to apply the ProductRelease manifest.
```
Do you want to proceed with applying this ProductRelease?
(yes/no): 
```
  The script applies the manifest using kubectl apply and triggers the full component deployment.
Monitor the deployment until all components install successfully.
The script streams operator logs and tracks the status of each component as the operator installs them sequentially.
Important:
- Kopf handler retries (up to 10 attempts)
- Component retries (up to 3 to 5 attempts per component)
- ProductRelease phase transitions
- Permanent versus temporary failures
When all components are installed and the cluster has stabilized, the script prints the final deployment summary.
```
[SUCCESS] All components installed successfully
[INFO] Total deployment time: ~27 minutes
```
Run this command to verify the ProductRelease status.
```
kubectl get productrelease -n iqstudio-operator
```
The ProductRelease status moves through the following phases in order:
- Pending: The operator has received the manifest and is preparing to install components.
- InProgress: The operator is actively installing components.
- Ready: All components are installed and running.
Note: Run the kubectl logs -l iqstudio-operator -n iqstudio-operator command to review the operator logs if the status remains in an unexpected state such as Error, Failed, or Partial.

All iQ Studio components have been installed successfully.

After iQ Studio installs successfully, continue with model deployment. For more information, see Deploying AI and ML models.