Boto3 Services¶
Classes wrapping ServiceResource
objects.
The methods and arguments on these classes somtimes differ in name from those in Boto3’s Resources to make them easier to understand in this context..
- Glossary:
- service_name:
The snake_case name of an AWS service (e.g.
ec2
)- resource_type:
The (unpluralised) snake_case name of the type of the resource in snake case (e.g.
instance
)- secondary_attribute:
An attribute of a resource which requires a secondary API call to retrieve (e.g. VPC Attributes)
- subresource:
A child resource which does not have its own ARN and must be queried by referencing its parent resource’s ID (e.g. inline role policies). Different from Boto3 subresources which simply indicate a hierarchical relationship between resources (e.g. subnets are a child resource of vpcs).
-
class
Boto3Services
(boto3_session=None, service_loader=None, service_mapping_loader=None, account_id=None)¶ Wraps Boto3 Session.
Allows us to:
Wrap Boto3 ServiceResource objects with CloudWandererBoto3Service objects.
Inject custom service definitions into our
CloudWandererBoto3ResourceFactory
and return them alongside the default Boto3 ServiceResource objects.
Used by
CloudWandererAWSInterface
to instantiate services and can be used to get resources from their URN.-
__init__
(boto3_session=None, service_loader=None, service_mapping_loader=None, account_id=None)¶ Initialise the Boto3SessionWrapper.
- Parameters
boto3_session (Optional[boto3.session.Session]) – The
boto3.session.Session
object to use for any queries.service_loader (Optional[cloudwanderer.boto3_loaders.MergedServiceLoader]) – Optionally specify your own service loader if you wish to insert your own resources.
service_mapping_loader (Optional[cloudwanderer.boto3_loaders.ServiceMappingLoader]) – Optionally specify your own service mapping loader if you wish to insert your own service mappings.
account_id (Optional[str]) – Optionally specify your account id to save a call to STS.
- Return type
None
-
property
account_id
¶ Return the AWS Account ID our Boto3 session is authenticated against.
-
property
available_services
¶ Return a list of service names that can be loaded by
Boto3Services.get_service()
.
-
get_empty_service
(service_name, region_name=None)¶ Return the :class`CloudWandererBoto3Service` by this name without a Boto3 Client instantiated.
Useful for querying service/resource metadata.
- Parameters
service_name (str) – The name of the service to instantiate.
region_name (Optional[str]) – The region to instantiate the service for.
- Return type
-
get_resource_from_urn
(urn)¶ Return the
CloudWandererBoto3Resource
resource picked out by this urn.- Parameters
urn (URN) – The urn of the resource to get.
- Raises
BadUrnAccountIdError – When the account ID of the URN does not match the account id of the current session.
BadUrnRegionError – When the region of the URN is not possible with the service and/or resource type.
BadUrnSubResourceError – Subresources must be queried via their parent resource.
- Return type
-
get_service
(service_name, region_name=None, **kwargs)¶ Return the :class`CloudWandererBoto3Service` by this name.
- Parameters
service_name (str) – The name of the service to instantiate.
region_name (Optional[str]) – The region to instantiate the service for.
**kwargs – Additional keyword args will be passed to the Boto3 client.
- Return type
-
class
CloudWandererBoto3Resource
(account_id, boto3_resource, cloudwanderer_boto3_service, service_map)¶ Wraps Boto3 R:class:~boto3.resources.base.ServiceResource resource-level objects.
Allows us to provide additional functionality specific to CloudWanderer.
This is almost always tied to a specific resource that exists in AWS, but is occasionally instantiated abstractly in order to interrogate metadata about this resource type.
-
property
get_and_cleanup_actions
¶ Return the query and cleanup actions to be performed if getting this resource type in this region.
-
get_secondary_attributes
()¶ Return the secondary attributes for this resource.
- Return type
Generator[cloudwanderer.cloud_wanderer_resource.SecondaryAttribute, None, None]
-
get_subresources
()¶ Return the CloudWanderer style subresources of this resource.
- Return type
Generator[cloudwanderer.boto3_services.CloudWandererBoto3Resource, None, None]
-
property
id
¶ Return the id of the resource.
Used for URN generation.
-
property
normalised_raw_data
¶ Return the raw data ditionary for this resource, ensuring that all keys for this resource are present.
-
property
raw_data
¶ Return the raw dictionary data for this resource.
-
property
region
¶ Return the region for this resource.
Typically this just takes the region of the session the resource was discovered from. However for some resources (e.g. S3 buckets) it performs an API call to look it up.
-
property
resource_type
¶ Return the snake_case resource type of this resource.
-
property
secondary_attribute_models
¶ Return the secondary attribute models it’s possible for this resource type to have.
-
property
secondary_attribute_names
¶ Return a list fof secondary attributes its possible for this resource type to have.
-
property
service
¶ Return the snake_case service type for this resource.
-
property
subresource_models
¶ Yield the Boto3 models for the CloudWanderer style subresources of this resource type.
-
property
subresource_types
¶ Return a list of CloudWanderer style subresource types it’s possible for this resource type to have.
-
property
urn
¶ Return the resource’s Universal Resource Name.
-
property
-
class
CloudWandererBoto3ResourceFactory
(boto3_session=None)¶ Factory class for generating Boto3 Resource objects.
-
__init__
(boto3_session=None)¶ Initialise the ResourceFactory.
- Parameters
boto3_session (boto3.session.Session) – The
boto3.session.Session
object to use for any queries.- Return type
None
-
load
(service_name, resource_definitions, service_definition)¶ Load the specified resource definition dictionaries into a Resource object.
- Parameters
service_name (str) – The name of the service to load (e.g.
'ec2'
)resource_definitions (dict) – A dict describing the resource definitions. This is the
'resources'
key in eachresource_definition
json.service_definition (dict) – A dict describing the service definition. This is the
'service'
key in eachresource_definition
json.
- Return type
Type
-
-
class
CloudWandererBoto3Service
(boto3_service, service_map, account_id, boto3_session, region_name=None, enabled_regions=None)¶ Wraps Boto3
ServiceResource
service-level objects.Allows us to include additional CloudWanderer specific functionality. The object represents an AWS service (e.g.
ec2
) in a specific region. Used to get resources from the API as well as get metadata about the resource type from Boto3.-
__init__
(boto3_service, service_map, account_id, boto3_session, region_name=None, enabled_regions=None)¶ Instantiate CloudWandererBoto3Service.
- Parameters
boto3_service (boto3.resources.base.ServiceResource) – The boto3 service object to wrap.
service_map (cloudwanderer.boto3_loaders.ServiceMap) – The CloudWanderer service map that provides additional context about this service.
account_id (str) – The ID of the AWS account our session is in.
region_name (Optional[str]) – The region to get resources from for this service.
boto3_session (boto3.session.Session) – The Boto3 session that created this client.
enabled_regions (Optional[List[str]]) – The list of regions currently enabled.
- Return type
None
-
property
enabled_regions
¶ Return a list of enabled regions in this account.
-
property
get_regions_discovered_from_region
¶ Return a list of regions resources will have been discovered in by querying this resource in this region.
-
get_resource_from_urn
(urn)¶ Return the
CloudWandererBoto3Resource
resource picked out by this urn.- Parameters
urn (URN) – The urn of the resource to get.
- Raises
BadUrnSubResourceError – Occurs when we try to fetch a subresource diretly.
BadRequestError – Occurs when the AWS API returns a 4xx HTTP error other than 404.
ResourceNotFoundError – Occurs when the AWS API Returns a 404 HTTP error.
UnsupportedResourceTypeError – Occurs when the definition for the resource does not support loading by id.
botocore.exceptions.ClientError – Boto3 Client Error
- Return type
-
get_resources
(resource_type)¶ Yield all resources of resource_type in this region.
- Parameters
resource_type (str) – The snake_case resource type to get.
- Return type
Generator[cloudwanderer.boto3_services.CloudWandererBoto3Resource, None, None]
-
property
name
¶ Return the snake_case name of this service.
-
property
region
¶ Return the name of the region this service is querying.
-
property
resource_summary
¶ Return a summary of resource types in this service.
-
property
resource_types
¶ Return a list of snake_case resource types available on this service.
-
property
should_query_resources_in_region
¶ Return whether this service’s resources should be queried from this region.
-
-
class
ResourceSummary
(resource_type, resource_friendly_name, service_friendly_name, subresource_types, secondary_attribute_names)¶ A summary of a resource’s subresource types and secondary attribute names.
-
property
resource_friendly_name
¶ Alias for field number 1
-
property
resource_type
¶ Alias for field number 0
-
property
secondary_attribute_names
¶ Alias for field number 4
-
property
service_friendly_name
¶ Alias for field number 2
-
property
subresource_types
¶ Alias for field number 3
-
property