Install Portworx on Elastic Kubernetes Service and EKS-D

This topic explains how to install Portworx on Amazon Web Services (AWS) Elastic Kubernetes Service (EKS) and EKS-D.

Prerequisites

• An AWS EKS cluster that meets the Portworx prerequisites

• You must have the supported disk types

• Recommended disk sizes:

  • GP2: 150 (GB) size disk is needed as the minimum IOP require.
  • GP3 specify IOPS required from EBS volume and specify throughput for EBS volume
  • IO1 specify IOPS required from EBS volume

• For production environments Portworx by Pure Storage recommends 3 Availability Zones (AZs)

• For installation on EKS version 1.30, ensure to increase the HttpPutResponseHopLimit to 3 for all nodes on which Portworx will be installed by running the following command:

  aws ec2 modify-instance-metadata-options --instance-id <instanceID> --http-put-response-hop-limit 3 --http-endpoint enabled 

• Portworx by Pure Storage recommends you set Max storage nodes per availability zone, Portworx will ensure that many storage nodes exist in the zone

note

• You can follow the same procedures explained in this topic to deploy Portworx on AWS Outposts.
• You can also follow the steps in this topic to install Portworx on EKS-D.
• For details on GP2, GP3, and IO1 performance characteristics, refer to the AWS documentation.

Create an IAM policy

Provide the permissions for all the instances in the autoscaling cluster by creating an IAM role.

Perform the following steps on your AWS Console:

For non-encrypted volumes

1. Navigate to the IAM page on your AWS console, then select Policies under the Identity and Access Management (IAM) sidebar section, then select the Create Policy button in the upper right corner:

   

2. Choose the JSON tab, then paste the following permissions into the editor, providing your own value for Sid if applicable. You can either use the minimum permissions required or use the permissions required for disk encryption:

   note

   These are the minimum permissions needed for storage operations for a Portworx cluster. For complete permissions required for all of Portworx storage operations, see the credentials reference.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "", 
               "Effect": "Allow",
               "Action": [
                   "ec2:AttachVolume",
                   "ec2:ModifyVolume",
                   "ec2:DetachVolume",
                   "ec2:CreateTags",
                   "ec2:CreateVolume",
                   "ec2:DeleteTags",
                   "ec2:DeleteVolume",
                   "ec2:DescribeTags",
                   "ec2:DescribeVolumeAttribute",
                   "ec2:DescribeVolumesModifications",
                   "ec2:DescribeVolumeStatus",
                   "ec2:DescribeVolumes",
                   "ec2:DescribeInstances",
                   "autoscaling:DescribeAutoScalingGroups"
               ],
               "Resource": ["*"]
           }
       ]
   }

3. Name and create the policy.

   

For encrypted volumes

1. Navigate to the IAM page on your AWS console, then select Policies under the Identity and Access Management (IAM) sidebar section, then select the Create Policy button in the upper right corner:

   

2. Choose the JSON tab, then paste the following permissions into the editor, providing your own value for Sid if applicable. You can either use the minimum permissions required or use the permissions required for disk encryption:

   note

   These are the minimum permissions needed for storage operations for a Portworx cluster. For complete permissions required for all of Portworx storage operations, see the credentials reference.

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "", 
               "Effect": "Allow",
               "Action": [
                   "ec2:AttachVolume",
                   "ec2:ModifyVolume",
                   "ec2:DetachVolume",
                   "ec2:CreateTags",
                   "ec2:CreateVolume",
                   "ec2:DeleteTags",
                   "ec2:DeleteVolume",
                   "ec2:DescribeTags",
                   "ec2:DescribeVolumeAttribute",
                   "ec2:DescribeVolumesModifications",
                   "ec2:DescribeVolumeStatus",
                   "ec2:DescribeVolumes",
                   "ec2:DescribeInstances",
                   "autoscaling:DescribeAutoScalingGroups"
               ],
               "Resource": ["arn:aws:kms:*:<account-id>:key/<kms-key-id>"]
           }
       ]
   }

3. Name and create the policy.

   

Attach IAM policy

Attach the above created policy to your Node instance role or user account.

Attach policy to a Node Instanace Role

Follow the instructions below for attaching the policy with your NodeInstanceRole:

1. From the IAM page, click Roles in the left pane.

2. On the Roles page, search for and select your nodegroup NodeInstanceRole using your cluster name. The following example shows eksctl-victorpeksdemo2-nodegroup-NodeInstanceRole-M9QTT58HQ9ZX as the nodegroup Instance Role:

   

   note

   If there are more than one nodegroup NodeInstanceRole for your cluster, attach the policy to those NodeInstanceRoles as well.

3. Attach the previously created policy by selecting Attach policies from the Add permissions dropdown on the right side of the screen:

   

4. Under Other permissions policies, search for your policy name. Select your policy name and select the Attach policies button to attach it.

   The policy you attached will appear under Permissions policies if successful:

   

Attach policy to your AWS user account

1. From the IAM page, click Users in the left pane.

2. On the Users page, search for and select your AWS user account.

3. On your user account detail page, click Add permissions in the upper right corner of the Permissions policies section.

4. Select Attach policies directly in the Permissions options section.

5. Use the search bar in the Permissions policies section to search and select your previously created policy, and click Next.

6. Click Add permissions to attach the policy to your AWS user account.

   Once the policy is successfully attached to your user account, you will be navigated back to your user account detail page and the policy will be listed in the Permissions policies section.

Deploy Portworx

Follow this section to deploy Portworx.

Generate specs

To install Portworx with Kubernetes, you must generate Kubernetes manifests that you will deploy in your cluster.

1. Navigate to Portworx Central and log in, or create an account, then follow the process to generate a spec.

2. Select Portworx Enterprise from the product catalog and click Continue.

3. On the Product Line page, choose any option depending on which license you intend to use, then select Continue to start the spec generator.

4. For Platform, select your K8s AWS as your cloud environment.

5. For Distribution Name, select Elastic Kubernetes Service (EKS).

6. Click Save Spec to generate the specs. You may customize the storage and network for your Portworx cluster if needed, by clicking on Customize.

important

As the PX-StoreV2 option is set to Auto, the Operator performs a pre-flight check across the cluster to determine if your cluster is capable of deploying Portworx with the PX-StoreV2 datastore. If the pre-flight check passes for each node, then PX-StoreV2 will be automatically selected as your default datastore during Portworx installation.

Apply specs

Apply the Operator and StorageCluster specs you generated in the section above using the kubectl apply command:

1. Deploy the Operator:

   kubectl apply -f 'https://install.portworx.com/<version-number>?comp=pxoperator'

   serviceaccount/portworx-operator created
   podsecuritypolicy.policy/px-operator created
   clusterrole.rbac.authorization.k8s.io/portworx-operator created
   clusterrolebinding.rbac.authorization.k8s.io/portworx-operator created
   deployment.apps/portworx-operator created

2. Deploy the StorageCluster:

   kubectl apply -f 'https://install.portworx.com/<version-number>?operator=true&mc=false&kbver=&b=true&kd=type%3Dgp2%2Csize%3D150&s=%22type%3Dgp2%2Csize%3D150%22&c=px-cluster-XXXX-XXXX&eks=true&stork=true&csi=true&mon=true&tel=false&st=k8s&e==AWS_ACCESS_KEY_ID%3XXXX%2CAWS_SECRET_ACCESS_KEY%3XXXX&promop=true'

   storagecluster.core.libopenstorage.org/px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-8dfd338e915b created

Monitor Portworx nodes

1. Enter the following kubectl get command and wait until all Portworx nodes show as Online in the output:

   kubectl -n <px-namespace> get storagenodes -l name=portworx

   NAME                 ID                                     STATUS   VERSION          AGE
   username-k8s1-node0   xxxxxxxx-xxxx-xxxx-xxxx-43cf085e764e   Online   2.11.1-3a5f406   4m52s
   username-k8s1-node1   xxxxxxxx-xxxx-xxxx-xxxx-4597de6fdd32   Online   2.11.1-3a5f406   4m52s
   username-k8s1-node2   xxxxxxxx-xxxx-xxxx-xxxx-e2169ffa111c   Online   2.11.1-3a5f406   4m52s

2. Enter the following kubectl describe command with the NAME of one of the Portworx nodes you retrieved above to show the current installation status for individual nodes:

   kubectl -n <px-namespace> describe storagenode <portworx-node-name>

   ...
   Events:
       Type     Reason                             Age                     From                  Message
       ----     ------                             ----                    ----                  -------
       Normal   PortworxMonitorImagePullInPrgress  7m48s                   portworx, k8s-node-2  Portworx image portworx/px-enterprise:2.10.1.1 pull and extraction in progress
       Warning  NodeStateChange                    5m26s                   portworx, k8s-node-2  Node is not in quorum. Waiting to connect to peer nodes on port 9002.
       Normal   NodeStartSuccess                   5m7s                    portworx, k8s-node-2  PX is ready on this node
   note

   • In your output, the image pulled will differ based on your chosen Portworx license type and version.
   • For Portworx Enterprise, the default license activated on the cluster is a 30 day trial that you can convert to a SaaS-based model or a generic fixed license.
   • For Portworx Essentials, your cluster must have internet connectivity so that it can send usage information every 24 hours to renew the license on the cluster. You can convert an Essentials license to either a fixed license or SaaS-based license.

Verify your Portworx installation Once you've installed Portworx, you can perform the following tasks to verify that Portworx has installed correctly.

Verify if all pods are running Enter the following kubectl get pods command to list and filter the results for Portworx pods:

kubectl get pods -n <px-namespace> -o wide | grep -e portworx -e px

portworx-api-774c2                                      1/1     Running   0                2m55s   192.168.121.196   username-k8s1-node0    <none>           <none>
portworx-api-t4lf9                                      1/1     Running   0                2m55s   192.168.121.99    username-k8s1-node1    <none>           <none>
portworx-api-dvw64                                      1/1     Running   0                2m55s   192.168.121.99    username-k8s1-node2    <none>           <none>
portworx-kvdb-94bpk                                     1/1     Running   0                4s      192.168.121.196   username-k8s1-node0    <none>           <none>
portworx-kvdb-8b67l                                     1/1     Running   0                10s     192.168.121.196   username-k8s1-node1    <none>           <none>
portworx-kvdb-fj72p                                     1/1     Running   0                30s     192.168.121.196   username-k8s1-node2    <none>           <none>
portworx-operator-58967ddd6d-kmz6c                      1/1     Running   0                4m1s    10.244.1.99       username-k8s1-node0    <none>           <none>
prometheus-px-prometheus-0                              2/2     Running   0                2m41s   10.244.1.105      username-k8s1-node0    <none>           <none>
px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-3e9bf3cd834d-9gs79   2/2     Running   0                2m55s   192.168.121.196   username-k8s1-node0    <none>           <none>
px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-3e9bf3cd834d-vpptx   2/2     Running   0                2m55s   192.168.121.99    username-k8s1-node1    <none>           <none>
px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-3e9bf3cd834d-bxmpn   2/2     Running   0                2m55s   192.168.121.191   username-k8s1-node2    <none>           <none>
px-csi-ext-868fcb9fc6-54bmc                             4/4     Running   0                3m5s    10.244.1.103      username-k8s1-node0    <none>           <none>
px-csi-ext-868fcb9fc6-8tk79                             4/4     Running   0                3m5s    10.244.1.102      username-k8s1-node2    <none>           <none>
px-csi-ext-868fcb9fc6-vbqzk                             4/4     Running   0                3m5s    10.244.3.107      username-k8s1-node1    <none>           <none>
px-prometheus-operator-59b98b5897-9nwfv                 1/1     Running   0                3m3s    10.244.1.104      username-k8s1-node0    <none>           <none>

Note the name of one of your px-cluster pods. You'll run pxctl commands from these pods in following steps.

Verify Portworx cluster status You can find the status of the Portworx cluster by running pxctl status commands from a pod. Enter the following kubectl exec command, specifying the pod name you retrieved in the previous section:

kubectl exec <pod-name> -n <px-namespace> -- /opt/pwx/bin/pxctl status

Defaulted container "portworx" out of: portworx, csi-node-driver-registrar
Status: PX is operational
Telemetry: Disabled or Unhealthy
Metering: Disabled or Unhealthy
License: Trial (expires in 31 days)
Node ID: xxxxxxxx-xxxx-xxxx-xxxx-70c31d0f478e
        IP: 192.168.121.99 
        Local Storage Pool: 1 pool
        POOL    IO_PRIORITY     RAID_LEVEL      USABLE  USED    STATUS  ZONE    REGION
        0       HIGH            raid0           3.0 TiB 10 GiB  Online  default default
        Local Storage Devices: 3 devices
        Device  Path            Media Type              Size            Last-Scan
        0:1     /dev/vdb        STORAGE_MEDIUM_MAGNETIC 1.0 TiB         14 Jul 22 22:03 UTC
        0:2     /dev/vdc        STORAGE_MEDIUM_MAGNETIC 1.0 TiB         14 Jul 22 22:03 UTC
        0:3     /dev/vdd        STORAGE_MEDIUM_MAGNETIC 1.0 TiB         14 Jul 22 22:03 UTC
        * Internal kvdb on this node is sharing this storage device /dev/vdc  to store its data.
        total           -       3.0 TiB
        Cache Devices:
         * No cache devices
Cluster Summary
        Cluster ID: px-cluster-xxxxxxxx-xxxx-xxxx-xxxx-3e9bf3cd834d
        Cluster UUID: xxxxxxxx-xxxx-xxxx-xxxx-6f3fd5522eae
        Scheduler: kubernetes
        Nodes: 3 node(s) with storage (3 online)
        IP              ID                                      SchedulerNodeName       Auth            StorageNode     Used    Capacity        Status  StorageStatus       Version         Kernel                  OS
        192.168.121.196 xxxxxxxx-xxxx-xxxx-xxxx-fad8c65b8edc    username-k8s1-node0      Disabled        Yes             10 GiB  3.0 TiB         Online  Up 2.11.0-81faacc   3.10.0-1127.el7.x86_64  CentOS Linux 7 (Core)
        192.168.121.99  xxxxxxxx-xxxx-xxxx-xxxx-70c31d0f478e    username-k8s1-node1      Disabled        Yes             10 GiB  3.0 TiB         Online  Up (This node)      2.11.0-81faacc  3.10.0-1127.el7.x86_64  CentOS Linux 7 (Core)
        192.168.121.191 xxxxxxxx-xxxx-xxxx-xxxx-19d45b4c541a    username-k8s1-node2      Disabled        Yes             10 GiB  3.0 TiB         Online  Up  2.11.0-81faacc  3.10.0-1127.el7.x86_64  CentOS Linux 7 (Core)
Global Storage Pool        
        Total Used      :  30 GiB
        Total Capacity  :  9.0 TiB

Create your first PVC

For your apps to use persistent volumes powered by Portworx, you must use a StorageClass that references Portworx as the provisioner. Portworx includes a number of default StorageClasses, which you can reference with PersistentVolumeClaims (PVCs) you create. For a more general overview of how storage works within Kubernetes, refer to the Persistent Volumes section of the Kubernetes documentation.

Perform the following steps to create a PVC:

1. Create a PVC referencing the px-csi-db default StorageClass and save the file:

kind: PersistentVolumeClaim
apiVersion: v1
metadata:
    name: px-check-pvc
spec:
    storageClassName: px-csi-db
    accessModes:
        - ReadWriteOnce
    resources:
        requests:
            storage: 2Gi

2. Run the kubectl apply command to create a PVC:

kubectl apply -f <your-pvc-name>.yaml

persistentvolumeclaim/example-pvc created

Verify your StorageClass and PVC

1. Enter the kubectl get storageclass command:

kubectl get storageclass

NAME                                 PROVISIONER                     RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
px-csi-db                            pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-db-cloud-snapshot             pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-db-cloud-snapshot-encrypted   pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-db-encrypted                  pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-db-local-snapshot             pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-db-local-snapshot-encrypted   pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-replicated                    pxd.portworx.com                Delete          Immediate           true                   43d
px-csi-replicated-encrypted          pxd.portworx.com                Delete          Immediate           true                   43d
px-db                                kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-db-cloud-snapshot                 kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-db-cloud-snapshot-encrypted       kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-db-encrypted                      kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-db-local-snapshot                 kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-db-local-snapshot-encrypted       kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-replicated                        kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
px-replicated-encrypted              kubernetes.io/portworx-volume   Delete          Immediate           true                   43d
stork-snapshot-sc                    stork-snapshot                  Delete          Immediate           true                   43d

kubectl returns details about the StorageClasses available to you. Verify that px-csi-db appears in the list.

2. Enter the kubectl get pvc command. If this is the only StorageClass and PVC that you've created, you should see only one entry in the output:

kubectl get pvc <your-pvc-name>

NAME          STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS           AGE
example-pvc   Bound    pvc-xxxxxxxx-xxxx-xxxx-xxxx-2377767c8ce0   2Gi        RWO            example-storageclass   3m7s

kubectl returns details about your PVC if it was created correctly. Verify that the configuration details appear as you intended.