genvid.toolbox.Clusters

class genvid.toolbox.Clusters(use_wan=False, *, noproxy=False, **kwargs)

Bases: BastionAPI

Base class to manage clusters.

CLUSTER_MAPPED_ARGS = {'plans': 'plan_file'}

global_show(): Show the global configuration.

global_update(bastion_id)

Update the global configuration.

Parameters:: bastion_id – The Bastion ID.

global_tfvars_show(): Show the global Terraform variables.

global_tfvars_update(tffile: str): Update the global Terraform variables.

cluster_list(): Print the list of clusters.

cluster_exists(cluster_id: str)

cluster_create(cluster_id: str, backend: str = 'default', variable: Optional[List[str]] = None, category: str = 'cluster')

Create a cluster.

Parameters:

cluster_id (str) – A unique ID for this cluster.
backend (str) – A backend ID.
variable (str) – The backend variables.
category (str) – A category for this cluster. The only special value is cluster, which indicate a cluster that could managed the cluster-api service.

cluster_delete(cluster_id: str, force: bool = False)

Delete a cluster.

Parameters:

cluster_id –
force – Force the cluster to be deleted.

cluster_show(cluster_id: str)

Show information about the specified cluster.

Parameters:: cluster_id –

Changed in version 1.42.0: Dump values as proper JSON if a list or dict.

cluster_static_create(cluster_id: str, output: dict, *, category: str = 'cluster')

Create a static cluster.

Parameters:

cluster_id – A unique ID for this cluster.
output – A dictionary for the output, must be compatible with Terraform JSON output.
category – A category for this cluster. The only special value is cluster, which indicate a cluster that could managed the cluster-api service.

New in version 1.42.0.

cluster_static_update(cluster_id: str, output: dict) → None

Update a static cluster.

Parameters:

cluster_id – The unique ID identifying the cluster.
output – A dictionary for the output, must be compatible with Terraform JSON output.

New in version 1.42.0.

get_instances(clusters: Optional[List[str]] = None) → List[dict]

Get the cluster instances.

Parameters:: clusters – The list of clusters.

get_instance_id(clusters: Optional[List[str]] = None, globalcontext: bool = False)

Get a single instance ID.

Parameters:

clusters – A list of clusters (must be a single list).
globalcontext – The global context.

Returns:

A single instance or raised exception.

Raises:

ValueError if the number of instances isn’t 1.

execute_global_action(action: str, globalcontext: bool = False, silent: bool = False, **kwargs)

Execute a global action.

Parameters:

action – init, plan, apply, destroy, or refresh.
globalcontext – If the action is for global context.
silent – Do not print the command logs.
kwargs –

execute_clusters_action(action: str, clusters: Optional[List[str]] = None, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute an action for multiple clusters in parallel.

Parameters:

action – init, plan, apply, destroy, or refresh.
clusters – The list of clusters.
silent – Do not print the command logs.
kwargs –

Returns:

A dictionary

execute_action(action: Optional[str] = None, cluster_id: Optional[str] = None, instance_id: Optional[str] = None, silent: bool = False, **kwargs)

Execute an action.

Parameters:

action – init, plan, apply, destroy, or refresh.
cluster_id – The cluster ID. May be empty for the global context.
instance_id – The instance ID.
silent – Do not print the command logs.
kwargs –

Returns:

terraform_get(clusters: Optional[List[str]] = None, globalcontext: bool = False)

Execute a Terraform get.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.

terraform_plan(clusters: Optional[List[str]] = None, globalcontext: bool = False, destroy: bool = False, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform plan.

A Terraform plan command validates the operation to be carried out on a cluster without actually carrying them. It is good practice to run this command before a terraform_apply() to avoid leaving a cluster half configured in case of errors.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to perform the operation in the global context.
destroy – Whether to plan the destruction of a cluster instead, prior to a terraform_destroy() operation for example.
silent – Do not output to the console.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_plan_destroy(clusters: Optional[List[str]] = None, globalcontext: bool = False, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform plan for destroying clusters.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to perform the operation in the global context.
silent – Do not output to the console.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

See also

terraform_plan() for more information.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_import_module(clusters: Optional[List[str]] = None, module_path: str = 'cluster/default', globalcontext: bool = False, silent: bool = False, force: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform import module operation.

This command is used to import a Terraform module unto some clusters. This will effectively move the clusters from state EMPTY to DOWN, waiting for an eventual apply operation to be carried out.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
module_path – Path to the Terraform module to import.
globalcontext – Whether to perform the operation in the global context.
destroy – Whether to plan the destruction of a cluster instead, prior to a terraform_destroy() operation for example.
silent – Do not output to the console.
force – Force the import even if the cluster is in an invalid state.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_init(clusters: Optional[List[str]] = None, globalcontext: bool = False, silent: bool = False, force: bool = False, doall: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform init.

Initialize or update the working directory containing the Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
module_path – Path to the Terraform module to import.
globalcontext – Whether to perform the operation in the global context.
destroy – Whether to plan the destruction of a cluster instead, prior to a terraform_destroy() operation for example.
silent – Do not output to the console.
force – Force the command even if some of the clusters are in an invalid state.
doall – If True will ignore instances and clusters and will operate on all non-static instances.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.14.0: Add the doall parameter.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_apply(clusters: Optional[List[str]] = None, globalcontext: bool = False, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform apply.

A Terraform apply command is used to apply the required configuration on the clusters to reach the state described in the Terraform module.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to perform the operation in the global context.
silent – Do not output to the console.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_destroy(clusters: Optional[List[str]] = None, globalcontext: bool = False, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform destroy.

A Terraform destroy command is used to clean up the work did by a previous apply command.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to perform the operation in the global context.
silent – Do not output to the console.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_refresh(clusters: Optional[List[str]] = None, globalcontext: bool = False, silent: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Execute a Terraform refresh.

A Terraform refresh command is used to update the clusters’ state files with the real-world infrastructure.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to perform the operation in the global context.
silent – Do not output to the console.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

terraform_output(clusters: Optional[List[str]] = None, globalcontext=False, **kwargs)

Execute a Terraform output.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

terraform_status(clusters: Optional[List[str]] = None, globalcontext=False)

Print the status of the clusters on the command line.

The result can be:

VOID: The instance doesn’t exist.

EMPTY: The instance exists but isn’t initialized.

DOWN: The instance is initialized but doesn’t contain any
resources.

UP: The instance is managing some resources.

BUSY: The instance is currently running a command.

ERROR: An error has occured during status retrieval.

INVALID: The current status of the instance is unknown.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

terraform_tfvars_show(clusters: Optional[List[str]] = None, globalcontext=False, **kwargs)

Show the terraform.tfvars.json file.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

terraform_tfvars_default(clusters: Optional[List[str]] = None, globalcontext=False, **kwargs)

Show the default terraform.tfvars.json file.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

terraform_schema(clusters: Optional[List[str]] = None, globalcontext=False, **kwargs)

Show the default terraform.tfvars.json file.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

terraform_tfvars_update(clusters: Optional[List[str]] = None, globalcontext=False, tffile: str = '', **kwargs)

Update the terraform.tfvars.json file.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
file – The source file to update from.
kwargs –

set_terraform_providers(clusters: Optional[Iterable[str]] = None, *, providers_file: str, **kwargs)

Update the Terraform providers using the content of a file.

The file content should match the expected JSON format of BastionAPI.terraform_put_providers.

Parameters:

clusters – IDs of clusters to operate on.
providers_file – File containing the new providers.

get_terraform_providers(clusters: Optional[Iterable[str]] = None, **kwargs)

Display the Terraform providers configuration for some clusters.

The displayed JSON will match the format of BastionAPI.terraform_get_providers.

Parameters:: clusters – IDs of clusters to operate on.

delete_terraform_providers(clusters: Optional[Iterable[str]] = None, **kwargs)

Delete the Terraform providers configured on a cluster.

Parameters:: clusters – IDs of clusters to operate on.

commands_list(clusters: Optional[List[str]] = None, globalcontext: bool = False, *, instances: Optional[List[dict]] = None, **kwargs)

Show the list of available commands.

Parameters:

clusters – Optional list of cluster IDs to operate on if the instances parameter is None.
globalcontext – Whether to list the command from the global context.
instances – Instances to operate on.

Warning

If instances is not None then clusters is ignored.

Changed in version 1.21.0:

Added support to operate on multiple clusters.
New parameter instances to bypass querying of instances by the method.
Augmented documentation and typing annotations.

commands_log(clusters: Optional[List[str]] = None, globalcontext=False, command_id: str = '', **kwargs)

Print a command log.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
command_id – The command ID.
kwargs –

commands_latest(clusters: Optional[List[str]] = None, globalcontext=False, **kwargs)

Print the latest command logs.

Parameters:

clusters – The list of clusters.
globalcontext – The global context.
kwargs –

repository_list(): List of all terraform repositories configuration.

path_to_uri(url)

Ensure a path is actually a uri and not a file.

The file pointing by the url must actually exist.

repository_add(repository: str, url: str)

Add a repository.

Parameters:

repository – The unique name of the repository.
url – The url of the repository (must be accessible from the bastion).

Returns:

The repository configuration.

repository_update(repository: str, url: str = '')

Update an existing repository.

Parameters:

repository – The name of the repository.
url – The url of the repository(optional).

Returns:

The repository configuration.

repository_remove(repository: str)

Remove a repository.

Parameters:: name – The name of the repository
Returns:: The repository configuration.

repository_update_all(): Update all registered repositories.

repository_clean(): Remove all registered repositories.

backend_list(): Get the list of all backend templates.

backend_add(backend_id: str, backend_type: str, variables: Optional[dict] = None)

Add a new backend template.

Parameters:

backend_id – The backend ID.
backend_type – The type of backend.
variables – A list of default variables for the backend.

backend_update(backend_id: str, backend_type: str, variables: Optional[dict] = None)

Update an existing backend template.

Parameters:

backend_id – The backend ID.
backend_type – The type of backend.
variables – A list of default variables for the backend.

backend_remove(backend_id: str)

Remove a backend template.

Parameters:: backend_id – The backend ID.

wait_command(command)