An introduction to the pcloud command

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: test
cloudID: 7f16fae4f3f54d8bb62f75645db56905
cloudName: test-us-east4
region: us-east4

# pcloud compute clouds list
CloudID                           Name              Region       Current  
7f16fae4f3f54d8bb62f75645db56905  test-us-east4     us-east4     true     
7f8e1c3032484fa390d7e87d329afdb1  test-us-central1  us-central1  false   

# pcloud compute clouds describe test-us-east4
cloudID: 7f16fae4f3f54d8bb62f75645db56905
name: test-us-east4
accountID: test
ibmCustomerNumber: "1234"
region: us-east4
storageTypes: ssd, standard
defaultStorageType: standard
usage:
  memory: 152
  cores: 21.5
  storage: 3.378
  instances: 7
limits:
  memory: 640
  cores: 70
  storage: 50
  instances: 40
  peeringNetworks: 1
  peeringBandwidth: 1000
limitsPerVM:
  memory: 400
  cores: 15

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 name to be created, and mandatory image and network names.
 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 {"affinity", "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)
  -s, --namingScheme string     Replicants naming scheme (must be one of {"prefix", "suffix"}) (default "suffix")
  -n, --network strings         Networks to assign to the VM Instance, (values must follow the <NetworkName[:IPAddress]> form, note that 'NetworkID' can be provided instead of 'NetworkName', 'IPAddress' is optional, several --network allowed) (required)
  -P, --pinPolicy string        VM pinning policy (must be one of {"none", "soft", "hard"}) (default "none")
  -t, --proctype string         Dedicated, Shared or Capped Processing Type (must be one of {"dedicated", "shared", "capped"}) (default "dedicated")
  -r, --replicants float        Number of replicants (default 1)
  -T, --storagetype string      Storage type for VMInstance deployment (required only if image is a "stock" image - default value set).
                                Storage type depends on the region of your cloud and can only be set from a short list of available values.
                                You can list the available storage types and the default storage type for your cloud by running the "pcloud compute clouds describe" command.
  -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 test-vm10
instanceID: 4f99e4c5-b8e4-4751-80a8-dd02ccbb00d0
name: test-vm10
cloudID: 7f16fae4f3f54d8bb62f75645db56905
systemType: s922
cores: 2
procType: shared
memory: 24
pinPolicy: none
status: ACTIVE
health:
  status: OK
  lastUpdate: 2021-04-22T17:23:12.354988
  reason: '-'
fault:
  code: 0
  created: '-'
  details: '-'
  message: '-'
imageID: 91e656a6-a9a1-4a99-abb9-7bcb366c3546
networks:
- ipAddress: 192.168.0.17
  macAddress: fa:b8:ef:cf:4b:20
  networkName: gcp-network
  networkID: 8e72b5cc-9e50-4b06-bc56-eb4e1781eefe
volumes:
- name: test-vm10-4f99e4c5-00000ad1-boot-0
  ID: bc141301-85a2-461e-8c68-1f0bc67a35c4
  storageType: standard
  size: 20
  shareable: false
  bootable: true
  bootVolume: true
creationDate: "2021-04-22T17:09:37.000Z"
updateDate: "2021-04-22T17:09:37.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.converge.cloud/console/index.html?token=30ffd05a-c263-42b8-bc64-b33767b70f6f

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  StorageType    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  StorageType    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 test-vm10-4f99e4c5-00000ad1-boot-0
volumeID: bc141301-85a2-461e-8c68-1f0bc67a35c4
name: test-vm10-4f99e4c5-00000ad1-boot-0
cloudID: 7f16fae4f3f54d8bb62f75645db56905
storageType: standard
size: 20
shareable: false
bootable: true
state: in-use
instanceIDs:
- 4f99e4c5-b8e4-4751-80a8-dd02ccbb00d0
creationDate: "2021-04-22T17:09:44.000Z"
updateDate: "2021-04-22T17:10:06.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)

Adding an additional network interface to a virtual machine

The pcloud command line interface provides functionality to add a network interface to a virtual machine.

The command to add the additional network interface is as follows:

pcloud compute instances attach-network <InstanceName> --network <NetworkName[:IPAddress]> [flags]