Add CLI examples for CloudWatch NetworkFlowMonitor (#9127)

aws · Jan 31, 2025 · e456c27 · e456c27
1 parent 60dccec
commit e456c27
Show file tree

Hide file tree

Showing 23 changed files with 396 additions and 0 deletions.
diff --git a/awscli/examples/networkflowmonitor/create-monitor.rst b/awscli/examples/networkflowmonitor/create-monitor.rst
@@ -0,0 +1,19 @@
+**To create a monitor**
+
+The following ``create-monitor`` example creates a monitor named ``demo`` in the specified account. ::
+
+    aws networkflowmonitor create-monitor \
+        --monitor-name demo \
+        --local-resources type="AWS::EC2::VPC",identifier="arn:aws:ec2:us-east-1:123456789012:vpc/vpc-03ea55eeda25adbb0"  \
+        --scope-arn arn:aws:networkflowmonitor:us-east-1:123456789012:scope/e21cda79-30a0-4c12-9299-d8629d76d8cf
+
+Output::
+
+    {
+        "monitorArn": "arn:aws:networkflowmonitor:us-east-1:123456789012:monitor/demo",
+        "monitorName": "demo",
+        "monitorStatus": "ACTIVE",
+        "tags": {}
+    }
+
+For more information, see `Create a monitor in Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-monitors-create.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/create-scope.rst b/awscli/examples/networkflowmonitor/create-scope.rst
@@ -0,0 +1,16 @@
+**To create a scope**
+
+The following ``create-scope`` example creates a scope that includes a set of resources for which Network Flow Monitor will generate network traffic metrics. ::
+
+    aws networkflowmonitor create-scope \
+        --targets '[{"targetIdentifier":{"targetId":{"accountId":"123456789012"},"targetType":"ACCOUNT"},"region":"us-east-1"}]'
+
+Output::
+
+    {
+        "scopeId": "97626f8d-8a21-4b5d-813a-1a0962dd4615",
+        "status": "IN_PROGRESS",
+        "tags": {}
+    }
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/delete-monitor.rst b/awscli/examples/networkflowmonitor/delete-monitor.rst
@@ -0,0 +1,10 @@
+**To delete a monitor**
+
+The following ``delete-monitor`` example deletes a monitor named ``demo`` in the specified account. ::
+
+    aws networkflowmonitor delete-monitor \
+        --monitor-name demo
+
+This command produces no output.
+
+For more information, see `Delete a monitor in Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-monitors-delete.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/delete-scope.rst b/awscli/examples/networkflowmonitor/delete-scope.rst
@@ -0,0 +1,10 @@
+**To delete a scope**
+
+The following ``delete-scope`` example deletes a specified scope. ::
+
+    aws networkflowmonitor delete-scope \
+        --scope-id fdc20616-6bb4-4242-a24e-a748e65ca7ac
+
+This command produces no output.
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/get-monitor.rst b/awscli/examples/networkflowmonitor/get-monitor.rst
@@ -0,0 +1,26 @@
+**To retrieve information about a monitor**
+
+The following ``get-monitor`` example displays information about the monitor named ``demo`` in the specified account. ::
+
+    aws networkflowmonitor get-monitor \ 
+        --monitor-name Demo
+
+Output::
+
+    {
+        "monitorArn": "arn:aws:networkflowmonitor:us-east-1:123456789012:monitor/Demo",
+        "monitorName": "Demo",
+        "monitorStatus": "ACTIVE",
+        "localResources": [
+            {
+                "type": "AWS::EC2::VPC",
+                "identifier": "arn:aws:ec2:us-east-1:123456789012:vpc/vpc-03ea55eeda25adbb0"
+            }
+        ],
+        "remoteResources": [],
+        "createdAt": "2024-12-09T12:21:51.616000-06:00",
+        "modifiedAt": "2024-12-09T12:21:55.412000-06:00",
+        "tags": {}
+    }
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...etworkflowmonitor/get-query-results-workload-insights-top-contributors-data.rst b/...etworkflowmonitor/get-query-results-workload-insights-top-contributors-data.rst
@@ -0,0 +1,30 @@
+**To retrieve the top contributor data on workload insights**
+
+The following ``get-query-results-workload-insights-top-contributors-data`` example returns the data for the specified query. ::
+
+    aws networkflowmonitor get-query-results-workload-insights-top-contributors-data \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id cc4f4ab3-3103-33b8-80ff-d6597a0c6cea
+
+Output::
+
+    {
+        "datapoints": [
+            {
+                "timestamps": [
+                    "2024-12-09T19:00:00+00:00",
+                    "2024-12-09T19:05:00+00:00",
+                    "2024-12-09T19:10:00+00:00"
+                ],
+                "values": [
+                    259943.0,
+                    194856.0,
+                    216432.0
+                ],
+                "label": "use1-az6"
+            }
+        ],
+        "unit": "Bytes"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...les/networkflowmonitor/get-query-results-workload-insights-top-contributors.rst b/...les/networkflowmonitor/get-query-results-workload-insights-top-contributors.rst
@@ -0,0 +1,27 @@
+**To retrieve the top contributors on workload insights**
+
+The following ``get-query-results-workload-insights-top-contributors`` example returns the data for the specified query. ::
+
+    aws networkflowmonitor get-query-results-workload-insights-top-contributors \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id 1fc423d3-b144-37a6-80e6-e2c7d26eea0c
+
+Output::
+
+    {
+        "topContributors": [
+            {
+                "accountId": "123456789012",
+                "localSubnetId": "subnet-0a5b30fb95dca2c14",
+                "localAz": "use1-az6",
+                "localVpcId": "vpc-03ea55eeda25adbb0",
+                "localRegion": "us-east-1",
+                "remoteIdentifier": "",
+                "value": 908443,
+                "localSubnetArn": "arn:aws:ec2:us-east-1:123456789012:subnet/subnet-0a5b30fb95dca2c14",
+                "localVpcArn": "arn:aws:ec2:us-east-1:123456789012:vpc/vpc-03ea55eeda25adbb0"
+            }
+        ]
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/get-query-status-monitor-top-contributors.rst b/awscli/examples/networkflowmonitor/get-query-status-monitor-top-contributors.rst
@@ -0,0 +1,15 @@
+**To retrieve the status of the query**
+
+The following ``get-query-status-monitor-top-contributors`` example displays the current status of the query in the specified account. ::
+
+    aws networkflowmonitor get-query-status-monitor-top-contributors \
+        --monitor-name Demo \
+        --query-id 5398eabd-bc40-3f5f-aba3-bcb639d3c7ca
+
+Output::
+
+    {
+        "status": "SUCCEEDED"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...networkflowmonitor/get-query-status-workload-insights-top-contributors-data.rst b/...networkflowmonitor/get-query-status-workload-insights-top-contributors-data.rst
@@ -0,0 +1,15 @@
+**To retrieve the status of the query**
+
+The following ``get-query-status-workload-insights-top-contributors-data`` example displays the current status of the query in the specified account. ::
+
+    aws networkflowmonitor get-query-status-workload-insights-top-contributors-data \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id 4333754d-8ae1-3f29-b6b7-c36db2e7f8ac
+
+Output::
+
+    {
+        "status": "SUCCEEDED"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...ples/networkflowmonitor/get-query-status-workload-insights-top-contributors.rst b/...ples/networkflowmonitor/get-query-status-workload-insights-top-contributors.rst
@@ -0,0 +1,15 @@
+**To retrieve the status of the query**
+
+The following ``get-query-status-workload-insights-top-contributors`` example displays the current status of the query in the specified account. ::
+
+    aws networkflowmonitor get-query-status-workload-insights-top-contributors \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id f2a87c70-3e5a-362e-8beb-4747d13d8419
+
+Output::
+
+    {
+        "status": "SUCCEEDED"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/get-scope.rst b/awscli/examples/networkflowmonitor/get-scope.rst
@@ -0,0 +1,28 @@
+**To retrieve information about a scope**
+
+The following ``get-scope`` example displays information about a scope, such as status, tags, name and target details. ::
+
+    aws networkflowmonitor get-scope \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf
+
+Output::
+
+    {
+        "scopeId": "e21cda79-30a0-4c12-9299-d8629d76d8cf",
+        "status": "SUCCEEDED",
+        "scopeArn": "arn:aws:networkflowmonitor:us-east-1:123456789012:scope/e21cda79-30a0-4c12-9299-d8629d76d8cf",
+        "targets": [
+            {
+                "targetIdentifier": {
+                    "targetId": {
+                        "accountId": "123456789012"
+                    },
+                    "targetType": "ACCOUNT"
+                },
+                "region": "us-east-1"
+            }
+        ],
+        "tags": {}
+    }
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/list-monitors.rst b/awscli/examples/networkflowmonitor/list-monitors.rst
@@ -0,0 +1,19 @@
+**To retrieve a list of monitors**
+
+The following ``list-monitors`` example returns returns all the monitors in the specified account. ::
+
+    aws networkflowmonitor list-monitors 
+
+Output::
+
+    {
+        "monitors": [
+            {
+                "monitorArn": "arn:aws:networkflowmonitor:us-east-1:123456789012:monitor/Demo",
+                "monitorName": "Demo",
+                "monitorStatus": "ACTIVE"
+            }
+        ]
+    }
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/list-scopes.rst b/awscli/examples/networkflowmonitor/list-scopes.rst
@@ -0,0 +1,19 @@
+**To retrieve a list of scopes**
+
+The following ``list-scopes`` example lists all scopes in the specified account. ::
+
+    aws networkflowmonitor list-scopes 
+
+Output::
+
+    {
+        "scopes": [
+            {
+                "scopeId": "fdc20616-6bb4-4242-a24e-a748e65ca7ac",
+                "status": "SUCCEEDED",
+                "scopeArn": "arn:aws:networkflowmonitor:us-east-1:123456789012:scope/fdc20616-6bb4-4242-a24e-a748e65ca7ac"
+            }
+        ]
+    }
+
+For more information, see `Components and features of Network Flow Monitor <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-components.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/list-tags-for-resource.rst b/awscli/examples/networkflowmonitor/list-tags-for-resource.rst
@@ -0,0 +1,17 @@
+**To list the tags**
+
+The following ``list-tags-for-resource`` example returns all the tags associated with the specified resource. ::
+
+    aws networkflowmonitor list-tags-for-resource \
+        --resource-arn arn:aws:networkflowmonitor:us-east-1:123456789012:monitor/Demo
+
+Output::
+
+    {
+        "tags": {
+            "Value": "Production",
+            "Key": "stack"
+        }
+    }
+
+For more information, see `Tagging your Amazon CloudWatch resources <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Tagging.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/start-query-monitor-top-contributors.rst b/awscli/examples/networkflowmonitor/start-query-monitor-top-contributors.rst
@@ -0,0 +1,18 @@
+**To start a query**
+
+The following ``start-query-monitor-top-contributors``  example starts the query which returns a query ID to retrieve the top contributors. ::
+
+    aws networkflowmonitor start-query-monitor-top-contributors \
+        --monitor-name Demo \
+        --start-time 2024-12-09T19:00:00Z \
+        --end-time 2024-12-09T19:15:00Z \
+        --metric-name DATA_TRANSFERRED \
+        --destination-category UNCLASSIFIED
+
+Output::
+
+    {
+        "queryId": "aecd3a88-0283-35b0-a17d-6e944dc8531d"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...ples/networkflowmonitor/start-query-workload-insights-top-contributors-data.rst b/...ples/networkflowmonitor/start-query-workload-insights-top-contributors-data.rst
@@ -0,0 +1,18 @@
+**To start a query**
+
+The following ``start-query-workload-insights-top-contributors-data``  example starts the query which returns a query ID to retrieve the top contributors. ::
+
+    aws networkflowmonitor start-query-workload-insights-top-contributors-data \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --start-time 2024-12-09T19:00:00Z \
+        --end-time 2024-12-09T19:15:00Z \
+        --metric-name DATA_TRANSFERRED \
+        --destination-category UNCLASSIFIED
+
+Output::
+
+    {
+        "queryId": "cc4f4ab3-3103-33b8-80ff-d6597a0c6cea"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/.../examples/networkflowmonitor/start-query-workload-insights-top-contributors.rst b/.../examples/networkflowmonitor/start-query-workload-insights-top-contributors.rst
@@ -0,0 +1,18 @@
+**To start a query**
+
+The following ``start-query-workload-insights-top-contributors``  example starts the query which returns a query ID to retrieve the top contributors. ::
+
+    aws networkflowmonitor start-query-workload-insights-top-contributors \
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --start-time 2024-12-09T19:00:00Z \
+        --end-time 2024-12-09T19:15:00Z \
+        --metric-name DATA_TRANSFERRED \
+        --destination-category UNCLASSIFIED
+
+Output::
+
+    {
+        "queryId": "1fc423d3-b144-37a6-80e6-e2c7d26eea0c"
+    }
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/networkflowmonitor/stop-query-monitor-top-contributors.rst b/awscli/examples/networkflowmonitor/stop-query-monitor-top-contributors.rst
@@ -0,0 +1,11 @@
+**To stop a query**
+
+The following ``stop-query-monitor-top-contributors`` example stops the query in the specified account. ::
+
+    aws networkflowmonitor stop-query-monitor-top-contributors \
+        --monitor-name Demo \
+        --query-id aecd3a88-0283-35b0-a17d-6e944dc8531d
+
+This command produces no output.
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...mples/networkflowmonitor/stop-query-workload-insights-top-contributors-data.rst b/...mples/networkflowmonitor/stop-query-workload-insights-top-contributors-data.rst
@@ -0,0 +1,11 @@
+**To stop a query**
+
+The following ``stop-query-workload-insights-top-contributors-data`` example stops the query in the specified account. ::
+
+    aws networkflowmonitor stop-query-workload-insights-top-contributors-data \ 
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id cc4f4ab3-3103-33b8-80ff-d6597a0c6cea
+
+This command produces no output.
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/...i/examples/networkflowmonitor/stop-query-workload-insights-top-contributors.rst b/...i/examples/networkflowmonitor/stop-query-workload-insights-top-contributors.rst
@@ -0,0 +1,11 @@
+**To stop a query**
+
+The following ``stop-query-workload-insights-top-contributors`` example stops the query in the specified account. ::
+
+    aws networkflowmonitor stop-query-workload-insights-top-contributors \ 
+        --scope-id e21cda79-30a0-4c12-9299-d8629d76d8cf \
+        --query-id 1fc423d3-b144-37a6-80e6-e2c7d26eea0c
+
+This command produces no output.
+
+For more information, see `Evaluate network flows with workload insights <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-NetworkFlowMonitor-configure-evaluate-flows.html>`__ in the *Amazon CloudWatch User Guide*.