impl#

See AbstractBotoSesFactory.

class aws_ops_alpha.boto_ses.impl.AbstractBotoSesFactory[source]#

Manages the creation of the boto session manager (bsm) for multi-AWS-account, multi-environment deployment.

For all bsm objects, it provides a factory method to create a new instance of the bsm object, and a cached_property to obtain the singleton object, reducing authentication overhead.

An instance of this class serves as the central point for accessing different Boto sessions for AWS accounts in various environments.

The purpose of this class is to provide a human-friendly interface to access different boto session for different purpose, regardless of the current runtime.

Note that THIS CLASS IS AN ABSTRACT CLASS, you should inherit from it and implement the following abstract methods before using it:

AbstractBotoSesFactory.get_devops_bsm()
AbstractBotoSesFactory.get_env_bsm()
AbstractBotoSesFactory.get_app_bsm()
AbstractBotoSesFactory.bsm_devops()
AbstractBotoSesFactory.bsm_app()
AbstractBotoSesFactory.bsm()

Sample usage:

>>> import dataclasses
>>> from boto_session_manager import BotoSesManager

>>> @dataclasses.dataclass
... class MyBotoSesFactory(AbstractBotoSesFactory):
...     def get_devops_bsm(self) -> BotoSesManager:
...         return BotoSesManager(profile_name="my_devops_profile")

>>> boto_ses_factory = MyBotoSesFactory()
>>> boto_ses_factory.bsm_devops.sts_client.get_caller_identity()
{'UserId': '...', 'Account': '123456789012', 'Arn': '...'}

abstract get_devops_bsm() → BotoSesManager[source]#

Get the boto session manager for devops AWS account.

This bsm is used in devops automation or CI/CD pipeline for upload artifacts. It SHOULD NOT be used by the application code.

abstract get_env_bsm(env_name: str) → BotoSesManager[source]#

Get the boto session manager for workload AWS account.

This bsm is used to in devops automation or CI/CD pipeline for app deployment. Developers can also use this method to explicitly switch to the AWS account of a specific environment.

abstract get_app_bsm() → BotoSesManager[source]#: Get the boto session manager for application code logic.

property bsm_devops: BotoSesManager#: cached property of the AbstractBotoSesFactory.get_devops_bsm().

property bsm_app: BotoSesManager#: cached property of the AbstractBotoSesFactory.get_app_bsm().

abstract property bsm: BotoSesManager#: The shortcut to access the most commonly used boto session manager. Usually, it is for the application code.

class aws_ops_alpha.boto_ses.impl.AlphaBotoSesFactory(runtime: ~aws_ops_alpha.runtime.impl.Runtime, env_to_profile_mapper: ~typing.Dict[str, str] = <factory>, aws_region: ~typing.Optional[str] = None, default_app_env_name: str = 'sbx')[source]#

Manages creation of boto session manager for multi-aws-account, multi-environment deployment.

The instance of this class is the central place to access different boto session for different environments’ AWS account.

Using this class, you agree to the following assumptions:

You use AWS CLI named profile to access devops and workload AWS accounts.
on your local laptop. You should provide the env_to_profile_mapper attribute to map the environment name to the AWS CLI named profile name. make sure your AWS CLI named profile also defines the region name.
You use IAM role for devops and assumed IAM role for workload AWS accounts
on CI/CD or AWS Cloud 9 runtime. The default IAM principal should be on the devops AWS account, and the assumed IAM role should be on the workload AWS accounts. The CI/CD or AWS Cloud 9 runtime should have a mechanism to find the workload IAM role arn. For example, you can store them in environment variables.
In your application runtime, such as AWS EC2, Lambda, the default
IAM principal is already on the workload AWS account.

Parameters:

env_to_profile_mapper – a dictionary to map the environment name to the AWS CLI named profile name. Normally, it should have the following keys: devops, sbx, tst, stg, prd.
aws_region – if specified, use this region name to create the boto session.

Note

There’s no need for special handling in AWS Glue local container runtime. Because we mount the ${HOME}/.aws directory to the container.

abstract get_env_role_arn(env_name: str) → str[source]#

An abstract method to get the workload AWS account IAM role name for deployment. You have to subclass this class and implement this method.

Usually, you only need this method in CI environment, because on local, you may just need to use AWS CLI named profile to assume the role. But in CI, you don’t have AWS CLI named profile, you have to use the default role, which is the devops role to assume workload role.

I recommend you to use environment variable to store the IAM role name. Let say you have three environments, sbx, tst, prd. Then you can create three environment variables, SBX_AWS_ACCOUNT_ID, TST_AWS_ACCOUNT_ID, PRD_AWS_ACCOUNT_ID. And use the following naming convention for workload IAM role arn: arn:aws:iam::{AWS_ACCOUNT_ID}:role/{ENV_NAME}_deployment_role. In this way, the implementation of this method should be:

>>> import os
>>> def get_env_role_arn(self, env_name: str) -> str:
...     aws_account_id = os.environ[f"{env_name.upper()}_AWS_ACCOUNT_ID"]
...     return f"arn:aws:iam::{aws_account_id}:role/{env_name}_deployment_role"

abstract get_env_role_session_name(env_name: str) → str[source]#

An abstract method to get the workload AWS account IAM role session name for assumed role. You have to subclass this class and implement this method.

A role session name is just an identifier for the assumed role session. You can then check the principal arn to identify which environment the session belongs to.

>>> def get_env_role_session_name(self, env_name: str) -> str:
...     return f"{env_name}_role_session"

get_current_env() → str[source]#: An abstract method to get the current environment name.

is_devops_bsm(bsm: BotoSesManager) → bool[source]#: Check if the boto session manager is for devops AWS account.

get_devops_bsm(path_bsm_snapshot: Path = PosixPath('/home/docs/.bsm-snapshot.json')) → BotoSesManager[source]#

Get the boto session manager for devops AWS account.

for local laptop, you should use the devops AWS cli profile
for AWS cloud 9, the cloud 9 default IAM role is the devops role
for ci runtime, the default IAM principal is the devops role

There’s an edge case in CI. Usually, we set the workload boto session credentials as the default for the cdk deploy command runtime. The cdk deploy command will launch another Python process to execute the deployment. By default, we assume that the default AWS credential is the DevOps role. However, in this case, the default AWS credential is the workload role. If we discover that the default role is NOT the DevOps role, we will load the credentials from a snapshot file. A snapshot file is created by the BotoSesManager.temp_snapshot() context manager. Before running the cdk deploy command, it stores the DevOps role credentials and automatically deletes this file after the cdk deploy command finishes or when the program exits unexpectedly.

get_env_bsm(env_name: str, role_session_name: Optional[str] = None, duration_seconds: int = 3600, region_name: Optional[str] = None, auto_refresh: bool = False, path_bsm_snapshot: Path = PosixPath('/home/docs/.bsm-snapshot.json')) → BotoSesManager[source]#

Get the boto session manager for workload AWS account.

This bsm is used to in devops automation or CI/CD pipeline for app deployment. Developers can also use this method to explicitly switch to the AWS account of a specific environment.

for local laptop, but not AWS cloud 9, you should use the AWS CLI named profile
for ci runtime or AWS cloud 9, you should use the devops role to assume the
given workload role. But if the env_name is devops, then return the devops role immediately without assuming any role. there’s a pitfall in CI, sometimes you may force to set the workload role as the default AWS CLI profile, in that case the default role is workload role, NOT the devops role. so we have to add additional logic to handle this edge case. we compare the default role to the workload role we want to assume, if they are the same, we just use the default role (it is already the workload role)

Parameters:

env_name – the environment name, for example, sbx, tst, prd.
role_session_name – the session name for the assumed role.
duration_seconds – the duration in seconds for the assumed role.
region_name – the region name for the assumed role, if not specified, then use the region name of the devops AWS account.
auto_refresh – whether to auto refresh the assumed role.

get_app_bsm() → BotoSesManager[source]#

Get the boto session manager for application code logic.

This bsm is used to access the environment specific AWS resource for application code logic, unit test, integration test, etc.

For local, we use the default app env AWS CLI profile.
For ci runtime, if the current env is devops, in other words,
we are in artifacts building phase, then we should switch to the default app env. if the current env is workload env, then we just use the corresponding IAM role.

property bsm: BotoSesManager#: The shortcut to access the most commonly used boto session manager. Usually, it is for the application code.