### Complete Integration Test Workflow Example

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

A comprehensive example demonstrating the steps to set up CRC, log in, build and push images, and then run integration tests.

```bash
# 1. Start CRC and login
crc start
eval $(crc oc-env)
oc login -u kubeadmin -p $(crc console --credentials | grep kubeadmin | awk -F"'" '{print $2}') https://api.crc.testing:6443

# 2. Build and push images (from project root)
cd /path/to/truenas-csi
make release
```

--------------------------------

### Copy Install Manifests

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/cluster-setup.md

Commands to copy the default OpenShift install configuration files to a working directory.

```bash
mkdir ~/ocp-install
cp operator/ocp-install/install-config.yaml ~/ocp-install/
cp operator/ocp-install/agent-config.yaml ~/ocp-install/
```

--------------------------------

### Verify Kind Installation

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

Verify that Kind (Kubernetes in Docker) is installed. This tool is used to create a local Kubernetes cluster for testing.

```bash
kind --version
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

Verify that Docker is installed on your system. This is a prerequisite for running the Kind cluster and building container images.

```bash
docker --version
```

--------------------------------

### Verify kubectl Installation

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

Verify that kubectl, the Kubernetes command-line tool, is installed. This is necessary for interacting with the Kubernetes cluster.

```bash
kubectl version --client
```

--------------------------------

### Create NFS StorageClass and PVC

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Apply example StorageClass and PersistentVolumeClaim (PVC) manifests for NFS volumes to provision storage.

```bash
kubectl apply -f examples/storageclass-nfs.yaml
```

```bash
kubectl apply -f examples/pvc-nfs.yaml
```

--------------------------------

### MicroK8s Mount Propagation Setup

Source: https://context7.com/truenas/truenas-csi/llms.txt

Ensure shared mount propagation is enabled for MicroK8s by running a command and creating a systemd service for persistence.

```bash
sudo mount --make-rshared /
microk8s start
```

```bash
sudo tee /etc/systemd/system/microk8s-mount-propagation.service <<EOF
[Unit]
Description=Ensure shared mount propagation for MicroK8s
Before=snap.microk8s.daemon-containerd.service
[Service]
Type=oneshot
ExecStart=/bin/mount --make-rshared /
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable microk8s-mount-propagation
```

--------------------------------

### Example TrueNAS CSI Driver ConfigMap

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

An example of a populated ConfigMap for the TrueNAS CSI driver, demonstrating secure WebSocket connection and self-signed certificate usage.

```yaml
data:
  truenasURL: "wss://10.0.0.136/api/current"          # Secure WebSocket (wss://)
  truenasInsecure: "true"                             # Allow self-signed certificate
  defaultPool: "tank"
  nfsServer: "10.0.0.136"
  iscsiPortal: "10.0.0.136:3260"
  iscsiIQNBase: "iqn.2024-01.com.acmecorp"  # Optional: use your company domain
```

--------------------------------

### Monitor OpenShift Installation

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/cluster-setup.md

Commands to monitor the OpenShift cluster installation progress. The `wait-for install-complete` command will output cluster access details upon successful completion.

```bash
openshift-install agent wait-for bootstrap-complete --dir ~/ocp-install --log-level info
```

```bash
openshift-install agent wait-for install-complete --dir ~/ocp-install --log-level info
```

--------------------------------

### Troubleshoot Operator Pod Not Starting

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/upgrade.md

Check the status and logs of the operator pod if it fails to start. This helps in diagnosing issues with the controller manager.

```bash
# Check operator pod status
oc describe pod -n openshift-operators -l control-plane=controller-manager
```

```bash
# Check operator logs
oc logs -n openshift-operators deployment/truenas-csi-operator-controller-manager
```

--------------------------------

### Build TrueNAS CSI Driver Binary

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Use this command to build the TrueNAS CSI driver binary. Ensure you have the necessary build tools installed.

```bash
make build
```

--------------------------------

### Setup DNS VM Script

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/cluster-setup.md

Bash script to configure DNS records on a dedicated VM for OpenShift. Ensure variables at the top are updated with your specific IP addresses before execution.

```bash
API_VIP="10.220.15.200"
INGRESS_VIP="10.220.15.201"
MASTER0_IP="10.220.15.210"
MASTER1_IP="10.220.15.211"
MASTER2_IP="10.220.15.212"

cat <<EOF > /etc/dnsmasq.d/openshift.conf
address=/api.ocp.local/$(echo $API_VIP)
address=/api-int.ocp.local/$(echo $API_VIP)
address=/apps.ocp.local/$(echo $INGRESS_VIP)
$(for i in 0 1 2; do echo "address=/master$i.ocp.local/$(eval echo \$$MASTER$i_IP)"; done)
$(for i in 0 1 2; do echo "address=/*.$i.ocp.local/$(eval echo \$$MASTER$i_IP)"; done)
$(for i in 0 1 2; do echo "address=/*.$i.apps.ocp.local/$(eval echo \$$INGRESS_VIP)"; done)
EOF

systemctl restart dnsmasq
```

--------------------------------

### NFS StorageClass Example

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Define a Kubernetes StorageClass for provisioning NFS volumes using the TrueNAS CSI driver. Includes parameters for protocol, pool, compression, and sync settings.

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: truenas-nfs
provisioner: csi.truenas.io
parameters:
  protocol: nfs
  pool: tank
  # Optional parameters
  compression: "lz4"
  sync: "standard"
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: Immediate
```

--------------------------------

### Clean Up Namespace and Secrets

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Optionally, delete the namespace and any associated secrets created during the installation.

```bash
oc delete namespace truenas-csi
```

--------------------------------

### Check Volume Snapshot Status

Source: https://context7.com/truenas/truenas-csi/llms.txt

Use `kubectl get volumesnapshot` to verify the status of a created volume snapshot. The `READYTOUSE` field should indicate `true`.

```bash
# Check snapshot status
kubectl get volumesnapshot my-snapshot
# NAME           READYTOUSE   SOURCEPVC     RESTORESIZE   ...
# my-snapshot    true         shared-data   5Gi           ...

# Verify clone PVC is bound
kubectl get pvc restored-pvc
# NAME           STATUS   VOLUME            CAPACITY   ACCESS MODES
# restored-pvc   Bound    pvc-a1b2c3d4-...  5Gi        RWX

```

--------------------------------

### Run E2E Tests

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Run end-to-end tests for the operator. This requires Kind to be installed and configured.

```bash
make test-e2e
```

--------------------------------

### Verify TrueNAS CSI Driver Installation

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Check if the TrueNAS CSI driver pods are running and if the CSI driver is registered with Kubernetes.

```bash
# Check driver pods are running
kubectl get pods -n truenas-csi
```

```bash
# Verify CSI driver is registered
kubectl get csidrivers
```

--------------------------------

### TrueNAS CSI Custom Resource Configuration

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Example configuration for the TrueNAS CSI Custom Resource. Ensure required fields like truenasURL, credentialsSecret, and defaultPool are set.

```yaml
apiVersion: csi.truenas.io/v1alpha1
kind: TrueNASCSI
metadata:
  name: truenas-csi
spec:
  # Required: TrueNAS WebSocket URL
  truenasURL: "wss://truenas.example.com/api/current"

  # Required: Name of secret containing api-key
  credentialsSecret: "truenas-credentials"

  # Required: Default ZFS pool for provisioning
  defaultPool: "tank"

  # Optional: NFS server address (for NFS volumes)
  nfsServer: "192.168.1.100"

  # Optional: iSCSI portal address (for iSCSI volumes)
  iscsiPortal: "192.168.1.100:3260"

  # Optional: Driver image (default: quay.io/truenas_solutions/truenas-csi:latest)
  driverImage: "quay.io/truenas_solutions/truenas-csi:v0.1.0"

  # Optional: Controller replicas (default: 1, max: 3)
  controllerReplicas: 1

  # Optional: Log level 1-5 (default: 4)
  logLevel: 4

  # Optional: Skip TLS verification (default: false)
  insecureSkipTLS: false

  # Optional: Namespace for CSI components (default: truenas-csi)
  namespace: "truenas-csi"

  # Optional: ManagementState (Managed, Unmanaged, Removed)
  managementState: "Managed"
```

--------------------------------

### Install Snapshot Controller CRDs and RBAC

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Apply the necessary Custom Resource Definitions (CRDs) and Role-Based Access Control (RBAC) configurations for the Kubernetes snapshot controller.

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
```

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
```

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
```

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
```

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml
```

--------------------------------

### iSCSI StorageClass Example

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Define a Kubernetes StorageClass for provisioning iSCSI volumes using the TrueNAS CSI driver. Includes parameters for protocol, pool, filesystem type, and compression.

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: truenas-iscsi
provisioner: csi.truenas.io
parameters:
  protocol: iscsi
  pool: tank
  fsType: ext4
  # Optional parameters
  compression: "lz4"
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: Immediate
```

--------------------------------

### Persistent Volume Claim Example

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Create a Persistent Volume Claim (PVC) to request storage from a TrueNAS CSI provisioned StorageClass. Specify access modes, storage class, and requested size.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce  # Use ReadWriteMany for NFS
  storageClassName: truenas-iscsi  # or truenas-nfs
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Run Simple Demo Script (Kind)

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Execute the simple demo script for testing CSI driver functionality on a local Kind cluster. Ensure TrueNAS connection details are updated in the deployment file.

```bash
# Set TrueNAS connection details in deploy/truenas-csi-driver.yaml, then:
./demo-simple.sh
```

--------------------------------

### Building TrueNAS CSI Driver Binaries and Images

Source: https://context7.com/truenas/truenas-csi/llms.txt

Build the Go binary for the CSI driver, container images (standard and UBI-based), operator image, and OLM bundle image using Make targets.

```bash
# Build the Go binary (version injected via ldflags)
make build                         # outputs bin/truenas-csi

# Build container images
make docker-build                  # Alpine-based (standard Kubernetes)
make build-ubi                     # UBI-based (Red Hat OpenShift)
make operator-build                # Operator image
make bundle-build                  # OLM bundle image
```

--------------------------------

### Run the TrueNAS CSI Driver Demo

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

Execute the `demo-simple.sh` script to run the interactive demonstration of the TrueNAS CSI driver. Ensure the script has execute permissions.

```bash
chmod +x ./demo-simple.sh
./demo-simple.sh
```

--------------------------------

### Build All UBI-Based Images

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Builds the driver, operator, and bundle images using UBI. Ensure you are in the project root directory.

```bash
# From project root
make build-all    # Build all images (driver, operator, bundle)
```

--------------------------------

### Release Workflow

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Build and push all necessary container images for a release, including driver, operator, and bundle images. This is the recommended way to prepare for integration tests.

```bash
# From the project root directory (not operator/)
make release
```

--------------------------------

### Run OpenShift Demo Script (CRC/OpenShift Local)

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Run the demo script for OpenShift environments. Set the necessary environment variables for TrueNAS IP, API key, and pool before execution.

```bash
# Set environment variables
export TRUENAS_IP=192.168.1.100
export TRUENAS_API_KEY=your-api-key
export TRUENAS_POOL=tank

# Run the demo
./demo-openshift.sh
```

--------------------------------

### Deploy and Remove Operator

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Install CRDs, deploy the operator to the cluster, and remove it when no longer needed. Specify the operator image for deployment.

```bash
# Install CRDs
make install

# Deploy operator to cluster
make deploy IMG=quay.io/truenas_solutions/truenas-csi-operator:v0.1.0

# Remove operator
make undeploy
```

--------------------------------

### Run Interactive Demo Script

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Execute the provided demo script to test CSI driver functionality on OpenShift. Environment variables can be set beforehand or provided interactively.

```bash
# Set environment variables (optional - script will prompt if not set)
export TRUENAS_IP=192.168.1.100
export TRUENAS_API_KEY=1-abcdef1234567890
export TRUENAS_POOL=tank
export TRUENAS_INSECURE=true

# Run the demo
./demo-openshift.sh
```

--------------------------------

### Build and Run Locally

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Build the operator binary and run it outside of a cluster for local development and testing.

```bash
make build
make run
```

--------------------------------

### Build and Push All Images

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Build and push all container images, including the 'latest' tag, for a specified version.

```bash
# Build and push everything including 'latest' tag
make release VERSION=1.0.0
```

--------------------------------

### Submit Driver Image for Container Certification

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Runs preflight checks and submits the driver image to Red Hat Partner Connect. Requires PYXIS_API_TOKEN and the correct certification-component-id.

```bash
# Submit driver image (project: 6984e4411c8ca46590f85669)
PFLT_PYXIS_API_TOKEN="$PYXIS_API_KEY" preflight check container \
  quay.io/truenas_solutions/truenas-csi:v1.0.0 \
  --submit \
  --certification-component-id=6984e4411c8ca46590f85669
```

--------------------------------

### Create TrueNAS CSI Credentials Secret

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Create a Kubernetes secret to store TrueNAS API credentials. Ensure the namespace matches your CSI driver installation.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: truenas-api-credentials
  namespace: truenas-csi
stringData:
  api-key: "YOUR-API-KEY"
```

--------------------------------

### Build All Operator Images

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Builds all necessary container images for the operator, including the driver, operator, and bundle images. Specify the version tag for the build.

```bash
make build-all VERSION=x.y.z
```

--------------------------------

### TrueNASCSI Status Fields Example

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/configuration.md

This snippet shows the status subresource of the TrueNASCSI custom resource, which is updated by the operator to reflect the deployment status of the CSI driver.

```yaml
status:
  phase: Running          # Current phase: Pending, Running, Failed
  controllerReady: true   # Controller deployment ready
  nodeDaemonSetReady: true # Node DaemonSet ready
  conditions:
    - type: Ready
      status: "True"
      reason: DeploymentReady
      message: "CSI driver is ready"
      lastTransitionTime: "2026-01-20T00:00:00Z"

```

--------------------------------

### Generate, Build, and Push OLM Bundle

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Commands to generate, build, and push an OLM bundle for the operator. Specify the version and image details as needed.

```bash
# Generate OLM bundle
make bundle VERSION=0.1.0 IMG=quay.io/truenas_solutions/truenas-csi-operator:v0.1.0

# Build bundle image
make bundle-build BUNDLE_IMG=quay.io/truenas_solutions/truenas-csi-operator-bundle:v0.1.0

# Push bundle
make bundle-push BUNDLE_IMG=quay.io/truenas_solutions/truenas-csi-operator-bundle:v0.1.0
```

--------------------------------

### Generate Agent ISO

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/cluster-setup.md

Command to generate the agent ISO image for OpenShift installation using the configured manifests. This command will consume and delete the input YAML files.

```bash
openshift-install agent create image --dir ~/ocp-install
```

--------------------------------

### Build Multi-Arch Image

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Build a container image that supports multiple architectures using docker buildx.

```bash
make docker-buildx IMG=quay.io/truenas_solutions/truenas-csi-operator:v0.1.0
```

--------------------------------

### Configure Custom IQN Prefix for StorageClasses

Source: https://github.com/truenas/truenas-csi/blob/master/docs/demo.md

Customize IQN prefixes for multi-tenant deployments by defining separate StorageClasses with unique `iscsi.iqn-base` parameters.

```yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: finance-iscsi
parameters:
  protocol: "iscsi"
  iscsi.iqn-base: "iqn.2024-01.com.acme.finance"
---
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: engineering-iscsi
parameters:
  protocol: "iscsi"
  iscsi.iqn-base: "iqn.2024-01.com.acme.engineering"
```

--------------------------------

### OpenShift Operator: Check Deployment Status

Source: https://context7.com/truenas/truenas-csi/llms.txt

Check the status of the operator-managed CSI driver deployment using `oc get truenascsi` and retrieve detailed status information.

```bash
# Step 3 — Check operator-managed deployment status
oc get truenascsi truenas
# NAME      PHASE     CONTROLLER   NODES   AGE
# truenas   Running   true         true    2m

oc get truenascsi truenas -o jsonpath='{.status}'
# {"phase":"Running","controllerReady":true,"nodeDaemonSetReady":true,
#  "controllerReplicas":1,"nodeReplicas":3,"driverVersion":"v1.0.0"}
```

--------------------------------

### Rollback TrueNAS CSI Operator via CLI

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/upgrade.md

Use these commands to list installed ClusterServiceVersions (CSVs), delete the current CSV, or patch the subscription to specify a previous version for rollback.

```bash
# List installed CSVs
oc get csv -n openshift-operators | grep truenas
```

```bash
# Delete current CSV
oc delete csv truenas-csi-operator.v0.2.0 -n openshift-operators
```

```bash
# OLM will reinstall from subscription
# Or manually specify previous version:
oc patch subscription truenas-csi-operator -n openshift-operators \
  --type merge \
  -p '{"spec":{"startingCSV":"truenas-csi-operator.v0.1.0"}}'
```

--------------------------------

### Run Linter

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Execute the linter to check code quality and style.

```bash
make lint
```

--------------------------------

### Integration Test with Options

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Run integration tests with custom configurations for TrueNAS pool, TLS verification, and operator/driver image overrides.

```bash
TRUENAS_IP=192.168.1.100 \
TRUENAS_API_KEY=1-abcdef123456 \
TRUENAS_POOL=mypool \
SKIP_OPERATOR_DEPLOY=true \
make test-integration
```

--------------------------------

### API Credentials Secret Example

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/configuration.md

This YAML defines a Kubernetes Secret of type Opaque, used to store the TrueNAS API key. The `stringData` field contains the API key, which the CSI driver uses to authenticate with the TrueNAS API.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: truenas-api-credentials
  namespace: truenas-csi
type: Opaque
stringData:
  api-key: "1-abcdef1234567890"

```

--------------------------------

### Build Binary with Version Injection

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Build the operator binary, injecting version information. Use the VERSION variable for specific versions.

```bash
# Build binary with version injection
make build

# Build with specific version
VERSION=0.1.0 make build
```

--------------------------------

### Release Operator Images (Recommended)

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Automates the entire release process, including building, pushing versioned images, and updating the 'latest' tag. This is the recommended method for releasing new versions.

```bash
# Option A: Use the release target (recommended - does everything)
make release VERSION=x.y.z
```

--------------------------------

### Regenerate, Build, and Push Bundle

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Regenerate the OLM bundle with image digests, then build and push the bundle image.

```bash
cd operator && make bundle USE_IMAGE_DIGESTS=true
cd .. && make bundle-build bundle-push
```

--------------------------------

### Kubernetes VolumeSnapshot and Clone Workflow

Source: https://context7.com/truenas/truenas-csi/llms.txt

This section demonstrates creating a VolumeSnapshotClass, taking a ZFS snapshot of a PVC, and restoring it into a new PVC (cloning). The `deletionPolicy` in VolumeSnapshotClass controls snapshot persistence.

```yaml
# 1. Create a VolumeSnapshotClass (one-time cluster resource)
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: truenas-snapclass
driver: csi.truenas.io
deletionPolicy: Delete   # Delete (remove snapshot when VolumeSnapshot is deleted)
                         # or Retain (keep snapshot on TrueNAS after deletion)

---
# 2. Take a snapshot of an existing PVC
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: my-snapshot
spec:
  volumeSnapshotClassName: truenas-snapclass
  source:
    persistentVolumeClaimName: shared-data   # PVC to snapshot

---
# 3. Restore into a new PVC (clone)
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: restored-pvc
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: truenas-nfs
  resources:
    requests:
      storage: 5Gi
  dataSource:
    name: my-snapshot
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io

```

--------------------------------

### Validate TrueNAS StorageClass Configuration

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/configuration.md

Use `oc describe` to inspect the details of a specific StorageClass, such as `truenas-nfs`, to verify its parameters and settings.

```bash
# Check StorageClass configuration
oc describe storageclass truenas-nfs
```

--------------------------------

### Submit Operator Image for Container Certification

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Runs preflight checks and submits the operator image to Red Hat Partner Connect. Requires PYXIS_API_TOKEN and the correct certification-component-id.

```bash
# Submit operator image (project: 6984f4f22806a3280f06bc67)
PFLT_PYXIS_API_TOKEN="$PYXIS_API_KEY" preflight check container \
  quay.io/truenas_solutions/truenas-csi-operator:v1.0.0 \
  --submit \
  --certification-component-id=6984f4f22806a3280f06bc67
```

--------------------------------

### Push Container Image

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Push the built container image to a registry. Ensure the IMG variable is set correctly.

```bash
make docker-push IMG=quay.io/truenas_solutions/truenas-csi-operator:v0.1.0
```

--------------------------------

### Push TrueNAS CSI Driver Images to Quay.io

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Commands to log in to quay.io and push the UBI-based image or all images. Ensure you are logged in before pushing.

```bash
# Login to quay.io
docker login quay.io
```

```bash
# Push UBI image to quay.io/truenas_solutions
make push-ubi
```

```bash
# Push all images (driver, operator, bundle)
make push-all
```

--------------------------------

### Run OpenShift Integration Tests

Source: https://context7.com/truenas/truenas-csi/llms.txt

Execute integration tests against a real TrueNAS instance and an OpenShift cluster. Ensure you are in the 'operator' directory and provide the necessary TrueNAS connection details.

```bash
cd operator
make test-integration \
  TRUENAS_IP=10.0.0.100 \
  TRUENAS_API_KEY=1-abcdef123456 \
  TRUENAS_POOL=tank
```

--------------------------------

### Prepare Kubeconfig for CSI Tests

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Copy the local kubeconfig file to a designated working directory for use by the test container.

```bash
# Copy kubeconfig to a working directory
cp ~/.kube/config /path/to/workdir/kubeconfig.yaml
```

--------------------------------

### Create TrueNASCSI Custom Resource

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Define and apply the TrueNASCSI custom resource to deploy the CSI driver. Configure TrueNAS connection details, credentials, and default storage pool.

```yaml
apiVersion: csi.truenas.io/v1alpha1
kind: TrueNASCSI
metadata:
  name: truenas
spec:
  # Required: TrueNAS WebSocket API URL
  truenasURL: "wss://your-truenas-ip/api/current"

  # Required: Name of the secret containing the API key
  credentialsSecret: "truenas-api-credentials"

  # Required: Default ZFS pool for volume provisioning
  defaultPool: "tank"

  # Optional: NFS server IP (required for NFS volumes)
  nfsServer: "your-truenas-ip"

  # Optional: iSCSI portal address (required for iSCSI volumes)
  iscsiPortal: "your-truenas-ip:3260"

  # Optional: Skip TLS verification (for self-signed certs)
  insecureSkipTLS: false
```

--------------------------------

### Troubleshoot Volumes Not Mounting After Upgrade

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/upgrade.md

Diagnose issues with volumes not mounting by checking node pod logs, verifying CSIDriver registration, and inspecting the node CSI socket.

```bash
# Check node pod logs
oc logs -n truenas-csi daemonset/truenas-csi-node -c csi-node
```

```bash
# Verify CSIDriver registration
oc get csidriver csi.truenas.io
```

```bash
# Check node CSI socket
oc debug node/<node-name> -- ls -la /var/lib/kubelet/plugins/csi.truenas.io/
```

--------------------------------

### Build TrueNAS CSI Driver Container Images

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Builds container images for the TrueNAS CSI driver. Use `make docker-build` for standard Kubernetes and `make build-ubi` for Red Hat OpenShift.

```bash
# Build Alpine-based image (standard Kubernetes)
make docker-build
```

```bash
# Build UBI-based image (Red Hat OpenShift certification)
make build-ubi
```

--------------------------------

### Submit Driver Image for Preflight Check

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Submit the truenas-csi driver image for preflight checks. Requires PYXIS_API_KEY environment variable.

```bash
PFLT_PYXIS_API_TOKEN="$PYXIS_API_KEY" preflight check container \
  quay.io/truenas_solutions/truenas-csi:v1.0.0 \
  --submit --certification-component-id=6984e4411c8ca46590f85669
```

--------------------------------

### Run Integration Tests

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Run integration tests against a real TrueNAS instance on OpenShift or CRC. Requires TrueNAS IP and API key.

```bash
make test-integration TRUENAS_IP=192.168.1.100 TRUENAS_API_KEY=your-key
```

--------------------------------

### Build Container Image

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Build a container image for the operator. Specify the image name and tag using the IMG variable.

```bash
make docker-build IMG=quay.io/truenas_solutions/truenas-csi-operator:v0.1.0
```

--------------------------------

### Regenerate Manifests and Methods

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Use 'make manifests' to regenerate CRDs and RBAC manifests. Use 'make generate' to regenerate DeepCopy methods.

```bash
# Regenerate CRDs and RBAC manifests
make manifests

# Regenerate DeepCopy methods
make generate
```

--------------------------------

### K3s CSI Driver Configuration

Source: https://context7.com/truenas/truenas-csi/llms.txt

Configure the CSI driver for K3s by setting environment variables and volume mounts for kubelet.

```yaml
env:
  - name: DRIVER_REG_SOCK_PATH
    value: /var/lib/rancher/k3s/agent/kubelet/plugins/csi.truenas.io/csi.sock
volumeMounts:
  - name: kubelet-dir
    mountPath: /var/lib/rancher/k3s/agent/kubelet
    mountPropagation: Bidirectional
volumes:
  - name: plugin-dir
    hostPath:
      path: /var/lib/rancher/k3s/agent/kubelet/plugins/csi.truenas.io/
      type: DirectoryOrCreate
  - name: registration-dir
    hostPath:
      path: /var/lib/rancher/k3s/agent/kubelet/plugins_registry/
      type: DirectoryOrCreate
  - name: kubelet-dir
    hostPath:
      path: /var/lib/rancher/k3s/agent/kubelet
      type: Directory
```

--------------------------------

### Running TrueNAS CSI Driver Tests

Source: https://context7.com/truenas/truenas-csi/llms.txt

Execute unit tests and the CSI sanity suite for the TrueNAS CSI driver using Make targets.

```bash
# Run tests
make test                          # unit tests
make test-sanity                   # CSI sanity suite
```

--------------------------------

### Configure MicroK8s Mount Propagation

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Ensure shared mount propagation is enabled for MicroK8s by running a command and creating a systemd unit for persistence across reboots.

```bash
sudo mount --make-rshared /
microk8s start
```

```bash
sudo tee /etc/systemd/system/microk8s-mount-propagation.service <<EOF
[Unit]
Description=Ensure shared mount propagation for MicroK8s
Before=snap.microk8s.daemon-containerd.service

[Service]
Type=oneshot
ExecStart=/bin/mount --make-rshared /
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable microk8s-mount-propagation
```

--------------------------------

### Deploy TrueNAS CSI Driver

Source: https://context7.com/truenas/truenas-csi/llms.txt

Applies the main manifest to deploy the TrueNAS CSI driver after configuring the Secret and ConfigMap. Verify the pods are running and the CSI driver is registered.

```bash
# 1. Install snapshot CRDs (required for VolumeSnapshot support)
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/deploy/kubernetes/snapshot-controller/rbac-snapshot-controller.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/deploy/kubernetes/snapshot-controller/setup-snapshot-controller.yaml

# 2. Deploy the TrueNAS CSI driver (edit ConfigMap + Secret first)
kubectl apply -f deploy/truenas-csi-driver.yaml

# 3. Verify pods are running
kubectl get pods -n truenas-csi
# NAME                                    READY   STATUS    RESTARTS
# truenas-csi-controller-7d8f5b9c-xkp2n   6/6     Running   0
# truenas-csi-node-4fj9t                  3/3     Running   0

# 4. Verify the CSI driver is registered
kubectl get csidrivers
# NAME              ATTACHREQUIRED   PODINFOONMOUNT   ... 
# csi.truenas.io    true             true             ... 
```

--------------------------------

### Package CSI Certification Results

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Create a tarball containing the necessary files for CSI functional certification, including test manifests and JUnit XML results.

```bash
cd operator/certification-results

tar czf truenas-csi-functional-cert-results.tar.gz \
  manifest-iscsi.yaml \
  manifest-nfs.yaml \
  iscsi/junit_e2e__*.xml \
  nfs/junit_e2e__*.xml
```

--------------------------------

### Create TrueNAS CSI Resource

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Define the TrueNAS CSI custom resource to configure the driver. Replace placeholders with your TrueNAS details.

```yaml
apiVersion: csi.truenas.io/v1alpha1
kind: TrueNASCSI
metadata:
  name: truenas
spec:
  truenasURL: "wss://your-truenas-ip/api/current"
  credentialsSecret: "truenas-api-credentials"
  defaultPool: "tank"
  nfsServer: "your-truenas-ip"
```

--------------------------------

### Configure Non-Standard Kubelet Path

Source: https://context7.com/truenas/truenas-csi/llms.txt

For Kubernetes distributions like MicroK8s and K3s that use non-default kubelet root directories, update all four locations within the node DaemonSet spec in `deploy/truenas-csi-driver.yaml` to match the distribution's path.

```yaml
# In deploy/truenas-csi-driver.yaml — node DaemonSet section
# Replace every occurrence of /var/lib/kubelet with the distribution path.

```

--------------------------------

### Run NFS CSI Certification Tests

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Execute the NFS CSI certification tests using the `ose-tests` Docker image. Ensure the kubeconfig and NFS manifest are mounted into the container. Use `--network=host` for cluster access and `--max-parallel-tests=1` for serialized execution.

```bash
# NFS tests
docker run --rm --network=host \
  -v /path/to/workdir/kubeconfig.yaml:/kubeconfig.yaml:z \
  -v /path/to/workdir/manifest-nfs.yaml:/manifest.yaml:z \
  -v /path/to/workdir/results-nfs:/results:z \
  registry.redhat.io/openshift4/ose-tests-rhel9:v4.20 \
  openshift-tests run openshift/csi \
    --provider '{"type":"skeleton"}' \
    --max-parallel-tests=1 \
    --timeout 20m \
    --junit-dir /results \
    -o /results/results.txt \
    --file /manifest.yaml
```

--------------------------------

### Verify OpenShift CSI Driver Deployment

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Use these commands to check if the CSI driver pods, StorageClasses, and VolumeSnapshotClass are correctly deployed and configured on the OpenShift cluster.

```bash
# Verify driver pods are running
oc get pods -n truenas-csi

# Verify StorageClasses exist
oc get sc truenas-nfs truenas-iscsi

# Verify VolumeSnapshotClass exists
oc get volumesnapshotclass truenas-snapclass

# VolumeSnapshot CRDs and snapshot controller must be installed
# (CRC does not include these by default)
oc get crd volumesnapshots.snapshot.storage.k8s.io
```

--------------------------------

### Apply API Credentials Secret

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Apply the created Kubernetes Secret to your cluster using the oc command-line tool.

```bash
oc apply -f truenas-api-credentials.yaml
```

--------------------------------

### Push Operator Bundle Image

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Pushes the operator bundle image to the registry, typically done before submitting for review.

```bash
make bundle-push
```

--------------------------------

### Run TrueNAS CSI Driver Tests

Source: https://github.com/truenas/truenas-csi/blob/master/README.md

Execute the test suite for the TrueNAS CSI driver using this command. Ensure all dependencies are met before running tests.

```bash
make test
```

--------------------------------

### Test TrueNAS WebSocket API Connectivity

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/configuration.md

Use `oc run` to launch a temporary pod and test the WebSocket API connection to your TrueNAS IP address. The `-k` flag ignores certificate validation.

```bash
# Test WebSocket connection from a pod
oc run test-ws --rm -it --image=curlimages/curl -- \
  curl -k wss://your-truenas-ip/api/current
```

--------------------------------

### Apply TrueNASCSI Resource

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Apply the TrueNASCSI custom resource definition to your OpenShift cluster.

```bash
oc apply -f truenas-csi.yaml
```

--------------------------------

### Test TrueNAS Volume Provisioning with PVC

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/configuration.md

Create a PersistentVolumeClaim (PVC) to test volume provisioning using the `truenas-iscsi` StorageClass. Apply the PVC definition and monitor its status.

```bash
# Create a test PVC
cat <<EOF | oc apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: truenas-iscsi
  resources:
    requests:
      storage: 1Gi
EOF

# Check PVC status
oc get pvc test-pvc

# Check events for errors
oc describe pvc test-pvc
```

--------------------------------

### Verify CSI Pods

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/installation.md

Check that the CSI controller and node pods are running correctly in the truenas-csi namespace.

```bash
oc get pods -n truenas-csi
```

--------------------------------

### Cleanup Build Artifacts

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Remove temporary build artifacts and downloaded tools to clean up the development environment.

```bash
make clean
```

--------------------------------

### Run iSCSI CSI Certification Tests

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Execute the iSCSI CSI certification tests using the `ose-tests` Docker image. Ensure the kubeconfig and iSCSI manifest are mounted into the container. Use `--network=host` for cluster access and `--max-parallel-tests=1` for serialized execution.

```bash
# iSCSI tests
docker run --rm --network=host \
  -v /path/to/workdir/kubeconfig.yaml:/kubeconfig.yaml:z \
  -v /path/to/workdir/manifest-iscsi.yaml:/manifest.yaml:z \
  -v /path/to/workdir/results-iscsi:/results:z \
  registry.redhat.io/openshift4/ose-tests-rhel9:v4.20 \
  openshift-tests run openshift/csi \
    --provider '{"type":"skeleton"}' \
    --max-parallel-tests=1 \
    --timeout 20m \
    --junit-dir /results \
    -o /results/results.txt \
    --file /manifest.yaml
```

--------------------------------

### Run TrueNAS CSI Driver in All-in-One Mode

Source: https://context7.com/truenas/truenas-csi/llms.txt

This command runs both the controller and node components of the CSI driver in a single process. It's useful for development and testing environments. Ensure the TRUENAS_URL and TRUENAS_API_KEY environment variables are set.

```bash
./bin/truenas-csi \
  --endpoint unix:///csi/csi.sock \
  --mode all
```

--------------------------------

### Verify NFS PVC Binding

Source: https://context7.com/truenas/truenas-csi/llms.txt

This command verifies that the PersistentVolumeClaim has been successfully bound and an NFS dataset has been created on TrueNAS.

```bash
# Verify PVC bound and NFS dataset created on TrueNAS
kubectl get pvc shared-data
# NAME          STATUS   VOLUME                                     CAPACITY   ACCESS MODES
# shared-data   Bound    pvc-3f8e1a2b-...                           5Gi        RWX
```

--------------------------------

### Generate OLM Bundle with Image Digests

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Generate an OLM bundle for the operator, ensuring image digests are used. This is a prerequisite for certification.

```bash
make bundle USE_IMAGE_DIGESTS=true
```

--------------------------------

### Run Scorecard via Make

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Initiates the scorecard validation process using a make target. This is an alternative to running the operator-sdk command directly and can be executed from the project root.

```bash
make scorecard
```

--------------------------------

### Backup TrueNAS CSI CR Configuration

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/upgrade.md

Before upgrading, back up the current TrueNAS CSI CR configuration to a YAML file for potential rollback or reference.

```bash
oc get truenascsi truenas -o yaml > truenas-backup.yaml
```

--------------------------------

### Run Operator SDK Scorecard

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Execute the Operator SDK scorecard against the OLM bundle. This verifies the operator's compliance with OpenShift standards.

```bash
operator-sdk scorecard bundle/
```

--------------------------------

### Build and Release TrueNAS CSI Driver

Source: https://context7.com/truenas/truenas-csi/llms.txt

Use this command to build and push versioned and latest images for the TrueNAS CSI driver and its operator.

```bash
make release VERSION=1.0.0
```

--------------------------------

### Run TrueNAS CSI Driver as Controller

Source: https://context7.com/truenas/truenas-csi/llms.txt

Executes the TrueNAS CSI driver binary in controller mode. This is typically used within the controller Deployment and requires specifying the endpoint, node ID, and log verbosity.

```bash
./bin/truenas-csi \
  --endpoint unix:///csi/csi.sock \
  --node-id my-node \
  --mode controller \
  --v 4
```

--------------------------------

### Run Operator SDK Scorecard

Source: https://github.com/truenas/truenas-csi/blob/master/operator/README.md

Validates the operator bundle against OLM best practices and certification requirements. Run this command from the operator directory to perform the validation.

```bash
# From the operator directory
operator-sdk scorecard bundle/
```

--------------------------------

### Monitor CSI Pods During Upgrade

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/upgrade.md

Observe the CSI driver pods in the `truenas-csi` namespace to ensure they are updating correctly.

```bash
# Watch CSI pods
oc get pods -n truenas-csi -w
```

--------------------------------

### Release New CSI Driver Version

Source: https://github.com/truenas/truenas-csi/blob/master/docs/openshift/certification.md

Build, push, and tag all container images for a new release, updating version information across Makefiles and Dockerfiles.

```bash
make release VERSION=x.y.z
```