Edit

Use Docker to run PowerShell for Azure Stack Hub

  • Article

Caution

This article references CentOS, a Linux distribution that is nearing End Of Life (EOL) status. Please consider your use and plan accordingly. For more information, see the CentOS End Of Life guidance.

In this article, you can use Docker to create a container on which to run the version of PowerShell that's required for working with the various interfaces. You can find instructions for using both AzureRM modules and the latest Az modules. AzureRM requires a Windows-based container. Az uses a Linux-based container.

Docker prerequisites

Install Docker

  1. Install Docker.

  2. In a command-line program, such as PowerShell or Bash, enter:

    docker --version

Set up a service principal for using PowerShell

To use PowerShell to access resources in Azure Stack Hub, you need a service principal in your Microsoft Entra tenant. You delegate permissions with user role-based access control (RBAC). You may need to request the service principal from your cloud operator.

  1. To set up your service principal, follow the instructions in Give applications access to Azure Stack Hub resources by creating service principals.

  2. Note the application ID, the secret, your tenant ID, and object ID for later use.

Run PowerShell in Docker

In these instructions, you will run a Linux-based container image that contains the PowerShell and the required modules for Azure Stack Hub.

  1. You need to run Docker by using Linux container. When you run Docker, switch to Linux containers.

  2. Run Docker from a machine that's joined to the same domain as Azure Stack Hub. If you are using the Azure Stack Development Kit (ASDK), you need to install the VPN on your remote machine.

Install Azure Stack Hub Az module on a Linux container

  1. From your command line, run the following Docker command to run PowerShell in an Ubuntu container:

    docker run -it mcr.microsoft.com/azurestack/powershell

    You can run Ubuntu, Debian, or Centos. You can find the following Docker files in the GitHub repository, azurestack-powershell. Refer to the GitHub repository for the latest changes to the Docker files. Each OS is tagged. Replace the tag, the section after the colon, with the tag for the desired OS.

    Linux Docker image
    Ubuntu docker run -it mcr.microsoft.com/azurestack/powershell:ubuntu-18.04
    Debian docker run -it mcr.microsoft.com/azurestack/powershell:debian-9
    Centos docker run -it mcr.microsoft.com/azurestack/powershell:centos-7

  2. The shell is ready for your cmdlets. Test your shell connectivity by signing in and then running Test-AzureStack.ps1.

    First, create your service principal credentials. You will need the secret and application ID. You will also need the object ID when running the Test-AzureStack.ps1 to check your container. You may need to request a service principal from your cloud operator.

    Type the following cmdlets to create a service principle object:

    $passwd = ConvertTo-SecureString <Secret> -AsPlainText -Force
$pscredential = New-Object System.Management.Automation.PSCredential('<ApplicationID>', $passwd)

  3. Connect to your environment by running the following script with the following values from your Azure Stack Hub instance.

    Value Description
    The name of the environment. The name of your Azure Stack Hub environment.
    Resource Manager Endpoint The URL for the Resource Manager. Contact your cloud operator if you don't know it. It will look something like https://management.region.domain.com.
    Directory Tenant ID The ID of your Azure Stack Hub tenant directory.
    Credential An object containing your service principal. In this case $pscredential. 
    ./Login-Environment.ps1 -Name <String> -ResourceManagerEndpoint <resource manager endpoint> -DirectoryTenantId <String> -Credential $pscredential

    PowerShell returns your account object.

  4. Test your environment by running the Test-AzureStack.ps1 script in the container. Specify the service principal object ID. If you do not indicate the object ID, the script will still run but it will just test tenant (user) modules and fail on modules that require administrator privileges.

    ./Test-AzureStack.ps1 <Object ID>

Next steps