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:

• Container ID (Docker)
• Pod Name (Kubernetes)
• 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.

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

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 database migration status

This command queries the status of all in-flight or required migrations:

$ tfectl db migration-status

Use the --required-only flag to return the status of required migrations:

$ tfectl db migration-status --required-only

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.