Limited Availability: PowerShell deployment to Red Hat OpenShift

The deployment process includes creating a bootable volume in OpenShift and deploying the Unified Access Gateway instance by using the delivered QCOW2 image.

Prerequisites

Recommended Operating Systems for running the PowerShell deployment script

OpenShift environment requirements

• The target namespace exists in the OpenShift cluster.
• A supported StorageClass is available at the cluster level.
• The required NetworkAttachmentDefinitions exists in the target deployment namespace. If not found in the target namespace, the deployment uses a NetworkAttachmentDefinition with the same name from the default namespace.
• If you enforce network policies, the required NetworkPolicy resources exist in the target deployment namespace. Network policies are applied based on podSelector label matching. The labels assigned to the Unified Access Gateway resources must match the selectors defined in the policies.
• Sufficient cluster resources, including CPU, memory, and storage are available to support the deployment.
• The deployment user or service account has the required RBAC permissions.

Bootable volume creation requirements

• For Web Console-based bootable volume creation, download the Unified Access Gateway (UAG) QCOW2 for Nutanix and OpenShift image from Customer Connect and save on your local machine.
• For PowerShell-based bootable volume creation, ensure the following:
  • The Unified Access Gateway QCOW2 image is available through an HTTP or HTTPS URL that is reachable from the OpenShift cluster.
  • The OpenShift CLI tool (oc) is installed and available on the VM used for performing deployment.
  • You have the required credentials or token to log in to the target OpenShift cluster by using the OpenShift CLI.

Install and verify the OpenShift CLI

The OpenShift CLI tool oc is required to interact with the OpenShift cluster. Install the OpenShift CLI binary on Windows.

1. Go to OpenShift Container Platform downloads section on the Red Hat Customer Portal.
2. From the Version drop-down menu, select the required OpenShift version.
3. Locate the OpenShift v Windows Client entry and click Download Now to download the archive.
4. Extract the downloaded ZIP file.
5. Place the oc binary in a directory that is available in the system PATH.

After you install the OpenShift CLI, you can use the oc command from Command Prompt:

C:\> oc <command>

Verify that the OpenShift CLI is installed successfully. This command displays the installed oc client version.

C:\> oc version

Prepare an INI file

1. Configure the required settings in the [General] section. See PowerShell deployment parameters.

2. In the .ini file, add a new group, [OpenShift] and the necessary settings specific to OpenShift.

   * indicates these parameters are mandatory.

   Parameter	Description	Example
   openShiftUserName*	OpenShift user account or service account with sufficient RBAC permissions to authenticate and create and manage resources in the target namespace.	admin
   openShiftEndpoint*	Fully qualified OpenShift API server endpoint, including port.	https://cluster.example.com:6443
   namespace*	Target OpenShift project, or namespace, where all Unified Access Gateway resources are created and managed.	uag-namespace
   instanceType*	VM instance profile that defines the CPU and memory allocation for the Unified Access Gateway virtual machine. Minimum of 2CPU and 4GB RAM
   storageClass*	Storage class used for dynamic provisioning of persistent volumes that the deployment requires.	uag-standard-storage
   diskSizeGi*	Size of the Unified Access Gateway root disk in GiB. Minimum disk size should be20GB
   volume*	Name of the bootable volume that you use to create the Unified Access Gateway VM. The volume must exist in the target deployment namespace.	uag-bootable-volume
   nadName0*	Primary NetworkAttachmentDefinition that provides network connectivity for NIC 0. It should exist in the target namespace. If not found, a NetworkAttachmentDefinition with the same name in the default namespace is used.	uag-external-network
   networkPolicies	A comma-separated list of existing OpenShift NetworkPolicy resources that you can associate with the deployment for reference and validation purposes. These policies must exist in the target namespace or in the default namespace if not found in the target. Network policies are applied to the VM based on label matching defined in the podSelector. The policy is enforced only when the labels on the VM and its backing pod match the selector criteria.	uag-policy1,uag-policy2
   labels	Key-value labels assigned to Unified Access Gateway resources, including the VM and underlying pods. You can use these labels for resource identification, grouping, selection, and integration with other OpenShift or Kubernetes features such as scheduling, monitoring, and network policies.	env=prod,app=uag
   bearerToken	OpenShift bearer token for authentication. If you specify this parameter, the deployment uses this token instead of username and password authentication.	sha256~xxxxxx

Sample INI configuration for a single Unified Access Gateway deployment

[General]
name=<vm_name>
deploymentOption=<onenic|twonic|threenic>
ipMode0=<DHCPV4|STATICV4>

[OpenShift]
openShiftUserName=<openshift_username>
openShiftEndpoint=<openshift_api_endpoint:port>
namespace=<target_namespace>
instanceType=<flavor_or_size>
storageClass=<storage_class_name>
diskSizeGi=<disk_size_in_Gi>

# Must exist in the target deployment namespace
volume=<bootable_volume_name>

# Should exist in the target namespace; falls back to default namespace if not found
nadName0=<network_attachment_name>

When you use network policies, they rely on label matching, podSelector, to determine whether a policy applies to the Unified Access Gateway workload.

Procedure

Step 1: Create the bootable volume

You can create the Unified Access Gateway bootable volume by using either the OpenShift Web Console or the OpenShift CLI in PowerShell. Select the method that best suits your workflow.

Option 1: Create the bootable volume by using the OpenShift Web Console

1. Log in to the OpenShift Web Console.
2. Navigate to Virtualization > Bootable Volumes.
3. Switch to the target project, the namespace that you created for the Unified Access Gateway deployment.
4. Click Add Volume > With Upload Form.
5. Configure the following settings:
   • Source Type: Volume
   • Upload: Select the downloaded QCOW2 file
   • Storage Class: Select from the drop-down menu
   • Volume Mode: Filesystem (recommended)
   • Access Mode: Shared access (RWX) (recommended)
   • Disk Size: 20 GiB. Ensure that you specify the same value in the INI file.
   • Volume Name: Enter a meaningful name
   • Destination Project: Select the Unified Access Gateway namespace
   • Volume metadata > Preference: Linux (required)
   • Description: Optional
6. Click Save and wait for the upload to complete.
7. Verify that the bootable volume is listed and available under Virtualization > Bootable Volumes.

Option 2: Create the bootable volume by using the OpenShift CLI in PowerShell

1) Log in to the OpenShift cluster

Before you apply the bootable volume manifest, log in to the target OpenShift cluster by using the OpenShift CLI.

Run the following command:

C:\> oc login --token=<api-token> --server=<openshift-api-server-url>

Alternatively, log in by using your username and password if token-based login is not used:

C:\> oc login --server=<openshift-api-server-url> --username=<username> --password=<password>

2) Prepare and apply the bootable volume manifest

Create a file with the name bootable-volume.yaml.

This manifest creates the Unified Access Gateway bootable volume in OpenShift Virtualization. It imports the QCOW2 image into a PersistentVolumeClaim and creates a DataSource that points to the same PVC. The DataSource makes the imported volume appear as a bootable volume in the OpenShift UI.

Update the placeholder values enclosed in < > based on your target OpenShift cluster.

apiVersion: cdi.kubevirt.io/v1beta1
kind: DataVolume
metadata:
  name: <volume-name>
  namespace: <destination-project>
  annotations:
    description: "<description>"
spec:
  source:
    http:
      url: "<qcow2-image-url>"
  storage:
    accessModes:
      - ReadWriteMany
    volumeMode: Filesystem
    resources:
      requests:
        storage: <disk-size>
    storageClassName: <storage-class>
---
apiVersion: cdi.kubevirt.io/v1beta1
kind: DataSource
metadata:
  name: <volume-name>
  namespace: <destination-project>
  labels:
    instancetype.kubevirt.io/default-preference: linux
  annotations:
    vm.kubevirt.io/os: "linux"
    description: "<description>"
spec:
  source:
    pvc:
      name: <volume-name>
      namespace: <destination-project>

Update the following values before you apply the manifest.

Run the following command and provide the path to the bootable-volume.yaml file:

C:\> oc apply -f <path-to-bootable-volume.yaml>

This creates the DataVolume and DataSource resources in the specified namespace.

If the manifest is applied successfully, a similar output appears:

datavolume.cdi.kubevirt.io/<volume-name> created
datasource.cdi.kubevirt.io/<volume-name> created

3) Track the image import and verify the PVC

The CDI controller creates an importer pod to download the Unified Access Gateway QCOW2 image and write it to the storage volume. Track the import progress by running the following command:

C:\> oc get dv <volume-name> -n <destination-project>

Result: The import is complete when the DataVolume phase is Succeeded and the progress is 100.0%.

Verify that the PVC is created and in the Bound state:

C:\> oc get pvc <volume-name> -n <destination-project>

If the import fails or does not progress, run the following command to view detailed status and events:

C:\> oc describe dv <volume-name> -n <destination-project>

4) Verify the DataSource

Run the following command to verify that the DataSource is created successfully:

C:\> oc get datasource <volume-name> -n <destination-project>

The DataSource is valid when it is listed successfully.

Output is similar to the following:

NAME            AGE
<volume-name>   <age>

The DataSource points to the PVC that is created from the Unified Access Gateway QCOW2 image and makes the volume available as a bootable volume in the OpenShift UI.

5) Log out from the OpenShift cluster

After you complete the bootable volume creation and verification, log out from the OpenShift cluster.

C:\> oc logout

Step 2: Deploy to Red Hat OpenShift

1. From the Omnissa Customer Connect, go to Unified Access Gateway (UAG) PowerShell Scripts file and click DOWNLOAD NOW.
   A zip file uagdeploy-xx.xx.x.x-xxxxxxxx is downloaded on your local machine.

2. Extract the files from the zip file. Ensure that the following PowerShell scripts are available on your machine.
   uagdeployopenshift.ps1 and uagdeploy.psm1 on your Windows machine.

3. Start a PowerShell command window and change the directory to the folder that contains the downloaded scripts.

4. Run the following command.

   .\uagdeployopenshift.ps1 -iniFile <ini-filename>.ini

5. Enter the admin and root password when prompted. For more information about the root user and admin password requirements, see Password requirements. Alternatively, you can use non-interactive mode to deploy. For more information, see Non-Interactive mode deployment parameters.

Verify the deployment status

After the deployment is complete, verify the status in the PowerShell console.

A successful deployment displays messages indicating that the virtual machine is deployed successfully and is in the Running and Ready state. The PowerShell console also displays deployment details such as the VM name, namespace, number of network interfaces, and assigned IP addresses.

Alternatively, log in to the OpenShift Web Console and navigate to Virtualization > Virtual Machines. Confirm that the Unified Access Gateway VM is created and in the Running state, and verify that the VM is assigned an IP address.