scopes

Creates, updates, deletes, gets or lists a scopes resource.

Overview

Name	scopes
Type	Resource
Id	aws.networkflowmonitor.scopes

Fields

The following fields are returned by SELECT queries:

get_scope

Name	Datatype	Description
scope_arn	string	The Amazon Resource Name (ARN) of the scope. (pattern: <code>arn:.*</code>)
scope_id	string	The identifier for the scope that includes the resources you want to get data results for. A scope ID is an internally-generated identifier that includes all the resources for a specific root account. A scope ID is returned from a CreateScope API call.
status	string	The status for a scope. The status can be one of the following: SUCCEEDED, IN_PROGRESS, FAILED, DEACTIVATING, or DEACTIVATED. A status of DEACTIVATING means that you've requested a scope to be deactivated and Network Flow Monitor is in the process of deactivating the scope. A status of DEACTIVATED means that the deactivating process is complete. (SUCCEEDED, IN_PROGRESS, FAILED, DEACTIVATING, DEACTIVATED)
tags	object	The tags for a scope.
targets	array	The targets to define the scope to be monitored. A target is an array of targetResources, which are currently Region-account pairs, defined by targetResource constructs.

list_scopes

Name	Datatype	Description
scope_arn	string	The Amazon Resource Name (ARN) of the scope. (pattern: <code>arn:.*</code>)
scope_id	string	The identifier for the scope that includes the resources that you want to get data results for. A scope ID is an internally-generated identifier that includes all the resources for the accounts in a scope.
status	string	The status for a scope. The status can be one of the following: SUCCEEDED, IN_PROGRESS, FAILED, DEACTIVATING, or DEACTIVATED. A status of DEACTIVATING means that you've requested a scope to be deactivated and Network Flow Monitor is in the process of deactivating the scope. A status of DEACTIVATED means that the deactivating process is complete. (SUCCEEDED, IN_PROGRESS, FAILED, DEACTIVATING, DEACTIVATED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_scope	select	scope_id, region		Gets information about a scope, including the name, status, tags, and target details. The scope in Network Flow Monitor is an account.
list_scopes	select	region	nextToken, maxResults	List all the scopes for an account.
create_scope	insert	region, targets		In Network Flow Monitor, you specify a scope for the service to generate metrics for. By using the scope, Network Flow Monitor can generate a topology of all the resources to measure performance metrics for. When you create a scope, you enable permissions for Network Flow Monitor. A scope is a Region-account pair or multiple Region-account pairs. Network Flow Monitor uses your scope to determine all the resources (the topology) where Network Flow Monitor will gather network flow performance metrics for you. To provide performance metrics, Network Flow Monitor uses the data that is sent by the Network Flow Monitor agents you install on the resources. To define the Region-account pairs for your scope, the Network Flow Monitor API uses the following constucts, which allow for future flexibility in defining scopes: Targets, which are arrays of targetResources. Target resources, which are Region-targetIdentifier pairs. Target identifiers, made up of a targetID (currently always an account ID) and a targetType (currently always an account).
update_scope	update	scope_id, region		Update a scope to add or remove resources that you want to be available for Network Flow Monitor to generate metrics for, when you have active agents on those resources sending metrics reports to the Network Flow Monitor backend.
delete_scope	delete	scope_id, region		Deletes a scope that has been defined.
start_query_workload_insights_top_contributors	exec	scope_id, region, startTime, endTime, metricName, destinationCategory		Create a query with the Network Flow Monitor query interface that you can run to return workload insights top contributors. Specify the scope that you want to create a query for. The call returns a query ID that you can use with GetQueryResultsWorkloadInsightsTopContributors to run the query and return the top contributors for the workload insights for a scope. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable APIs for the top contributors that you want to be returned.
start_query_workload_insights_top_contributors_data	exec	scope_id, region, startTime, endTime, metricName, destinationCategory		Create a query with the Network Flow Monitor query interface that you can run to return data for workload insights top contributors. Specify the scope that you want to create a query for. The call returns a query ID that you can use with GetQueryResultsWorkloadInsightsTopContributorsData to run the query and return the data for the top contributors for the workload insights for a scope. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.
stop_query_workload_insights_top_contributors	exec	scope_id, query_id, region		Stop a top contributors query for workload insights. Specify the query that you want to stop by providing a query ID and a scope ID. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.
stop_query_workload_insights_top_contributors_data	exec	scope_id, query_id, region		Stop a top contributors data query for workload insights. Specify the query that you want to stop by providing a query ID and a scope ID. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
query_id	string	The identifier for the query. A query ID is an internally-generated identifier for a specific query returned from an API call to create a query.
region	string	AWS region (default: us-east-1)
scope_id	string	The identifier for the scope that includes the resources you want to get data results for. A scope ID is an internally-generated identifier that includes all the resources for a specific root account.
maxResults	integer	The number of query results that you want to return with this call.
nextToken	string	The token for the next set of results. You receive this token from a previous call.

SELECT examples

get_scope

Gets information about a scope, including the name, status, tags, and target details. The scope in Network Flow Monitor is an account.

SELECT
scope_arn,
scope_id,
status,
tags,
targets
FROM aws.networkflowmonitor.scopes
WHERE scope_id = '{{ scope_id }}' -- required
AND region = '{{ region }}' -- required
;

list_scopes

List all the scopes for an account.

SELECT
scope_arn,
scope_id,
status
FROM aws.networkflowmonitor.scopes
WHERE region = '{{ region }}' -- required
AND nextToken = '{{ nextToken }}'
AND maxResults = '{{ maxResults }}'
;

INSERT examples

create_scope

In Network Flow Monitor, you specify a scope for the service to generate metrics for. By using the scope, Network Flow Monitor can generate a topology of all the resources to measure performance metrics for. When you create a scope, you enable permissions for Network Flow Monitor. A scope is a Region-account pair or multiple Region-account pairs. Network Flow Monitor uses your scope to determine all the resources (the topology) where Network Flow Monitor will gather network flow performance metrics for you. To provide performance metrics, Network Flow Monitor uses the data that is sent by the Network Flow Monitor agents you install on the resources. To define the Region-account pairs for your scope, the Network Flow Monitor API uses the following constucts, which allow for future flexibility in defining scopes: Targets, which are arrays of targetResources. Target resources, which are Region-targetIdentifier pairs. Target identifiers, made up of a targetID (currently always an account ID) and a targetType (currently always an account).

INSERT INTO aws.networkflowmonitor.scopes (
targets,
clientToken,
tags,
region
)
SELECT 
'{{ targets }}' /* required */,
'{{ clientToken }}',
'{{ tags }}',
'{{ region }}'
RETURNING
scope_arn,
scope_id,
status,
tags
;

Manifest

# Description fields are for documentation purposes
- name: scopes
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the scopes resource.
  - name: targets
    value:
      - targetIdentifier:
          targetId:
            accountId: "{{ accountId }}"
          targetType: "{{ targetType }}"
        region: "{{ region }}"
  - name: clientToken
    value: "{{ clientToken }}"
  - name: tags
    value: "{{ tags }}"

UPDATE examples

update_scope

Update a scope to add or remove resources that you want to be available for Network Flow Monitor to generate metrics for, when you have active agents on those resources sending metrics reports to the Network Flow Monitor backend.

UPDATE aws.networkflowmonitor.scopes
SET 
resourcesToAdd = '{{ resourcesToAdd }}',
resourcesToDelete = '{{ resourcesToDelete }}'
WHERE 
scope_id = '{{ scope_id }}' --required
AND region = '{{ region }}' --required
RETURNING
scope_arn,
scope_id,
status,
tags;

DELETE examples

delete_scope

Deletes a scope that has been defined.

DELETE FROM aws.networkflowmonitor.scopes
WHERE scope_id = '{{ scope_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

start_query_workload_insights_top_contributors

Create a query with the Network Flow Monitor query interface that you can run to return workload insights top contributors. Specify the scope that you want to create a query for. The call returns a query ID that you can use with GetQueryResultsWorkloadInsightsTopContributors to run the query and return the top contributors for the workload insights for a scope. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable APIs for the top contributors that you want to be returned.

EXEC aws.networkflowmonitor.scopes.start_query_workload_insights_top_contributors 
@scope_id='{{ scope_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"startTime": "{{ startTime }}", 
"endTime": "{{ endTime }}", 
"metricName": "{{ metricName }}", 
"destinationCategory": "{{ destinationCategory }}", 
"limit": {{ limit }}
}'
;

start_query_workload_insights_top_contributors_data

Create a query with the Network Flow Monitor query interface that you can run to return data for workload insights top contributors. Specify the scope that you want to create a query for. The call returns a query ID that you can use with GetQueryResultsWorkloadInsightsTopContributorsData to run the query and return the data for the top contributors for the workload insights for a scope. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.

EXEC aws.networkflowmonitor.scopes.start_query_workload_insights_top_contributors_data 
@scope_id='{{ scope_id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"startTime": "{{ startTime }}", 
"endTime": "{{ endTime }}", 
"metricName": "{{ metricName }}", 
"destinationCategory": "{{ destinationCategory }}"
}'
;

stop_query_workload_insights_top_contributors

Stop a top contributors query for workload insights. Specify the query that you want to stop by providing a query ID and a scope ID. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.

EXEC aws.networkflowmonitor.scopes.stop_query_workload_insights_top_contributors 
@scope_id='{{ scope_id }}' --required, 
@query_id='{{ query_id }}' --required, 
@region='{{ region }}' --required
;

stop_query_workload_insights_top_contributors_data

Stop a top contributors data query for workload insights. Specify the query that you want to stop by providing a query ID and a scope ID. Top contributors in Network Flow Monitor are network flows with the highest values for a specific metric type. Top contributors can be across all workload insights, for a given scope, or for a specific monitor. Use the applicable call for the top contributors that you want to be returned.

EXEC aws.networkflowmonitor.scopes.stop_query_workload_insights_top_contributors_data 
@scope_id='{{ scope_id }}' --required, 
@query_id='{{ query_id }}' --required, 
@region='{{ region }}' --required
;