Managing cloud credentials using pxctl

Prerequisites

This document provides instructions for managing your cloud credentials using pxctl.

The cloud provider credentials are stored in an external secret store. Before you use the commands from below, you should configure a secret provider of your choice with Portworx. For more information, head over to the Key Management page.

Overview

You can use the pxctl credentials command to create, list, validate, or delete your cloud credentials. Then, Portworx will use these credentials, for example, to back up your volumes to the cloud.

Enter the pxctl credentials --help command to display the list of subcommands:

/opt/pwx/bin/pxctl credentials --help

Manage credentials for cloud providers

Usage:
  pxctl credentials [flags]
  pxctl credentials [command]

Aliases:
  credentials, cred

Available Commands:
  create      Create a credential for cloud providers
  delete      Delete a credential for cloud
  delete-refs Delete references to a credential
  list        List all credentials for cloud
  validate    Validate a credential for cloud

Flags:
  -h, --help   help for credentials

Global Flags:
      --ca string            path to root certificate for ssl usage
      --cert string          path to client certificate for ssl usage
      --color                output with color coding
      --config string        config file (default is $HOME/.pxctl.yaml)
      --context string       context name that overrides the current auth context
  -j, --json                 output in json
      --key string           path to client key for ssl usage
      --output-type string   use "wide" to show more details
      --raw                  raw CLI output for instrumentation
      --ssl                  ssl enabled for portworx

Use "pxctl credentials [command] --help" for more information about a command.

List credentials

To list all configured credentials, use this command:

pxctl credentials list

S3 Credentials
UUID                        REGION          ENDPOINT            ACCESS KEY          SSL ENABLED ENCRYPTION
XXXX                        us-east-1       s3.amazonaws.com    XXXX                false       false

Azure Credentials
UUID                        ACCOUNT NAME        ENCRYPTION
XXXX                        portworxtest        false

Create and configure credentials

You can create and configure credentials in multiple ways depending on your cloud provider and how you want to manage them.

Create credentials on AWS by specifying your keys

note

The --s3-storage-class flag requires Portworx Enterprise version 2.5.3 or higher

Enter the pxctl credentials create command, specifying:

• The --provider flag with the name of the cloud provider (s3).

• The --s3-access-key flag with your secret access key

• The --s3-secret-key flag with your access key ID

• The --s3-region flag with the name of the S3 region (us-east-1)

• The --s3-endpoint flag with the name of the endpoint (s3.amazonaws.com)

• The optional --s3-storage-class flag with either the STANDARD or STANDARD-IA value, depending on which storage class you prefer.

• The name of your cloud credentials

  pxctl credentials create \
    --provider s3 \
    --s3-access-key <YOUR-SECRET-ACCESS-KEY>
    --s3-secret-key <YOUR-ACCESS-KEY-ID> \
    --s3-region us-east-1 \
    --s3-endpoint s3.amazonaws.com \
    --s3-storage-class STANDARD \                 
      <NAME>

  Credentials created successfully

note

This command will create a bucket with the Portworx cluster ID to use for the backups.

Create credential on AWS with s3 encryption

You can configure AWS s3 credentials to use server-side encryption, assuming the s3 object-store provider supports it.

Enter the pxctl credentials create command, specifying:

• The --provider flag with the name of the cloud provider (s3).

• The --s3-access-key flag with your secret access key

• The --s3-secret-key flag with your access key ID

• The --s3-region flag with the name of the S3 region (us-east-1)

• The --s3-endpoint flag with the name of the endpoint (s3.amazonaws.com)

• The optional --s3-storage-class flag with either the STANDARD or STANDARD-IA value, depending on which storage class you prefer

• The optional --s3-sse flag with AES256 or aws:kms, depending on how you want to do the server side encryption. If using aws:kms, see the AWS s3 documentation.

• The name of your cloud credentials

  pxctl credentials create \
    --provider s3 \
    --s3-access-key <YOUR-SECRET-ACCESS-KEY>
    --s3-secret-key <YOUR-ACCESS-KEY-ID> \
    --s3-region us-east-1 \
    --s3-endpoint s3.amazonaws.com \
    --s3-sse AES256 \                  
      <NAME>

  Credentials created successfully

Create credentials on AWS using IAM

note

This feature requires Portworx Enterprise version 2.5.1 or greater

Instead of storing your secret access key and access key ID on the host, you can grant Portworx bucket permissions using IAM. You can grant the EC2 instances on which Portworx is running, or you can grant permissions for a specific bucket.

Grant IAM permissions for your EC2 instance in general

1. In AWS, grant IAM permissions for an EC2 instance with no bucket:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:GetObject",
                   "s3:ListAllMyBuckets",
                   "s3:CreateBucket",
                   "s3:ListBucket",
                   "s3:DeleteObject",
                   "s3:GetBucketLocation"
               ],
               "Resource": "*"
           }
       ]
   }

2. Enter the following pxctl credentials create command, specifying the following:

   • The --provider flag with the name of the cloud provider (s3).
   • The --s3-region flag with the the S3 region associated with your account
   • The optional --s3-storage-class flag with either the STANDARD or STANDARD-IA value, depending on which storage class you prefer
   • The use-iam flag
   • The name of your cloud credentials

   ./pxctl credentials create \
   --provider s3 \
   --s3-region us-east-1 \
   --s3-storage-class STANDARD \
   --use-iam \
   <NAME>

   Credentials created successfully, UUID:12345678-a901-2bc3-4d56-7890ef1d23ab

Grant IAM permissions for a specific bucket

1. In AWS, grant IAM permissions for a specific bucket:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": [
                   "s3:ListAllMyBuckets",
                   "s3:GetBucketLocation"
               ],
               "Resource": "*"
           },
           {
               "Sid": "VisualEditor1",
               "Effect": "Allow",
               "Action": "s3:*",
               "Resource": [
                   "arn:aws:s3:::<bucket-name>",
                   "arn:aws:s3:::<bucket-name>/*"
               ]
           }
       ]
   }

2. Enter the following pxctl credentials create command, specifying the following:

   • The --provider flag with the name of the cloud provider (s3)
   • The --s3-region flag with your bucket's s3 region
   • The optional --s3-storage-class flag with either the STANDARD or STANDARD-IA value, depending on which storage class you prefer
   • The --bucket flag with your bucket's name
   • The use-iam flag
   • The name of your cloud credentials

   ./pxctl credentials create \
   --provider s3 \
   --s3-region <region> \
   --s3-storage-class STANDARD \
   --bucket <bucket-name> \
   --use-iam \
   <NAME>

   Credentials created successfully, UUID:12345678-a901-2bc3-4d56-7890ef1d23ab

Create credentials on Google by specifying the credential file

note

This feature requires Portworx Enterprise version 2.10.1 or greater

1. Specify the following:

   • The --provider flag with the name of the cloud provider (google)
   • The --google-project-id flag with the relevant google project ID
   • the --google-json-key-file flag with the path to the credentials
   • The --bucket flag with your bucket's name

   ./pxctl credentials create \
   --provider google \
   --google-project-id <project-id> \
   --google-json-key-file /path/to/gcloud.json \
   --bucket <bucket-name> \
   <NAME>

   Credentials created successfully, UUID:12345678-a901-2bc3-4d56-7890ef1d23ab

Delete existing credentials

To delete a particular set of credentials, you can run pxctl credentials delete with the uuid or the name as parameters like this:

pxctl credentials delete <uuid or name>

Credential deleted successfully

note

Don't forget to replace <uuid or name> with the actual uuid or name of the credentials you want to delete.

Validate credentials

If you want to validate a set of credentials for a particular cloud provider, run the following:

pxctl credentials validate <uuid or name>

Credential validated successfully

note

Don't forget to replace <uuid or name> with the actual uuid or name of the credentials you want to delete.

Delete pending credential references from the KVDB

Requests to delete cloudsnaps are long-running operations, and are executed asynchronously in the background. Portworx stores these requests in the KVDB so that it can resume delete operations if the node restarts or is otherwise interrupted. Portworx periodically retires these delete requests as part of a cleanup routine.

If the credentials for these cloudsnaps are configured through Kubernetes secrets, the credential object must be available at the time Portworx attempts to delete it. If the credential object is deleted while the cloudsnap delete requests are pending, these delete requests will fail and continue to remain in the KVDB where they will continue to log alerts about the failure to delete.

If this happens in your cluster, you can use the use the pxctl credentials delete-refs command to delete these pending references to credentials from the KVDB:

pxctl credentials delete-refs <name-or-UUID>

Related topics

• For information about integrating Portworx with Kubernetes Secrets, refer to the Kubernetes Secrets page.