Skip to main content
Version: Next

Rover commands

Commonly used commands​

Beyond a container, rover is your one-stop tool to help on landing zone and landing zones state management.

What people love about rover is the ubiquity it gives them and seamless transition from local development environment with pipelines. In this articles, you will find the most commonly used commands for rover and some details on the state locator process.

Rover is by nature multi-subscription, and in landing zones worlds, the subscription where you want to deploy your resource is just another parameter of rover, just as the subscription where to store the state files and locate the launchpad.

Login​

The first command you will have to run is rover login:

You can run a plain rover login:

rover login

You can specify additional context to restrict the token, like the tenant name and subscription to use:

rover login --tenant [tenant_name.onmicrosoft.com or tenant_guid (optional)] --subscription [subscription_id_to_target(optional)]

You can log out running the following command:

rover logout

Landing zones commands​

Once authentication is completed, a typical rover command looks like:

rover \
 -lz /tf/caf/landingzones/caf_launchpad \
 -var-folder /tf/caf/configuration/contoso/platform/level0/launchpad \
 -tfstate_subscription_id a-b-c-d-e \
 -target_subscription f-g-h-i \
 -tfstate caf_launchpad.tfstate \
 -log-severity ERROR \
 -launchpad \
 -env contoso \
 -level level0 \
 -p ${TF_DATA_DIR}/caf_launchpad.tfstate.tfplan \
 -a plan

The following table summarizes the most common parameters and their default values:

argumentrequireddefault valueDescriptionExample
-lzyesN/APath to landing zone (.tf files) to be executed. This is typically /tf/caf/landingzones/caf_launchpad , /tf/caf/landingzones/caf_solution or any add-ons from /tf/caf/landingzones/caf_solution/add-ons. This could also be your own custom written Terraform files./tf/caf/landingzones/caf_launchpad
-var-folderyesN/APath to the set of configuration files. All .tfvars files in directory will be expanded./tf/caf/configuration/contoso/platform/level0/launchpad
-envyesN/AString that defines a name for an environment to use. This is defined as (used in the state locator function as described below.)contoso
-levelyesN/ASpecifies the level in the CAF hierarchy where to deploy the resources (possible value are level1-level4)level1
-ayesN/AAction to take with the current parameters, possible values are plan, apply, destroy, validate, refresh, graph, import, output, taint, untaint, 'state list', 'state rm', 'state show'plan
-log-severitynoERRORSpecifies the Terraform log verbosity this sets the TF_IN_AUTOMATION parameters, possible options are: VERBOSE, DEBUG, INFO, WARN or ERRORERROR
-tfstate_subscription_idnoIf no value specified, rover is assuming the currently logged-in subscription from az cli context.GUID of the subscription containing the tfstate (launchpad). This will be used to locate and store the tfstate files.a-b-c-d-e
-target_subscriptionnoIf no value specified, rover is assuming the currently logged-in subscription from az cli context.GUID of the subscription where to deploy the resources.a-b-c-d-e
-workspacenotfstateSpecifies the storage account container where to store the tfstate for this landing zone. This could be used to isolate landing zones from each others by specifying Azure AD RBAC entries on the specific container withing the storage account.my_container
-pnoN/ASpecifies the location where to store the plan file, if not specified a plan file will be automatically created for you when you specify -a apply and will be stored in ${TF_DATA_DIR}${TF_DATA_DIR}/caf_launchpad.tfstate.tfplan
-launchpadnoN/AFlag that indicates that the current deployment is a launchpad.-launchpad
-tfcnoN/AFlag that indicates that the current deployment will use the TFC configured settings to store the state (refer to the Use TFC section of this guide)-tfc
-skip-permission-checknoN/AFlag to skip the check that the currently logged-in principal is owner of the target subscription (only checked for launchpad)-skip-permission-check
-impersonate-sp-from-keyvault-urlnoN/AFlag that indicates rover to use impersonate the Service Principal and use the credentials stored in the Azure Key Vault which URL is specified as parameter. Requires launchpad_credentials landing zone to be setup (more details to be published soon.)-impersonate-sp-from-keyvault-url https://myakv.vault.azure.net/
initnoN/AInitialize developer remote state management in azurerminit -env name -location southeastasia
init --cleannoN/ADelete the initialized remote state management in azurerminit --clean -env name -location southeastasia

Examples​

untaint​

When a resource has been marked as tainted and you want to untaint it.

# module.solution.module.storage_containers["storageWorkspace_di001"].azurerm_storage_container.stg is tainted, so must be replaced
+/- resource "azurerm_storage_container" "stg" {
      ~ has_immutability_policy = false -> (known after apply)
      ~ has_legal_hold          = false -> (known after apply)
      ~ id                      = "https://xxxxxxxxxxxxxxxx.blob.core.windows.net/di001" -> (known after apply)
      ~ metadata                = {} -> (known after apply)
        name                    = "di001"
      ~ resource_manager_id     = "/subscriptions/000000000-0000-0000-0000-000000000000/resourceGroups/cont-rg-data-landing-zone-storage-lqi/providers/Microsoft.Storage/storageAccounts/xxxxxxxxxxxxxxx/blobServices/default/containers/di001" -> (known after apply)
        # (2 unchanged attributes hidden)
    }

You need to extract the terraform resource. In our example:

module.solution.module.storage_containers["storageWorkspace_di001"].azurerm_storage_container.stg

and run the following rover command. You need to wrap the resource under double quotes and escape the quotes in the square brakets.

rover \
  --impersonate-sp-from-keyvault-url https://cont-kv-scl-xxx.vault.azure.net/ \  // Remove this line if you are not using service principals
  -lz /tf/caf/landingzones/caf_solution \
  -tfstate_subscription_id 000000000-0000-0000-0000-000000000000 \
  -target_subscription 000000000-0000-00000-00000000 \
  -tfstate data-landing-zone_prod_level3.tfstate \
  -env contoso \
  -level level3 \
  -w data-landing-zone-prod `\
  -p ${TF_DATA_DIR}/data-landing-zone_prod_level3.tfstate.tfplan \
  -a untaint "module.solution.module.storage_containers[\"storageWorkspace_di001\"].azurerm_storage_container.stg"

When executed the rover will display a similar output.

Terraform has been successfully initialized!
Terraform init return code 0
@calling other
running terraform untaint -state=/home/vscode/.terraform.cache/contoso/rover_jobs/20220316003626962686570/tfstates/level3/data-landing-zone-prod/data-landing-zone_prod_level3.tfstate  module.solution.module.storage_containers["storageWorkspace_di001"].azurerm_storage_container.stg
Resource instance module.solution.module.storage_containers["storageWorkspace_di001"].azurerm_storage_container.stg has been successfully untainted.
Terraform untaint return code: 0

Workspace management​

In the previous section, workspace is used as a argument to specify where to place the tfstate (in-lieu of the default tfstate container inside the storage account), rover workspace can be used as a command to manage workspaces:

Create a workspace:

rover workspace create application-workspace -level level1 -env contoso-sandpit

Delete a workspace:

rover workspace delete application-workspace -level level1 -env contoso-sandpit

List all workspaces for a level in an environment:

rover workspace list -level level1 -env contoso-sandpit
note

Although this is possible to create the workspace containers with rover, we recommend you create and manage them via Terraform code.