20231114 powershell

Author: WilliamDAssafMSFT

azure-sql/database/elastic-jobs-overview.md

@@ -4,7 +4,7 @@ description: "Learn about how you can use elastic jobs to run Transact-SQL (T-SQ
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: srinia
-ms.date: 11/06/2023
+ms.date: 11/13/2023
 ms.service: sql-database
 ms.subservice: elastic-jobs
 ms.topic: overview
@@ -171,6 +171,7 @@ For more information on UMI in Azure SQL Database, see [Managed identities for A
 
 > [!IMPORTANT]
 > When using Microsoft Entra ID authentication, create your `jobuser` user from that Microsoft Entra ID in every target database. Grant that user the permissions needed to execute your job(s) in each target database.
+
 Using a system-assigned managed identity (SMI) is not supported.
 
 ### Authentication via database-scoped credentials
@@ -222,6 +223,9 @@ During job agent creation, a schema, tables, and a role called *jobs_reader* are
 |---------|---------|---------|
 |**jobs_reader** | SELECT | None |
 
+> [!CAUTION]
+> You should not update internal catalog views in the *job database*, such as [jobs.target_group_members](/sql/relational-databases/system-catalog-views/jobs-target-group-members-elastic-jobs-transact-sql?view=azuresqldb-current&preserve-view=true). Manually changing these catalog views can corrupt the *job database* and cause failure. These views are for read-only querying only. You can use the stored procedures on your *job database* to add/delete target groups/members, such as [jobs.sp_add_target_group_member](/sql/relational-databases/system-stored-procedures/sp-add-target-group-member-elastic-jobs-transact-sql?view=azuresqldb-current&preserve-view=true).
+
 > [!IMPORTANT]
 > Consider the security implications before granting any elevated access to the *job database*. A malicious user with permissions to create or edit jobs could create or edit a job that uses a stored credential to connect to a database under the malicious user's control, which could allow the malicious user to determine the credential's password or execute malicious commands.
 
@@ -278,7 +282,7 @@ Most environments require less than 100 concurrent jobs at any time, so JA100 is
 
 Exceeding the job agent's concurrency capacity tier with job targets will create queuing delays for some target databases/servers. For example, if you start a job with 110 target in the JA100 tier, 10 jobs will wait to start until others finish.
 
-The tier or service objective of an elastic job agent can be modified through the Azure portal, [PowerShell](/powershell/module/az.sql/set-azsqlelasticjobagent), or [the Job Agents REST API](/rest/api/sql/2021-02-01-preview/job-agents). <!-- TODO update /2021-02-01/ when available --> For an example, see [Scale the job agent](elastic-jobs-tutorial.md#scale-the-job-agent).
+The tier or service objective of an elastic job agent can be modified through the Azure portal, [PowerShell](/powershell/module/az.sql/set-azsqlelasticjobagent), or [the Job Agents REST API](/rest/api/sql/job-agents). For an example, see [Scale the job agent](elastic-jobs-tutorial.md#scale-the-job-agent).
 
 ### Limit job impact on elastic pools
 

azure-sql/database/elastic-jobs-powershell-create.md

@@ -4,7 +4,7 @@ description: Learn how to create an elastic job agent and run scripts across man
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: srinia
-ms.date: 11/02/2023
+ms.date: 11/14/2023
 ms.service: sql-database
 ms.subservice: elastic-jobs
 ms.topic: tutorial
@@ -35,6 +35,8 @@ In this end-to-end tutorial, you learn the steps required to run a query across
 
 Elastic database jobs have a set of PowerShell cmdlets.
 
+These cmdlets were updated in November 2023.
+
 ### Install the latest elastic jobs cmdlets
 
 If you don't have an Azure subscription, [create a free account](https://azure.microsoft.com/free/) before you begin.
@@ -169,28 +171,85 @@ An elastic job agent is an Azure resource for creating, running, and managing jo
 
 The [New-AzSqlElasticJobAgent](/powershell/module/az.sql/new-azsqlelasticjobagent) cmdlet requires a database in Azure SQL Database to already exist, so the `resourceGroupName`, `serverName`, and `databaseName` parameters must all point to existing resources. Similarly, [Set-AzSqlElasticJobAgent](/powershell/module/az.sql/set-azsqlelasticjobagent) can be used to modify the elastic job agent.
 
+To create a new elastic job agent using Microsoft Entra authentication with a user-assigned managed identity, use the `IdentityType` and `IdentityID` arguments of `New-AzSqlElasticJobAgent`:
+
 ```powershell
 Write-Output "Creating job agent..."
 $agentName = Read-Host "Please enter a name for your new elastic job agent"
 $parameters = @{
     Name = $agentName 
+    IdentityType = "UserAssigned" 
+    IdentityID = "/subscriptions/abcd1234-caaf-4ba9-875d-f1234/resourceGroups/contoso-jobDemoRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-UMI"
 }
 $jobAgent = $jobDatabase | New-AzSqlElasticJobAgent @parameters
 $jobAgent
 ```
 
+To create a new elastic job agent using database-scoped credentials, `IdentityType` and `IdentityID` are not provided.
+
 ## Create the job authentication
 
 The elastic job agent must be able to authenticate to each target server or database.
 
 As covered in [Create job agent authentication](elastic-jobs-tutorial.md#create-job-agent-authentication):
 
-- Use database users mapped to user-assigned managed identity (UMI) to authenticate to target server(s)/database(s).
-    - Using a UMI with Microsoft Entra authentication (formerly Azure Active Directory) is the recommended method.
-    - Using PowerShell cmdlets to configure Microsoft Entra authentication is currently not supported. See [Create and manage elastic jobs by using T-SQL (preview)](elastic-jobs-tsql-create-manage.md).
+- Use database users mapped to [user-assigned managed identity (UMI) to authenticate to target server(s)/database(s)](#use-microsoft-entra-authentication-with-a-umi-for-authentication-to-targets).
+    - Using a UMI with Microsoft Entra authentication (formerly Azure Active Directory) is the recommended method. PowerShell cmdlets now have new arguments to support Microsoft Entra authentication with a UMI.
+    - This is the recommended authentication method.
 - Use database users mapped to [database-scoped credentials](#create-the-job-credentials) in each database.
     - Previously, database-scoped credentials were the only option for the elastic job agent to authenticate to targets.
 
+### Use Microsoft Entra authentication with a UMI for authentication to targets
+
+To use the recommended method of Microsoft Entra (formerly Azure Active Directory) authentication to a user-assigned managed identity (UMI), follow these steps. The elastic job agent connects to the desired target logical server(s)/databases(s) via Entra authentication.
+
+In addition to the login and database users, note the addition of the `GRANT` commands in the following script. These permissions are required for the script we chose for this example job. Your jobs may require different permissions. Because the example creates a new table in the targeted databases, the database user in each target database needs the proper permissions to successfully run.
+
+In each of the target server(s)/database(s), create a contained user mapped to the UMI.
+
+- If the elastic job has logical server or pool targets, you must create the contained user mapped to the UMI in the `master` database of the target logical server.
+- For example, to create a contained database login in the `master` database, and a user in the user database, based on the user-assigned managed identity (UMI) named `job-agent-UMI`:
+
+```powershell
+$targetServer = '<target server name>'
+$adminLogin = '<username>'
+$adminPassword = '<password>'
+
+# For the target logical server, in the master database
+# Create the login named [job-agent-UMI] based on the UMI [job-agent-UMI], and a user
+$params = @{
+  'database' = 'master'
+  'serverInstance' =  $targetServer.ServerName + '.database.windows.net'
+  'username' = $adminLogin
+  'password' = $adminPassword
+  'outputSqlErrors' = $true
+  'query' = 'CREATE LOGIN [job-agent-UMI] FROM EXTERNAL PROVIDER;'
+}
+Invoke-SqlCmd @params
+$params.query = "CREATE USER [job-agent-UMI] FROM LOGIN [job-agent-UMI]"
+Invoke-SqlCmd @params
+
+# For each target database in the target logical server
+# Create a database user from the job-agent-UMI login 
+$targetDatabases = @( $db1.DatabaseName, $Db2.DatabaseName )
+$createJobUserScript =  "CREATE USER [job-agent-UMI] FROM LOGIN [job-agent-UMI]"
+
+# Grant permissions as necessary. For example ALTER and CREATE TABLE:
+$grantAlterSchemaScript = "GRANT ALTER ON SCHEMA::dbo TO [job-agent-UMI]" 
+$grantCreateScript = "GRANT CREATE TABLE TO [job-agent-UMI]"
+
+$targetDatabases | % {
+  $params.database = $_
+  $params.query = $createJobUserScript
+  Invoke-SqlCmd @params
+  $params.query = $grantAlterSchemaScript
+  Invoke-SqlCmd @params
+  $params.query = $grantCreateScript
+  Invoke-SqlCmd @params
+}
+```
+
+
 ### <a id="create-the-job-credentials"></a> Use database-scoped credentials for authentication to targets
 
 Job agents use credentials specified by the target group upon execution and execute scripts. These database-scoped credentials are also used to connect to the `master` database to discover all the databases in a server or an elastic pool, when either of these are used as the target group member type.

azure-sql/database/elastic-jobs-tsql-create-manage.md

@@ -4,7 +4,7 @@ description: Learn how to create an elastic job agent and run scripts across man
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: srinia
-ms.date: 11/06/2023
+ms.date: 11/13/2023
 ms.service: sql-database
 ms.subservice: elastic-jobs
 ms.topic: how-to
@@ -235,6 +235,8 @@ SELECT * FROM jobs.target_group_members WHERE target_group_name = N'PoolGroup';
 
 With T-SQL, create jobs using system stored procedures in the jobs database: [jobs.sp_add_job](/sql/relational-databases/system-stored-procedures/sp-add-job-elastic-jobs-transact-sql?view=azuresql-db&preserve-view=true) and [jobs.sp_add_jobstep](/sql/relational-databases/system-stored-procedures/sp-add-jobstep-elastic-jobs-transact-sql?view=azuresql-db&preserve-view=true). The T-SQL commands are syntax are similar to the steps needed to create SQL Agent jobs and job steps in SQL Server.
 
+You should not update internal catalog views in the *job database*. Manually changing these catalog views can corrupt the *job database* and cause failure. These views are for read-only querying only. You can use the stored procedures in the `jobs` schema on your *job database*.
+
 - When using Microsoft Entra authentication for a Microsoft Entra ID or user-assigned managed identity to authenticate to target server(s)/database(s), the *@credential_name* argument shouldn't be provided for `sp_add_jobstep` or `sp_update_jobstep`. Similarly, omit the optional *@output_credential_name* and *@refresh_credential_name* arguments.
 - When using database-scoped credentials to authenticate to target server(s)/database(s), the *@credential_name* parameter is required for `sp_add_jobstep` and `sp_update_jobstep`.
     - For example, `@credential_name = 'job_credential'`.

azure-sql/database/elastic-jobs-tutorial.md

@@ -4,7 +4,7 @@ description: "Learn how to create, configure, and manage elastic jobs to run Tra
 author: WilliamDAssafMSFT
 ms.author: wiassaf
 ms.reviewer: srinia
-ms.date: 11/02/2023
+ms.date: 11/14/2023
 ms.service: sql-database
 ms.subservice: elastic-jobs
 ms.topic: how-to
@@ -21,7 +21,7 @@ This article provides the steps required to create, configure, and manage elasti
 
 ## Create and configure the elastic job agent
 
-1. Create or identify an empty S1 or higher Azure SQL Database. This database should be in the same server as the job agent. This database is used as the *job database* during elastic job agent creation. You can [create a single database](single-database-create-quickstart.md?view=azuresql-db&preserve-view=true) via the Azure portal, Azure CLI, Azure CLI (sql up), or PowerShell.
+1. Create or identify an empty S1 or higher Azure SQL Database, using the DTU purchase model. This database should be in the same server as the job agent. This database is used as the *job database* during elastic job agent creation. You can [create a single database](single-database-create-quickstart.md?view=azuresql-db&preserve-view=true) via the Azure portal, Azure CLI, Azure CLI (sql up), or PowerShell.
 1. Create an **elastic job agent** in the Azure portal or with [PowerShell](elastic-jobs-powershell-create.md#create-the-elastic-job-agent).
 
     The instructions to create an elastic job agent in the Azure portal are as follows:
@@ -62,9 +62,18 @@ Use [Microsoft Entra (formerly Azure Active Directory)](authentication-aad-overv
     - [A new UMI can be created](/azure/active-directory/managed-identities-azure-resources/how-manage-user-assigned-managed-identities) through the Azure portal, Azure CLI, PowerShell, Resource Manager, or REST API.
 1. Assign the UMI to the created elastic job agent.
     - It's recommended to assign a UMI when creating the elastic job agent, see the steps in [Create and configure the elastic job agent](#create-and-configure-the-elastic-job-agent). When creating a job agent in the Azure portal, in the **Identity** tab, assign to the elastic job agent.
-    - Currently in the Elastic Jobs preview, you cannot use PowerShell cmdlets to create or modify elastic job agents to use Microsoft Entra authentication with a UMI.
     - To update an existing elastic job agent to use a UMI, on the Azure portal page for the **elastic job agent**, navigate to **Identity** under the **Security** menu in the resource menu. Select and assign the UMI to the elastic job agent.
-    - The [REST API can also be used to create or update the elastic job agent](/rest/api/sql/2021-02-01-preview/job-agents/create-or-update?tabs=HTTP). <!-- TODO update /2021-02-01/ when available -->
+    - When creating or updating an elastic job agent with the `New-AzSqlElasticJobAgent` or `Set-AzSqlElasticJobAgent` PowerShell cmdlets, use the parameters: `-IdentityType UserAssigned -IdentityID <identity resource path>`. For example:
+        ```powershell
+        $parameters = @{
+            Name = '<job agent name>'
+            ResourceGroupName = '<Resource_Group_Name>'
+            IdentityType = 'UserAssigned'
+            IdentityID = '/subscriptions/fa58cf66-caaf-4ba9-875d-f1234/resourceGroups/<resource group name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<UMI name here>'
+        }
+        Set-AzSqlElasticJobAgent @parameters
+        ```
+    - The [REST API can also be used to create or update the elastic job agent](/rest/api/sql/job-agents/create-or-update). 
 1. Create a target group and add targets for the jobs. [Define the target group and targets (the databases you want to run the job against) using PowerShell](elastic-jobs-powershell-create.md#define-target-servers-and-databases) or [define the target group and targets using T-SQL](elastic-jobs-tsql-create-manage.md#define-target-servers-and-databases).
 1. In each of the target server(s)/database(s), [create a contained user mapped to the UMI](#use-microsoft-entra-authentication-with-a-user-assigned-managed-identity-umi).
 1. In the output database, create and assign permissions to the UMI job user. Connect to the output database and run the following example script for a user named `jobuserUMI`:
@@ -166,7 +175,7 @@ To proceed with the Azure portal:
 
 By default, job agents are created at JA100, allowing up to 100 elastic job executions concurrently. Initiating a service level change is an asynchronous operation and the new service level will be made available after a short provisioning delay.
 
-If you need more than 100 concurrent executions of elastic job agents, higher service levels are available, see [Concurrent capacity tiers](elastic-jobs-overview.md#concurrent-capacity-tiers). You can currently change the service level of a job agent via the Azure portal or REST API.
+If you need more than 100 concurrent executions of elastic job agents, higher service levels are available, see [Concurrent capacity tiers](elastic-jobs-overview.md#concurrent-capacity-tiers). You can currently change the service level of a job agent via the Azure portal, PowerShell, or REST API.
 
 Exceeding the service level with concurrent jobs will create queuing delays before jobs start in excess of the [service level's concurrent jobs limit](elastic-jobs-overview.md#concurrent-capacity-tiers).
 
@@ -178,10 +187,21 @@ Exceeding the service level with concurrent jobs will create queuing delays befo
 1. Review the cost card.
 1. Select **Update**.
 
+### Scale the elastic job agent by using PowerShell
+
+The optional `-ServiceObjective` parameter for `Set-AzSqlElasticJobAgent` can be used to specify a new service objective. For example:
+```powershell
+$parameters = @{
+    Name = '<job agent name>'
+    ResourceGroupName = '<Resource_Group_Name>'
+    ServiceObjective = 'JA200'
+}
+Set-AzSqlElasticJobAgent @parameters
+```
 
 ### Scale the elastic job agent by using REST API
 
-You can use the [Job agent REST API](/rest/api/sql/2021-02-01-preview/job-agents#operations) <!-- update 2021-02-01-preview --> to scale a job agent. For example:
+You can use the [Job agent REST API](/rest/api/sql/job-agents) to scale a job agent. For example:
 
 ```json
 { 

docs/relational-databases/system-catalog-views/jobs-job-executions-elastic-jobs-transact-sql.md

@@ -3,7 +3,7 @@ title: "jobs.job_executions (Azure Elastic Jobs) (Transact-SQL)"
 description: "The jobs.job_executions system view contains information about Azure Elastic job execution history."
 author: WilliamDAssafMSFT
 ms.author: wiassaf
-ms.date: 11/03/2023
+ms.date: 11/13/2023
 ms.service: sql-database
 ms.subservice: system-objects
 ms.topic: "reference"
@@ -66,6 +66,9 @@ The following table lists the possible job execution states in `lifecycle`:
 
 Members of the *jobs_reader* role can SELECT from this view. For more information, see [Elastic jobs in Azure SQL Database (preview)](/azure/azure-sql/database/elastic-jobs-overview?view=azuresql-db&preserve-view=true#elastic-job-database-permissions).
 
+> [!CAUTION]
+> You should not update internal catalog views in the *job database*. Manually changing these catalog views can corrupt the *job database* and cause failure. These views are for read-only querying only. You can use the stored procedures on your *job database*.
+
 ## Remarks
 
 All times in elastic jobs are in the UTC time zone.

docs/relational-databases/system-catalog-views/jobs-job-versions-elastic-jobs-transact-sql.md

@@ -3,7 +3,7 @@ title: "jobs.job_versions (Azure Elastic Jobs) (Transact-SQL)"
 description: "The jobs.job_versions system view contains job version history in Azure Elastic jobs."
 author: WilliamDAssafMSFT
 ms.author: wiassaf
-ms.date: 10/30/2023
+ms.date: 11/13/2023
 ms.service: sql-database
 ms.subservice: system-objects
 ms.topic: "reference"
@@ -33,6 +33,9 @@ Contains version history about jobs in the [Azure Elastic Jobs service for Azure
 
 Members of the *jobs_reader* role can SELECT from this view. For more information, see [Elastic jobs in Azure SQL Database (preview)](/azure/azure-sql/database/elastic-jobs-overview?view=azuresql-db&preserve-view=true#elastic-job-database-permissions).
 
+> [!CAUTION]
+> You should not update internal catalog views in the *job database*. Manually changing these catalog views can corrupt the *job database* and cause failure. These views are for read-only querying only. You can use the stored procedures on your *job database*.
+
 ## Remarks
 
 All times in elastic jobs are in the UTC time zone.