Docs
chromia.com

cluster

On this page
Help output
Usage: pmc cluster [OPTIONS] COMMAND [ARGS]...

  Interacting with clusters

╭─ Options ───────────────────────────────────────────────────────────────────╮
│  -h, --help  Show this message and exit                                     │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────╮
│  list        List all existing clusters                                     │
│  add         Create a new cluster that can hold containers with blockchains.│
│              This cluster will not be tracked by economy chain and nodes    │
│              running in it will not be rewarded. To create a cluster that is│
│              managed by economy chain please see command: 'pmc economy      │
│              add-cluster'                                                   │
│  info        Get information about a cluster                                │
│  containers  List all existing cluster containers                           │
│  provider    Proposes an update of a cluster's providers                    │
│  limits      Propose new resource limits for given cluster                  │
│  remove      Propose removal of cluster. Command is irreversible            │
│  verify      Verify cluster status                                          │
│  replica     Cluster replica commands                                       │
╰─────────────────────────────────────────────────────────────────────────────╯

The cluster command (pmc cluster) consists of sub-commands to interact with clusters. For example, list existing clusters, create new clusters, and remove clusters.

cluster list

Help output
Usage: pmc cluster list [OPTIONS]

  List all existing clusters

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  -i, --interactive  Prompt for item to show details for                     │
│  -h, --help         Show this message and exit                              │
╰─────────────────────────────────────────────────────────────────────────────╯

The list command (pmc cluster list) lists all the clusters.

cluster add

Help output
Usage: pmc cluster add [OPTIONS]

  Create a new cluster that can hold containers with blockchains. This cluster
  will not be tracked by economy chain and nodes running in it will not be
  rewarded. To create a cluster that is managed by economy chain please see
  command: 'pmc economy add-cluster'

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE              Add timeb operation to make transaction fail │
│                                if applied after the given time (UTC).       │
│                                Supported formats: yyyy-MM-dd HH:mm,         │
│                                yyyy-MM-dd'T'HH:mm and milliseconds since    │
│                                1970 (unix/epoch time)                       │
│  --timeb-after=VALUE           Add timeb operation to make transaction fail │
│                                if applied after the given number of seconds │
│                                from now.                                    │
│  --save-tx                     Always save transaction to file, even if it  │
│                                is fully signed                              │
│  --target=PATH                 Path where transaction file should be saved  │
│                                (default: /opt/chromaway/postchain)          │
│  -n, --name=TEXT               Cluster name                                 │
│  -a, --auto-generate-name      Set if cluster name should be autogenerated  │
│                                (suppressed by -n)                           │
│  --voter-set=VALUE             Name of voter set                            │
│  --pubkeys=VALUE               Comma delimited list of public keys          │
│  -clu, --cluster-units=INT     Cluster Units (minimum 1) (default: 1)       │
│  -es, --extra-storage=INT      Extra Storage (MiB) (default: 0)             │
│* -g, --governor=TEXT           Name of another voter set which can update   │
│                                this cluster.                                │
│  --system-container-units=INT  Number of container units to reserve for     │
│                                cluster system container (default: 4)        │
│  --cu-cpu=INT                  Container unit CPU limit (percent of cpus, 10│
│                                == 0.1 cpu(s), 150 == 1.5 cpu(s)) (default:  │
│                                50)                                          │
│  --cu-ram=INT                  Container unit RAM limit (MiB) (default:     │
│                                2048)                                        │
│  --cu-storage=INT              Container unit storage limit (MiB) (default: │
│                                16384)                                       │
│  --cu-io-read=INT              Container unit storage I/O read limit (MiB/s)│
│                                (default: 25)                                │
│  --cu-io-write=INT             Container unit storage I/O write limit       │
│                                (MiB/s) (default: 20)                        │
│  -mn, --max-nodes=INT          Maximum number of nodes in the cluster       │
│                                (default: 9223372036854775807)               │
│  -h, --help                    Show this message and exit                   │
╰─────────────────────────────────────────────────────────────────────────────╯

The add command (pmc cluster add) creates a new cluster that can hold nodes with containers holding blockchains.

To add a cluster, you must provide:

  • The name of the cluster.
  • The name of the voter set.
  • The pubkeys of the providers will be included in the cluster.
  • The name of the governor.

cluster info

Help output
Usage: pmc cluster info [OPTIONS]

  Get information about a cluster

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│* -n, --name=TEXT  Cluster Name                                              │
│  -h, --help       Show this message and exit                                │
╰─────────────────────────────────────────────────────────────────────────────╯

The info command (pmc cluster info) shows the information about a cluster.

cluster containers

Help output
Usage: pmc cluster containers [OPTIONS]

  List all existing cluster containers

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│* -n, --name=TEXT  Cluster name                                              │
│  -h, --help       Show this message and exit                                │
╰─────────────────────────────────────────────────────────────────────────────╯

The containers command (pmc cluster containers) lists all cluster containers.

cluster provider

Help output
Usage: pmc cluster provider [OPTIONS]

  Proposes an update of a cluster's providers

  To remove provider from cluster set --add to false. Cluster governance voter
  set has authority to update a cluster's providers

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE          Add timeb operation to make transaction fail if  │
│                            applied after the given time (UTC). Supported    │
│                            formats: yyyy-MM-dd HH:mm, yyyy-MM-dd'T'HH:mm and│
│                            milliseconds since 1970 (unix/epoch time)        │
│  --timeb-after=VALUE       Add timeb operation to make transaction fail if  │
│                            applied after the given number of seconds from   │
│                            now.                                             │
│  --save-tx                 Always save transaction to file, even if it is   │
│                            fully signed                                     │
│  --target=PATH             Path where transaction file should be saved      │
│                            (default: /opt/chromaway/postchain)              │
│* -pk, --pubkey=PUBKEY      Public key                                       │
│* -c, --cluster=TEXT        Name of existing cluster to update               │
│  -a, --add / -r, --remove  Add or remove provider pubkey from cluster       │
│  --description=TEXT        Proposal description                             │
│  -h, --help                Show this message and exit                       │
╰─────────────────────────────────────────────────────────────────────────────╯

The provider command (pmc cluster provider) proposes an update to a cluster's providers.

Example usage:

Terminal
pmc cluster provider --add --pubkey <pubkey> --cluster <cluster-name>

cluster limits

Help output
Usage: pmc cluster limits [OPTIONS]

  Propose new resource limits for given cluster

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE           Add timeb operation to make transaction fail if │
│                             applied after the given time (UTC). Supported   │
│                             formats: yyyy-MM-dd HH:mm, yyyy-MM-dd'T'HH:mm   │
│                             and milliseconds since 1970 (unix/epoch time)   │
│  --timeb-after=VALUE        Add timeb operation to make transaction fail if │
│                             applied after the given number of seconds from  │
│                             now.                                            │
│  --save-tx                  Always save transaction to file, even if it is  │
│                             fully signed                                    │
│  --target=PATH              Path where transaction file should be saved     │
│                             (default: /opt/chromaway/postchain)             │
│* -n, --name=TEXT            Cluster name                                    │
│  -clu, --cluster-units=INT  Cluster Units (minimum 1)                       │
│  -es, --extra-storage=INT   Extra Storage (MiB)                             │
│  --description=TEXT         Proposal description                            │
│  -h, --help                 Show this message and exit                      │
╰─────────────────────────────────────────────────────────────────────────────╯

The limits command (pmc cluster limits) proposes a set of new resource limits for a cluster. There are several types of limitations; the maximum number of containers in the cluster, the maximum number of blockchains in the container, CPU limits, RAM limit, and storage limit.

cluster remove

Help output
Usage: pmc cluster remove [OPTIONS]

  Propose removal of cluster. Command is irreversible

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE     Add timeb operation to make transaction fail if       │
│                       applied after the given time (UTC). Supported formats:│
│                       yyyy-MM-dd HH:mm, yyyy-MM-dd'T'HH:mm and milliseconds │
│                       since 1970 (unix/epoch time)                          │
│  --timeb-after=VALUE  Add timeb operation to make transaction fail if       │
│                       applied after the given number of seconds from now.   │
│  --save-tx            Always save transaction to file, even if it is fully  │
│                       signed                                                │
│  --target=PATH        Path where transaction file should be saved (default: │
│                       /opt/chromaway/postchain)                             │
│* -n, --name=TEXT      Cluster name to remove                                │
│  --description=TEXT   Proposal description                                  │
│  -h, --help           Show this message and exit                            │
╰─────────────────────────────────────────────────────────────────────────────╯

The remove command (pmc cluster remove) proposes the removal of a cluster. It's important to note that this action is irreversible.

cluster verify

Help output
Usage: pmc cluster verify [OPTIONS]

  Verify cluster status

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│* -n, --name=TEXT  name of cluster                                           │
│  -h, --help       Show this message and exit                                │
╰─────────────────────────────────────────────────────────────────────────────╯

The verify command (pmc cluster verify) verifies the status of a specific cluster identified by its name (-n).

cluster replica

Help output
Usage: pmc cluster replica [OPTIONS] COMMAND [ARGS]...

  Cluster replica commands

╭─ Options ───────────────────────────────────────────────────────────────────╮
│  -h, --help  Show this message and exit                                     │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────╮
│  add     add replica of a cluster                                           │
│  remove  Remove replica of a cluster                                        │
╰─────────────────────────────────────────────────────────────────────────────╯

The replica command (pmc cluster replica) manages cluster replicas. It includes sub-commands for adding and removing replicas of a cluster.

cluster replica add

Help output
Usage: pmc cluster replica add [OPTIONS]

  add replica of a cluster

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE      Add timeb operation to make transaction fail if      │
│                        applied after the given time (UTC). Supported        │
│                        formats: yyyy-MM-dd HH:mm, yyyy-MM-dd'T'HH:mm and    │
│                        milliseconds since 1970 (unix/epoch time)            │
│  --timeb-after=VALUE   Add timeb operation to make transaction fail if      │
│                        applied after the given number of seconds from now.  │
│  --save-tx             Always save transaction to file, even if it is fully │
│                        signed                                               │
│  --target=PATH         Path where transaction file should be saved (default:│
│                        /opt/chromaway/postchain)                            │
│* -n, --name=TEXT       Cluster Name                                         │
│* -pk, --pubkey=PUBKEY  Public key                                           │
│  -h, --help            Show this message and exit                           │
╰─────────────────────────────────────────────────────────────────────────────╯

The replica add command (pmc cluster replica add) adds a replica of a cluster. You need to specify the cluster name (-n) and the public key of the replica (-pk, --pubkey).

cluster replica remove

Help output
Usage: pmc cluster replica remove [OPTIONS]

  Remove replica of a cluster

╭─ Configuration Properties ──────────────────────────────────────────────────╮
│  -cfg, --config=CONFIG    Alternate path for client configuration file      │
│  -s, --settings=SETTINGS  Alternate path for project settings file          │
│  --lookup-brid            Ignore any 'brid' property in configuration file, │
│                           always perform lookup                             │
│  --lookup-nodes / --no-lookup-nodes                                         │
│                           Lookup system cluster signer nodes for sending    │
│                           transactions to (default: yes)                    │
│  --network=TEXT           Target network to make requests to (if chromia.yml│
│                           is configured)                                    │
│  --secret=PATH            Path to secret file (pubkey/privkey)              │
│  --key-id=KEY_ID          Key ID of the keypair to use                      │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Signers, leave out this option to send transaction directly ───────────────╮
│  --signer=VALUE       Public keys of signer (can be repeated)               │
│  --signers=VALUE      Comma separated list of keys of signers               │
│  --signers-file=PATH  Path to file containing public keys of signers, one   │
│                       per line                                              │
╰─────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────╮
│  --timeb-at=VALUE      Add timeb operation to make transaction fail if      │
│                        applied after the given time (UTC). Supported        │
│                        formats: yyyy-MM-dd HH:mm, yyyy-MM-dd'T'HH:mm and    │
│                        milliseconds since 1970 (unix/epoch time)            │
│  --timeb-after=VALUE   Add timeb operation to make transaction fail if      │
│                        applied after the given number of seconds from now.  │
│  --save-tx             Always save transaction to file, even if it is fully │
│                        signed                                               │
│  --target=PATH         Path where transaction file should be saved (default:│
│                        /opt/chromaway/postchain)                            │
│* -n, --name=TEXT       Cluster Name                                         │
│* -pk, --pubkey=PUBKEY  Public key                                           │
│  -h, --help            Show this message and exit                           │
╰─────────────────────────────────────────────────────────────────────────────╯

The replica remove command (pmc cluster replica remove) removes a replica of a cluster. You need to specify the cluster name (-n) and the public key of the replica (-pk, --pubkey).