Using the Amazon CLI to create and manage multi-Region tables - Amazon Keyspaces (for Apache Cassandra)
Creating a new multi-Region keyspace (CLI)Creating a new multi-Region table with default settings (CLI)Creating a new multi-Region table in provisioned mode with auto scaling (CLI)Updating the provisioned capacity and auto scaling settings of a multi-Region table (CLI)Viewing the provisioned capacity and auto scaling settings of a multi-Region table (CLI)Turning off auto scaling for a multi-Region table (CLI)Setting the provisioned capacity of a multi-Region table manually (CLI)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using the Amazon CLI to create and manage multi-Region tables

You can use the Amazon Command Line Interface (Amazon CLI) to create and manage multi-Region keyspaces and tables in Amazon Keyspaces.

This section provides examples of how to create and manage multi-Region tables with the Amazon CLI. All tables that you create in a multi-Region keyspace automatically inherit the multi-Region settings from the keyspace.

For more information about the Amazon Keyspaces Amazon CLI commands described in this topic, see the Amazon CLI Command Reference for Amazon Keyspaces.

Creating a new multi-Region keyspace (CLI)

To create a multi-Region keyspace, you can use the following CLI statement. Specify your current Region and at least one additional Region in the regionList.

aws keyspaces create-keyspace --keyspace-name mykeyspace 
             \ --replication-specification replicationStrategy=MULTI_REGION,regionList=us-east-1,eu-west-1
Note

When creating a multi-Region keyspace, Amazon Keyspaces creates a service-linked role with the name AWSServiceRoleForAmazonKeyspacesReplication in your account. This role allows Amazon Keyspaces to replicate writes to all replicas of a multi-Region table on your behalf. To learn more, see Using roles for Amazon Keyspaces Multi-Region Replication.

Creating a new multi-Region table with default settings (CLI)

To create a multi-Region table with default settings, you only need to specify the schema. You can use the following example.

aws keyspaces create-table --keyspace-name mykeyspace --table-name mytable 
            \ --schema-definition 'allColumns=[{name=pk,type=int}],partitionKeys={name= pk}'

The output of the command is:

{
    "resourceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/mykeyspace/table/mytable"
}

To confirm the table's settings, you can use the following statement.

aws keyspaces get-table --keyspace-name mykeyspace --table-name mytable

The output shows all default settings of a multi-Region table. 

{
    "keyspaceName": "mykeyspace",
    "tableName": "mytable",
    "resourceArn": "arn:aws:cassandra:us-east-1:111122223333:/keyspace/mykeyspace/table/mytable",
    "creationTimestamp": "2023-12-19T16:50:37.639000+00:00",
    "status": "ACTIVE",
    "schemaDefinition": {
        "allColumns": [
            {
                "name": "pk",
                "type": "int"
            }
        ],
        "partitionKeys": [
            {
                "name": "pk"
            }
        ],
        "clusteringKeys": [],
        "staticColumns": []
    },
    "capacitySpecification": {
        "throughputMode": "PAY_PER_REQUEST",
        "lastUpdateToPayPerRequestTimestamp": "2023-12-19T16:50:37.639000+00:00"
    },
    "encryptionSpecification": {
        "type": "AWS_OWNED_KMS_KEY"
    },
    "pointInTimeRecovery": {
        "status": "DISABLED"
    },
    "defaultTimeToLive": 0,
    "comment": {
        "message": ""
    },
    "clientSideTimestamps": {
        "status": "ENABLED"
    },
    "replicaSpecifications": [
        {
            "region": "us-east-1",
            "status": "ACTIVE",
            "capacitySpecification": {
                "throughputMode": "PAY_PER_REQUEST",
                "lastUpdateToPayPerRequestTimestamp": 1702895811.469
            }
        },
        {
            "region": "eu-north-1",
            "status": "ACTIVE",
            "capacitySpecification": {
                "throughputMode": "PAY_PER_REQUEST",
                "lastUpdateToPayPerRequestTimestamp": 1702895811.121
            }
        }
    ]
}

Creating a new multi-Region table in provisioned mode with auto scaling (CLI)

To create a multi-Region table in provisioned mode with auto scaling configuration, you can use the Amazon CLI. Note that you must use the Amazon Keyspaces CLI create-table command to configure multi-Region auto scaling settings. This is because Application Auto Scaling, the service that Amazon Keyspaces uses to perform auto scaling on your behalf, doesn't support multiple Regions.

For more information about auto scaling settings, the target tracking policy, target value, and optional settings, see Create a new table with automatic scaling using the Amazon CLI.

When you create a new multi-Region table in provisioned mode with auto scaling settings, you can specify the general settings for the table that are valid for all Amazon Web Services Regions that the table is replicated in. You can then overwrite read capacity settings and read auto scaling settings for each replica. The write capacity, however, remains synchronized between all replicas to ensure that there's enough capacity to replicate writes across all Regions.

To define the read capacity for a table replica in a specific Region, you can configure the following parameters as part of the table's replicaSpecifications:

  • The Region

  • The provisioned read capacity units (optional)

  • Auto scaling settings for read capacity (optional)

When you're creating provisioned multi-Region tables with complex auto scaling settings and different configurations for table replicas, it's helpful to load the table's auto scaling settings and replica configurations from JSON files.

To use the following code example, you can download the example JSON files from auto-scaling.zip, and extract auto-scaling.json and replication.json. Take note of the path to the files.

In this example, the JSON files are located in the current directory. For different file path options, see How to load parameters from a file.

aws keyspaces create-table --keyspace-name mykeyspace --table-name mytable 
           \ --schema-definition 'allColumns=[{name=pk,type=int},{name=ck,type=int}],partitionKeys=[{name=pk},{name=ck}]' 
           \ --capacity-specification throughputMode=PROVISIONED,readCapacityUnits=1,writeCapacityUnits=1 
           \ --auto-scaling-specification file://auto-scaling.json 
           \ --replica-specifications file://replication.json

Updating the provisioned capacity and auto scaling settings of a multi-Region table (CLI)

To update the provisioned mode and auto scaling configuration of an existing table, you can use the Amazon CLI update-table command.

Note that you must use the Amazon Keyspaces CLI commands to create or modify multi-Region auto scaling settings. This is because Application Auto Scaling, the service that Amazon Keyspaces uses to perform auto scaling of table capacity on your behalf, doesn't support multiple Amazon Web Services Regions.

When you update the provisioned mode or auto scaling settings of a multi-Region table, you can update read capacity settings and the read auto scaling configuration for each replica of the table.

The write capacity, however, remains synchronized between all replicas to ensure that there's enough capacity to replicate writes across all Regions. To update the read capacity for a table replica in a specific Region, you can change one of the following optional parameters of the table's replicaSpecifications:

  • The provisioned read capacity units (optional)

  • Auto scaling settings for read capacity (optional)

When you're updating multi-Region tables with complex auto scaling settings and different configurations for table replicas, it's helpful to load the table's auto scaling settings and replica configurations from JSON files.

To use the following code example, you can download the example JSON files from auto-scaling.zip, and extract auto-scaling.json and replication.json. Take note of the path to the files.

In this example, the JSON files are located in the current directory. For different file path options, see How to load parameters from a file.

aws keyspaces update-table --keyspace-name mykeyspace --table-name mytable 
           \ --capacity-specification throughputMode=PROVISIONED,readCapacityUnits=1,writeCapacityUnits=1 
           \ --auto-scaling-specification file://auto-scaling.json 
           \ --replica-specifications file://replication.json

Viewing the provisioned capacity and auto scaling settings of a multi-Region table (CLI)

To view the auto scaling configuration of a multi-Region table, you can use the get-table-auto-scaling-settings operation. The following CLI command is an example of this.

aws keyspaces get-table-auto-scaling-settings --keyspace-name mykeyspace --table-name mytable

You should see the following output.

{
    "keyspaceName": "mykeyspace",
    "tableName": "mytable",
    "resourceArn": "arn:aws:cassandra:us-east-1:777788889999:/keyspace/mykeyspace/table/mytable",
    "autoScalingSpecification": {
        "writeCapacityAutoScaling": {
            "autoScalingDisabled": false,
            "minimumUnits": 5,
            "maximumUnits": 10,
            "scalingPolicy": {
                "targetTrackingScalingPolicyConfiguration": {
                    "disableScaleIn": false,
                    "scaleInCooldown": 0,
                    "scaleOutCooldown": 0,
                    "targetValue": 50.0
                }
            }
        },
        "readCapacityAutoScaling": {
            "autoScalingDisabled": false,
            "minimumUnits": 5,
            "maximumUnits": 20,
            "scalingPolicy": {
                "targetTrackingScalingPolicyConfiguration": {
                    "disableScaleIn": false,
                    "scaleInCooldown": 60,
                    "scaleOutCooldown": 60,
                    "targetValue": 70.0
                }
            }
        }
    },
    "replicaSpecifications": [
        {
            "region": "us-east-1",
            "autoScalingSpecification": {
                "writeCapacityAutoScaling": {
                    "autoScalingDisabled": false,
                    "minimumUnits": 5,
                    "maximumUnits": 10,
                    "scalingPolicy": {
                        "targetTrackingScalingPolicyConfiguration": {
                            "disableScaleIn": false,
                            "scaleInCooldown": 0,
                            "scaleOutCooldown": 0,
                            "targetValue": 50.0
                        }
                    }
                },
                "readCapacityAutoScaling": {
                    "autoScalingDisabled": false,
                    "minimumUnits": 5,
                    "maximumUnits": 20,
                    "scalingPolicy": {
                        "targetTrackingScalingPolicyConfiguration": {
                            "disableScaleIn": false,
                            "scaleInCooldown": 60,
                            "scaleOutCooldown": 60,
                            "targetValue": 70.0
                        }
                    }
                }
            }
        },
        {
            "region": "eu-north-1",
            "autoScalingSpecification": {
                "writeCapacityAutoScaling": {
                    "autoScalingDisabled": false,
                    "minimumUnits": 5,
                    "maximumUnits": 10,
                    "scalingPolicy": {
                        "targetTrackingScalingPolicyConfiguration": {
                            "disableScaleIn": false,
                            "scaleInCooldown": 0,
                            "scaleOutCooldown": 0,
                            "targetValue": 50.0
                        }
                    }
                },
                "readCapacityAutoScaling": {
                    "autoScalingDisabled": false,
                    "minimumUnits": 5,
                    "maximumUnits": 10,
                    "scalingPolicy": {
                        "targetTrackingScalingPolicyConfiguration": {
                            "disableScaleIn": false,
                            "scaleInCooldown": 60,
                            "scaleOutCooldown": 60,
                            "targetValue": 50.0
                        }
                    }
                }
            }
        }
    ]
}

Turning off auto scaling for a multi-Region table (CLI)

You can use the Amazon CLI update-table command to turn off auto scaling for an existing table. Note that you can't turn off auto scaling for an individual table replica.

In the following example, auto scaling is turned off for the table's read capacity.

aws keyspaces update-table --keyspace-name mykeyspace --table-name mytable 
           \ --auto-scaling-specification readCapacityAutoScaling={autoScalingDisabled=true}
Note

To delete the service-linked role that's used by Application Auto Scaling, you must disable automatic scaling on all tables in the account across all Amazon Web Services Regions.

Setting the provisioned capacity of a multi-Region table manually (CLI)

If you have to turn off auto scaling for a multi-Region table, you can use update-table to provision the table's read capacity for a replica table manually.

aws keyspaces update-table --keyspace-name mykeyspace --table-name mytable 
           \ --capacity-specification throughputMode=PROVISIONED,readCapacityUnits=1,writeCapacityUnits=1 
           \ --replica-specifications region="us-east-1",readCapacityUnits=5
Note

We recommend using auto scaling for multi-Region tables that use provisioned capacity. For more information, see Working with multi-Region tables in Amazon Keyspaces.