progfigsite command¶

Once you have created a progfiguration site (see Getting started), you can use the configured progfigsite command to interact with it. This command can apply configuration to site nodes/groups/functions, encrypt and decrypt secrets (if an appropriate private key is available), and apply a node’s roles to the local machine.

In order to use this command, you need to add a shim file to your site’s Python package, typically in <package>/cli/progfigsite_shim.py, which calls into progfiguration.cli.progfiguration_site_cmd. See an example at example_site.cli.progfigsite_shim. If you create your site from the example site as in Creating a New Progfiguration Site, this file will be created for you.

Note that your progfigsite’s pyproject.toml can call the command anything it wants. (And of course the module name of the progfigsite is arbitrary, too.) The default name is progfigsite, but you may wish to rename it to something that fits your site’s name better. See the [project.scripts] table in pyproject.toml to change this.

This is also the command that is run when you run a progfigsite pyz.

[project.scripts]
progfigsite = "progfigsite.cli.progfigsite_shim:main"

Command-line help¶

usage: progfigsite [-h] [--debug | --syslog-exception]
                   [--log-stderr {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET,NONE}]
                   [--log-syslog {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET,NONE}]
                   [--secret-store-arguments SECRET_STORE_ARGUMENTS]
                   {version,apply,deploy,zipapp,list,info,encrypt,decrypt,validate,debugger}
                   ...

Positional Arguments¶

action: Possible choices: version, apply, deploy, zipapp, list, info, encrypt, decrypt, validate, debugger

Named Arguments¶

--debug, -d

Open the debugger if an unhandled exception is encountered

Default: False

--syslog-exception

When encountering an unhandle exception, print exception details to syslog before exiting

Default: False

--log-stderr

Possible choices: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET, NONE

Log level to send to stderr. Defaults to NOTSET (all messages, including debug). NONE to disable.

Default: “NOTSET”

--log-syslog

Possible choices: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET, NONE

Log level to send to syslog. Defaults to INFO if /dev/log exists, otherwise NONE. NONE to disable. If a value other than NONE is passed explicitly and /dev/log does not exist, an exception will be raised.

Default: “INFO”

--secret-store-arguments

A comma-separated list of key=value pairs to configure the secret store. See the documentation for your secret store for details.

Sub-commands¶

version¶

Show progfiguration core and progfigsite versions

progfigsite version [-h] [--site]

Named Arguments¶

--site, -s

Show only the simple site version (can be usefil in CI)

Default: False

apply¶

Apply configuration

progfigsite apply [-h] [--roles ROLES] [--force-apply] nodename

Positional Arguments¶

nodename: The name of a node in the progfiguration hoststore

Named Arguments¶

--roles, -r

A role, or list of roles separated by commas. The role(s) must be defined in the hoststore for the node(s).

Default: []

--force-apply

Force apply, even if the node has TESTING_DO_NOT_APPLY set.

Default: False

deploy¶

Deploy progfiguration to remote system in hoststore as a pyz package; requires passwordless SSH configured

progfigsite deploy [-h] [--nodes NODES] [--groups GROUPS] {apply,copy} ...

Positional Arguments¶

deploy_action: Possible choices: apply, copy

Named Arguments¶

--nodes, -n

A node, or list of nodes separated by commas

Default: []

--groups, -g

A group, or list of groups separated by commas

Default: []

Sub-commands¶

apply¶

Deploy and apply configuration

progfigsite deploy apply [-h] [--roles ROLES] [--remote-debug] [--force-apply]
                         [--keep-remote-file]

Named Arguments¶

--roles, -r

A role, or list of roles separated by commas. The role(s) must be defined in the hoststore for the node(s).

Default: []

--remote-debug

Open the debugger on the remote system if an unhandled exception is encountered

Default: False

--force-apply

Force apply, even if the node has TESTING_DO_NOT_APPLY set.

Default: False

--keep-remote-file

Don’t delete the remote file after execution

Default: False

copy¶

Copy the configuration to the remote system

progfigsite deploy copy [-h] [--destination DESTINATION]

Named Arguments¶

--destination, -d

The destination path on the remote system, default is based on the time this program was started, like /tmp/progfiguration-17209989358788943.pyz

Default: “/tmp/progfiguration-17209989358788943.pyz”

zipapp¶

Create a zipapp of the progfigsite

progfigsite zipapp [-h] output

Positional Arguments¶

output: The output file for the zipapp

list¶

List hoststore items

progfigsite list [-h] {nodes,groups,functions,svcpreps}

Positional Arguments¶

collection

Possible choices: nodes, groups, functions, svcpreps

The items to list. Options: [‘nodes’, ‘groups’, ‘functions’, ‘svcpreps’]

info¶

Display info about nodes and groups

progfigsite info [-h] [--nodes NODES] [--groups GROUPS]
                 [--functions FUNCTIONS]

Named Arguments¶

--nodes, -n

A node, or list of nodes separated by commas

Default: []

--groups, -g

A group, or list of groups separated by commas

Default: []

--functions, -f

A function, or list of functions separated by commas

Default: []

encrypt¶

Encrypt a value with age

progfigsite encrypt [-h] [--nodes NODES] [--groups GROUPS] [--controller]
                    [--value VALUE | --file FILE] [--save-as SAVE_AS]
                    [--stdout]

Named Arguments¶

--nodes, -n

A node, or list of nodes separated by commas

Default: []

--groups, -g

A group, or list of groups separated by commas

Default: []

--controller, -c

En/decrypt to/from the controller secret store

Default: False

--value

Encrypt this value

--file

Encrypt the contents of this file

--save-as

Save under this name in each node/group’s secret store. Otherwise, just print to stdout and do not save.

--stdout

Print encrypted value to stdout

Default: False

decrypt¶

Decrypt secrets from the secret store

progfigsite decrypt [-h] [--nodes NODES] [--groups GROUPS] [--controller]

Named Arguments¶

--nodes, -n

A node, or list of nodes separated by commas

Default: []

--groups, -g

A group, or list of groups separated by commas

Default: []

--controller, -c

En/decrypt to/from the controller secret store

Default: False

validate¶

Validate the progfigsite that it matches the required API

progfigsite validate [-h]

debugger¶

Open a debugger on localhost.

progfigsite debugger [-h]