PCD CLI - pcdctl

PCD CLI (pcdctl) is a unified command line interface (CLI) tool to manage all your Private Cloud Director services. pcdctl lets you install, manage, update Platform9 host agent and related software components on your hypervisor hosts. It also enables you to run all supported operations across all Private Cloud Director services. The goal of PCD CLI is to be a single unified tool that enables you to control all Private Cloud Director services and automate them.

Under The Hood

pcdctl acts as a wrapper on OpenStack CLI and exposes all OpenStack CLI commands for OpenStack services that Private Cloud Director is API compatible with. Read Service Specific Commands for more info.

pcdctl also provides access to all non OpenStack services that Private Cloud Director utilizes and exposes.

Before You Install

Before you install PCD CLI, please note the following:

• When using PCD CLI to prepare and onboard a new host to be added to Private Cloud Director, you need to install and run the CLI on the host being added. Ability to perform remote install and onboarding of new host using PCD is coming in the future.
• When using PCD CLI to control your Private Cloud Director services, you can run PCD CLI on any node with network connectivity to your Private Cloud Director environment.

Prerequisites

• If using PCD CLI to onboard a new host into your Private Cloud Director setup, make sure to install PCD CLI on that host. Also ensure that the host prerequisites are met before using PCD CLI to onboard a new host.
• If using PCD to access your Private Cloud Director service specific commands beyond host onboarding, you can install it on any Ubuntu machine with network access to your Private Cloud Director setup.
• If your host is configured with network bonds, verify that the bonding mode is either active-passive or LACP.

Installation

To install PCD CLI pcdctl, execute the following command on the machine you are installing the CLI on:

bash <(curl -s https://pcdctl.s3.us-west-2.amazonaws.com/pcdctl-setup)

To view available commands and their information, use the help command:

pcdctl --help

For help with a specific command, run the following:

pcdctl [command] --help

Global Flags

Following global flags apply to any run of pcdctl

--log-dir string path to save pcdctl logs

--no-prompt disable all user prompts

--verbose print verbose logs

Configuration

Before using pcdctl with your Private Cloud Director environment, you need to configure it:

1. Navigate to Settings menu option located on the top right corner in the UI.
2. Choose API Access -> pcdctl RC.
3. Copy the contents to a new file named pcdctlrc
4. Update OS_PASSWORD with your Private Cloud Director password
5. Run source pcdctlrc to set the required environment variables

Configuration Commands

config set

This command sets the configuration details for your Private Cloud Director setup. These configuration details are stored in ~/pf9/db/config.json `file`.

Run this command first prior to running any other pcdctl commands to set your account url and credentials once instead of having to specify it for each command.

pcdctl config set

Parameters:

-u, --account-url string – Sets account URL

-h, --help – Displays help for set

-p, --password string – Sets password (use 'single quotes' to pass password)

-r, --region string – Sets region

-t, --tenant string – Sets tenant

-e, --username string – Sets the username

config get

Retrieves the current configuration settings

pcdctl config get

Host Onboarding & Management Commands

prep-node

The prep-node command allows you to add a new host to your Private Cloud Director environment. This command prepares the host with required pre-requisites by downloading and installing a set of required software packages on the host, so that it can be used in your Private Cloud Director environment.

pcdctl prep-node

authorize-node

This command assigns a Private Cloud Director role to the host.

pcdctl authorize-node [flags]

Flags:

-h, --help help for authorize-node

--role string role for the host

decommission-node

Decommissions this host from PCD management plane and purges all PCD components on the host.

pcdctl decommission-node [flags]

Parameters:

-h, --help help for decommission-node

-f, --force force decommission node purging everything

-r, --skip-installed-role-check Skip checking for installed roles

deauthorize-node

Removes roles from an onboarded node.

pcdctl deauthorize-node [flags]

Parameters:

-h, --help help for deauthorize-node

-H, --skip-host-removal Skip host removal

-r, --skip-role-removal Skip role removal

-t, --timeout string Timeout for the operation (default "5m")

Service Specific Commands

pcdctl acts as a wrapper on open source OpenStack CLI for all operations specific to the following Private Cloud Director services, as these services expose OpenStack APIs.

• Compute Service
• Block Storage Service
• Network Service
• Identity Service

It exposes all commands that are exposed by the OpenStack CLI corresponding to these services.

You can find a complete reference here for supported OpenStack CLI commands. When executing these commands with pcdctl, replace openstack with pcdctlbefore executing the command.

pcdctl [command] [flags] [subcommands]

Examples

Following command lists all block storage volumes.

pcdctl volume list

Following command lists all networks in your Private Cloud Director setup

pcdctl network list

Troubleshooting

If you encounter issues:

• Ensure your configuration file is sourced correctly
• If you receive endpoint or SSLErrors, it is likely due to using a self-signed certificate. The --insecure flag can be used as a workaround
• Verify network connectivity to your Private Cloud Director environment
• Check that you have the necessary permissions for the operation
• Review logs for detailed error information

Support bundle

The pcdctl generate-support-bundle utility generates an encrypted archive file containing logs and configuration files specific to PCD troubleshooting scenarios. This command must be executed from the host where the support bundle is required, as the collected data pertains exclusively to that host.

Options specific to the generate-support-bundle command are:

$ sudo pcdctl generate-support-bundle --help

Gathers support bundle that includes logs for pf9 services and pf9ctl.

​

Usage:

  pcdctl generate-support-bundle [flags]

​

Flags:

  -h, --help   help for generate-support-bundle

​

Global Flags:

      --log-dir string   path to save logs

      --no-prompt        disable all user prompts

      --verbose          print verbose logs

The command to generate the support bundle is:

$ sudo pcdctl generate-support-bundle --verbose

A sample execution of the support bundle generation:

$ sudo pcdctl generate-support-bundle --verbose

​

DEBUG ==========Genetating SupportBundle==========

DEBUG Using local executor

Generating support bundle...

DEBUG Ran command sudo "bash" "-c" "LD_LIBRARY_PATH="/opt/pf9/python/pf9-lib:${LD_LIBRARY_PATH}""

DEBUG stdout:stderr:

DEBUG Ran command sudo "bash" "-c" "PYTHONPATH="/opt/pf9/python/lib/python3.9:${PYTHONPATH}""

DEBUG stdout:stderr:

Generating support bundle...

DEBUG Ran command sudo "bash" "-c" "/opt/pf9/hostagent/bin/python /opt/pf9/hostagent/lib/python3.9/site-packages/datagatherer/datagatherer.py"

DEBUG stdout:stderr:

Generating support bundle...

DEBUG Ran command sudo "bash" "-c" "ls /tmp | grep -i pf9-support.tgz.*"

DEBUG stdout:pf9-support.tgz.[hash].gpg

stderr:

✓ Support bundle generated successfully. 

✓ Location of bundle: /tmp/pf9-support.tgz.*.gpg

The archived contents are stored in an encrypted format within the /tmp/pf9-support.tgz.*.gpg file by default. For comprehensive guidance on sharing the support bundle, please reach out to the Platform9 support team.

To specify a custom path for the archived support bundle, use the --log-dir option.

$ sudo pcdctl generate-support-bundle --log-dir <PATH_TO_FOLDER> --verbose