Skip to main content
Version: 3.6

Installation on an Azure Red Hat OpenShift Cluster

This topic provides instructions for installing Portworx on an Azure Red Hat OpenShift (ARO) cluster using the OpenShift Container Platform web console. Ensure that your cluster meets all the prerequisites before installing Portworx Enterprise.

The following collection of tasks describe how to install Portworx on an Azure Red Hat OpenShift cluster:

Complete all the tasks to install Portworx.

Prepare your Azure Red Hat OpenShift Cluster​

  1. Create an Azure Red Hat OpenShift cluster. For more information, see Microsoft documentation.
  2. Connect to the Azure Red Hat OpenShift cluster. For more information, see Microsoft documentation.

Configure Authentication​

When deploying Portworx on an Azure Red Hat OpenShift cluster, the worker virtual machines are created in a resource group with a Deny Assignment role that prevents any principal from accessing those resources except the principal that ARO created for the cluster. Portworx must authenticate to Azure APIs using one of the principals that the deny-assignment allows.

Portworx supports two authentication methods on ARO:

  • Azure Service Principal - static credentials (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) stored in a Kubernetes secret. Use the service principal that ARO created for your cluster's resource group.
  • Azure Managed Identity - the user-assigned managed identity that ARO attached to the cluster worker VMs. Portworx reads the identity's client ID from a Kubernetes secret and authenticates through the Azure Instance Metadata Service.

Choose the method that matches your ARO cluster configuration. ARO clusters created with --enable-managed-identity support Managed Identity; clusters created with a service principal use Service Principal.

Before you begin, create the portworx namespace if it does not exist. The px-azure secret must live in this namespace:

oc create namespace portworx

With Service Principal authentication, Portworx reads static credentials from a Kubernetes secret named px-azure and uses them to authenticate to Azure APIs. ARO automatically created a service principal for your cluster's resource group; use that same service principal so the deny-assignment does not block Portworx.

Perform the following steps from the Azure portal to retrieve the cluster's service principal and generate a client secret:

  1. Select Virtual Machines from the top navigation menu.

  2. From the Virtual machines page, select the Resource Group associated with your cluster.

  3. From the left panel on the Resource Group page, select Access control (IAM).

  4. On the Access control (IAM) subpage of your resource group, select Deny assignments from the toolbar in the center of the page, then select the link under the Name column (this is typically an autogenerated string of letters and numbers).
    This page shows that all principals are denied access, except for your resource group.

  5. Select your resource group's name.

  6. From the application page, copy and save the following values:

    • Name
    • Application ID
    • Object ID

    Use these to create the px-azure secret.

  7. From the home page, select All services and search for Microsoft Entra ID.

  8. From the Microsoft Entra ID page, select App registrations on the left pane.

  9. In the search bar in the center of the page, paste the application name you saved in the previous step and press the enter key.
    Select the application link that shows in the results to open the next page.

  10. From your application's page, select Certificates & secrets under Manage from the left pane.

  11. From the Certificates & secrets page, select + New client secret to create a new secret.

  12. On the Add a client secret page, provide the description and expiry date of your secret and click Add.

  13. You can see the newly created secret listed on the Client secret subpage. Copy and save the following values of your newly created secret:

    • Value
    • Secret ID

  14. Create the px-azure Kubernetes secret in the portworx namespace using the values from the previous steps:

    oc create secret generic -n portworx px-azure \
        --from-literal=AZURE_TENANT_ID=<tenant> \
        --from-literal=AZURE_CLIENT_ID=<appId> \
        --from-literal=AZURE_CLIENT_SECRET=<value>
    secret/px-azure created
    • AZURE_TENANT_ID: Run the az login command to get this value.
    • AZURE_CLIENT_ID: Provide the Application ID associated with your cluster's resource group, which you saved in step 6.
    • AZURE_CLIENT_SECRET: Provide the Value of the client secret you created in step 13.

After you create the secret, the spec generator automatically incorporates it, and Portworx fetches the secret to authenticate.

Create a monitoring ConfigMap​

Enable monitoring for user-defined projects before installing the Portworx Operator. Use the instructions in this section to configure the OpenShift Prometheus deployment to monitor Portworx metrics.

To integrate OpenShift’s monitoring and alerting system with Portworx, create a cluster-monitoring-config ConfigMap in the openshift-monitoring namespace:

apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-monitoring-config
  namespace: openshift-monitoring
data:
  config.yaml: |
    enableUserWorkload: true

The enableUserWorkload parameter enables monitoring for user-defined projects in the OpenShift cluster. This creates a prometheus-operated service in the openshift-user-workload-monitoring namespace.

Install Portworx Operator using OpenShift Console​

  1. Sign in to the OpenShift Container Platform web console.

  2. From the left navigation pane, select OperatorHub.
    The system displays the OperatorHub page.

  3. Search for Portworx Operator and select Portworx Operator.
    The system displays the Portworx Operator page.

  4. Click Install.
    The system initiates the Portworx Operator installation and displays the Install Operator page.

  5. In the Installation mode section, select A specific namespace on the cluster.

  6. From the Installed Namespace dropdown, choose Create Project.
    The system displays the Create Project window.

  7. Provide the name portworx and click Create to create a namespace called portworx.

  8. In the Console plugin section, select Enable to manage your Portworx cluster using the Portworx dashboard within the OpenShift console.

    note

    If the Portworx Operator is installed but the OpenShift Console plugin is not enabled, or was previously disabled, you can re-enable it by running the following command.

    oc patch console.operator cluster --type=json -p='[{"op":"add","path":"/spec/plugins/-","value":"portworx"}]'

  9. Click Install to deploy Portworx Operator in the portworx namespace.
    After you successfully install Portworx Operator, the system displays the Create StorageCluster option.

Install Portworx​

You can install Portworx using one of the following methods:

Install Portworx using Specification​

  1. Sign in to the Portworx Central console.
    The system displays the Welcome to Portworx Central! page.

  2. In the Portworx Enterprise section, select Generate Cluster Spec.
    The system displays the Generate Spec page.

  3. From the Portworx Version dropdown menu, select the Portworx version to install.

  4. From the Platform dropdown menu, select Azure.

  5. From the Distribution Name dropdown menu, select Azure Red Hat OpenShift (ARO)+.

  6. In the Namespace field, enter the namespace where you plan to install Portworx.
    By default, the namespace is portworx.

  7. (Optional) To customize the configuration options and generate a custom specification, click Customize and perform the following steps:

    note

    To continue without customizing the default configuration or generating a custom specification, proceed to Step 8.

  • Basic tab:
    1. Select one of the following:
    • To use an existing etcd cluster, do the following:
      1. Select the Your etcd details option.
      2. In the field provided, enter the host name or IP and port number. For example, http://test.com.net:1234.
        To add another etcd cluster, click the + icon.
        note

        You can add up to three etcd clusters.

      3. Select one of the following authentication methods:
        • Disable HTTPS – To use HTTP for etcd communication.
        • Certificate Auth – To use HTTPS with an SSL certificate.
          For more information, see Secure your etcd communication.
        • Password Auth – To use HTTPS with username and password authentication.
    • To use an internal Portworx-managed key-value store (kvdb), do the following:
      1. Select the Built-in option.
      2. TLS for internal KVDB is enabled, by default. If Cert-Manager is already running in your Kubernetes cluster, deselect the Deploy Cert-Manager for TLS certificates option to avoid installation failures.
    1. Select Next.
  • Storage tab:
    1. Select one of the following:
    • To enable Portworx to provision drives using a specification, do the following:
      1. Select the Create Using a Spec option.
      2. Select PX-Store Version: (Optional) To designate PX-StoreV1 as the datastore, select PX-StoreV1. By default, the system selects PX-StoreV2 as the datastore.
      3. To add one or more cloud storage drive types for Portworx to use, click + Add Drive and select one of the following types of drives:
        • Standard HDD
        • Standard SSD
        • Premium SSD
        • Premium SSD v2
        • Ultra disk
        note
        • To use an Ultra disk, the Azure instance must have the Ultra SSD feature enabled.
        • The system automatically selects the minimum number of drives to ensure optimal performance.
      4. Configure the following fields for the drive:
        • Size (GB) - Specify the size of the drive in gigabytes.
        • IOPS - Enter the input/output operations per second (IOPS) value for the drive.
          note
          • IOPS is required when you select Ultra Disk drive type.
          • If you do not specify an IOPS value for Premium SSDv2, Portworx uses the default value of 3000.
        • Throughput - Enter the required data transfer rate for the drive.
          note
          • Throughput is required when you select Ultra Disk drive type.
          • If you do not specify a Throughput value for Premium SSDv2, Portworx uses the default value of 125.
        • Encryption - Choose None to disable encryption or BYOK Encryption to encrypt your Azure cluster data disk using BYOK encryption.
        • Encryption Key - If you choose BYOK Encryption, specify the key to use for BYOK encryption.
        • Drive Tags - Add labels in key:value format to organize and identify drives.
          This is useful for policies and workload mapping.
        • Action - Use the trash icon to remove a drive type from the configuration.
      5. Initial Storage Nodes (Optional): Enter the number of storage nodes that need to be created across zones and node pools.
      6. From the Default IO Profile dropdown menu, select Auto.
        This enables Portworx to automatically choose the best I/O profile based on detected workload patterns.
      7. From the Journal Device dropdown menu, select one of the following:
        • None – To use the default journaling setting.
        • Auto – To automatically allocate journal devices.
        • Custom – To manually enter a journal device path.
          Enter the path of the journal device in the Journal Device Path field.
    • To enable Portworx to use all available, unused, and unmounted drives on the node, do the following:
      1. Select the Consume Unused option.
      2. From the Journal Device dropdown menu, select one of the following:
        • None – To use the default journaling setting.
        • Auto – To automatically allocate journal devices.
        • Custom – To manually enter a journal device path.
          Enter the path of the journal device in the Journal Device Path field.
      3. (Optional) To designate PX-StoreV1 as the datastore, clear the PX-StoreV2 checkbox. By default, the system selects PX-StoreV2 as the datastore.
      4. For PX-StoreV2, in the Metadata Path field, enter a pre-provisioned path for storing the Portworx metadata.
        The path must be at least 64 GB in size.
      5. Select the Use unmounted disks even if they have a partition or filesystem on it. Portworx will never use a drive or partition that is mounted checkbox to use unmounted disks, even if they contain a partition or filesystem.
        Portworx will not use any mounted drive or partition.
    • To enable Portworx to use existing drives on a node, do the following:
      1. Select the Use Existing Drives option.
      2. In the Drive/Device field, specify the block drive(s) that Portworx uses for data storage.
      3. In the Pool Label field, assign a custom label in key:value format to identify and categorize storage pools.
      4. (Optional) To designate PX-StoreV1 as the datastore, clear the PX-StoreV2 checkbox. By default, the system selects PX-StoreV2 as the datastore.
      5. For PX-StoreV2, in the Metadata Path field, enter a pre-provisioned path for storing the Portworx metadata.
        The path must be at least 64 GB in size.
      6. From the Journal Device dropdown menu, select one of the following:
        • None – To use the default journaling setting.
        • Auto – To automatically allocate journal devices.
        • Custom – To manually enter a journal device path.
          Enter the path of the journal device in the Journal Device Path field.
    1. Select Next.
  • Network tab:
    1. In the Interface(s) section, do the following:
      1. Enter the Data Network Interface to be used for data traffic.
      2. Enter the Management Network Interface to be used for management traffic.
    2. In the Advanced Settings section, do the following:
      1. Enter the Starting port for Portworx services.
    3. Select Next.
  • Deployment tab:

    1. In the Kubernetes Distribution section, under Are you running on either of these?, select Azure Red Hat OpenShift (ARO)+.

    2. In the Component Settings section:

      1. Select the Enable Stork checkbox to enable Stork.
        • Select the Restrict Data Protection RBAC to restrict RBAC permissions for Stork (if enabled). You will not be able to use Backup and DR capabilities with this restriction. For more information, see Restrict Data Protection RBAC.
      2. Select the Enable Monitoring checkbox to enable monitoring of Portworx components and resources.
        • To configure the monitoring stack, select one of the following:
          • Portworx Managed - To enable Portworx to install and manage Prometheus and Operator automatically.
            Ensure that no other Prometheus Operator instance already running on the cluster.
          • User Managed - To configure and manage your own monitoring stack.
        • Select the Enable Autopilot checkbox to enable Portworx Autopilot. For User Managed monitoring stack, Portworx supports the following metrics providers that Autopilot will use to fetch metrics for rule evaluation and automated actions.
      3. Select the Enable Telemetry checkbox to enable telemetry in the StorageCluster spec.
        For more information, see Enable Pure1 integration for upgrades on an Azure Red Hat OpenShift cluster.
      4. Enter the prefix for the Portworx cluster name in the Cluster Name Prefix field.
      5. Select the Secrets Store Type from the dropdown menu to store and manage secure information for features such as CloudSnaps and Encryption.

    3. In the Identity and Access Management (IAM) section, choose one of the following authentication methods to use for Portworx to access Azure resources:

      • Managed Identity - To use the user-assigned managed identity that ARO attached to the cluster's worker VMs.
        If you selected this option, the spec generator automatically fetches the px-azure secret that contains the managed identity's client ID (AZURE_CLIENT_ID) stored in a Kubernetes secret.
      • Static Credentials - To use a service principal with static credentials.
        If you selected this option, the spec generator automatically fetches the px-azure secret that contains the static credentials (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET) stored in a Kubernetes secret.

      Your selection here must match the authentication method you configured in the Configure Authentication section.

    4. In the Environment Variables section, enter name-value pairs in the respective fields.

      note

      For deploying Portworx on an Azure Sovereign cloud, specify the value of the AZURE_ENVIRONMENT variable in the Name and Value fields.

    5. In the Registry and Image Settings section:

      1. Enter the Custom Container Registry Location to download the Docker images.
      2. Enter the Kubernetes Docker Registry Secret that serves as the authentication to access the custom container registry.
      3. From the Image Pull Policy dropdown menu, select Default, Always, IfNotPresent, or Never.
        This policy influences how images are managed on the node and when updates are applied.

    6. In the Security Settings section, select the Enable Authorization checkbox to enable Role-Based Access Control (RBAC) and secure access to storage resources in your cluster.

    7. Click Finish.

    8. In the summary page, enter a name for the specification in the Spec Name field, and tags in the Spec Tags field.

    9. Click Download .yaml to download the yaml file with the customized specification or Save Spec to save the specification.

  1. Click Save & Download to generate the specification.
  2. Use the generated specification to install Portworx in your cluster.

Install Portworx using OpenShift Console​

  1. Click Create StorageCluster.
    The system displays the Create StorageCluster page.

  2. Select YAML view.

  3. Copy and paste the specification that you generated in the Install Portworx using Specification section into the text editor.

  4. Click Create.
    The system deploys Portworx, and displays the Portworx instance in the Storage Cluster tab of the Installed Operators page.

    note

    The system performs a pre-flight check on each node after Portworx is installed. This check verifies whether the hardware and software on each node meet the PX-StoreV2 prerequisites. PX-StoreV2 is installed only if all nodes in the cluster pass this compatibility check.

Verify Portworx Cluster Status​

After you install Portworx Operator and create the StorageCluster, you can see the Portworx option in the left pane of the OpenShift UI.

  1. Click the Cluster sub-tab to view the Portworx dashboard. If Portworx is installed correctly, the status will be displayed as Running. You can also see the information about the status of Telemetry, Monitoring, and the version of Portworx and its components installed in your cluster.
  2. Navigate to the Node Summary section. If your cluster is running as intended, the status of all Portworx nodes displays Online.

Verify Portworx Pod Status​

  1. From the left pane of the OpenShift UI, click Pods under the Workload option.
  2. To check the status of all pods in the portworx namespace, select portworx from the Project drop-down. If Portworx is installed correctly, then all pods should be in Running status.

What to do next​

Create a PVC. For more information, see Create your first PVC.

Last updated on