How to Create a Local Admin User in the Terraform Enterprise Flexible Deployment Option

Introduction

Before enabling a single sign-on (SSO) integration in Terraform Enterprise, we recommend creating a non-SSO local administrator account. This account serves as a recovery mechanism if access via SSO is unavailable. This guide explains how to access the Rails console and create a local user within a Terraform Enterprise (TFE) Flexible Deployment Option (FDO) Kubernetes deployment.

Prerequisites

• Terraform Enterprise Flexible Deployment Option (FDO) version v202309-1 or later.
• A Kubernetes-based FDO deployment.

Use Case

Creating a local administrator provides a reliable way to access the Terraform Enterprise instance to manage settings or troubleshoot issues, particularly if the primary SSO provider is experiencing an outage or is misconfigured.

Note: The email address assigned to this local administrator should not be associated with a user account that will be managed by SAML or SSO.

Procedure

Follow these steps to create a local administrator user.

1. Authenticate to your Kubernetes cluster. For example, if you are using Azure Kubernetes Service (AKS), run the following command.

   $ az aks get-credentials --resource-group <resource-group-name> --name <aks-cluster-name>

2. Retrieve the name of the Terraform Enterprise pod.

   $ kubectl get pods -n <namespace>

3. Execute a remote shell session into the pod.

   $ kubectl exec -n <namespace> -it <pod-name> -- bash

4. From the shell inside the pod, connect to the internal Rails console.

   $ tfectl support console

5. Create a user and assign it to the u variable. Replace the example values with your desired credentials.

   u = User.create!(email: "admin-local@example.com", username: "admin-local", password: "your-secure-password", is_admin: true)

6. Confirm the user's email address to bypass the standard email confirmation process.

   u.confirm
   u.save

7. Add the new user to the owners team of an organization. This grants the user administrative permissions within that organization.

   Organization.find_by_name("your-org").add_owner!(u)

After completing these steps, you can use this local administrator account to log into the Terraform Enterprise instance without SSO. This allows you to manage SSO settings or perform other administrative tasks.