Version: 3.1

Google Cloud KMS

Portworx integrates with Google Cloud KMS to store your Portworx secrets for Volume Encryption and Cloud Credentials. This guide will help configure Portworx with Google Cloud KMS.

Portworx requires the following Google Cloud credentials to use its APIs

Google Application Credentials [GOOGLE_APPLICATION_CREDENTIALS]

Portworx requires permissions to use Google CloudKMS APIs. It requires the following two predefined roles
- roles/cloudkms.cryptoKeyEncrypterDecrypter
- roles/cloudkms.publicKeyViewer
More info about these roles and the included permissions can be found here
Google KMS Public Key Resource ID [GOOGLE_KMS_RESOURCE_ID]

Portworx uses Google's asymmetric key pairs to encrypt and decrypt secrets. More information about asymmetric key pairs and how to create them can be found here

Make sure that while creating the asymmetric key you specify the purpose of the key as Asymmetric decrypt

Once the asymmetric key is created, provide its complete resourceID to Portworx. A typical asymmetric key pair's resource ID looks like this
```
projects/<Project ID>/locations/<Region>/keyRings/<Key Ring Name>/cryptoKeys/<Asymmetric Key Name>/cryptoKeyVersions/1
```
Portworx requires the above resource ID as an input argument.

For Kubernetes Users

Provide the Google credentials to Portworx by using any one of these methods

Google instance IAM roles (Recommended)

Provide the instances running Portworx privileges to access the GCP API server. This is the preferred method since it requires the least amount of setup on each instance.

Owner and Compute Admin Roles

These Roles provides Portworx access to the Google Cloud Storage APIs to provision persistent disks. Make sure the service account for the instances has these roles.
Cloud KMS predefined roles

Following predefined roles provide Portworx access to the Google Cloud KMS APIs to manage secrets.
```
roles/cloudkms.cryptoKeyEncrypterDecrypter
roles/cloudkms.publicKeyViewer
```

Google Service Accounts

Step 1: Create a service account

Alternatively, you can give Portworx access to the GCP API server via an account file and environment variables. First, you will need to create a service account in GCP and download the account file.

To access the GCP API server, Portworx needs a service account with the following roles

Owner and Compute Admin Roles

These Roles provides Portworx access to the Google Cloud Storage APIs to provision persistent disks. Make sure the service account created below has these roles.
Cloud KMS predefined roles

Following predefined roles provide Portworx access to the Google Cloud KMS APIs to manage secrets.
```
roles/cloudkms.cryptoKeyEncrypterDecrypter
roles/cloudkms.publicKeyViewer
```

Follow these steps to create a service account and download its corresponding account file:

Create a service account in the "Service Account" section that has the above permissions.
Go to IAM & admin -> Service Accounts -> (Instance Service Account) -> Select "Create Key" and download the .json file.

Step 2: Create a Kubernetes secret for the Google credentials.

Copy the downloaded account file in a directory gcloud-secrets/ and rename it gcloud.json to create a Kubernetes secret from it.

ls -1 gcloud-secrets

gcloud.json

Create a kubernetes secret with the following command

 kubectl -n kube-system create secret generic px-gcloud --from-file=gcloud-secrets/ --from-literal=gcloud-kms-resource-id=projects/<Project ID>/locations/<Region>/keyRings/<Key Ring Name>/cryptoKeys/<Asymmetric Key Name>/cryptoKeyVersions/1

Make sure to replace the Project ID, Key Ring Name and Asymmetric Key Name in the above command.

Step 3: Update the Portworx DaemonSet

New installation

When generating the Portworx Kubernetes spec file on the Portworx spec generator page in Portworx Central), select Google Cloud KMS from the "Secrets type" list.
Existing installation

For an existing Portworx cluster follow these steps in the next section

Step 3a: Update the Portworx DaemonSet to use the Google KMS secret store

Edit the Portworx DaemonSet's secret_type field to gcloud-kms, so that all the new Portworx nodes will also start using Google Cloud KMS.

kubectl edit daemonset portworx -n kube-system

Add the "-secret_type", "gcloud-kms" arguments to the portworx container in the daemonset. It should look something like this:

containers:
  - args:
    - -c
    - testclusterid
    - -s
    - /dev/sdb
    - -x
    - kubernetes
    - -secret_type
    - gcloud-kms
    name: portworx

Step 3b: Patch the Portworx DaemonSet

Use the following command to patch the daemon set, so that it has access to the secret created Step 2

Create a patch file

cat <<EOF> patch.yaml
spec:
  template:
    spec:
      containers:
      - name: portworx
        env:
          - name: GOOGLE_KMS_RESOURCE_ID
            valueFrom:
              secretKeyRef:
                name: px-gcloud
                key: gcloud-kms-resource-id
          - name: GOOGLE_APPLICATION_CREDENTIALS
            value: /etc/pwx/gce/gcloud.json
        volumeMounts:
          - mountPath: /etc/pwx/gce
            name: gcloud-certs
      volumes:
        - name: gcloud-certs
          secret:
            secretName: px-gcloud
            items:
              - key: gcloud.json
                path: gcloud.json
EOF

Apply the patch

kubectl -n kube-system patch ds portworx --patch "$(cat patch.yaml)" --type=strategic

Known Issues

note

Fixed in Portworx Enterprise version 2.10.1

When creating Google Cloud credentials using Google KMS as the secret provider, users might encounter the error: crypto/rsa: message too long for RSA public key size

Other users

Step 1: Provide Google Cloud credentials to Portworx

Provide the following Google Cloud credentials (key value pairs) as environment variables to Portworx

[Required] GOOGLE_APPLICATION_CREDENTIALS=[/path/to/service/account file]
[Required] GOOGLE_KMS_RESOURCE_ID=[asymmetric_resource_id]

note

Important: The service account file needs to be present on all the nodes where Portworx is running.

Step 2: Set up Google Cloud KMS as the secrets provider for Portworx.

New installation

While installing Portworx set the input argument -secret_type to gcloud-kms.

Existing installation

Based on your installation method provide the -secret_type gcloud-kms input argument and restart Portworx on all the nodes.

Using Google Cloud KMS with Portworx

📄️ Encrypting Kubernetes PVCs with Google Cloud KMS

Instructions on using Google Cloud KMS with Portworx for encrypting PVCs

📄️ (Other Schedulers) Encrypt Portworx volumes using Google Cloud KMS

Instructions on using Google Cloud KMS with Portworx for encrypting Portworx Volumes

For Kubernetes Users​

Google instance IAM roles (Recommended)​

Google Service Accounts​

Step 1: Create a service account​

Step 2: Create a Kubernetes secret for the Google credentials.​

Step 3: Update the Portworx DaemonSet​

Step 3a: Update the Portworx DaemonSet to use the Google KMS secret store​

Step 3b: Patch the Portworx DaemonSet​

Known Issues​

Other users​

Step 1: Provide Google Cloud credentials to Portworx​

Step 2: Set up Google Cloud KMS as the secrets provider for Portworx.​

New installation​

Existing installation​

Using Google Cloud KMS with Portworx​