[metadata]
abstract: Insert abstract text
assets_root: /assets
default_state: getting-started
deployment_region: IAD
description: Get started with Cloud Control API. Learn to perform CRUD-L operations on a resource.
feedback-item: CloudFormation
feedback-no: feedbackno.html?topic_url=https://docs.aws.amazon.com/en_us/cloudcontrolapi/latest/userguide/getting-started.html
feedback-yes: feedbackyes.html?topic_url=https://docs.aws.amazon.com/en_us/cloudcontrolapi/latest/userguide/getting-started.html
feedback: https://docs.aws.amazon.com/forms/aws-doc-feedback?hidden_service_name=CloudFormation&topic_url=https://docs.aws.amazon.com/en_us/cloudcontrolapi/latest/userguide/getting-started.html
forums: https://repost.aws/tags/TArPmMO7eHRYympxY7eh_tXA
guide-locale: en_us
guide: User Guide
keywords: Cloud Control API,cloudapi
pdf: /pdfs/cloudcontrolapi/latest/userguide/cloudapi-service.pdf#getting-started
product: Cloud Control API
rss: cloudapi-service.rss
target_state: getting-started
this_doc_guide: User Guide
this_doc_product: Cloud Control API
tocs: toc-contents.json
viewport: width=device-width,initial-scale=1

[canonical-links]
https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/getting-started.html

[document-links]
/pdfs/cloudcontrolapi/latest/userguide/cloudapi-service.pdf#getting-started
AWS Cloud Control API: /cloudcontrolapi/index.html
AWS::Logs::LogGroup: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html
Cloud Control API resource operations: ./resource-operations.html
Composing the patch document: ./resource-operations-update.html#resource-operations-update-patch
Document Conventions: /general/latest/gr/docconventions.html
Documentation: /index.html
User Guide: what-is-cloudcontrolapi.html
View a markdown version of this page: getting-started.md

[structured-data]
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://aws.amazon.com","name":"AWS","position":1},{"@type":"ListItem","item":"https://docs.aws.amazon.com/cloudcontrolapi/index.html","name":"AWS Cloud Control API","position":2},{"@type":"ListItem","item":"https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide","name":"User Guide","position":3},{"@type":"ListItem","item":"https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/getting-started.html","name":"Getting started with Cloud Control API","position":4}]}

[content]
Getting started with Cloud Control API - Cloud Control API
View a markdown version of this page
Getting started with Cloud Control API - Cloud Control API
Documentation
AWS Cloud Control API
User Guide
Create a resource
Read a resource
Update a resource
List resources
Delete a resource
Next 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.
Topics
Step 1: Create a resource
Step 2: Read (describe) a resource
Step 3: Update a resource
Step 4: List all resources of a certain type
Step 5: Delete a resource
Next steps
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.
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" } }
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.
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" } }
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.
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" } }
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
.
Document Conventions
Setting up
Cloud Control API resource operations
Did this page help you? - Yes
Thanks for letting us know we're doing a good job!
If you've got a moment, please tell us what we did right so we can do more of it.
Did this page help you? - No
Thanks for letting us know this page needs work. We're sorry we let you down.
If you've got a moment, please tell us how we can make the documentation better.
