View Untagged Virtual Machines

This task reports on untagged virtual machines for a chosen subscription.

You can run this task interactively, from a schedule, or via an API call to PPA.

It requires credentials for an Azure service principal with the correct permissions.

If you choose to create a new issue in Jira for the untagged instances, it requires Jira access credentials.

Playbook Files

# The task was built to work with these plugin versions.
plugins:
  azure: ~1
  ppa: ~3
  hashicorp_vault: ~4

steps:
  - name: Check if Interactive/Scheduled/API Triggered
    actions:
      - set:
          name: headless
          value: true
        when: globals.task.trigger in ["job", "api"]

      - set:
          name: headless
          value: false
        when: globals.task.trigger == "ui"

  - name: Establish Subscription if Headless
    when: headless
    actions:
      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.azure.full }}


            ### Untagged Virtual Machines Report


            This task was started by {{ "a __schedule__" if globals.task.trigger == "job" else "an __API__ call" }}.

  - name: Introduction
    when: not headless
    actions:
      - ppa.ui.output_markdown:
          doc: >
            {{ globals.icons.azure.full }}


            ### Untagged Virtual Machines Report


            This task finds untagged virtual machines associated with an Azure subscription & displays them in a table.


            You will need to:

            - Provide Azure access credentials

            - Choose whether to create a Jira issue with the untagged VM details

            - If you choose to create a Jira issue - you will need to provide Jira access credentials

      - ppa.ui.input_accept:
          text: Start

  - name: Get Azure Secrets
    actions:
      - hashicorp_vault.key_value.read_secret_keys:
          secret: azure
          keys: []
          sensitive_keys:
            - tenant_id
            - client_id
            - client_secret
          create_missing: true
        save: azure_secrets

      - hashicorp_vault.key_value.read_secret_keys:
          secret: azure
          keys: []
          sensitive_keys:
            - subscription_id
          create_missing: true
        save: subscription

  - name: Find Untagged Virtual Machines
    actions:
      - ppa.ui.output_progress:
          text: Finding untagged VMs...
          percent: null
          element_id: finding_instances

      - azure.compute.virtual_machines.get_untagged:
        load:
          subscription_id: subscription["subscription_id"]
          azure_client: azure_secrets
        save: untagged_instances

      - eval:
          expression: len(untagged_instances)
        save: instance_count

      - ppa.ui.output_progress:
          text: Found {{ instance_count }} untagged VM(s)
          percent: 100
          element_id: finding_instances

  - name: Exit if No Instances Found
    when: instance_count == 0
    actions:
      - ppa.ui.output_info:
          text: No untagged VMs were found!

      - exit:
          exit_code: 0

  - name: Generate Report
    actions:
      - eval:
          expression: >
            [
                [
                    instance["name"],
                    instance["id"],
                ]
                for instance in untagged_instances
            ]
        save: untagged_instance_rows

      - ppa.ui.output_table:
          text: Untagged VMs
          header:
            - Name
            - ID
        load:
          rows: untagged_instance_rows

      - ppa.ui.input_confirm:
          text: Create Jira Issue?
          confirm: Yes
          cancel: No
        save: create_jira_issue
        when: not headless

      # Always create an issue if the task was started from a schedule or API call.
      - set:
          name: create_jira_issue
          value: true
        when: headless

  - name: Get Jira credentials
    when: create_jira_issue
    actions:
      - hashicorp_vault.key_value.read_secret_keys:
          secret: jira
          keys:
            - host
            - user_name
          sensitive_keys:
            - api_key
          create_missing: true
        save: jira_secrets

  - name: Get Jira details (payload)
    when: create_jira_issue and headless
    actions:
      # When run via a schedule get Jira details from payload
      - ppa.task.payload:
        save: payload

      - set:
          name: jira_project_name
          value: "{{ payload.jira_project_name }}"
        rescue:
          - ppa.ui.output_error:
              text: "Could not find 'jira_project_name' in schedule or API payload."
          - exit:
              exit_code: 1

      - set:
          name: jira_user_name
          value: "{{ payload.jira_user_name }}"
        rescue:
          - ppa.ui.output_error:
              text: "Could not find 'jira_user_name' in schedule or API payload."
          - exit:
              exit_code: 1

  - name: Get Jira details (interactive)
    when: create_jira_issue and not headless
    actions:
      - ppa.ui.input_text:
          text: Jira Project name
          required: true
        save: jira_project_name

      - ppa.ui.input_text:
          text: Jira Issue Assignee (user name)
          required: true
        save: jira_user_name

  - name: Check Jira details
    when: create_jira_issue
    actions:
      - jira.projects.get_by_name:
        load:
          access_details: jira_secrets
          name: jira_project_name
        save: jira_project
        rescue:
          - ppa.ui.output_error:
              text: "Could not find Jira project: {{ jira_project_name }}"
          - exit:
              exit_code: 1

      - jira.users.get_by_name:
        load:
          access_details: jira_secrets
          name: jira_user_name
        save: jira_user
        rescue:
          - ppa.ui.output_error:
              text: "Could not find Jira user: {{ jira_user_name }}"
          - exit:
              exit_code: 1

  - name: Create Jira Issue
    when: create_jira_issue
    actions:
      - jira.issues.create_issue:
          summary: Untagged Virtual Machines in Azure
          description: >
            The following Azure Virtual Machines are not tagged:
            {{ untagged_instances|join(', ', attribute='name') }}
          issue_type: Bug
        load:
          project_key: jira_project["key"]
          access_details: jira_secrets
        save: jira_issue

      - ppa.ui.output_info:
          text: "Successfully created Jira issue: {{ jira_issue['id'] }}"

  - name: Assign Jira Issue
    when: create_jira_issue
    actions:
      - jira.issues.assign_issue:
        load:
          issue_id: jira_issue["id"]
          user_name: jira_user_name
          access_details: jira_secrets
        save: jira_issue

      - ppa.ui.output_info:
          text: "Successfully assigned Jira issue to {{ jira_user_name }}"

Running this Playbook

Click download playbook
Import the downloaded file via the Playbooks page on PPA
Build the playbook from the Edit & Build tab
Run the playbook from the Preview & Deploy tab

* Requires PPA v2.9.x or newer

Integrations

PPA User Interface & Events
Hashicorp Vault Key-Value engine
Azure Compute Virtual Machines
Atlassian Jira Issues

Required PPA Configuration

If you run start this task from a schedule or API call, a new issue will be created in Jira with details of the untagged instances.

When started interactively the user will have the choice to create a new issue in Jira.

Required Vault Details

Azure

Tenant ID
Client ID
Client Secret
Subscription ID

The service principal must have permissions to read virtual machine details.

Jira
(optional)

Host
Username
API key

Vault Configuration Wizard

The first time you run a task built from this playbook, PPA will check the required Vault details exist.

If they don't exist, PPA will ask you to supply the details at the start of the task.

Below you can see a user providing details the first time they run an Active Directory task.

vault-config-wizard

Once the details are added to Vault, the task won't ask for them again.

If you don't know the required details, ask an administrator to run the task or configure Vault manually.

API/Schedule Payload

To run this task from a schedule or API call, you'll need to supply a Jira project name and Jira user name in the task payload.

The payload should be in this format:

{ "jira_project_name": "your_project_name", "jira_user_name": "your_user_name" }

You can use the example payload above as a template.

What the Task Does

Interactive

When run interactively this task will:

Find all untagged virtual machines
Display them in a table
Ask the user whether to create a new Jira issue
Ask the user to provide a Jira project name and Jira user to assign the issue to

Schedule/API

When started from a schedule or API call, this task will:

Find all untagged virtual machines
Display them in a table
Create an issue in Jira with details of the untagged VMs (using Jira project details provided in the payload)

See our other playbooks

Get PPA for free!

Start automating your estate with a free 30 day trial today. No signup required!

Get PPA Express

Documentation

Installation Guide
See how easy it is to get started with our installation guide
Playbooks
View our task writing reference guide
Plugins
See how to integrate with different systems using our plugins reference guide.