AWS powershell documentation change
Summary
Clarified removal of $AWSHistory and associated cmdlets (Clear-AWSHistory, Set-AWSHistoryConfiguration)
Security assessment
Removal of deprecated features does not indicate a security issue or add security documentation.
Diff
diff --git a/powershell/v5/userguide/migrating-v5.md b/powershell/v5/userguide/migrating-v5.md index e7b831939..3a2052853 100644 --- a//powershell/v5/userguide/migrating-v5.md +++ b//powershell/v5/userguide/migrating-v5.md @@ -5 +5 @@ -Minimum PowerShell versionNullable value typesCollectionsPipelining and $AWSHistoryThe -PassThru parameterSome DynamoDB cmdlets moved and renamedLogging of sensitive informationCredential and profile resolutionConsistent Auto-IterationS3 cmdlets deprecated and replacedCleaning and trimming S3 key parametersInteractive session capabilitiesCloudWatch alarmsLitJsonProgramming elements that were removed +Minimum PowerShell versionNullable value typesCollectionsDateTime versus UTC DateTimePipelining and $AWSHistoryThe -PassThru parameterSome DynamoDB cmdlets moved and renamedLogging of sensitive informationCredential and profile resolutionConsistent Auto-IterationS3 cmdlets deprecated and replacedCleaning and trimming S3 key parametersInteractive session capabilitiesCloudWatch alarmsLitJsonProgramming elements that were removed @@ -27 +27,51 @@ For more information about the AWSPowerShell module, see [Installing on Windows] -The types adopted from the AWS SDK for .NET have been updated to use that SDK's new nullable changes. For example, properties of type `int` have been changed to `Nullable[int]`. For additional information including examples, see the blog post [Preview 1 of AWS Tools for PowerShell V5](https://aws.amazon.com/blogs/developer/preview-1-of-aws-tools-for-powershell-v5/) and the migration content for [Value types](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html#net-dg-v4-value-types) in the [AWS SDK for .NET Developer Guide](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/). +The types adopted from the AWS SDK for .NET have been updated to use the SDK's new nullable changes. For example, properties of type `int` have been changed to `Nullable[int]`. This change doesn't affect how input parameter values are specified for AWS cmdlets because those value type parameters were already modeled as nullable. However, nullable types for cmdlet output is a breaking change because properties within the cmdlet output will contain `$null` instead of the various default values for types. + +The following example demonstrates the behavior in V4 of the Tools for PowerShell. In this example, the `MissingMeta` property is set to 0 because that is the default value of type `int`. + + + # In V4 + PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | + >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled + + LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled + ------------ ----------- ------------------------- ---------------- + 8/29/2023 10:20:44 PM 0 1/1/0001 12:00:00 AM + +The following example demonstrates the behavior in V5 of the Tools for PowerShell. In this example, the `MissingMeta` property is set to `$null`. + + + # In V5 + PS > Get-S3ObjectMetadata -BucketName amzn-s3-demo-bucket -Key 'test' | + >> Select LastModified, MissingMeta, ObjectLockRetainUntilDate, BucketKeyEnabled + + LastModified MissingMeta ObjectLockRetainUntilDate BucketKeyEnabled + ------------ ----------- ------------------------- ---------------- + 8/29/2023 10:20:44 PM + +In most cases, no code change is necessary because PowerShell has implicit conversion from nullable value types to non-nullable value types. However, this is a breaking change for comparison-logic code that checks explicitly for a default value of a nullable value type. Comparison logic that checks for the default value of a non-nullable type must be modified to check for `$null`. + +For some of these types, the following examples show how to update code written for V4 that checks if nothing was returned: + + + #Type int: + # In V4, if you were checking whether an int is 0... + if($s3Metadata.MissingMeta -eq 0){} + + # In V5, check if the int is null instead: + if($s3Metadata.MissingMeta -eq $null) {} + + # Type datetime: + # In V4, if you were checking whether a datetime is '0001-01-01'... + if($s3Metadata.ObjectLockRetainUntilDate -eq '0001-01-01'){} + + # In V5, check if the datetime is null instead: + if($s3Metadata.ObjectLockRetainUntilDate -eq $null){} + + # Type boolean: + # In V4, if you were checking whether a boolean is $false... + if($s3Metadata.BucketKeyEnabled -eq $false){} + + # In V5, check if the boolean is null instead: + if($s3Metadata.BucketKeyEnabled -eq $null) + +Since the AWS Tools for PowerShell rely on the AWS SDK for .NET, it might be useful to examine how similar changes affected version 4 of the SDK. To find this information, see the [Value types](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html#net-dg-v4-value-types) migration content in the [AWS SDK for .NET Developer Guide](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/). @@ -32,0 +83,90 @@ Some cmdlet output has been changed to return `$null` instead of empty collectio +## DateTime versus UTC DateTime + +Some V4 cmdlets define DateTime parameters that are obsolete, as well as alternative UTC DateTime parameters. These obsolete DateTime parameters have been removed from the V5 cmdlets, and the name of the UTC DateTime parameters have been changed to the original name of the non-UTC DateTime parameters. + +The following are some examples of cmdlets for which this change has been implemented. + + * `Get-ASScheduledAction` ([V4 cmdlet](https://docs.aws.amazon.com/powershell/v4/reference/items/Get-ASScheduledAction.html) and [V5 cmdlet](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ASScheduledAction.html)): + + * The `StartTime` parameter has been removed, and the name of the `UtcStartTime` parameter has been changed to "StartTime". + + * The `EndTime` parameter has been removed, and the name of the `UtcEndTime` parameter has been changed to "EndTime". + + * `Copy-S3Object` ([V4 cmdlet](https://docs.aws.amazon.com/powershell/v4/reference/items/Copy-S3Object.html) and [V5 cmdlet](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html)): + + * The `ModifiedSinceDate` parameter has been removed, and the name of the `UtcModifiedSinceDate` parameter has been changed to "ModifiedSinceDate". + + * The `UnmodifiedSinceDate` parameter has been removed, and the name of the `UtcUnmodifiedSinceDate` parameter has been changed to "UnmodifiedSinceDate". + + + + +The following is a complete list of the cmdlets that are affected by this change. + + * [Get-ASScheduledAction](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ASScheduledAction.html) + + * [Write-ASScheduledUpdateGroupAction](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-ASScheduledUpdateGroupAction.html) + + * [Get-CWAlarmHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWAlarmHistory.html) + + * [Get-CWMetricData](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWMetricData.html) + + * [Get-CWMetricStatistic](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWMetricStatistic.html) (alias Get-CWMetricStatistics) + + * [New-EC2Fleet](https://docs.aws.amazon.com/powershell/v5/reference/items/New-EC2Fleet.html) + + * [Get-EC2FleetHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2FleetHistory.html) + + * [Get-EC2ScheduledInstance](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2ScheduledInstance.html) + + * [Get-EC2ScheduledInstanceAvailability](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2ScheduledInstanceAvailability.html) + + * [Get-EC2SpotFleetRequestHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2SpotFleetRequestHistory.html) + + * [Get-EC2SpotPriceHistory](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EC2SpotPriceHistory.html) + + * [Import-EC2Image](https://docs.aws.amazon.com/powershell/v5/reference/items/Import-EC2Image.html) + + * [Import-EC2Snapshot](https://docs.aws.amazon.com/powershell/v5/reference/items/Import-EC2Snapshot.html) + + * [Request-EC2SpotFleet](https://docs.aws.amazon.com/powershell/v5/reference/items/Request-EC2SpotFleet.html) + + * [Request-EC2SpotInstance](https://docs.aws.amazon.com/powershell/v5/reference/items/Request-EC2SpotInstance.html) + + * [Send-EC2InstanceStatus](https://docs.aws.amazon.com/powershell/v5/reference/items/Send-EC2InstanceStatus.html) + + * [Get-ECEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-ECEvent.html) + + * [Get-EBEnvironment](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EBEnvironment.html) + + * [Get-EBEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-EBEvent.html) + + * [Get-IOTTaskList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-IOTTaskList.html) + + * [Get-IOTViolationEventList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-IOTViolationEventList.html) + + * [Get-RDSEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RDSEvent.html) + + * [Reset-RDSDBCluster](https://docs.aws.amazon.com/powershell/v5/reference/items/Reset-RDSDBCluster.html) + + * [Restore-RDSDBClusterToPointInTime](https://docs.aws.amazon.com/powershell/v5/reference/items/Restore-RDSDBClusterToPointInTime.html) + + * [Restore-RDSDBInstanceToPointInTime](https://docs.aws.amazon.com/powershell/v5/reference/items/Restore-RDSDBInstanceToPointInTime.html) + + * [Get-RSClusterSnapshot](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RSClusterSnapshot.html) (alias Get-RSClusterSnapshots) + + * [Get-RSEvent](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-RSEvent.html) (alias Get-RSEvents) + + * [Copy-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html) + + * [Read-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Read-S3Object.html) + + * [Get-S3ObjectMetadata](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectMetadata.html) + + * [Send-SESBounce](https://docs.aws.amazon.com/powershell/v5/reference/items/Send-SESBounce.html) + + * [Get-WDActivity](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-WDActivity.html) + + + + @@ -39 +179 @@ In V4 of the Tools for PowerShell, this session variable was deprecated in favor -In V5 of the Tools for PowerShell, the `$AWSHistory` session variable has been removed completely. +In V5 of the Tools for PowerShell, the `$AWSHistory` session variable has been removed completely. As a consequence, the `Clear-AWSHistory` and `Set-AWSHistoryConfiguration` cmdlets have also been removed. @@ -47 +187 @@ The `-PassThru` parameter has been removed. When a cmdlet doesn't return any out -The `Get-DDBStream` and `Get-DDBStreamList` cmdlets have been moved from the DynamoDBV2 module to a new module called DynamoDBStreams. They have also been renamed to [Get-DDBSStream](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-DDBSStream.html) and [Get-DDBSStreamList](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-DDBSStreamList.html), respectively. +The `Get-DDBStream` and `Get-DDBStreamList` cmdlets have been moved from the DynamoDBV2 module to a new module called DynamoDBStreams. They have also been renamed to [Get-DDBSStream](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-DDBSStream.html) and [Get-DDBSStreamList](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-DDBSStreamList.html), respectively. @@ -59 +199 @@ The AWS Tools for PowerShell have been updated to use certain environment variab -All paginated cmdlets have been updated to auto-iterate all data by default. You can revert this behavior by using the [Set-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/latest/reference/items/Set-AWSAutoIterationMode.html) cmdlet. If you run `Set-AWSAutoIterationMode -IterationMode v4`, operations that auto-iterated in v4 will still auto-iterate, but the rest will revert to manual iteration. To determine what mode auto-iteration is set to, use the [Get-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-AWSAutoIterationMode.html) cmdlet. +All paginated cmdlets have been updated to auto-iterate all data by default. You can revert this behavior by using the [Set-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-AWSAutoIterationMode.html) cmdlet. If you run `Set-AWSAutoIterationMode -IterationMode v4`, operations that auto-iterated in v4 will still auto-iterate, but the rest will revert to manual iteration. To determine what mode auto-iteration is set to, use the [Get-AWSAutoIterationMode](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-AWSAutoIterationMode.html) cmdlet. @@ -63 +203 @@ All paginated cmdlets have been updated to auto-iterate all data by default. You -For Amazon S3, the [Get-S3ACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-S3ACL.html) and [Set-S3ACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Set-S3ACL.html) cmdlets have been deprecated. Use the following new cmdlets instead: [Get-S3BucketACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-S3BucketACL.html), [Set-S3BucketACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Set-S3BucketACL.html), [Get-S3ObjectACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-S3ObjectACL.html), [Set-S3ObjectACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Set-S3ObjectACL.html). +For Amazon S3, the [Get-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ACL.html) and [Set-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ACL.html) cmdlets have been deprecated. Use the following new cmdlets instead: [Get-S3BucketACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3BucketACL.html), [Set-S3BucketACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3BucketACL.html), [Get-S3ObjectACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectACL.html), [Set-S3ObjectACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ObjectACL.html). @@ -71 +211 @@ This information applies to the following cmdlets: - * [Copy-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Copy-S3Object.html) + * [Copy-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Copy-S3Object.html) @@ -73 +213 @@ This information applies to the following cmdlets: - * [Get-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-S3Object.html) + * [Get-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3Object.html) @@ -75 +215 @@ This information applies to the following cmdlets: - * [Get-S3ObjectV2](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-S3ObjectV2.html) + * [Get-S3ObjectV2](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-S3ObjectV2.html) @@ -77 +217 @@ This information applies to the following cmdlets: - * [Read-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Read-S3Object.html) + * [Read-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Read-S3Object.html) @@ -79 +219 @@ This information applies to the following cmdlets: - * [Remove-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Remove-S3Object.html) + * [Remove-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Remove-S3Object.html) @@ -81 +221 @@ This information applies to the following cmdlets: - * [Set-S3ACL](https://docs.aws.amazon.com/powershell/latest/reference/items/Set-S3ACL.html) + * [Set-S3ACL](https://docs.aws.amazon.com/powershell/v5/reference/items/Set-S3ACL.html) @@ -83 +223 @@ This information applies to the following cmdlets: - * [Write-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-S3Object.html) + * [Write-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-S3Object.html) @@ -90 +230 @@ This information applies to the following cmdlets: -Interactive session capabilities have been added to the [Start-SSMSession](https://docs.aws.amazon.com/powershell/latest/reference/items/Start-SSMSession.html) cmdlet, which aligns with the AWS CLI behavior. If you need legacy behavior, include the `-DisablePluginInvocation` parameter in the `Start-SSMSession` command. For example: +Interactive session capabilities have been added to the [Start-SSMSession](https://docs.aws.amazon.com/powershell/v5/reference/items/Start-SSMSession.html) cmdlet, which aligns with the AWS CLI behavior. If you need legacy behavior, include the `-DisablePluginInvocation` parameter in the `Start-SSMSession` command. For example: @@ -97 +237 @@ Interactive session capabilities have been added to the [Start-SSMSession](https -The [Get-CWAlarm](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-CWAlarm.html) cmdlet has been updated to return both metric and composite Amazon CloudWatch alarms by default. To limit the output to either metric or composite alarms, you must specify the `-AlarmType` parameter: `Get-CWAlarm -AlarmType 'MetricAlarms'` or `Get-CWAlarm -AlarmType 'CompositeAlarms'`, respectively. +The [Get-CWAlarm](https://docs.aws.amazon.com/powershell/v5/reference/items/Get-CWAlarm.html) cmdlet has been updated to return both metric and composite Amazon CloudWatch alarms by default. To limit the output to either metric or composite alarms, you must specify the `-AlarmType` parameter: `Get-CWAlarm -AlarmType 'MetricAlarms'` or `Get-CWAlarm -AlarmType 'CompositeAlarms'`, respectively. @@ -105 +245 @@ The AWS Tools for PowerShell have been updated to use `System.Text.Json` instead -The following programming elements have been removed from V5 of the Tools for PowerShell: +A number of programming elements have been removed from V5 of the Tools for PowerShell. These are listed below, if not already covered previously, along with potential steps that you can take to accommodate their removal, if any. @@ -111 +251 @@ The following programming elements have been removed from V5 of the Tools for Po - * The `CalculateContentMD5Header` parameter from the [Write-S3Object](https://docs.aws.amazon.com/powershell/latest/reference/items/Write-S3Object.html) cmdlet. + * The `CalculateContentMD5Header` parameter from the [Write-S3Object](https://docs.aws.amazon.com/powershell/v5/reference/items/Write-S3Object.html) cmdlet.