Supported from Portworx Enterprise 1.7 onwards
Portworx integrates with IBM Key Protect and Hyper Protect Crypto Services (HPCS) to store your encryption keys/secrets and credentials. This guide helps you configure Portworx with IBM Key Protect or HPCS. IBM Key Protect and HPCS can be used to store Portworx secrets for Volume Encryption and Cloud Credentials.
Portworx requires the following IBM Key Protect or HPCS credentials to use its APIs:
Service Instance ID [IBM_SERVICE_INSTANCE_ID]
The Instance ID of the IBM Key Protect or HPCS service can be found by running the following command
ibmcloud resource service-instance <name-of-your-service>
This should output something like. The ID from the below CRN is
Service API Key [IBM_SERVICE_API_KEY]
Follow this IBM document to retrieve the API Key.
Customer Root Key [IBM_CUSTOMER_ROOT_KEY]
Follow this IBM document to create a Customer Root Key
Base URL [IBM_BASE_URL]
The base URL specifies the URL where your Key Protect or HPCS instance resides. It is region specific.
The default value is:
- If you are using IBM HPCS, take the key management endpoint URL from the overview page of your HPCS service on IBM Cloud.
- The base URL is mandatory if Portworx is running on an IBM (IKS or ROKS) air-gapped cluster. To get the Key Protect endpoint URL for your region, refer to the IBM Key Protect documentation. For example, the IBM_BASE_URL for the
Token URL [IBM_TOKEN_URL]
Default value which will be used is:
The token URL is mandatory if Portworx is running on an IBM (IKS or ROKS) air-gapped cluster. To get the IAM service private endpoint URL for your region, refer to the IBM Cloud API documentation. For example, the IBM_TOKEN_URL for the
Based on your installation type use the following methods to provide these credentials to Portworx.
For Kubernetes Users
Step 1: Provide IBM key management credentials to Portworx.
Portworx reads the IBM credentials required to authenticate with IBM Key Protect through a Kubernetes secret. Create a Kubernetes secret with the name
px-ibm in the
portworx namespace. Following is an example kubernetes secret spec
Portworx is going to look for this secret with name
px-ibm under the
portworx namespace. While installing Portworx it creates a Kubernetes role binding which grants access to reading Kubernetes secrets only from the
Step 2: Set up IBM key management as the secrets provider for Portworx.
Using helm chart
While deploying Portworx using helm chart on an IKS cluster, by default Portworx is configured to use IBM Key Protect and HPCS as a secrets provider. Follow these instructions to install the helm chart.
In a non-IKS cluster, set the
ibm-kp in the helm chart's values.yml configuration file.
secretType for both IBM Key Protect and HPCS.
Using the Portworx spec generator
When generating the Portworx Kubernetes spec file on the Portworx spec generator page in Portworx Central, select
IBM Key Protect from the "Secrets type" list.
For an existing Portworx cluster follow these steps to configure IBM Key Protect or HPCS as the secrets provider
Step 2a: Add Permissions to access kubernetes secrets
Portworx needs permissions to access the
px-ibm secret created in Step 1. The following Kubernetes spec grants portworx access to all the secrets defined under the
cat <<EOF | kubectl apply -f -
# Namespace to store credentials
# Role to access secrets under portworx namespace only
- apiGroups: [""]
verbs: ["get", "list", "create", "update", "patch"]
# Allow portworx service account to access the secrets under the portworx namespace
- kind: ServiceAccount
Step 2b: Edit the Portworx spec
Depending on your Portworx installation, proceed to one of the following sections.
Edit the Portworx DaemonSet spec
Edit the Portworx DaemonSet
secret_type field to
ibm-kp, so that all the new Portworx nodes will also start using IBM or HPCS.
kubectl edit daemonset portworx -n kube-system
"-secret_type", "ibm-kp" arguments to the
portworx container in the daemonset. It should look something like this:
Editing the daemonset will restart all the Portworx pods.
Edit the Portworx Operator spec
Get the name of the StorageCluster running in your IBM cluster:
kubectl get storagecluster -A
NAMESPACE NAME CLUSTER UUID STATUS VERSION AGE
kube-system px-ocpkptest 89dfb5a4-47d6-440a-95bf-65502f548d97 Online 2.12.1 5h49m
Run the following command to edit the above StorageClsuter, then set the
secretsProviderfield of the
kubectl edit storageCluster px-ocpkptest -n kube-system
Once the StorageClsuter spec is edited, all Portworx pods will restart and use IBM Key Protect or HPCS.
Step 1: Provide IBM key management services credentials to Portworx.
Provide the following IBM credentials (key value pairs) as environment variables to Portworx
- [Required] IBM_SERVICE_INSTANCE_ID=[service_instance_id]
- [Required] IBM_SERVICE_API_KEY=[service_api_key]
- [Required] IBM_CUSTOMER_ROOT_KEY=[customer_root_key]
- [Optional] IBM_BASE_URL=[base_url] → only required if the instance is in a different region
- [Optional] IBM_TOKEN_URL=[token_url] → only required if the different than the default token url
Step 2: Set up IBM key management services as the secrets provider for Portworx.
While installing Portworx set the input argument
Based on your installation method provide the
-secret_type ibm-kp input argument and restart Portworx on all the nodes.
Using IBM key management services with Portworx
📄️ Encrypting Kubernetes PVCs with IBM key management services
Instructions on using IBM key management services with Portworx for encrypting PVCs in Kubernetes
📄️ (Other Schedulers) Encrypting Portworx Volumes using IBM Key Protect
Instructions on using IBM Key Protect with Portworx for encrypting Portworx Volumes