Edit

New-AzContainerGroup

  • Reference
Module:
Az.ContainerInstance

Create or update container groups with specified configurations.

Syntax

New-AzContainerGroup
   -Name <String>
   -ResourceGroupName <String>
   -Container <IContainer[]>
   -Location <String>
   [-SubscriptionId <String>]
   [-DnsConfigNameServer <String[]>]
   [-DnsConfigOption <String>]
   [-DnsConfigSearchDomain <String>]
   [-EncryptionPropertyKeyName <String>]
   [-EncryptionPropertyKeyVersion <String>]
   [-EncryptionPropertyVaultBaseUrl <String>]
   [-IdentityType <ResourceIdentityType>]
   [-IdentityUserAssignedIdentity <Hashtable>]
   [-ImageRegistryCredential <IImageRegistryCredential[]>]
   [-InitContainer <IInitContainerDefinition[]>]
   [-IPAddressDnsNameLabel <String>]
   [-IPAddressIP <String>]
   [-IPAddressPort <IPort[]>]
   [-IPAddressType <ContainerGroupIPAddressType>]
   [-LogAnalyticLogType <LogAnalyticsLogType>]
   [-LogAnalyticMetadata <Hashtable>]
   [-LogAnalyticWorkspaceId <String>]
   [-LogAnalyticWorkspaceKey <String>]
   [-LogAnalyticWorkspaceResourceId <String>]
   [-OSType <OperatingSystemTypes>]
   [-Priority <String>]
   [-RestartPolicy <ContainerGroupRestartPolicy>]
   [-Sku <ContainerGroupSku>]
   [-SubnetId <IContainerGroupSubnetId[]>]
   [-Tag <Hashtable>]
   [-Volume <IVolume[]>]
   [-Zone <String[]>]
   [-DefaultProfile <PSObject>]
   [-AsJob]
   [-NoWait]
   [-Confirm]
   [-WhatIf]
   [<CommonParameters>]

Description

Create or update container groups with specified configurations.

Examples

Example 1: Create a container group with a container instance and request a public IP address with opening ports

$port1 = New-AzContainerInstancePortObject -Port 8000 -Protocol TCP
$port2 = New-AzContainerInstancePortObject -Port 8001 -Protocol TCP
$container = New-AzContainerInstanceObject -Name test-container -Image nginx -RequestCpu 1 -RequestMemoryInGb 1.5 -Port @($port1, $port2)
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -OsType Linux -RestartPolicy "Never" -IpAddressType Public

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group with a container instance, whose image is latest nginx, and requests a public IP address with opening port 8000 and 8001.

Example 2: Create container group and runs a custom script inside the container.

$env1 = New-AzContainerInstanceEnvironmentVariableObject -Name "env1" -Value "value1"
$env2 = New-AzContainerInstanceEnvironmentVariableObject -Name "env2" -SecureValue (ConvertTo-SecureString -String "value2" -AsPlainText -Force)
$container = New-AzContainerInstanceObject -Name test-container -Image alpine -Command "/bin/sh -c myscript.sh" -EnvironmentVariable @($env1, $env2)
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -OsType Linux

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group and runs a custom script inside the container.

Example 3: Create a run-to-completion container group

$container = New-AzContainerInstanceObject -Name test-container -Image alpine -Command "echo hello" 
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -OsType Linux

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group which prints out 'hello' and stops.

Example 4: Create a container group with a container instance using image nginx in Azure Container Registry

$container = New-AzContainerInstanceObject -Name test-container -Image myacr.azurecr.io/nginx:latest
$imageRegistryCredential = New-AzContainerGroupImageRegistryCredentialObject -Server "myacr.azurecr.io" -Username "username" -Password (ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force) 
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -ImageRegistryCredential $imageRegistryCredential

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group with a container instance, whose image is nginx in Azure Container Registry.

Example 5: Create a container group with a container instance using image nginx in custom container image Registry

$container = New-AzContainerInstanceObject -Name test-container -Image myserver.com/nginx:latest
$imageRegistryCredential = New-AzContainerGroupImageRegistryCredentialObject -Server "myserver.com" -Username "username" -Password (ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force) 
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -ImageRegistryCredential $imageRegistryCredential

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group with a container instance, whose image is a custom image from a custom container image registry.

Example 6: Create a container group that mounts Azure File volume

$volume = New-AzContainerGroupVolumeObject -Name "myvolume" -AzureFileShareName "myshare" -AzureFileStorageAccountName "username" -AzureFileStorageAccountKey (ConvertTo-SecureString "PlainTextPassword" -AsPlainText -Force)
$mount = New-AzContainerInstanceVolumeMountObject -MountPath "/aci/logs" -Name "myvolume"
$container = New-AzContainerInstanceObject -Name test-container -Image alpine -VolumeMount $mount
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -Volume $volume

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group with a container instance, whose image is a custom image from a custom container image registry.

Example 7: Create a container group with system assigned and user assigned identity

$container = New-AzContainerInstanceObject -Name test-container -Image alpine
$containerGroup = New-AzContainerGroup -ResourceGroupName test-rg -Name test-cg -Location eastus -Container $container -IdentityType "SystemAssigned, UserAssigned" -IdentityUserAssignedIdentity @{"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}" = @{}}

Location Name    Zone ResourceGroupName
-------- ----    ---- -----------------
eastus   test-cg      test-rg

This commands creates a container group with system assigned and user assigned identity.

Parameters

-AsJob

Run the command as a job

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Container

The containers within the container group. To construct, see NOTES section for CONTAINER properties and create a hash table.

Type:IContainer[]
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-DefaultProfile

The credentials, account, tenant, and subscription used for communication with Azure.

Type:PSObject
Aliases:AzureRMContext, AzureCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DnsConfigNameServer

The DNS servers for the container group.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DnsConfigOption

The DNS options for the container group.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DnsConfigSearchDomain

The DNS search domains for hostname lookup in the container group.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionPropertyKeyName

The encryption key name.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionPropertyKeyVersion

The encryption key version.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EncryptionPropertyVaultBaseUrl

The keyvault base url.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdentityType

The type of identity used for the container group. The type 'SystemAssigned, UserAssigned' includes both an implicitly created identity and a set of user assigned identities. The type 'None' will remove any identities from the container group.

Type:ResourceIdentityType
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdentityUserAssignedIdentity

The list of user identities associated with the container group. The user identity dictionary key references will be ARM resource ids in the form: '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}'.

Type:Hashtable
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ImageRegistryCredential

The image registry credentials by which the container group is created from. To construct, see NOTES section for IMAGEREGISTRYCREDENTIAL properties and create a hash table.

Type:IImageRegistryCredential[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-InitContainer

The init containers for a container group. To construct, see NOTES section for INITCONTAINER properties and create a hash table.

Type:IInitContainerDefinition[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPAddressDnsNameLabel

The Dns name label for the IP.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPAddressIP

The IP exposed to the public internet.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPAddressPort

The list of ports exposed on the container group. To construct, see NOTES section for IPADDRESSPORT properties and create a hash table.

Type:IPort[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IPAddressType

Specifies if the IP is exposed to the public internet or private VNET.

Type:ContainerGroupIPAddressType
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Location

The resource location.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-LogAnalyticLogType

The log type to be used.

Type:LogAnalyticsLogType
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LogAnalyticMetadata

Metadata for log analytics.

Type:Hashtable
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LogAnalyticWorkspaceId

The workspace id for log analytics

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LogAnalyticWorkspaceKey

The workspace key for log analytics

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-LogAnalyticWorkspaceResourceId

The workspace resource id for log analytics

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

The name of the container group.

Type:String
Aliases:ContainerGroupName
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-NoWait

Run the command asynchronously

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OSType

The operating system type required by the containers in the container group.

Type:OperatingSystemTypes
Position:Named
Default value:"Linux"
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Priority

The priority of the Container Group.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ResourceGroupName

The name of the resource group.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-RestartPolicy

Restart policy for all containers within the container group.

  • Always Always restart- OnFailure Restart on failure- Never Never restart
Type:ContainerGroupRestartPolicy
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Sku

The SKU for a container group.

Type:ContainerGroupSku
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SubnetId

The subnet resource IDs for a container group. To construct, see NOTES section for SUBNETID properties and create a hash table.

Type:IContainerGroupSubnetId[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SubscriptionId

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

Type:String
Position:Named
Default value:(Get-AzContext).Subscription.Id
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Tag

The resource tags.

Type:Hashtable
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Volume

The list of volumes that can be mounted by containers in this container group. To construct, see NOTES section for VOLUME properties and create a hash table.

Type:IVolume[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Zone

The zones for the container group.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Outputs

IContainerGroup

Notes

ALIASES

COMPLEX PARAMETER PROPERTIES

To create the parameters described below, construct a hash table containing the appropriate properties. For information on hash tables, run Get-Help about_Hash_Tables.

CONTAINER <IContainer[]>: The containers within the container group.

  • Image <String>: The name of the image used to create the container instance.
  • Name <String>: The user-provided name of the container instance.
  • RequestCpu <Double>: The CPU request of this container instance.
  • RequestMemoryInGb <Double>: The memory request in GB of this container instance.
  • [Command <String[]>]: The commands to execute within the container instance in exec form.
  • [EnvironmentVariable <IEnvironmentVariable[]>]: The environment variables to set in the container instance.
    • Name <String>: The name of the environment variable.
    • [SecureValue <String>]: The value of the secure environment variable.
    • [Value <String>]: The value of the environment variable.
  • [LimitCpu <Double?>]: The CPU limit of this container instance.
  • [LimitMemoryInGb <Double?>]: The memory limit in GB of this container instance.
  • [LimitsGpuCount <Int32?>]: The count of the GPU resource.
  • [LimitsGpuSku <GpuSku?>]: The SKU of the GPU resource.
  • [LivenessProbeExecCommand <String[]>]: The commands to execute within the container.
  • [LivenessProbeFailureThreshold <Int32?>]: The failure threshold.
  • [LivenessProbeHttpGetHttpHeader <IHttpHeader[]>]: The HTTP headers.
    • [Name <String>]: The header name.
    • [Value <String>]: The header value.
  • [LivenessProbeHttpGetPath <String>]: The path to probe.
  • [LivenessProbeHttpGetPort <Int32?>]: The port number to probe.
  • [LivenessProbeHttpGetScheme <Scheme?>]: The scheme.
  • [LivenessProbeInitialDelaySecond <Int32?>]: The initial delay seconds.
  • [LivenessProbePeriodSecond <Int32?>]: The period seconds.
  • [LivenessProbeSuccessThreshold <Int32?>]: The success threshold.
  • [LivenessProbeTimeoutSecond <Int32?>]: The timeout seconds.
  • [Port <IContainerPort[]>]: The exposed ports on the container instance.
    • Port <Int32>: The port number exposed within the container group.
    • [Protocol <ContainerNetworkProtocol?>]: The protocol associated with the port.
  • [ReadinessProbeExecCommand <String[]>]: The commands to execute within the container.
  • [ReadinessProbeFailureThreshold <Int32?>]: The failure threshold.
  • [ReadinessProbeHttpGetHttpHeader <IHttpHeader[]>]: The HTTP headers.
  • [ReadinessProbeHttpGetPath <String>]: The path to probe.
  • [ReadinessProbeHttpGetPort <Int32?>]: The port number to probe.
  • [ReadinessProbeHttpGetScheme <Scheme?>]: The scheme.
  • [ReadinessProbeInitialDelaySecond <Int32?>]: The initial delay seconds.
  • [ReadinessProbePeriodSecond <Int32?>]: The period seconds.
  • [ReadinessProbeSuccessThreshold <Int32?>]: The success threshold.
  • [ReadinessProbeTimeoutSecond <Int32?>]: The timeout seconds.
  • [RequestsGpuCount <Int32?>]: The count of the GPU resource.
  • [RequestsGpuSku <GpuSku?>]: The SKU of the GPU resource.
  • [VolumeMount <IVolumeMount[]>]: The volume mounts available to the container instance.
    • MountPath <String>: The path within the container where the volume should be mounted. Must not contain colon (:).
    • Name <String>: The name of the volume mount.
    • [ReadOnly <Boolean?>]: The flag indicating whether the volume mount is read-only.

IMAGEREGISTRYCREDENTIAL <IImageRegistryCredential[]>: The image registry credentials by which the container group is created from.

  • Server <String>: The Docker image registry server without a protocol such as "http" and "https".
  • [Identity <String>]: The identity for the private registry.
  • [IdentityUrl <String>]: The identity URL for the private registry.
  • [Password <String>]: The password for the private registry.
  • [Username <String>]: The username for the private registry.

INITCONTAINER <IInitContainerDefinition[]>: The init containers for a container group.

  • Name <String>: The name for the init container.
  • [Command <String[]>]: The command to execute within the init container in exec form.
  • [EnvironmentVariable <IEnvironmentVariable[]>]: The environment variables to set in the init container.
    • Name <String>: The name of the environment variable.
    • [SecureValue <String>]: The value of the secure environment variable.
    • [Value <String>]: The value of the environment variable.
  • [Image <String>]: The image of the init container.
  • [VolumeMount <IVolumeMount[]>]: The volume mounts available to the init container.
    • MountPath <String>: The path within the container where the volume should be mounted. Must not contain colon (:).
    • Name <String>: The name of the volume mount.
    • [ReadOnly <Boolean?>]: The flag indicating whether the volume mount is read-only.

IPADDRESSPORT <IPort[]>: The list of ports exposed on the container group.

  • Port1 <Int32>: The port number.
  • [Protocol <ContainerGroupNetworkProtocol?>]: The protocol associated with the port.

SUBNETID <IContainerGroupSubnetId[]>: The subnet resource IDs for a container group.

  • Id <String>: Resource ID of virtual network and subnet.
  • [Name <String>]: Friendly name for the subnet.

VOLUME <IVolume[]>: The list of volumes that can be mounted by containers in this container group.

  • Name <String>: The name of the volume.
  • [AzureFileReadOnly <Boolean?>]: The flag indicating whether the Azure File shared mounted as a volume is read-only.
  • [AzureFileShareName <String>]: The name of the Azure File share to be mounted as a volume.
  • [AzureFileStorageAccountKey <String>]: The storage account access key used to access the Azure File share.
  • [AzureFileStorageAccountName <String>]: The name of the storage account that contains the Azure File share.
  • [EmptyDir <IVolumeEmptyDir>]: The empty directory volume.
    • [(Any) <Object>]: This indicates any property can be added to this object.
  • [GitRepoDirectory <String>]: Target directory name. Must not contain or start with '..'. If '.' is supplied, the volume directory will be the git repository. Otherwise, if specified, the volume will contain the git repository in the subdirectory with the given name.
  • [GitRepoRepository <String>]: Repository URL
  • [GitRepoRevision <String>]: Commit hash for the specified revision.
  • [Secret <ISecretVolume>]: The secret volume.
    • [(Any) <String>]: This indicates any property can be added to this object.