Merge pull request #7918 from derekeppinger/epps3contribution

Add 15 CLI Code Examples for S3, Lambda, EC2, IAM, and DynamoDB
aws · Jun 29, 2023 · c67fcba · c67fcba
2 parents 68d5a8d + 0c9a599
commit c67fcba
Show file tree

Hide file tree

Showing 7 changed files with 552 additions and 46 deletions.
diff --git a/awscli/examples/dynamodb/create-table.rst b/awscli/examples/dynamodb/create-table.rst
@@ -573,3 +573,172 @@ Output::
     }
 
 For more information, see `Basic Operations for Tables <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html>`__ in the *Amazon DynamoDB Developer Guide*.
+
+**Example 8: To create a table with Keys-Only Stream enabled**
+
+The following example creates a table called ``GameScores`` with DynamoDB Streams enabled. Only the key attributes of modified items are written to the stream. ::
+
+    aws dynamodb create-table \
+        --table-name GameScores \
+        --attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
+        --key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
+        --provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
+        --stream-specification StreamEnabled=TRUE,StreamViewType=KEYS_ONLY  
+
+Output:: 
+
+    {
+        "TableDescription": {
+            "AttributeDefinitions": [
+                {
+                    "AttributeName": "GameTitle",
+                    "AttributeType": "S"
+                },
+                {
+                    "AttributeName": "UserId",
+                    "AttributeType": "S"
+                }
+            ],
+            "TableName": "GameScores",
+            "KeySchema": [
+                {
+                    "AttributeName": "UserId",
+                    "KeyType": "HASH"
+                },
+                {
+                    "AttributeName": "GameTitle",
+                    "KeyType": "RANGE"
+                }
+            ],
+            "TableStatus": "CREATING",
+            "CreationDateTime": "2023-05-25T18:45:34.140000+00:00",
+            "ProvisionedThroughput": {
+                "NumberOfDecreasesToday": 0,
+                "ReadCapacityUnits": 10,
+                "WriteCapacityUnits": 5
+            },
+            "TableSizeBytes": 0,
+            "ItemCount": 0,
+            "TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
+            "TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+            "StreamSpecification": {
+                "StreamEnabled": true,
+                "StreamViewType": "KEYS_ONLY"
+            },
+            "LatestStreamLabel": "2023-05-25T18:45:34.140",
+            "LatestStreamArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/stream/2023-05-25T18:45:34.140",
+            "DeletionProtectionEnabled": false
+        }
+    }
+
+For more information, see `Change data capture for DynamoDB Streams <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html>`__ in the *Amazon DynamoDB Developer Guide*.
+
+**Example 9: To create a table with the Standard Infrequent Access class**
+
+The following example creates a table called ``GameScores`` and assigns the Standard-Infrequent Access (DynamoDB Standard-IA) table class. This table class is optimized for storage being the dominant cost. ::
+    
+    aws dynamodb create-table \
+        --table-name GameScores \
+        --attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
+        --key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
+        --provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
+        --table-class STANDARD_INFREQUENT_ACCESS
+
+Output:: 
+
+    {
+        "TableDescription": {
+            "AttributeDefinitions": [
+                {
+                    "AttributeName": "GameTitle",
+                    "AttributeType": "S"
+                },
+                {
+                    "AttributeName": "UserId",
+                    "AttributeType": "S"
+                }
+            ],
+            "TableName": "GameScores",
+            "KeySchema": [
+                {
+                    "AttributeName": "UserId",
+                    "KeyType": "HASH"
+                },
+                {
+                    "AttributeName": "GameTitle",
+                    "KeyType": "RANGE"
+                }
+            ],
+            "TableStatus": "CREATING",
+            "CreationDateTime": "2023-05-25T18:33:07.581000+00:00",
+            "ProvisionedThroughput": {
+                "NumberOfDecreasesToday": 0,
+                "ReadCapacityUnits": 10,
+                "WriteCapacityUnits": 5
+            },
+            "TableSizeBytes": 0,
+            "ItemCount": 0,
+            "TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
+            "TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+            "TableClassSummary": {
+                "TableClass": "STANDARD_INFREQUENT_ACCESS"
+            },
+            "DeletionProtectionEnabled": false
+        }
+    }
+
+
+For more information, see `Table classes <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html>`__ in the *Amazon DynamoDB Developer Guide*.
+
+**Example 10: To Create a table with Delete Protection enabled**
+
+The following example creates a table called ``GameScores`` and enables deletion protection. ::
+
+    aws dynamodb create-table \
+        --table-name GameScores \
+        --attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
+        --key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
+        --provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
+        --deletion-protection-enabled 
+
+Output::
+
+    {
+        "TableDescription": {
+            "AttributeDefinitions": [
+                {
+                    "AttributeName": "GameTitle",
+                    "AttributeType": "S"
+                },
+                {
+                    "AttributeName": "UserId",
+                    "AttributeType": "S"
+                }
+            ],
+            "TableName": "GameScores",
+            "KeySchema": [
+                {
+                    "AttributeName": "UserId",
+                    "KeyType": "HASH"
+                },
+                {
+                    "AttributeName": "GameTitle",
+                    "KeyType": "RANGE"
+                }
+            ],
+            "TableStatus": "CREATING",
+            "CreationDateTime": "2023-05-25T23:02:17.093000+00:00",
+            "ProvisionedThroughput": {
+                "NumberOfDecreasesToday": 0,
+                "ReadCapacityUnits": 10,
+                "WriteCapacityUnits": 5
+            },
+            "TableSizeBytes": 0,
+            "ItemCount": 0,
+            "TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
+            "TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
+            "DeletionProtectionEnabled": true
+        }
+    }
+
+For more information, see `Using deletion protection <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.DeletionProtection>`__ in the *Amazon DynamoDB Developer Guide*.
diff --git a/awscli/examples/ec2/stop-instances.rst b/awscli/examples/ec2/stop-instances.rst
@@ -1,10 +1,9 @@
-**To stop an Amazon EC2 instance**
+**Example 1: To stop an Amazon EC2 instance**
 
-This example stops the specified Amazon EBS-backed instance.
+The following ``stop-instances`` example stops the specified Amazon EBS-backed instance. ::
 
-Command::
-
-  aws ec2 stop-instances --instance-ids i-1234567890abcdef0
+    aws ec2 stop-instances \
+        --instance-ids i-1234567890abcdef0
 
 Output::
 
@@ -24,7 +23,34 @@ Output::
         ]
     }
 
-For more information, see `Stop and Start Your Instance`_ in the *Amazon Elastic Compute Cloud User Guide*.
+For more information, see `Stop and Start Your Instance <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html>`__ in the *Amazon Elastic Compute Cloud User Guide*.
+
+**Example 2: To hibernate an Amazon EC2 instance**
+
+The following ``stop-instances`` example hibernates Amazon EBS-backed instance if the instance is enabled for hibernation and meets the hibernation prerequisites. 
+After the instance is put into hibernation the instance is stopped. ::
+
+    aws ec2 stop-instances \
+        --instance-ids i-1234567890abcdef0 \
+        --hibernate
+
+Output::
+
+    {
+        "StoppingInstances": [
+            {
+                "CurrentState": {
+                    "Code": 64,
+                    "Name": "stopping"
+                },
+                "InstanceId": "i-1234567890abcdef0",
+                "PreviousState": {
+                    "Code": 16,
+                    "Name": "running"
+                }
+            }
+        ]
+    }
 
-.. _`Stop and Start Your Instance`: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Stop_Start.html
+For more information, see `Hibernate your On-Demand Linux instance <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Hibernate.html>`__ in the *Amazon Elastic Cloud Compute User Guide*.
 
diff --git a/awscli/examples/iam/create-policy.rst b/awscli/examples/iam/create-policy.rst
@@ -1,22 +1,10 @@
-The following command creates a customer managed policy named ``my-policy``::
+**Example 1: To create a customer managed policy**
 
-  aws iam create-policy --policy-name my-policy --policy-document file://policy
+The following command creates a customer managed policy named ``my-policy``. ::
 
-Output::
-
-  {
-      "Policy": {
-          "PolicyName": "my-policy",
-          "CreateDate": "2015-06-01T19:31:18.620Z",
-          "AttachmentCount": 0,
-          "IsAttachable": true,
-          "PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
-          "DefaultVersionId": "v1",
-          "Path": "/",
-          "Arn": "arn:aws:iam::0123456789012:policy/my-policy",
-          "UpdateDate": "2015-06-01T19:31:18.620Z"
-      }
-  }
+  aws iam create-policy 
+    --policy-name my-policy
+    --policy-document file://policy
 
 The file ``policy`` is a JSON document in the current folder that grants read only access to the ``shared`` folder in an Amazon S3 bucket named ``my-bucket``::
 
@@ -36,6 +24,129 @@ The file ``policy`` is a JSON document in the current folder that grants read on
       ]
   }
 
-For more information on using files as input for string parameters, see `Specifying Parameter Values`_ in the *AWS CLI User Guide*.
+Output::
+
+  {
+      "Policy": {
+          "PolicyName": "my-policy",
+          "CreateDate": "2015-06-01T19:31:18.620Z",
+          "AttachmentCount": 0,
+          "IsAttachable": true,
+          "PolicyId": "ZXR6A36LTYANPAI7NJ5UV",
+          "DefaultVersionId": "v1",
+          "Path": "/",
+          "Arn": "arn:aws:iam::0123456789012:policy/my-policy",
+          "UpdateDate": "2015-06-01T19:31:18.620Z"
+      }
+  }
+
+For more information on using files as input for string parameters, see `Specifying Parameter Values <https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html>`_ in the *AWS CLI User Guide*.
+
+**Example 2: To create a customer managed policy with a description**
+
+The following command creates a customer managed policy named ``my-policy`` with an immutable description. ::
+
+    aws iam create-policy \
+        --policy-name my-policy \
+        --policy-document file://policy.json \
+        --description "This policy grants access to all Put, Get, and List actions for my-bucket"
+
+The file ``policy.json`` is a JSON document in the current folder that grants access to all Put, List, and Get actions for an Amazon S3 bucket named ``my-bucket``::
+
+   {
+       "Version": "2012-10-17",
+       "Statement": [
+           {
+               "Effect": "Allow",
+               "Action": [
+                    "s3:ListBucket*",
+                    "s3:PutBucket*",
+                    "s3:GetBucket*"
+                ],
+                "Resource": [
+                    "arn:aws:s3:::my-bucket"
+                ]
+            }
+        ]
+    }
+
+Output::
+
+    {
+        "Policy": {
+            "PolicyName": "my-policy",
+            "PolicyId": "ANPAWGSUGIDPEXAMPLE",
+            "Arn": "arn:aws:iam::123456789012:policy/my-policy",
+            "Path": "/",
+            "DefaultVersionId": "v1",
+            "AttachmentCount": 0,
+            "PermissionsBoundaryUsageCount": 0,
+            "IsAttachable": true,
+            "CreateDate": "2023-05-24T22:38:47+00:00",
+            "UpdateDate": "2023-05-24T22:38:47+00:00"
+        }
+    }
+
+For more information on Idenity-based Policies, see `Identity-based policies and resource-based policies <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html>`_ in the *AWS IAM User Guide*.
+
+**Example 3: To Create a customer managed policy with tags**
+
+The following command creates a customer managed policy named ``my-policy`` with tags. This example uses the ``--tags`` parameter flag with the following 
+JSON-formatted tags: ``'{"Key": "Department", "Value": "Accounting"}' '{"Key": "Location", "Value": "Seattle"}'``. Alternatively, the ``--tags`` flag can be 
+used with tags in the shorthand format: ``'Key=Department,Value=Accounting Key=Location,Value=Seattle'``. ::
+
+    aws iam create-policy \
+        --policy-name my-policy \
+        --policy-document file://policy.json \
+        --tags '{"Key": "Department", "Value": "Accounting"}' '{"Key": "Location", "Value": "Seattle"}'
+
+The file ``policy.json`` is a JSON document in the current folder that grants access to all Put, List, and Get actions for an Amazon S3 bucket named ``my-bucket``::
+
+   {
+       "Version": "2012-10-17",
+       "Statement": [
+           {
+               "Effect": "Allow",
+               "Action": [
+                    "s3:ListBucket*",
+                    "s3:PutBucket*",
+                    "s3:GetBucket*"
+                ],
+                "Resource": [
+                    "arn:aws:s3:::my-bucket"
+                ]
+            }
+        ]
+    }
+
+Output::
+    
+    {
+        "Policy": {
+            "PolicyName": "my-policy",
+            "PolicyId": "ANPAWGSUGIDPEXAMPLE",
+            "Arn": "arn:aws:iam::12345678012:policy/my-policy",
+            "Path": "/",
+            "DefaultVersionId": "v1",
+            "AttachmentCount": 0,
+            "PermissionsBoundaryUsageCount": 0,
+            "IsAttachable": true,
+            "CreateDate": "2023-05-24T23:16:39+00:00",
+            "UpdateDate": "2023-05-24T23:16:39+00:00",
+            "Tags": [
+                {
+                    "Key": "Department",
+                    "Value": "Accounting"
+                },
+                    "Key": "Location",
+                    "Value": "Seattle"
+                {
+
+            ]
+        }
+    }
+
+
+For more information on Tagging policies, see `Tagging customer managed policies <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags_customer-managed-policies.html>`__ in the *IAM User Guide*.
+
 
-.. _`Specifying Parameter Values`: http://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html