Bulk Updating User Email Domains in Terraform Enterprise

Please note that this procedure should be performed by an administrator or someone with sufficient permissions and knowledge of the system. Always ensure you have a backup of your data before performing the operations described in this guide.

Introduction

Admins managing a Terraform Enterprise (TFE) instance may find themselves in a scenario where it becomes necessary to perform a bulk update of user email addresses. One common scenario could be a company-wide domain change, where all users are migrating from an old email domain to a new one. This could be due to rebranding, a company merger, or a shift in the company's email policy. A bulk update can help ensure consistency across all user accounts. This guide will provide a step-by-step process for efficiently handling such bulk email updates in a Terraform Enterprise environment.

Prerequisites

• Terraform Enterprise
• Admin Access to TFE host (requires access to the Rails Console)
• Backup all data prior to making changes
• Old and New email domain

Overview

Due to the limitations of the admin API, Terraform Enterprise does not natively support bulk updating of users' email addresses. However, there is a workaround that involves using the Rails console to perform this task. This method is particularly useful for large-scale operations where updating each user's email address individually is not feasible.

Procedures

• Access the Rails Console: This is where you will run the script to update the email addresses.

• Prepare the script: The script will iterate over all users, split their email address at the '@' symbol, and check if the domain matches the old domain. If it does, the script will update the domain to the new one. Here is the script:
  • Be sure to replace "old_domain.com" and "new_domain.com" with your actual old and new domains.

users = User.all
users.each do |user|
  parts = user.email.split("@")
  if parts.length() != 2 or parts.last != "old_domain.com"
    puts "Skipping #{user.email}."
    next
  end
  new_email = "#{parts.first}@new_domain"
  puts "Changing #{user.email} to #{new_email}."
  # user.email = new_email
  begin
    # user.save!
    puts "Successfully updated #{user.email}."
  rescue => e
    puts "Failed to update #{user.email}. Error: #{e.message}"
  end
end

• Perform a dry run: Before running the script with the intention of making any changes, it's recommended to perform a dry run to ensure it works as expected. The script above has the lines that actually change the email and save the user commented out by default to prevent unintended changes.
  
  • When you run this script, it will print out the changes that would be made without actually making them. This allows you to verify the changes before you proceed with the actual update.

# user.email = new_email
# user.save!

• Run the script: Once you're confident the script will perform as expected, you can uncomment the lines mentioned above in the dry run and re-run the script. This will update all user email addresses from the old domain to the new one.