Version: 2203.1

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.

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:

argument	required	default value	Description	Example
-lz	yes	N/A	Path 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-folder	yes	N/A	Path to the set of configuration files. All `.tfvars` files in directory will be expanded.	/tf/caf/configuration/contoso/platform/level0/launchpad
-env	yes	N/A	String that defines a name for an environment to use. This is defined as (used in the state locator function as described below.)	`contoso`
-level	yes	N/A	Specifies the level in the CAF hierarchy where to deploy the resources (possible value are level1-level4)	`level1`
-a	yes	N/A	Action 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-severity	no	ERROR	Specifies the Terraform log verbosity this sets the `TF_IN_AUTOMATION` parameters, possible options are: `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR`	`ERROR`
-tfstate_subscription_id	no	If 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_subscription	no	If 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`
-workspace	no	`tfstate`	Specifies 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`
-p	no	N/A	Specifies 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
-launchpad	no	N/A	Flag that indicates that the current deployment is a launchpad.	`-launchpad`
-tfc	no	N/A	Flag 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-check	no	N/A	Flag 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-url	no	N/A	Flag 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/`

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.

Rover commands

Commonly used commands​

Login​

Landing zones commands​

Examples​

untaint​

Workspace management​

Commonly used commands

Login

Landing zones commands

Examples

untaint

Workspace management