Getting started with Cloud Control API - Cloud Control API
Create a resourceRead a resourceUpdate a resourceList resourcesDelete a resourceNext steps
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).

Getting started with Cloud Control API

Use this short tutorial to get started performing resource operations with Amazon Cloud Control API. You'll learn the basics of using Cloud Control API to create, read, update, delete, and list resources.

Step 1: Create a resource

For this tutorial, create a resource of type AWS::Logs::LogGroup. Name this log group CloudControlExample, and set the retention policy on it to 90 days.

  1. In the Amazon Command Line Interface (Amazon CLI), run the create-resource command with the following parameters:

    • Specify the type-name as AWS::Logs::LogGroup.

    • Specify the desired-state as a string containing JSON that sets the desired properties:

      {"LogGroupName": "CloudControlExample", "RetentionInDays": 90}

    $ aws cloudcontrol create-resource --type-name AWS::Logs::LogGroup \
    --desired-state '{"LogGroupName": "CloudControlExample","RetentionInDays":90}'

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:07:23.347Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "IN_PROGRESS",
        "Operation": "CREATE",
        "Identifier": "CloudControlExample",
        "RequestToken": "758f4a4e-fef4-491a-9b07-00123456789"
    }
}

  2. To track the status of your resource operation request, run the get-resource-request-status command with the following parameter:

    • Specify the request-token parameter as the RequestToken property value returned in the ProgressEvent object.

    $ aws cloudcontrol get-resource-request-status --request-token 758f4a4e-fef4-491a-9b07-00123456789

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request. When Cloud Control API has successfully created the resource, it sets the OperationStatus value to SUCCESS.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:29:23.326Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "SUCCESS",
        "Operation": "CREATE",
        "Identifier": "CloudControlExample",
        "RequestToken": "758f4a4e-fef4-491a-9b07-00123456789"
    }
}

Step 2: Read (describe) a resource

Next, read the current state of the resource you just created.

  • In the Amazon CLI, run the get-resource command with the following parameter:

    • Specify identifier as the identifier property value returned in the ProgressEvent object when you created the resource. In this case, it's CloudControlExample, the name you specified for the log group.

    $ aws cloudcontrol get-resource --type-name AWS::Logs::LogGroup --identifier CloudControlExample

    Cloud Control API returns detailed information about the resource's current state, including a model of its properties and settings. In this case, this includes a property, Arn, that was generated by Amazon CloudWatch Events when the resource was created.

    {
    "TypeName": "AWS::Logs::LogGroup", 
    "ResourceDescription": {
        "Identifier": "CloudControlExample", 
        "ResourceModel": '{"RetentionInDays": 90, "LogGroupName": "CloudControlExample", "Arn": "arn:aws:logs:us-west-2:090123456789:log-group:CloudControlExample:*"}'
    }
}

Step 3: Update a resource

Next, update your log group to double the retention policy to 180 days.

  1. In the Amazon CLI, run the update-resource command with the following parameter:

    • Specify the type-name as AWS::Logs::LogGroup.

    • Specify identifier as the identifier property value returned in the ProgressEvent object when you created the resource. In this case, it's CloudControlExample, the name you specified for the log group.

    • Specify the patch-document parameter as a string containing JSON that represents a replacement operation that updates the retention policy to 180 days.

      [{"op": "replace", "path": "RetentionInDays", "value": 180}]

      For detailed information about composing patch documents, see Composing the patch document.

    $ aws cloudcontrol update-resource --type-name AWS::Logs::LogGroup \
    --identifier CloudControlExample \
    --patch-document '[{"op": "replace", "path": "RetentionInDays", "value":180}]'

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:29:22.547Z", 
        "ResourceModel": '{"RetentionInDays":180,"LogGroupName":"CloudControlExample"}',
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "IN_PROGRESS",
        "Operation": "UPDATE",
        "Identifier": "CloudControlExample", 
        "RequestToken": "2026055d-f21c-4b50-bd40-111111111111"
    }
}

  2. To track the status of your resource operation request, run the get-resource-request-status command with the following parameter:

    • Specify the request-token parameter as the RequestToken property value returned in the ProgressEvent object.

    $ aws cloudcontrol get-resource-request-status --request-token 2026055d-f21c-4b50-bd40-123456789012

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request. When Cloud Control API has successfully updated the resource, it sets the OperationStatus value to SUCCESS.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:29:23.326Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "SUCCESS",
        "Operation": "UPDATE",
        "Identifier": "CloudControlExample",
        "RequestToken": "2026055d-f21c-4b50-bd40-123456789012"
    }
}

Step 4: List all resources of a certain type

Next, use Cloud Control API to discover resources in your Amazon Web Services account.

  • In the Amazon CLI, run the list-resources command with the following parameter:

    • Specify the type-name as AWS::Logs::LogGroup.

    $ aws cloudcontrol list-resources --type-name AWS::Logs::LogGroup

    Cloud Control API returns a list of the AWS::Logs::LogGroup resources in your account, by primary identifier. This includes CloudControlExample, the resource you created as part of this tutorial, in addition to any other log groups that already exist in your account. Also, for AWS::Logs::LogGroup resources, the information returned by list-resources includes the properties for each resource.

    {
    "TypeName": "AWS::Logs::LogGroup",
    "ResourceDescriptions": [
        {
            "Identifier": "CloudControlExample",
            "Properties": '{"RetentionInDays":180, "LogGroupName": "CloudControlExample", "Arn":"arn:aws:logs:us-west-2:090123456789:log-group:CloudControlExample:*"}'
        },
        {
            "Identifier": "AnotherLogGroupResourceExample",
            "Properties": '{"RetentionInDays": 90, "LogGroupName": "AnotherLogGroupResourceExample", "Arn": "arn:aws:logs:us-west-2:011111111111:log-group:AnotherLogGroupResourceExample:*"}'
        },
    ]
}

Step 5: Delete a resource

Finally, delete your log group to clean up from this tutorial.

  1. In the Amazon CLI, run the delete-resource command with the following parameter:

    • Specify the type-name as AWS::Logs::LogGroup.

    • Specify identifier as the identifier property value returned in the ProgressEvent object when you created the resource. In this case, it's CloudControlExample, the name you specified for the log group.

    $ aws cloudcontrol delete-resource --type-name AWS::Logs::LogGroup --identifier CloudControlExample

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:50:20.037Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "IN_PROGRESS",
        "Operation": "DELETE",
        "Identifier": "CloudControlExample",
        "RequestToken": "bb0ed9cd-84f9-44c2-b638-000000000000"
    }
}

  2. To track the status of your resource operation request, run the get-resource-request-status command with the following parameter:

    • Specify the request-token parameter as the RequestToken property value returned in the ProgressEvent object.

    $ aws cloudcontrol get-resource-request-status --request-token 2026055d-f21c-4b50-bd40-111111111111

    Cloud Control API returns a ProgressEvent object that contains information about the status of your resource operation request. When Cloud Control API has successfully deleted the resource, it sets the OperationStatus value to SUCCESS.

    {
    "ProgressEvent": {
        "EventTime": "2021-08-26T22:50:20.831Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "SUCCESS",
        "Operation": "DELETE",
        "Identifier": "CloudControlExample",
        "RequestToken": "bb0ed9cd-84f9-44c2-b638-000000000000"
    }
}

Next steps

For detailed information and examples on using Cloud Control API with resources, see Performing resource operations.