AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the AWS Batch RegisterJobDefinition API operation.

Syntax

Register-BATJobDefinition
-JobDefinitionName <String>
-NetworkConfiguration_AssignPublicIp <AssignPublicIp>
-RetryStrategy_Attempt <Int32>
-ContainerProperties_Command <String[]>
-LinuxParameters_Device <Device[]>
-ContainerProperties_Environment <KeyValuePair[]>
-RetryStrategy_EvaluateOnExit <EvaluateOnExit[]>
-ContainerProperties_ExecutionRoleArn <String>
-ContainerProperties_Image <String>
-LinuxParameters_InitProcessEnabled <Boolean>
-ContainerProperties_InstanceType <String>
-ContainerProperties_JobRoleArn <String>
-LogConfiguration_LogDriver <LogDriver>
-NodeProperties_MainNode <Int32>
-LinuxParameters_MaxSwap <Int32>
-ContainerProperties_MountPoint <MountPoint[]>
-NodeProperties_NodeRangeProperty <NodeRangeProperty[]>
-NodeProperties_NumNode <Int32>
-LogConfiguration_Option <Hashtable>
-Parameter <Hashtable>
-PlatformCapability <String[]>
-FargatePlatformConfiguration_PlatformVersion <String>
-ContainerProperties_Privileged <Boolean>
-PropagateTag <Boolean>
-ContainerProperties_ReadonlyRootFilesystem <Boolean>
-ContainerProperties_ResourceRequirement <ResourceRequirement[]>
-SchedulingPriority <Int32>
-LogConfiguration_SecretOption <Secret[]>
-ContainerProperties_Secret <Secret[]>
-LinuxParameters_SharedMemorySize <Int32>
-LinuxParameters_Swappiness <Int32>
-Tag <Hashtable>
-Timeout <JobTimeout>
-LinuxParameters_Tmpf <Tmpfs[]>
-Type <JobDefinitionType>
-ContainerProperties_Ulimit <Ulimit[]>
-ContainerProperties_User <String>
-ContainerProperties_Volume <Volume[]>
-ContainerProperties_Memory <Int32>
-ContainerProperties_Vcpus <Int32>
-Select <String>
-PassThru <SwitchParameter>
-Force <SwitchParameter>

Description

Registers an Batch job definition.

Parameters

-ContainerProperties_Command <String[]>
The command that's passed to the container. This parameter maps to Cmd in the Create a container section of the Docker Remote API and the COMMAND parameter to docker run. For more information, see https://docs.docker.com/engine/reference/builder/#cmd.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_Environment <KeyValuePair[]>
The environment variables to pass to a container. This parameter maps to Env in the Create a container section of the Docker Remote API and the --env option to docker run.We don't recommend using plaintext environment variables for sensitive information, such as credential data.Environment variables must not start with AWS_BATCH; this naming convention is reserved for variables that are set by the Batch service.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_ExecutionRoleArn <String>
The Amazon Resource Name (ARN) of the execution role that Batch can assume. For jobs that run on Fargate resources, you must provide an execution role. For more information, see Batch execution IAM role in the Batch User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_Image <String>
The image used to start a container. This string is passed directly to the Docker daemon. Images in the Docker Hub registry are available by default. Other repositories are specified with repository-url/image:tag. Up to 255 letters (uppercase and lowercase), numbers, hyphens, underscores, colons, periods, forward slashes, and number signs are allowed. This parameter maps to Image in the Create a container section of the Docker Remote API and the IMAGE parameter of docker run.Docker image architecture must match the processor architecture of the compute resources that they're scheduled on. For example, ARM-based Docker images can only run on ARM-based compute resources.
  • Images in Amazon ECR Public repositories use the full registry/repository[:tag] or registry/repository[@digest] naming conventions. For example, public.ecr.aws/registry_alias/my-web-app:latest.
  • Images in Amazon ECR repositories use the full registry and repository URI (for example, 012345678910.dkr.ecr.<region-name>.amazonaws.com/<repository-name>).
  • Images in official repositories on Docker Hub use a single name (for example, ubuntu or mongo).
  • Images in other repositories on Docker Hub are qualified with an organization name (for example, amazon/amazon-ecs-agent).
  • Images in other online repositories are qualified further by a domain name (for example, quay.io/assemblyline/ubuntu).
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_InstanceType <String>
The instance type to use for a multi-node parallel job. All node groups in a multi-node parallel job must use the same instance type.This parameter isn't applicable to single-node container jobs or jobs that run on Fargate resources, and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_JobRoleArn <String>
The Amazon Resource Name (ARN) of the IAM role that the container can assume for Amazon Web Services permissions. For more information, see IAM roles for tasks in the Amazon Elastic Container Service Developer Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_Memory <Int32>
This parameter is deprecated, use resourceRequirements to specify the memory requirements for the job definition. It's not supported for jobs running on Fargate resources. For jobs running on EC2 resources, it specifies the memory hard limit (in MiB) for a container. If your container attempts to exceed the specified number, it's terminated. You must specify at least 4 MiB of memory for a job using this parameter. The memory hard limit can be specified in several places. It must be specified for each node at least once.This parameter is deprecated.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_MountPoint <MountPoint[]>
The mount points for data volumes in your container. This parameter maps to Volumes in the Create a container section of the Docker Remote API and the --volume option to docker run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_MountPoints
-ContainerProperties_Privileged <Boolean>
When this parameter is true, the container is given elevated permissions on the host container instance (similar to the root user). This parameter maps to Privileged in the Create a container section of the Docker Remote API and the --privileged option to docker run. The default value is false.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided, or specified as false.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_ReadonlyRootFilesystem <Boolean>
When this parameter is true, the container is given read-only access to its root file system. This parameter maps to ReadonlyRootfs in the Create a container section of the Docker Remote API and the --read-only option to docker run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_ResourceRequirement <ResourceRequirement[]>
The type and amount of resources to assign to a container. The supported resources include GPU, MEMORY, and VCPU.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_ResourceRequirements
-ContainerProperties_Secret <Secret[]>
The secrets for the container. For more information, see Specifying sensitive data in the Batch User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_Secrets
-ContainerProperties_Ulimit <Ulimit[]>
A list of ulimits to set in the container. This parameter maps to Ulimits in the Create a container section of the Docker Remote API and the --ulimit option to docker run.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_Ulimits
-ContainerProperties_User <String>
The user name to use inside the container. This parameter maps to User in the Create a container section of the Docker Remote API and the --user option to docker run.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_Vcpus <Int32>
This parameter is deprecated, use resourceRequirements to specify the vCPU requirements for the job definition. It's not supported for jobs running on Fargate resources. For jobs running on EC2 resources, it specifies the number of vCPUs reserved for the job.Each vCPU is equivalent to 1,024 CPU shares. This parameter maps to CpuShares in the Create a container section of the Docker Remote API and the --cpu-shares option to docker run. The number of vCPUs must be specified but can be specified in several places. You must specify it at least once for each node.This parameter is deprecated.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ContainerProperties_Volume <Volume[]>
A list of data volumes used in a job.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_Volumes
-FargatePlatformConfiguration_PlatformVersion <String>
The Fargate platform version where the jobs are running. A platform version is specified only for jobs that are running on Fargate resources. If one isn't specified, the LATEST platform version is used by default. This uses a recent, approved version of the Fargate platform for compute resources. For more information, see Fargate platform versions in the Amazon Elastic Container Service Developer Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_FargatePlatformConfiguration_PlatformVersion
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-JobDefinitionName <String>
The name of the job definition to register. It can be up to 128 letters long. It can contain uppercase and lowercase letters, numbers, hyphens (-), and underscores (_).
Required?True
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-LinuxParameters_Device <Device[]>
Any host devices to expose to the container. This parameter maps to Devices in the Create a container section of the Docker Remote API and the --device option to docker run.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_Devices
-LinuxParameters_InitProcessEnabled <Boolean>
If true, run an init process inside the container that forwards signals and reaps processes. This parameter maps to the --init option to docker run. This parameter requires version 1.25 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command: sudo docker version | grep "Server API version"
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_InitProcessEnabled
-LinuxParameters_MaxSwap <Int32>
The total amount of swap memory (in MiB) a container can use. This parameter is translated to the --memory-swap option to docker run where the value is the sum of the container memory plus the maxSwap value. For more information, see --memory-swap details in the Docker documentation.If a maxSwap value of 0 is specified, the container doesn't use swap. Accepted values are 0 or any positive integer. If the maxSwap parameter is omitted, the container doesn't use the swap configuration for the container instance it is running on. A maxSwap value must be set for the swappiness parameter to be used.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_MaxSwap
-LinuxParameters_SharedMemorySize <Int32>
The value for the size (in MiB) of the /dev/shm volume. This parameter maps to the --shm-size option to docker run.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_SharedMemorySize
-LinuxParameters_Swappiness <Int32>
This allows you to tune a container's memory swappiness behavior. A swappiness value of 0 causes swapping not to happen unless absolutely necessary. A swappiness value of 100 causes pages to be swapped very aggressively. Accepted values are whole numbers between 0 and 100. If the swappiness parameter isn't specified, a default value of 60 is used. If a value isn't specified for maxSwap, then this parameter is ignored. If maxSwap is set to 0, the container doesn't use swap. This parameter maps to the --memory-swappiness option to docker run.Consider the following when you use a per-container swap configuration.
  • Swap space must be enabled and allocated on the container instance for the containers to use.The Amazon ECS optimized AMIs don't have swap enabled by default. You must enable swap on the instance to use this feature. For more information, see Instance store swap volumes in the Amazon EC2 User Guide for Linux Instances or How do I allocate memory to work as swap space in an Amazon EC2 instance by using a swap file?
  • The swap space parameters are only supported for job definitions using EC2 resources.
  • If the maxSwap and swappiness parameters are omitted from a job definition, each container will have a default swappiness value of 60, and the total swap usage will be limited to two times the memory reservation of the container.
This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_Swappiness
-LinuxParameters_Tmpf <Tmpfs[]>
The container path, mount options, and size (in MiB) of the tmpfs mount. This parameter maps to the --tmpfs option to docker run.This parameter isn't applicable to jobs that are running on Fargate resources and shouldn't be provided.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LinuxParameters_Tmpfs
-LogConfiguration_LogDriver <LogDriver>
The log driver to use for the container. The valid values listed for this parameter are log drivers that the Amazon ECS container agent can communicate with by default.The supported log drivers are awslogs, fluentd, gelf, json-file, journald, logentries, syslog, and splunk.Jobs that are running on Fargate resources are restricted to the awslogs and splunk log drivers.
awslogs
Specifies the Amazon CloudWatch Logs logging driver. For more information, see Using the awslogs log driver in the Batch User Guide and Amazon CloudWatch Logs logging driver in the Docker documentation.
fluentd
Specifies the Fluentd logging driver. For more information, including usage and options, see Fluentd logging driver in the Docker documentation.
gelf
Specifies the Graylog Extended Format (GELF) logging driver. For more information, including usage and options, see Graylog Extended Format logging driver in the Docker documentation.
journald
Specifies the journald logging driver. For more information, including usage and options, see Journald logging driver in the Docker documentation.
json-file
Specifies the JSON file logging driver. For more information, including usage and options, see JSON File logging driver in the Docker documentation.
splunk
Specifies the Splunk logging driver. For more information, including usage and options, see Splunk logging driver in the Docker documentation.
syslog
Specifies the syslog logging driver. For more information, including usage and options, see Syslog logging driver in the Docker documentation.
If you have a custom driver that's not listed earlier that you want to work with the Amazon ECS container agent, you can fork the Amazon ECS container agent project that's available on GitHub and customize it to work with that driver. We encourage you to submit pull requests for changes that you want to have included. However, Amazon Web Services doesn't currently support running modified copies of this software.This parameter requires version 1.18 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command: sudo docker version | grep "Server API version"
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LogConfiguration_LogDriver
-LogConfiguration_Option <Hashtable>
The configuration options to send to the log driver. This parameter requires version 1.19 of the Docker Remote API or greater on your container instance. To check the Docker Remote API version on your container instance, log into your container instance and run the following command: sudo docker version | grep "Server API version"
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LogConfiguration_Options
-LogConfiguration_SecretOption <Secret[]>
The secrets to pass to the log configuration. For more information, see Specifying sensitive data in the Batch User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_LogConfiguration_SecretOptions
-NetworkConfiguration_AssignPublicIp <AssignPublicIp>
Indicates whether the job should have a public IP address. For a job that is running on Fargate resources in a private subnet to send outbound traffic to the internet (for example, to pull container images), the private subnet requires a NAT gateway be attached to route requests to the internet. For more information, see Amazon ECS task networking. The default value is "DISABLED".
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesContainerProperties_NetworkConfiguration_AssignPublicIp
-NodeProperties_MainNode <Int32>
Specifies the node index for the main node of a multi-node parallel job. This node index value must be fewer than the number of nodes.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NodeProperties_NodeRangeProperty <NodeRangeProperty[]>
A list of node ranges and their properties associated with a multi-node parallel job.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesNodeProperties_NodeRangeProperties
-NodeProperties_NumNode <Int32>
The number of nodes associated with a multi-node parallel job.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesNodeProperties_NumNodes
-Parameter <Hashtable>
Default parameter substitution placeholders to set in the job definition. Parameters are specified as a key-value pair mapping. Parameters in a SubmitJob request override any corresponding parameter defaults from the job definition.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesParameters
-PassThru <SwitchParameter>
Changes the cmdlet behavior to return the value passed to the JobDefinitionName parameter. The -PassThru parameter is deprecated, use -Select '^JobDefinitionName' instead. This parameter will be removed in a future version.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-PlatformCapability <String[]>
The platform capabilities required by the job definition. If no value is specified, it defaults to EC2. To run the job on Fargate resources, specify FARGATE.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesPlatformCapabilities
-PropagateTag <Boolean>
Specifies whether to propagate the tags from the job or job definition to the corresponding Amazon ECS task. If no value is specified, the tags are not propagated. Tags can only be propagated to the tasks during task creation. For tags with the same name, job tags are given priority over job definitions tags. If the total number of combined tags from the job and job definition is over 50, the job is moved to the FAILED state.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesPropagateTags
-RetryStrategy_Attempt <Int32>
The number of times to move a job to the RUNNABLE status. You can specify between 1 and 10 attempts. If the value of attempts is greater than one, the job is retried on failure the same number of attempts as the value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRetryStrategy_Attempts
-RetryStrategy_EvaluateOnExit <EvaluateOnExit[]>
Array of up to 5 objects that specify conditions under which the job should be retried or failed. If this parameter is specified, then the attempts parameter must also be specified.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SchedulingPriority <Int32>
The scheduling priority for jobs that are submitted with this job definition. This will only affect jobs in job queues with a fair share policy. Jobs with a higher scheduling priority will be scheduled before jobs with a lower scheduling priority.The minimum supported value is 0 and the maximum supported value is 9999.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is '*'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.Batch.Model.RegisterJobDefinitionResponse). Specifying the name of a property of type Amazon.Batch.Model.RegisterJobDefinitionResponse will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Tag <Hashtable>
The tags that you apply to the job definition to help you categorize and organize your resources. Each tag consists of a key and an optional value. For more information, see Tagging Amazon Web Services Resources in Batch User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesTags
-Timeout <JobTimeout>
The timeout configuration for jobs that are submitted with this job definition, after which Batch terminates your jobs if they have not finished. If a job is terminated due to a timeout, it isn't retried. The minimum value for the timeout is 60 seconds. Any timeout configuration that's specified during a SubmitJob operation overrides the timeout configuration defined here. For more information, see Job Timeouts in the Batch User Guide.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-Type <JobDefinitionType>
The type of job definition. For more information about multi-node parallel jobs, see Creating a multi-node parallel job definition in the Batch User Guide.If the job is run on Fargate resources, then multinode isn't supported.
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.Batch.Model.RegisterJobDefinitionResponse
This cmdlet returns an Amazon.Batch.Model.RegisterJobDefinitionResponse object containing multiple properties. The object can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack.
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z