This guide is meant to take an operator through all steps necessary for a successful installation of DC/OS using Terraform. If you are already familiar with the prerequisites, you can jump to Creating a DC/OS Cluster.

Prerequisites

• Linux, macOS, or Windows
• command-line shell terminal such as Bash or PowerShell
• verified Azure Resource Manager account with the necessary permissions

Install Terraform

1. Visit the Terraform releases page for bundled installations and support for Linux, macOS and Windows. Choose the latest 0.12 version.

   If you’re on a Mac environment with Homebrew installed, simply run the following command:

   brew unlink terraform || true
   brew install tfenv
   tfenv install 0.12.25
   tfenv use 0.12.25
   

   Windows users that have Chocolatey installed, run:

   choco install terraform --version 0.12.25 -y
   

Ensure your cloud provider credentials

There are many ways of passing in your credentials in order for Terraform to authenticate with your cloud provider. Most likely, you already have your cloud provider credentials loaded through the Azure CLI. Terraform will automatically detect those credentials during initialization for you. See installing the Azure CLI for more information. See the Terraform Azure provider reference for more information on how this works under the hood.

Alternatively, it can be set through your terminal. You can set the default account with the following command:

export ARM_SUBSCRIPTION_ID="desired-azure-id"

Ensure it is set:

echo $ARM_SUBSCRIPTION_ID

Or, You can pass your Azure ID in as the subscription_id through the configuration file you will create. Please keep in mind storing your credentials outside of your version control for security.

provider "azurerm" {
  subscription_id = "00000000-0000-0000-0000-000000000000"
}

Set up SSH credentials for your cluster

Terraform will need to send out SSH keys to connect securely to the nodes it creates. If you already have a key-pair available and added to your SSH-agent, you can skip this section.

1. Not sure if you have a keypair you want to use? List the contents of your ssh directory.

   ls ~/.ssh
   

2. If you don’t have one you like, start the ssh-keygen program to create a new key pair, following the prompts.

   ssh-keygen -t rsa
   

3. Add the key to your SSH agent by starting the agent if it isn’t already running and then loading your key:

   eval "$(ssh-agent -s)"
   

   ssh-add ~/.ssh/<your-key-name>
   

Verify you have a license key for Enterprise Edition

DC/OS Enterprise requires a valid license key provided by Mesosphere that will be passed into the main.tf configuration file as dcos_license_key_contents. If you do not set a password, the default superuser and password will be available for log in:

Username: bootstrapuser
Password: deleteme

IMPORTANT: You should NOT use the default credentials in a production environment. When you create or identify an administrative account for the production environment, you also need to generate a password hash for the account.

To set superuser credentials for the first log in, add the following values into your main.tf along with your license key. The password will need to be hashed to SHA-512.

dcos_superuser_username      = "superuser-name"
dcos_superuser_password_hash = "${file("./dcos_superuser_password_hash")}

Creating a DC/OS Cluster

1. Let’s start by creating a local folder and cd’ing into it. This folder will be used as the staging ground for downloading all required Terraform modules and holding the configuration for the cluster you are about to create.

   mkdir dcos-demo && cd dcos-demo
   

2. Create a file in that folder called main.tf, which is the configuration file that will be called on each time when terraform runs. The name of this file should always be main.tf. Open the file in the code editor of your choice and paste in the following. Notice the copy icon in the upper right hand corner of the code block to copy the code to your clipboard:

   provider "azurerm" {
     features {}
   }
   
   data "http" "whatismyip" {
     url = "http://whatismyip.akamai.com/"
   }
   
   module "dcos" {
     source  = "dcos-terraform/dcos/azurerm"
     version = "~> 0.3.0"
   
     providers = {
       azurerm = azurerm
     }
   
     cluster_name                      = "my-dcos-demo"
     ssh_public_key_file               = "<path-to-public-key-file>"
     admin_ips                         = ["${data.http.whatismyip.body}/32"]
     location                          = "West US"
     avset_platform_fault_domain_count = 3
   
     num_masters        = 3
     num_private_agents = 2
     num_public_agents  = 1
   
     dcos_version = "2.2"
   
     # Enterprise users uncomment this section and comment out below
     # dcos_variant              = "ee"
     # dcos_license_key_contents = "${file("./license.txt")}"
     # Make sure to set your credentials if you do not want the default EE
     # dcos_superuser_password_hash = "${file("./dcos_superuser_password_hash.sha512")}
     # dcos_superuser_username = "admin"
   
     dcos_variant = "open"
   }
   
   output "masters-ips" {
     value = module.dcos.masters-ips
   }
   
   output "cluster-address" {
     value = module.dcos.masters-loadbalancer
   }
   
   output "public-agents-loadbalancer" {
     value = module.dcos.public-agents-loadbalancer
   }
   

3. There are two main variables that must be set to complete the main.tf, and you can change any others here at this point too.

   1. ssh_public_key_file = "<path-to-public-key-file>": the path to the public key for your cluster, following our example it would be:

      "~/.ssh/arm-key.pub"
      

   2. location = "West US": The way the AzureRM provider is implemented forces us to specify the location in the module. If you want to use a different region replace location with your desired region.

4. Enterprise users, uncomment/comment the section for the dcos_variant to look like this, inserting the location to your license key, and adding superuser credentials if needed. Enterprise

   dcos_variant              = "ee"
   dcos_license_key_contents = "${file("./license.txt")}"
   # dcos_variant = "open"
   

5. If you want to change the cluster name or vary the number of masters/agents, feel free to adjust those values now as well. Cluster names must be unique, consist of alphanumeric characters, ‘-’, ‘_’ or ‘.’, start and end with an alphanumeric character, and be no longer than 24 characters. You can find additional input variables and their descriptions here.

   There are also simple helpers listed underneath the module which find your public ip and specify that the following output should be printed once cluster creation is complete:

   • master-ips A list of Your DC/OS master nodes
   • cluster-address The URL you use to access DC/OS UI after the cluster is setup.
   • public-agent-loadbalancer The URL of your Public routable services.

6. Check that you have inserted your cloud provider and public key paths to main.tf, changed or added any other additional variables as wanted, then save and close your file.

Initialize Terraform and create a cluster

1. Now the action of actually creating your cluster and installing DC/OS begins. First, initialize the project’s local settings and data. Make sure you are still working in the same folder where you created your main.tf file, and run the initialization.

   terraform init -upgrade
   

   Terraform has been successfully initialized!
   
   You may now begin working with Terraform. Try running "terraform plan" to see
   any changes that are required for your infrastructure. All Terraform commands
   should now work.
   
   If you ever set or change modules or backend configuration for Terraform,
   rerun this command to reinitialize your environment. If you forget, other
   commands will detect it and remind you to do so if necessary.
   

   Note: If terraform is not able to connect to your provider, ensure that you are logged in and are exporting your credentials and necessary region information for your cloud provider.

2. After Terraform has been initialized, the next step is to run the execution planner and save the plan to a static file - in this case, plan.out.

   terraform plan -out=plan.out
   

   Writing the execution plan to a file allows us to pass the execution plan to the apply command below as well help us guarantee the accuracy of the plan. Note that this file is ONLY readable by Terraform.

   Afterwards, we should see a message like the one below, confirming that we have successfully saved to the plan.out file. This file should appear in your dcos-demo folder alongside main.tf.

   lan: 97 to add, 0 to change, 0 to destroy.
   
   ------------------------------------------------------------------------
   
   This plan was saved to: plan.out
   
   To perform exactly these actions, run the following command to apply:
         terraform apply "plan.out"
   
   

   Every time you run terraform plan, the output will always detail the resources your plan will be adding, changing or destroying. Since we are creating our DC/OS cluster for the very first time, our output tells us that our plan will result in adding 38 pieces of infrastructure/resources.

3. The next step is to get Terraform to build/deploy our plan. Run the command below.

   terraform apply plan.out
   

   Sit back and enjoy! The infrastructure of your DC/OS cluster is being created while you watch. This may take a few minutes.

   Once Terraform has completed applying the plan, you should see output similar to the following:

   Apply complete! Resources: 97 added, 0 changed, 0 destroyed.
   
   The state of your infrastructure has been saved to the path
   below. This state is required to modify and destroy your
   infrastructure, so keep it safe. To inspect the complete state
   use the `terraform show` command.
   
   State path: terraform.tfstate
   
   Outputs:
   
   cluster-address = my-dcos-demo-705740393.us-east-1.elb.amazonaws.com
   masters-ips = [
     "3.83.23.21",
     "18.212.236.17",
     "54.91.103.151",
   ]
   public-agents-loadbalancer = ext-my-dcos-demo-cd20e369b92d07f7.elb.us-east-1.amazonaws.com
   

   And congratulations - you’re up and running!

Logging in to DC/OS

1. To log in and start exploring your cluster, navigate to the cluster-address listed in the output of the CLI. From here you can choose your provider to create the superuser account Open Source, or log in with your specified Enterprise credentials Enterprise.

Scaling Your Cluster

Terraform makes it easy to scale your cluster to add additional agents (public or private) once the initial cluster has been created. Simply follow the instructions below.

1. Increase the value for the num_private_agents and/or num_public_agents in your main.tf file. In this example we are going to scale our cluster from 2 private agents to 3, changing just that line, and saving the file.

   num_masters        = "1"
   num_private_agents = "3"
   num_public_agents  = "1"
   

2. Now that we’ve made changes to our main.tf, we need to re-run our new execution plan.

   terraform plan -out=plan.out
   

   Doing this helps us to ensure that our state is stable and to confirm that we will only be creating the resources necessary to scale our Private Agents to the desired number.

   

   You should see a message similar to above. There will be 3 resources added as a result of scaling up our cluster’s Private Agents (1 instance resource & 2 null resources which handle the DC/OS installation & prerequisites behind the scenes).

3. Now that our plan is set, just like before, let’s get Terraform to build/deploy it.

   terraform apply plan.out
   

   

   Once you see an output like the message above, check your DC/OS cluster to ensure the additional agents have been added.

   You should see now 4 total nodes connected like below via the DC/OS UI.

   

Upgrading Your Cluster

Terraform also makes it easy to upgrade our cluster to a newer version of DC/OS. If you are interested in learning more about the upgrade procedure that Terraform performs, please see the official DC/OS Upgrade documentation.

1. In order to perform an upgrade, we need to go back to our main.tf and modify the current DC/OS Version (dcos_version) to a newer version, such as 1.13.3 for this example.

   dcos_version = "2.2"
   

2. We also should make sure having the latest version of the Terraform modules. So we tell Terraform to request those from the registry.

   terraform get -update
   

3. Re-run the execution plan, terraform will notice the change in version and run accordingly.

   terraform plan -out=plan.out
   

   You should see an output like below, with your main.tf now set for normal operations on a new version of DC/OS.

   

4. Apply the plan.

   terraform apply plan.out
   

   Once the apply completes, you can verify that the cluster was upgraded via the DC/OS UI.

   

Deleting Your Cluster

If you want to destroy your cluster, then use the following command and wait for it to complete.

terraform destroy

Important: Running this command will cause your entire cluster and all of its associated resources to be destroyed. Only run this command if you are absolutely sure you no longer need access to your cluster.

You will be required to enter yes to verify.