genvid.toolbox.Clusters

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

Bases: genvid.toolbox.bastion_api.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: typing.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
get_instances(clusters: typing.List[str] = None) → typing.List[dict]

Get the cluster instances.

Parameters:clusters – The list of clusters.
get_instance_id(clusters: typing.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: typing.List[str] = None, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: str = None, cluster_id: str = None, instance_id: 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: typing.List[str] = None, globalcontext: bool = False)

Execute a Terraform get.

Parameters:
  • clusters – The list of clusters.
  • globalcontext – The global context.
terraform_plan(clusters: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, destroy: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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_plan_apply(clusters: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = None, **kwargs)

Execute a Terraform plan for applying modules to 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: typing.Union[typing.List[str], NoneType] = None, module_path: str = 'cluster/default', globalcontext: bool = False, silent: bool = False, force: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, force: bool = False, doall: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, silent: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.List[str] = None, globalcontext=False, **kwargs)

Execute a Terraform output.

Parameters:
  • clusters – The list of clusters.
  • globalcontext – The global context.
  • kwargs
terraform_status(clusters: typing.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: typing.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: typing.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: typing.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: typing.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: typing.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: typing.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: typing.Iterable[str] = None, **kwargs)

Delete the Terraform providers configured on a cluster.

Parameters:clusters – IDs of clusters to operate on.
commands_list(clusters: typing.Union[typing.List[str], NoneType] = None, globalcontext: bool = False, *, instances: typing.Union[typing.List[dict], NoneType] = 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: typing.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: typing.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: typing.Union[dict, NoneType] = 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: typing.Union[dict, NoneType] = 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)