Terraform Enterprise admin CLI reference

This topic provides reference information about tfectl commands that enable you to manage and administrate your Terraform Enterprise deployment.

Introduction

Terraform Enterprise includes a command line interface that enable you to change its configuration, stop the application safely, and produce support bundles. You must have access into the Docker container or Kubernetes pod to run these commands. For instructions on connecting to the command line, refer to Access the Terraform Enterprise command line.

tfectl command

The tfectl command is the root of the interface. It exposes a number of commands to perform different operations.

Most of the commands run directly on the node where Terraform Enterprise executes them. Some commands support a --node flag that you can use to specify which node to run a command on. The value of --node depends on the runtime environment of the Terraform Enterprise installation i.e:

Node: A TFE instance from which diagnostic information is collected. The type of node depends on the deployment environment.

• Docker: The node is identified by its container ID.
• Kubernetes: The node is identified by the pod name.
• Nomad: The node is identified by the allocation ID.
• Other environments: The node is identified by the machine hostname.

Gracefully stop work on a node

This command stops a terraform-enterprise node from executing new plans and applies. It allows the current work to complete before safely stopping the node from picking up any new tasks, which lets you safely stop the application.

Drain a single node.

$ tfectl node drain --node NODE_NAME

If you do not provide the --node flag, the command will drain the node you run it on.

$ tfectl node drain

Use the --all flag to drain all the nodes.

$ tfectl node drain --all

Restart the application to resume processing work after draining all the nodes.

Support bundle

The support bundle command generates support bundle on a Terraform Enterprise installation.

Generate a support bundle on a specific node.

$ tfectl support bundle --node NODE_NAME

If you do not provide the --node flag, Terraform Enterprise will by default generate the support bundle on the same node where you run the command.

$ tfectl support bundle

Use the --all flag to generate the support bundle on all the nodes.

$ tfectl support bundle --all

For mounted disk installations, Terraform Enterprise will generate support bundles in /run/terraform-enterprise/support-bundles. Downloading this file makes it immediately available, but it should be disabled once the file has been downloaded.

For External Services, Active/Active and Kubernetes installations, Terraform Enterprise will upload the support bundles to the same object store bucket where Terraform state files are stored. Each specific run of the admin support bundle command will upload the bundle to a directory with the same JobID, which is a timestamp in RFC3339 format (bucket/node/timestamp).

If you are sending a support bundle to HashiCorp Support, package and send all associated bundles to ensure that we have all the necessary information.

Example upload structure:

support-bundles
└── 2020-11-10T02:03:05Z
    ├── 10.0.0.5
    │   └── 10.0.0.5-support-bundle-timestamp.tar.gz
    └── 10.0.0.6
        └── 10.0.0.6-support-bundle-timestamp.tar.gz

Enable or disable support bundle downloads

The support bundle-download command enables the administrator of a mounted disk installation to access support bundles via https in the Terraform Enterprise node.

To enable downloads, use the --enable flag.

$ tfectl support bundle-download --enable

By enabling this feature, you will be able to download support bundles from https://${TFE_HOSTNAME}/_support-bundles/${timestamp}/${filename}. The filename follows the structure of ${node_hostname}-support-bundle-${timestamp}.tar.gz.

Once you have finished downloading support bundles, it is recommended to disable this feature using the following command:

$ tfectl support bundle-download --disable

If the command is executed in a Terraform Enterprise installation that is not running on a mounted disk, it will have no effect and perform no action.

Connect to the internal Rails Console

At times, it may become necessary to modify the internal state of the Terraform Enterprise application. An example is when you have lost credentials for all your admin accounts and need to manually set an existing user as an administrator.

This operation is very dangerous, and we strongly advise against using this command without the guidance of HashiCorp support. Once you have a concrete action plan on what needs to be changed via the Rails console, execute:

$ tfectl support console

This will prompt you for confirmation. Only the word yes is a valid response to proceed.

Review HashiCorp license status

This command displays the status of the license installed on your Terraform Enterprise application.

$ tfectl app license

Retrieve the initial admin user creation token

To create the first admin user in your Terraform Enterprise installation, you will need the Initial Admin Creation Token or IACT. You can retrieve this from any Terraform Enterprise node using:

$ tfectl admin token

This command should return the token value. You can also retrieve the REST resource that will allow you to create your initial admin user with the IACT token appended at the end via the flag:

$ tfectl admin token --url

This will provide the URL formatted to be used with curl or wget, and it only supports POST operations.

Generate product usage report

The admin usage-report command generates a product usage report in JSON format that you can view and download.

$ tfectl admin usage-report

When in external and active-active mode and on Kubernetes, Terraform Enterprise uploads the product usage report to the same object store bucket where Terraform state files are stored.

Each specific run of the admin usage-report command generates the product usage report in a new JSON file.

To send product usage reports to HashiCorp, visit the Licensing utilization reporting page and use the upload form.

Manage System API tokens

Terraform Enterprise provides commands to manage authentication tokens for the System API, which allows programmatic access to administrative functions. Note that this is not equivalent to the Admin API which manages organization and workspace resources. The System API interacts with the TFE deployment and not the TFE application.

Generate a System API token

To create a new System API token, use the admin api-token generate command with a required description that helps identify the token's purpose or owner:

$ tfectl admin api-token generate --description "Token description"

By default, tokens expire after 720 hours (30 days). You can specify a custom time-to-live (TTL) in hours using the --ttl flag:

$ tfectl admin api-token generate --description "Token description" --ttl 2000

List System API tokens

To list all existing System API tokens along with their metadata (excluding the actual token value), use:

$ tfectl admin api-token list

This command displays the token ID, creation date, expiration date, last used date, and description for each token. The output is ordered by creation date.

Revoke a System API token

To revoke a System API token, use the admin api-token revoke command with the token ID (obtained from the list command):

$ tfectl admin api-token revoke --id "1"

List all Terraform Enterprise installation nodes

To get a list of valid node values, use the following command:

$ tfectl node list

This will return a list of all active nodes in the installation that are sharing the same database connection.

View application health

Terraform Enterprise runs several integral systems for the application's overall health. To view the health of these systems, run the following command:

$ tfectl app status

You can also view the health on other nodes in the Terraform Enterprise installation. To see the status of a specific node, use the --node flag, e.g.:

$ tfectl app status --node NODE_NAME

For a health check on every node in the Terraform Enterprise installation, you could run:

$ tfectl app status --all

The tfectl app diagnostics command performs a comprehensive diagnostic check of all Terraform Enterprise subsystems. It returns detailed status information for each component, including warnings and errors.

Run diagnostics on the current node:

$ tfectl app diagnostics

Use the --all flag to run diagnostics on all nodes. This flag is mutually exclusive with the --node flag.

$ tfectl app diagnostics --all

Use the --node flag to specify a specific node to run diagnostics on. This flag is mutually exclusive with the --all flag.

$ tfectl app diagnostics --node NODE_NAME

Use the --timeout flag to set a custom timeout in seconds. You can specify 1- 300. The default is 30:

$ tfectl app diagnostics --timeout 60

Use the --check flag to run a subset of checks. The flag accepts a comma-separated list of checks. You can use the following format to specify a group name or a sub-check of a group: <group>, <group>.<subcheck>.

The following example runs checks on the redis group and the valid_config sub-check in the database group:

$ tfectl app diagnostics --check redis,database.valid_config

Output in JSON format:

$ tfectl app diagnostics --json

When the database is unavailable, the tfectl app diagnostics command can only fetch information from the current node. Running the command on remote nodes using the --node or --all flag requires database connectivity.

The --all and --node flags are mutually exclusive.

Check application readiness

The tfectl app health readiness command checks if Terraform Enterprise is ready to accept requests by querying the readiness endpoint.

Check readiness:

$ tfectl app health readiness

Use the --timeout flag to set a custom timeout in seconds. You can specify 1- 30. The default is 1:

$ tfectl app health readiness --timeout 5

Output in JSON format:

$ tfectl app health readiness --json

View application configuration

Reviewing the actual values used by the Terraform Enterprise application during execution is a useful method to verify correct configuration. To view it, simply run:

$ tfectl app config

This command will print the application's configuration in JSON format, with sensitive values redacted. To see the configuration without redaction, use:

$ tfectl app config --unredacted

However, some values, like the TLS CA Bundle Data, are truncated for readability. For the full configuration without truncation, use:

$ tfectl app config --full

You can save the configuration to a file with:

$ tfectl app config --out /path/to/config.json

To get the node's configuration from a specific node:

$ tfectl app config --node NODE_NAME

To read the configuration from all the nodes in the Terraform Enterprise installation, you can use:

$ tfectl app config --all

To convert your Terraform Enterprise configuration into a suitable Docker Compose file format, use the following command:

$ tfectl app config --format docker

Use this command when migrating from a Replicated installation to another deployment option.

Change encryption password

The TFE_ENCRYPTION_PASSWORD is used as a key for envelope encryption. This password is necessary to start and run Terraform Enterprise. The blob data cannot be decrypted without it. To change it, use:

$ tfectl app rotate-encryption-password

You'll be prompted for confirmation, where 'yes' is the only acceptable value. Then, you'll need to provide your current and new passwords:

$ tfectl app rotate-encryption-password --current CURRENT_PASSWORD --new NEW_PASSWORD

WARNING: After changing the encryption password, restart your Terraform Enterprise nodes with the new password as the value of the TFE_ENCRYPTION_PASSWORD environment variable. Ensure no one is using the system to avoid corrupting the application's state.

Back up the old password in case you need to restore the application. Otherwise, data in the backup can't be accessed.

Trigger startup checks

Terraform Enterprise runs validations to ensure proper application configuration. Use the following commands to manually trigger the validations:

$ tfectl app startup-check

View ongoing database migrations

This command retrieves the current version of the ongoing database migrations:

$ tfectl db last-applied-migration

View Terraform Enterprise application version

This command retrieves the currently running version of Terraform Enterprise:

$ tfectl app version

Mounted disk commands

When using TFE_OPERATIONAL_MODE: disk, Terraform Enterprise runs its Postgres instance managed through the container. Admin CLI provides commands for common operations.

Create a database backup

To create backups of the internal database instance, use the following command:

$ tfectl db backup

This command will generate the backup in the directory passed via the environment variable TFE_DISK_PATH, default /var/lib/terraform-enterprise. The backup filename will be created in the format TIMESTAMP_hashicorp.db. `

You can specify the backup's destination via the --out flag, e.g.

$ tfectl db backup --out /path/to/backup.db

Recreate database indices

Rebuild Postgres database indices using:

$ tfectl db reindex

Restore database from a backup

• The execution of this command will momentarily shut down your Terraform Enterprise instance. Please make sure that no work is being executed, and no one is using the instance before running this command. After the restore takes place, Atlas will come back online.

• This operation is irreversible, once a database backup has been loaded, all data created between the time of the backup and the date of restoration will be lost.

To restore a database from a backup file, run:

$ tfectl db restore --file /path/to/backup.db

Confirmation is needed, with only yes as a valid response.