Getting started with Cloud Control API - Cloud Control API
Create a resourceRead a resourceUpdate a resourceList resourcesDelete a resourceNext steps

Getting started with Cloud Control API

Use this short tutorial to get started performing resource operations with AWS 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 AWS Command Line Interface (AWS 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": "2024-08-26T22:07:23.347Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "IN_PROGRESS",
        "Operation": "CREATE",
        "Identifier": "CloudControlExample",
        "RequestToken": "758f4a4e-fef4-491a-9b07-123456789012"
    }
}

  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-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 created the resource, it sets the OperationStatus value to SUCCESS.

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

Step 2: Read (describe) a resource

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

  • In the AWS 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:123456789012:log-group:CloudControlExample:*"}'
    }
}

Step 3: Update a resource

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

  1. In the AWS 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": "2024-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-123456789012"
    }
}

  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": "2024-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 AWS account.

  • In the AWS 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:123456789012:log-group:CloudControlExample:*"}'
        },
        {
            "Identifier": "AnotherLogGroupResourceExample",
            "Properties": '{"RetentionInDays": 90, "LogGroupName": "AnotherLogGroupResourceExample", "Arn": "arn:aws:logs:us-west-2:123456789012:log-group:AnotherLogGroupResourceExample:*"}'
        },
    ]
}

Step 5: Delete a resource

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

  1. In the AWS 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": "2024-08-26T22:50:20.037Z",
        "TypeName": "AWS::Logs::LogGroup",
        "OperationStatus": "IN_PROGRESS",
        "Operation": "DELETE",
        "Identifier": "CloudControlExample",
        "RequestToken": "bb0ed9cd-84f9-44c2-b638-123456789012"
    }
}

  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 bb0ed9cd-84f9-44c2-b638-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 deleted the resource, it sets the OperationStatus value to SUCCESS.

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

Next steps

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