Skip to content

Commit b1eebfc

Browse files
author
Stephen Tramer
committed
Add AzPS files from the preview branch
1 parent 5a8c522 commit b1eebfc

File tree

4 files changed

+354
-0
lines changed

4 files changed

+354
-0
lines changed

‎docs-conceptual/azurermps-6.11.0/install-az-ps.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Install Azure PowerShell with PowerShellGet
3+
description: How to install Azure PowerShell with PowerShellGet
4+
author: sptramer
5+
ms.author: sttramer
6+
manager: carmonm
7+
ms.devlang: powershell
8+
ms.topic: conceptual
9+
ms.date: 10/29/2018
10+
---
11+
12+
# Install Azure PowerShell with PowerShellGet
13+
14+
This article explains the steps to install the Azure PowerShell modules using PowerShellGet. For the preview release of Az,
15+
no other install methods are supported.
16+
17+
## Requirements
18+
19+
Azure PowerShell works with either PowerShell 5.x on Windows, or PowerShell 6.x on any platform. To check the version of PowerShell running
20+
on your machine, run the following command:
21+
22+
```powershell-interactive
23+
$PSVersionTable.PSVersion
24+
```
25+
26+
If you have an outdated version or need to install PowerShell, see [Installing various versions of PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/setup/installing-powershell?view=powershell-6) and click on the link for
27+
your platform.
28+
29+
## Install the Azure PowerShell module
30+
31+
> [!IMPORTANT]
32+
>
33+
> It's not possible to have both the `AzureRM` and `Az` modules installed on a system at the same time. In order to install
34+
> the `Az` module, `AzureRM` must be uninstalled. For instructions on how to do that, see
35+
> [Uninstall the Azure PowerShell module (AzureRM)](/powershell/azure/uninstall-azurerm-ps?view=azurermps-6.11.0).
36+
37+
To install modules at a global scope, you need elevated privileges to install modules from the PowerShell Gallery. To install Azure PowerShell,
38+
run the following command in an elevated session ("Run as Administrator" on Windows, or with superuser privileges on macOS or Linux):
39+
40+
```powershell-interactive
41+
Install-Module -Name Az -AllowClobber
42+
```
43+
44+
If you don't have access to administrator privileges, you can install for the current user by adding the `-Scope` argument.
45+
46+
```powershell-interactive
47+
Install-Module -Name Az -AllowClobber -Scope CurrentUser
48+
```
49+
50+
By default, the PowerShell gallery isn't configured as a trusted repository for PowerShellGet. The
51+
first time you use the PSGallery you see the following prompt:
52+
53+
```output
54+
Untrusted repository
55+
56+
You are installing the modules from an untrusted repository. If you trust this repository, change
57+
its InstallationPolicy value by running the Set-PSRepository cmdlet.
58+
59+
Are you sure you want to install the modules from 'PSGallery'?
60+
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"):
61+
```
62+
63+
Answer `Yes` or `Yes to All` to continue with the installation.
64+
65+
The `Az` module is a rollup module for the Azure PowerShell cmdlets. Installing it downloads all of
66+
the available Azure Resource Manager modules, and makes their cmdlets available for use.
67+
68+
## Sign in
69+
70+
To start working with Azure PowerShell, you need to load `Az` into your current PowerShell session
71+
with the [Import-Module](/powershell/module/Microsoft.PowerShell.Core/Import-Module) cmdlet, and then sign in
72+
with your Azure credentials.
73+
74+
```powershell-interactive
75+
# Import the module into the PowerShell session
76+
Import-Module Az
77+
# Connect to Azure with a browser sign in token
78+
Connect-AzAccount
79+
```
80+
81+
You'll need to repeat these steps for every new PowerShell session you start. Automatically importing the `Az` module requires
82+
setting up a PowerShell profile, which you can learn about in [About Profiles](/powershell/module/microsoft.powershell.core/about/about_profiles).
83+
To learn how to persist your Azure sign-in across sessions, see [Persist user credentials across PowerShell sessions](context-persistence.md).
84+
85+
## Update the Azure PowerShell module
86+
87+
You can update your Azure PowerShell installation by running [Update-Module](/powershell/module/powershellget/update-module). This command does __not__ uninstall earlier versions.
88+
89+
```powershell-interactive
90+
Update-Module -Name Az
91+
```
92+
93+
If you want to remove older versions of Azure PowerShell from your system, see [Uninstall the Azure PowerShell module](uninstall-az-ps.md).
94+
95+
## Use multiple versions of Azure PowerShell
96+
97+
It's possible to install more than one version of Azure PowerShell. To check if you have multiple versions of Azure PowerShell installed, use the following
98+
command:
99+
100+
```powershell-interactive
101+
Get-Module -Name Az -List | select Name,Version
102+
```
103+
104+
To remove a version of Azure PowerShell, see [Uninstall the Azure PowerShell module](uninstall-az-ps.md).
105+
106+
You can load a specific version of the `Az` module by providing the `-RequiredVersion` argument to `Install-Module` or `Import-Module`:
107+
108+
```powershell-interactive
109+
Install-Module -Name Az -RequiredVersion 0.4.0
110+
Import-Module -Name Az -RequiredVersion 0.4.0
111+
```
112+
113+
If you have more than one version of the module installed, the latest version is loaded by default when importing.
114+
115+
## Provide feedback
116+
117+
If you find a bug when using Azure Powershell, [file an issue on GitHub](https://github.com/Azure/azure-powershell/issues).
118+
To provide feedback from the command line, use the [Send-Feedback](/powershell/module/az.profile/send-feedback) cmdlet.
119+
120+
## Next Steps
121+
122+
To get started using Azure PowerShell, see [Get Started with Azure PowerShell](get-started-azureps.md) to learn more about the module and its features.

‎docs-conceptual/azurermps-6.11.0/migrate-from-azurerm-to-az.md

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: Migrate Azure PowerShell scripts from AzureRM to Az
3+
description: Learn the steps and tools for migrating scripts from the AzureRM module to the new Az module.
4+
author: sptramer
5+
ms.author: sttramer
6+
manager: carmonm
7+
ms.devlang: powershell
8+
ms.topic: conceptual
9+
ms.date: 11/01/2018
10+
---
11+
12+
# Migrate from AzureRM to Azure PowerShell Az
13+
14+
With the introduction of the Az module, older scripts which use the AzureRM modules and cmdlets no
15+
longer work automatically. No migration that changes command names is ever convenient or easy to
16+
handle. In order to help with the process of changing all your scripts over from AzureRM to Az,
17+
this article will outline steps, tools, and scripts that you can take advantage of to automate
18+
the process of migrating to Az as easy as possible.
19+
20+
Each section of this article outlines a step in the process, and it's recommended that you follow
21+
them in order unless you've already completed the process outlined in a single step.
22+
23+
## Ensure your existing scripts work with the latest AzureRM release
24+
25+
This is the most important step! Run your existing scripts, and make sure that they work with the
26+
_latest_ release of AzureRM (__6.11.0__). If your scripts do not work, make sure to go through and read
27+
the [AzureRM migration guide](/powershell/azure/migration-guide.6.0.0).
28+
29+
## Install the Azure PowerShell Az module
30+
31+
The first step is to install the Az module on your platform. This _does_ require uninstalling
32+
the AzureRM module, but the following steps will outline how you can get compatibility with the old
33+
command set until your migration is completed.
34+
35+
To install the Azure PowerShell Az module, follow these steps:
36+
37+
* [Uninstall the AzureRM module](/powershell/azure/uninstall-azurerm-ps?view=azurermps-6.11.0). Make sure that
38+
you remove _all_ installed versions of AzureRM, not just the most recent version.
39+
* [Install the Az module](install-az-ps.md)
40+
41+
## <a name="aliases"/>Enable AzureRM alias mode
42+
43+
With AzureRM uninstalled and your scripts working with the latest AzureRM version, now is the time to
44+
enable the compatibility mode for the Az module. This is done with the command
45+
46+
```powershell-interactive
47+
Enable-AzureRmAlias -Scope CurrentUser
48+
```
49+
50+
This enables the ability to use old cmdlet names with the `Az` module installed, through aliases. These
51+
aliases are written to the user profile for the selected scope. If no user profile exists, one is created.
52+
53+
> [!WARNING]
54+
>
55+
> You can use a different `-Scope` for this command, but it's not recommended! Because the aliases are written to
56+
> the user profile for the selected scope, keep enabling them to as limited a scope as possible. Enabling aliases
57+
> system-wide could also cause issues for other users which have AzureRM installed in their local scope.
58+
59+
Once the alias mode is enabled, run your scripts again to confirm that they still function as expected.
60+
61+
## Change module imports and cmdlet names
62+
63+
In general, the module names have been changed so that `AzureRM` becomes `Az`, and the same for cmdlets.
64+
For example, the `AzureRM.Compute` module has been renamed to `Az.Compute`. `New-AzureRmVM` has become `New-AzVM`.
65+
There are some exceptions to this naming change that you should be aware of before doing any renaming:
66+
67+
| AzureRM module | Az module |
68+
|----------------|-----------|
69+
| Azure.Storage | Az.Storage |
70+
| Azure.AnalysisServices | Az.AnalysisServices |
71+
| AzureRM.DataFactories | Az.DataFactory |
72+
| AzureRM.DataFactoryV2 | Az.DataFactory |
73+
| AzureRM.RecoveryServices.Backup | Az.RecoveryServices |
74+
| AzureRM.RecoveryServices.SiteRecovery | Az.RecoveryServices |
75+
76+
In the case of `Azure.Storage` and `Azure.AnalysisServices`, the associated cmdlets have also been renamed
77+
so that `Azure` is replaced with `Az`. For example, `Get-AzureStorageBlob` has been renamed to `Get-AzStorageBlob`.
78+
79+
To help with the renaming of modules and cmdlets in your scripts, you can use the following PowerShell script
80+
to automate most of the work. You will still need to make sure that the script runs at the end of the edits,
81+
but the number of changes you have to make on your own will hopefully be much fewer!
82+
83+
```powershell-interactive
84+
function Update-AzureRmScript {
85+
param(
86+
[Parameter(mandatory=$true)]
87+
[string]$File
88+
)
89+
90+
$replacements = @(
91+
@{
92+
"name"="Azure.Storage"
93+
"module"="Az.Storage"
94+
},
95+
@{
96+
"name"="Azure.AnalysisServices"
97+
"module"="Az.AnalysisServices"
98+
},
99+
@{
100+
"name"="AzureRM.DataFactories"
101+
"module"="Az.DataFactory"
102+
"moduleOnly"=$true
103+
},
104+
@{
105+
"name"="AzureRM.DataFactoryV2"
106+
"module"="Az.DataFactory"
107+
"moduleOnly"=$true
108+
},
109+
@{
110+
"name"="AzureRM.RecoveryServices.Backup"
111+
"module"="Az.RecoveryServices"
112+
"moduleOnly"=$true
113+
},
114+
@{
115+
"name"="AzureRM.RecoveryServices.SiteRecovery"
116+
"module"="Az.RecoveryServices"
117+
"moduleOnly"=$true
118+
}
119+
)
120+
121+
echo "Updating $File..."
122+
$content = Get-Content $file
123+
for ($i=0; $i -lt $content.Length; $i++) {
124+
$line = $content[$i]
125+
if ($line -match "^\s*Import-Module.+(AzureRm)") {
126+
$content[$i] = $line -replace $matches[1],"Az"
127+
}
128+
elseif ($line -match "[A-Za-z]+-(AzureRm)") {
129+
$content[$i] = $line -replace $matches[1],"Az"
130+
}
131+
else {
132+
foreach ($module in $renames) {
133+
if ($line -match "^\s*Import-Module.+($($module.Name))") {
134+
$content[$i] = $line -replace $matches[1],$module.Module
135+
}
136+
elseif ((-not $module.moduleOnly) -and ($line -match "[A-Za-z]+-($($module.Module))")) {
137+
$content[$i] = $line -replace $matches[1],$module.Module
138+
}
139+
}
140+
}
141+
}
142+
Set-Content -Path $file -Value $content -Force
143+
}
144+
```
145+
146+
> [!IMPORTANT]
147+
>
148+
> If you used `AzureRM` as part of any of your function names in your script, those commands will be renamed to
149+
> use `Az` instead. As long as you also update all scripts which call these functions, that shouldn't
150+
> cause a problem. Just be aware that this script __will__ change all function and command names
151+
> containing `AzureRM`.
152+
153+
## Disable AzureRM aliases
154+
155+
When you've completed your script migration and no longer need AzureRM compatibility, you should disable the cmdlet
156+
aliases. This is done with the `Disable-AzureRmAlias` command:
157+
158+
```powershell-interactive
159+
Disable-AzureRmAlias -Scope CurrentUser
160+
```
161+
162+
If you provided a different value for `-Scope` when enabling aliases, make sure that you use it here as well.
163+
164+
## Summary
165+
166+
By following these steps, you can update all of your existing scripts to use the new module without a lot of pain or difficulty. If you have any questions or encountered problems with these steps that made your migration difficult, please feel free to comment on this article so that we can improve the instructions.

‎docs-conceptual/azurermps-6.11.0/new-azureps-module-az.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Introducing the Azure PowerShell Az module
3+
description: Introducing the new Azure PowerShell module Az, the replacement for the AzureRM module.
4+
ms.date: 10/22/2018
5+
author: sptramer
6+
ms.author: sttramer
7+
ms.manager: carmonm
8+
ms.devlang: powershell
9+
ms.topic: conceptual
10+
---
11+
# Introducing the new Azure PowerShell Az module
12+
13+
Starting in November 2018, the Azure PowerShell `Az` module is available for full public preview.
14+
This module is an improvement in the stability and portability of the old `AzureRM` module. It
15+
offers feature parity and an easy migration path through familiar, but shorter, cmdlet names.
16+
17+
`Az` is built on the .NET Standard library, which means that it runs under both PowerShell 5.x on
18+
Windows and PowerShell Core on any platform. Using .NET Standard allows us to unify the code base of Azure
19+
PowerShell with minimal impact on users.
20+
21+
This is a new module, so the version has been reset. The first stable release will be 1.0.
22+
23+
## Upgrade to Az
24+
25+
All users should upgrade to the new `Az` module. To do so:
26+
27+
* [Uninstall the Azure PowerShell AzureRM module](/powershell/azure/uninstall-azurerm-ps?view=azurermps-6.11.0)
28+
* [Install the Azure PowerShell Az module](/powershell/azure/install-azurerm-ps?view=azureazps-0.5.0)
29+
* Migrate existing `AzureRM` scripts to the new `Az` command syntax.
30+
31+
## Migrate existing scripts to Az
32+
33+
Major updates like this can be inconvenient. However, the `Az` module has a compatibility mode to
34+
help you use existing scripts while you work on updates to the new syntax. Use the
35+
`Enable-AzAlias` cmdlet to enable the `AzureRM` compatibility mode. This cmdlet defines
36+
`AzureRM` cmdlet names as aliases for the new `Az` cmdlet names.
37+
38+
For a full description of the migration process, including an example, see [__TBD__](link-tbd.md).
39+
40+
## The future of support for AzureRM
41+
42+
The existing `AzureRM` module enters maintenance mode when `Az` version 1.0 is released. After this
43+
release, the `AzureRM` module will continue to receive important bug fixes. New features will only
44+
be added to the `Az` module. To keep up with the latest Azure services and features, you must
45+
switch to the `Az` module.

‎docs-conceptual/include/az-replacing-azurerm.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
author: sptramer
3+
ms.author: sttramer
4+
ms.date: 10/22/2018
5+
ms.topic: include
6+
ms.prod: azureps
7+
---
8+
9+
> [!NOTE]
10+
> The `AzureRM` module is going into maintenance mode at the end of 2018, to be replaced with the new `Az` module. This module
11+
> has a backwards compatibility mode with `AzureRM`, and is designed to make migrating existing scripts easy. To learn more
12+
> about this new module and how to upgrade, see:
13+
>
14+
> * [Introducing the Azure PowerShell Az module](/powershell/azure/preview/new-azureps-module-az)
15+
> * [Install Azure PowerShell Az module](/powershell/azure/preview/install-azureps-az)
16+
> * [Migrate to the new Azure PowerShell Az module](__TBD__)
17+
>
18+
> If you have deployments that use the classic deployment model that cannot be converted,
19+
> you can install the Service Management version of Azure PowerShell. For more information, see
20+
> [Install the Azure PowerShell Service Management module](/powershell/azure/servicemanagement/install-azure-ps).
21+

0 commit comments

Comments
 (0)