An introduction to the pcloud command

The pcloud command line tool allows you to create and manage the lifecycle of VMs on your IBM Power Systems for Google Cloud instance. You can use the pcloud command line tool to manage related resources such as VM images and data volumes. The pcloud command line tool is a stand alone executable file that is available for use on Mac, Windows, and Linux operating systems. You can obtain the latest pcloud binaries from the cli download site.

Setting up pcloud

Before you can start using the pcloud tool, you must have an available Power Cloud instance that is provisioned and attached to a selected GCP project within your organization. This process occurs when you subscribe to the offering in the GCP Marketplace. Next, run the pcloud auth login command to authenticate to your cloud instance. When you authenticate, you must use the registered Google identity that is associated with the organization and the billing account that is used in the subscription. Running the pcloud auth login command provides you with a unique code to register your pcloud instance. In the following example, XXXX-YYYY represents the unique code.

pcloud auth login
To authorize pcloud you will need to complete following steps (within 30 minutes):
  1. Navigate to: https://www.google.com/device
  2. Enter the code: XXXX-YYYY
  3. Select your Google ID that was registered with IBM Power Systems for Google Cloud


Once these steps have been completed the login command will complete within 5 seconds

When you go to https://www.google.com/device, you must enter the code in the dialog box. Next, a popup is displayed and you select the appropriate identity. After you complete this process, pcloud is now enabled to operate against the Power Systems Cloud instance that is associated with your Google identity. To verify that pcloud is enabled, run the pcloud config list, pcloud compute clouds list, and pcloud compute clouds describe commands. The following example displays the correct sequence of running these commands.

pcloud config list
accountID: testuser
cloudID: 767738cf4a2248e09f16482a6b1de6ea


pcloud compute clouds list
CloudID                           Name    Region
767738cf4a2248e09f16482a6b1de6ea  cloud9  us-east4


pcloud compute clouds describe cloud9
cloudID: 767738cf4a2248e09f16482a6b1de6ea
name: cloud9
tenantID: testuser
ibmCustomerNumber: "1234"
region: us-east4
usage:
  memory: 57
  cores: 18.75
  storage: 1.188
  storageSSD: 0
  instances: 14
limits:
  memory: 256
  cores: 24
  storage: 16
  storageSSD: 2
  instances: 24
  peeringNetworks: 1
  peeringBandwidth: 200
limitsPerVM:
  memory: 64
  cores: 6

pcloud documentation

You can use the --help option with all subcommands to get additional information and available options for each of the operations. You can run the pcloud docs command to generate an up-to-date collection of documentation in markdown formatted (.md) files. By default, the markdown files are placed in a newly created pcloud-doc directory. You can use the -d option with pcloud docs to specify an alternate directory that will be created. If pcloud-doc or the alternate directory already exists, it must be renamed or removed before running pcloud docs. To view the markdown files, you can use a browser plug-in or other available tools. For example, you can use the Markdown Viewer plug-in for the Chrome browser. The pcloud_main.md file is the top level document with links to specific topics.

Obtaining a VM image so you can create your first VM (LPAR)

Before you can create your first VM on your Power cloud instance, you must have a VM image in your cloud instance catalog. IBM provides a few stock images. These stock images are ideal for creating your first VM. The service also supports options to bring your own images.

To view available stock images, run the pcloud compute images list -a command. The following example displays the output from running this command:

pcloud compute images list -a
ImageID                               Name
9f72fc9b-a8b9-4d50-ad2d-65564a80b6d8  7100-05-04
0d50200b-c1b7-41fc-a858-7d3627714384  7200-03-03

The previous command without the -a flag can be used to list the images that are currently in your image catalog.

pcloud compute images list
ImageID                               Name
a232f02c-f041-480a-8b5a-87058710e2b3  7200-03-03

To copy a stock image into your cloud catalog, run the pcloud compute images create command. The following example uses the AIX 7100-05-04 stock image.

pcloud compute images create 9f72fc9b-a8b9-4d50-ad2d-65564a80b6d8

Now that you created the 7100-05-04 image, it is part of the cloud instance catalog and can be used to deploy VMs.

Creating a VM and accessing it for the first time

After you have an image, you can create a VM by running the pcloud compute instances create command. The following is an example of the output from using the -h flag for this command:

pcloud compute instances create -h
Create a VM Instance in IBM Power Cloud.

 Most of the flags have default values, but you must enter the VM image name and the network name.
 You can list the images of your Cloud by running the "pcloud compute images list" command.
 You can list the available networks by running the "pcloud compute networks list" command.

 Creating a new VM instance can take a few minutes to fully complete. You can look at the state
 of the VM by using the "pcloud compute instances describe" subcommand.

Usage:
  pcloud compute instances create <InstanceName> --image <ImageName> --network <NetworkName[:IPAddress]> [flags]

Flags:
  -a, --affinityPolicy string   Affinity policy for replicants being created (must be one of {"anti-affinity", "none"}) (default "none")
  -c, --cores float             Number of cores to allocate to the VM Instance (default 2)
  -h, --help                    help for create
  -i, --image string            Image to allocate to the VM Instance (note that 'ImageID' or 'ImageName' can be used) (required)
  -k, --keypair string          SSHKeyPair Name
  -m, --memory float            Memory size (in GB) to allocate to the VM Instance (default 4)
  -M, --migratable              Indicates if the VM Instance is allowed to migrate between hosts
  -s, --namingScheme string     Replicants naming scheme (must be one of {"prefix", "suffix"}) (default "suffix")
  -n, --network strings         Networks to assign to the VM Instance (several --network allowed, note that 'NetworkID' or 'NetworkName' can be used) (required)
  -t, --proctype string         Shared or Dedicated Processing Pool (must be one of {"shared", "dedicated"}) (default "dedicated")
  -r, --replicants float        Number of replicants (default 1)
  -u, --userdata string         Cloud-init user defined data file (optional, if necessary data are uuencoded before being sent)
  -v, --volume strings          Volumes to assign to the VM Instance (several --volume allowed, note that 'VolumeID' or 'VolumeName' can be used)

Global Flags:
  -F, --format string      Available formats: 'table', 'yaml', 'json', 'csv'.
                            Default is command specific.
                            Can be used with describe and list subcommands.
  -D, --log.dir string     Override Log file directory
  -L, --log.file string    Override Log file name
  -V, --verbosity string   Override Log verbosity

Some of the flags have default values, but you must enter several parameters. For example, you must enter the VM image name and the network ID.

You can list the available networks by running the pcloud compute networks list command. A cloud instance has at least one network that was created when it was initially provisioned. This network is what connects the cloud instance and its VMs to GCP.

If you run the command in the following example, you create a new AIX 7.2 VM with two entitled shared cores of compute and 8 GB of RAM.

pcloud compute instances create mytestvm -i 7200-03-03 -m 8 -c 2 -t shared -n gcp-network

Creating a new VM instance can take a few minutes to fully complete. You can look at the state of the VM by using the describe subcommand. In the following example, the VM is still booting up and initializing.

pcloud compute instances describe mytestvm
instanceID: 7f11d296-2a75-4512-b380-cfa5848827eb
name: mytestvm
cloudID: 7f16fae4f3f54d8bb62f75645db56905
systemType: s922
cores: 2
procType: shared
memory: 8
migratable: false
status: ACTIVE
health:
  status: WARNING
  lastUpdate: 2020-01-06T18:59:21.563466
  reason: '-'
fault:
  code: 0
  created: '-'
  details: '-'
  message: '-'
imageID: 9cc1ac6f-4cc2-4476-8540-fb58d24ae8af
networks:
- ipAddress: 192.168.0.14
  macAddress: fa:e0:43:80:92:20
  networkName: gcp-network
  networkID: 8e72b5cc-9e50-4b06-bc56-eb4e1781eefe
volumes:
- name: mytestvm-7f11d296-000006ac-boot-0
  ID: 696226c7-0a97-4917-a220-9bcbe828dab8
  diskType: standard
  size: 20
  shareable: false
  bootable: true
  bootVolume: true
creationDate: "2019-06-03T16:59:43.000Z"
updateDate: "2019-06-03T16:59:43.000Z"
progress: 0

To initially access the new VM, you can use the console subcommand. This subcommand generates a url that can be used in your web browser to access the console of the VM. A recommended first task is to create a password for root using the passwd command so that ssh as root can be used with the VM.

pcloud compute instances console mytestvm


console: https://pforg.ibm.com/console/index.html?token=30ffd05a-c263-42b8-bc64-b33767b70f6f

Here is a screen capture of the console:

Working with additional data volumes

You can create more data volumes to hold application data or support multi-disk use cases with your VMs by using the compute volumes subcommand. The following are examples of using the compute volumes subcommand

To list out existing volumes:

pcloud compute volumes list
VolumeID                              Name                                    Size  Disk Type      State      Shareable  Bootable
696226c7-0a97-4917-a220-9bcbe828dab8  mytestvm-7f11d296-000006ac-boot-0       20    standard       in-use     false      true
e2c688bb-962d-413c-ba14-804e9fbb6042  instanceTestN-ef7c9d9d-00000697-boot-0  32    standard       in-use     false      true

To create a new 10 GB SSD volume and display it in the list of volumes:

pcloud compute volumes create my-test-volume -s 10 -t ssd
Volume "my-test-volume" created with ID: 4cd31e0e-eea1-4d3d-8b15-90a272b27bc0


pcloud compute volumes list
VolumeID                              Name                                    Size  Disk Type      State      Shareable  Bootable
4cd31e0e-eea1-4d3d-8b15-90a272b27bc0  my-test-volume                          10    ssd            available  false      false
696226c7-0a97-4917-a220-9bcbe828dab8  mytestvm-7f11d296-000006ac-boot-0       20    standard       in-use     false      true
e2c688bb-962d-413c-ba14-804e9fbb6042  instanceTestN-ef7c9d9d-00000697-boot-0  32    standard       in-use     false      true

To show the details of a volume:

pcloud compute volumes describe my-test-volume
volumeID: 4cd31e0e-eea1-4d3d-8b15-90a272b27bc0
name: my-test-volume
cloudID: 767738cf4a2248e09f16482a6b1de6ea
diskType: ssd
size: 10
shareable: false
bootable: false
state: available
creationDate: "2019-06-03T17:57:28.000Z"
updateDate: "2019-06-03T17:57:29.000Z"

The following example shows how to attach the new volume to an existing VM. In the following example, the new my-test-volume is now attached the VM.

pcloud compute instances attach-volume mytestvm -v my-test-volume
"rcb-test-volume" Volume being attached to "mytestvm" VM Instance (complete attach is not immediate)


pcloud compute instances describe mytestvm
instanceID: 7f11d296-2a75-4512-b380-cfa5848827eb
name: mytestvm
cloudID: 7f16fae4f3f54d8bb62f75645db56905
systemType: s922
cores: 2
procType: shared
memory: 8
migratable: false
status: ACTIVE
health:
  status: WARNING
  lastUpdate: 2020-01-06T18:59:21.563466
  reason: '-'
fault:
  code: 0
  created: '-'
  details: '-'
  message: '-'
imageID: 9cc1ac6f-4cc2-4476-8540-fb58d24ae8af
networks:
- ipAddress: 192.168.0.14
  macAddress: fa:e0:43:80:92:20
  networkName: gcp-network
  networkID: 8e72b5cc-9e50-4b06-bc56-eb4e1781eefe
volumes:
- name: my-test-volume
  ID: 4cd31e0e-eea1-4d3d-8b15-90a272b27bc0
  diskType: ssd
  size: 10
  shareable: false
  bootable: false
  bootVolume: false
- name: mytestvm-7f11d296-000006ac-boot-0
  ID: 696226c7-0a97-4917-a220-9bcbe828dab8
  diskType: standard
  size: 20
  shareable: false
  bootable: true
  bootVolume: true
creationDate: "2019-06-03T16:59:43.000Z"
updateDate: "2019-06-03T16:59:43.000Z"
progress: 0

Last updated: 2020-05-13