# 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](#getting-started-step1)
+ [Step 2: Read (describe) a resource](#getting-started-step2)
+ [Step 3: Update a resource](#getting-started-step3)
+ [Step 4: List all resources of a certain type](#getting-started-list)
+ [Step 5: Delete a resource](#getting-started-cleanup)
+ [Next steps](#getting-started-next-steps)
## Step 1: Create a resource
For this tutorial, create a resource of type `[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-logs-loggroup.html)`. 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"
}
}
```
1. 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](resource-operations-update.md#resource-operations-update-patch).
```
$ 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"
}
}
```
1. 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"
}
}
```
1. 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](resource-operations.md).