# App Staging Synthesizer
<!--BEGIN STABILITY BANNER-->---
> The APIs of higher level constructs in this module are experimental and under active development.
> They are subject to non-backward compatible changes or removal in any future version. These are
> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
> announced in the release notes. This means that while you may use them, you may need to update
> your source code when upgrading to a newer version of this package.
---
<!--END STABILITY BANNER-->
This library includes constructs aimed at replacing the current model of bootstrapping and providing
greater control of the bootstrap experience to the CDK user. The important constructs in this library
are as follows:
* the `IStagingResources` interface: a framework for an app-level bootstrap stack that handles
file assets and docker assets.
* the `DefaultStagingStack`, which is a works-out-of-the-box implementation of the `IStagingResources`
interface.
* the `AppStagingSynthesizer`, a new CDK synthesizer that will synthesize CDK applications with
the staging resources provided.
> As this library is `experimental`, there are features that are not yet implemented. Please look
> at the list of [Known Limitations](#known-limitations) before getting started.
To get started, update your CDK App with a new `defaultStackSynthesizer`:
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id", # put a unique id here
staging_bucket_encryption=BucketEncryption.S3_MANAGED
)
)
```
This will introduce a `DefaultStagingStack` in your CDK App and staging assets of your App
will live in the resources from that stack rather than the CDK Bootstrap stack.
If you are migrating from a different version of synthesis your updated CDK App will target
the resources in the `DefaultStagingStack` and no longer be tied to the bootstrapped resources
in your account.
## Bootstrap Model
In our default bootstrapping process, when you run `cdk bootstrap aws://<account>/<region>`, the following
resources are created:
* It creates Roles to assume for cross-account deployments and for Pipeline deployments;
* It creates staging resources: a global S3 bucket and global ECR repository to hold CDK assets;
* It creates Roles to write to the S3 bucket and ECR repository;
Because the bootstrapping resources include regional resources, you need to bootstrap
every region you plan to deploy to individually. All assets of all CDK apps deploying
to that account and region will be written to the single S3 Bucket and ECR repository.
By using the synthesizer in this library, instead of the
`DefaultStackSynthesizer`, a different set of staging resources will be created
for every CDK application, and they will be created automatically as part of a
regular deployment, in a separate Stack that is deployed before your application
Stacks. The staging resources will be one S3 bucket, and *one ECR repository per
image*, and Roles necessary to access those buckets and ECR repositories. The
Roles from the default bootstrap stack are still used (though their use can be
turned off).
This has the following advantages:
* Because staging resources are now application-specific, they can be fully cleaned up when you clean up
the application.
* Because there is now one ECR repository per image instead of one ECR repository for all images, it is
possible to effectively use ECR life cycle rules (for example, retain only the most recent 5 images)
to cut down on storage costs.
* Resources between separate CDK Apps are separated so they can be cleaned up and lifecycle
controlled individually.
* Because the only shared bootstrapping resources required are Roles, which are global resources,
you now only need to bootstrap every account in one Region (instead of every Region). This makes it
easier to do with CloudFormation StackSets.
For the deployment roles, this synthesizer still uses the Roles from the default
bootstrap stack, and nothing else. The staging resources from that bootstrap
stack will be unused. You can customize the template to remove those resources
if you prefer. In the future, we will provide a bootstrap stack template with
only those Roles, specifically for use with this synthesizer.
## Using the Default Staging Stack per Environment
The most common use case will be to use the built-in default resources. In this scenario, the
synthesizer will create a new Staging Stack in each environment the CDK App is deployed to store
its staging resources. To use this kind of synthesizer, use `AppStagingSynthesizer.defaultResources()`.
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
# The following line is optional. By default it is assumed you have bootstrapped in the same
# region(s) as the stack(s) you are deploying.
deployment_identities=DeploymentIdentities.default_bootstrap_roles(bootstrap_region="us-east-1")
)
)
```
Every CDK App that uses the `DefaultStagingStack` must include an `appId`. This should
be an identifier unique to the app and is used to differentiate staging resources associated
with the app.
### Default Staging Stack
The Default Staging Stack includes all the staging resources necessary for CDK Assets. The below example
is of a CDK App using the `AppStagingSynthesizer` and creating a file asset for the Lambda Function
source code. As part of the `DefaultStagingStack`, an S3 bucket and IAM role will be created that will be
used to upload the asset to S3.
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED
)
)
stack = Stack(app, "my-stack")
lambda_.Function(stack, "lambda",
code=lambda_.AssetCode.from_asset(path.join(__dirname, "assets")),
handler="index.handler",
runtime=lambda_.Runtime.PYTHON_3_9
)
app.synth()
```
### Custom Roles
You can customize some or all of the roles you'd like to use in the synthesizer as well,
if all you need is to supply custom roles (and not change anything else in the `DefaultStagingStack`):
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
deployment_identities=DeploymentIdentities.specify_roles(
cloud_formation_execution_role=BootstrapRole.from_role_arn("arn:aws:iam::123456789012:role/Execute"),
deployment_role=BootstrapRole.from_role_arn("arn:aws:iam::123456789012:role/Deploy"),
lookup_role=BootstrapRole.from_role_arn("arn:aws:iam::123456789012:role/Lookup")
)
)
)
```
Or, you can ask to use the CLI credentials that exist at deploy-time.
These credentials must have the ability to perform CloudFormation calls,
lookup resources in your account, and perform CloudFormation deployment.
For a full list of what is necessary, see `LookupRole`, `DeploymentActionRole`,
and `CloudFormationExecutionRole` in the
[bootstrap template](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml).
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
deployment_identities=DeploymentIdentities.cli_credentials()
)
)
```
The default staging stack will create roles to publish to the S3 bucket and ECR repositories,
assumable by the deployment role. You can also specify an existing IAM role for the
`fileAssetPublishingRole` or `imageAssetPublishingRole`:
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
file_asset_publishing_role=BootstrapRole.from_role_arn("arn:aws:iam::123456789012:role/S3Access"),
image_asset_publishing_role=BootstrapRole.from_role_arn("arn:aws:iam::123456789012:role/ECRAccess")
)
)
```
### Deploy Time S3 Assets
There are two types of assets:
* Assets used only during deployment. These are used to hand off a large piece of data to another
service, that will make a private copy of that data. After deployment, the asset is only necessary for
a potential future rollback.
* Assets accessed throughout the running life time of the application.
Examples of assets that are only used at deploy time are CloudFormation Templates and Lambda Code
bundles. Examples of assets accessed throughout the life time of the application are script files
downloaded to run in a CodeBuild Project, or on EC2 instance startup. ECR images are always application
life-time assets. S3 deploy time assets are stored with a `deploy-time/` prefix, and a lifecycle rule will collect them after a configurable number of days.
Lambda assets are by default marked as deploy time assets:
```python
# stack: Stack
lambda_.Function(stack, "lambda",
code=lambda_.AssetCode.from_asset(path.join(__dirname, "assets")), # lambda marks deployTime = true
handler="index.handler",
runtime=lambda_.Runtime.PYTHON_3_9
)
```
Or, if you want to create your own deploy time asset:
```python
from aws_cdk.aws_s3_assets import Asset
# stack: Stack
asset = Asset(stack, "deploy-time-asset",
deploy_time=True,
path=path.join(__dirname, "deploy-time-asset")
)
```
By default, we store deploy time assets for 30 days, but you can change this number by specifying
`deployTimeFileAssetLifetime`. The number you specify here is how long you will be able to roll back
to a previous version of an application just by doing a CloudFormation deployment with the old
template, without rebuilding and republishing assets.
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
deploy_time_file_asset_lifetime=Duration.days(100)
)
)
```
### Lifecycle Rules on ECR Repositories
By default, we store a maximum of 3 revisions of a particular docker image asset. This allows
for smooth faciliation of rollback scenarios where we may reference previous versions of an
image. When more than 3 revisions of an asset exist in the ECR repository, the oldest one is
purged.
To change the number of revisions stored, use `imageAssetVersionCount`:
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
image_asset_version_count=10
)
)
```
### Auto Delete Staging Assets on Deletion
By default, the staging resources will be cleaned up on stack deletion. That means that the
S3 Bucket and ECR Repositories are set to `RemovalPolicy.DESTROY` and have `autoDeleteObjects`
or `emptyOnDelete` turned on. This creates custom resources under the hood to facilitate
cleanup. To turn this off, specify `autoDeleteStagingAssets: false`.
```python
from aws_cdk.aws_s3 import BucketEncryption
app = App(
default_stack_synthesizer=AppStagingSynthesizer.default_resources(
app_id="my-app-id",
staging_bucket_encryption=BucketEncryption.S3_MANAGED,
auto_delete_staging_assets=False
)
)
```
### Staging Bucket Encryption
You must explicitly specify the encryption type for the staging bucket via the `stagingBucketEncryption` property. In
future versions of this package, the default will be `BucketEncryption.S3_MANAGED`.
In previous versions of this package, the default was to use KMS encryption for the staging bucket. KMS keys cost
$1/month, which could result in unexpected costs for users who are not aware of this. As we stabilize this module
we intend to make the default S3-managed encryption, which is free. However, the migration path from KMS to S3
managed encryption for existing buckets is not straightforward. Therefore, for now, this property is required.
If you have an existing staging bucket encrypted with a KMS key, you will likely want to set this property to
`BucketEncryption.KMS`. If you are creating a new staging bucket, you can set this property to
`BucketEncryption.S3_MANAGED` to avoid the cost of a KMS key.
You can learn more about choosing a bucket encryption type in the
[S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html).
## Using a Custom Staging Stack per Environment
If you want to customize some behavior that is not configurable via properties,
you can implement your own class that implements `IStagingResources`. To get a head start,
you can subclass `DefaultStagingStack`.
```python
class CustomStagingStack(DefaultStagingStack):
pass
```
Or you can roll your own staging resources from scratch, as long as it implements `IStagingResources`.
```python
@jsii.implements(IStagingResources)
class CustomStagingStack(Stack):
def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None):
super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation)
def add_file(self, *, sourceHash, executable=None, fileName=None, packaging=None, deployTime=None):
return FileStagingLocation(
bucket_name="amzn-s3-demo-bucket",
assume_role_arn="myArn",
dependency_stack=self
)
def add_docker_image(self, *, sourceHash, executable=None, directoryName=None, dockerBuildArgs=None, dockerBuildSecrets=None, dockerBuildSsh=None, dockerBuildTarget=None, dockerFile=None, repositoryName=None, networkMode=None, platform=None, dockerOutputs=None, assetName=None, dockerCacheFrom=None, dockerCacheTo=None, dockerCacheDisabled=None):
return ImageStagingLocation(
repo_name="myRepo",
assume_role_arn="myArn",
dependency_stack=self
)
```
Using your custom staging resources means implementing a `CustomFactory` class and calling the
`AppStagingSynthesizer.customFactory()` static method. This has the benefit of providing a
custom Staging Stack that can be created in every environment the CDK App is deployed to.
```python
@jsii.implements(IStagingResourcesFactory)
class CustomFactory:
def obtain_staging_resources(self, stack, *, environmentString, deployRoleArn=None, qualifier):
my_app = App.of(stack)
return CustomStagingStack(my_app, f"CustomStagingStack-{context.environmentString}")
app = App(
default_stack_synthesizer=AppStagingSynthesizer.custom_factory(
factory=CustomFactory(),
once_per_env=True
)
)
```
## Using an Existing Staging Stack
Use `AppStagingSynthesizer.customResources()` to supply an existing stack as the Staging Stack.
Make sure that the custom stack you provide implements `IStagingResources`.
```python
resource_app = App()
resources = CustomStagingStack(resource_app, "CustomStagingStack")
app = App(
default_stack_synthesizer=AppStagingSynthesizer.custom_resources(
resources=resources
)
)
```
## Known Limitations
Since this module is experimental, there are some known limitations:
* Currently this module does not support CDK Pipelines. You must deploy CDK Apps using this
synthesizer via `cdk deploy`. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26118)
to indicate you want this.
* This synthesizer only needs a bootstrap stack with Roles, without staging resources. We
haven't written such a bootstrap stack yet; at the moment you can use the existing modern
bootstrap stack, the staging resources in them will just go unused. You can customize the
template to remove them if desired.
* Due to limitations on the CloudFormation template size, CDK Applications can have
at most 20 independent ECR images. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26119)
if you need more than this.
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-cdk",
"name": "aws-cdk.app-staging-synthesizer-alpha",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Amazon Web Services",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f9/07/c91e45dce60dd0f1e2a35bf172ead31a5ee8bf95b843238d8bd44586360f/aws_cdk_app_staging_synthesizer_alpha-2.170.0a0.tar.gz",
"platform": null,
"description": "# App Staging Synthesizer\n\n<!--BEGIN STABILITY BANNER-->---\n\n\n\n\n> The APIs of higher level constructs in this module are experimental and under active development.\n> They are subject to non-backward compatible changes or removal in any future version. These are\n> not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be\n> announced in the release notes. This means that while you may use them, you may need to update\n> your source code when upgrading to a newer version of this package.\n\n---\n<!--END STABILITY BANNER-->\n\nThis library includes constructs aimed at replacing the current model of bootstrapping and providing\ngreater control of the bootstrap experience to the CDK user. The important constructs in this library\nare as follows:\n\n* the `IStagingResources` interface: a framework for an app-level bootstrap stack that handles\n file assets and docker assets.\n* the `DefaultStagingStack`, which is a works-out-of-the-box implementation of the `IStagingResources`\n interface.\n* the `AppStagingSynthesizer`, a new CDK synthesizer that will synthesize CDK applications with\n the staging resources provided.\n\n> As this library is `experimental`, there are features that are not yet implemented. Please look\n> at the list of [Known Limitations](#known-limitations) before getting started.\n\nTo get started, update your CDK App with a new `defaultStackSynthesizer`:\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\", # put a unique id here\n staging_bucket_encryption=BucketEncryption.S3_MANAGED\n )\n)\n```\n\nThis will introduce a `DefaultStagingStack` in your CDK App and staging assets of your App\nwill live in the resources from that stack rather than the CDK Bootstrap stack.\n\nIf you are migrating from a different version of synthesis your updated CDK App will target\nthe resources in the `DefaultStagingStack` and no longer be tied to the bootstrapped resources\nin your account.\n\n## Bootstrap Model\n\nIn our default bootstrapping process, when you run `cdk bootstrap aws://<account>/<region>`, the following\nresources are created:\n\n* It creates Roles to assume for cross-account deployments and for Pipeline deployments;\n* It creates staging resources: a global S3 bucket and global ECR repository to hold CDK assets;\n* It creates Roles to write to the S3 bucket and ECR repository;\n\nBecause the bootstrapping resources include regional resources, you need to bootstrap\nevery region you plan to deploy to individually. All assets of all CDK apps deploying\nto that account and region will be written to the single S3 Bucket and ECR repository.\n\nBy using the synthesizer in this library, instead of the\n`DefaultStackSynthesizer`, a different set of staging resources will be created\nfor every CDK application, and they will be created automatically as part of a\nregular deployment, in a separate Stack that is deployed before your application\nStacks. The staging resources will be one S3 bucket, and *one ECR repository per\nimage*, and Roles necessary to access those buckets and ECR repositories. The\nRoles from the default bootstrap stack are still used (though their use can be\nturned off).\n\nThis has the following advantages:\n\n* Because staging resources are now application-specific, they can be fully cleaned up when you clean up\n the application.\n* Because there is now one ECR repository per image instead of one ECR repository for all images, it is\n possible to effectively use ECR life cycle rules (for example, retain only the most recent 5 images)\n to cut down on storage costs.\n* Resources between separate CDK Apps are separated so they can be cleaned up and lifecycle\n controlled individually.\n* Because the only shared bootstrapping resources required are Roles, which are global resources,\n you now only need to bootstrap every account in one Region (instead of every Region). This makes it\n easier to do with CloudFormation StackSets.\n\nFor the deployment roles, this synthesizer still uses the Roles from the default\nbootstrap stack, and nothing else. The staging resources from that bootstrap\nstack will be unused. You can customize the template to remove those resources\nif you prefer. In the future, we will provide a bootstrap stack template with\nonly those Roles, specifically for use with this synthesizer.\n\n## Using the Default Staging Stack per Environment\n\nThe most common use case will be to use the built-in default resources. In this scenario, the\nsynthesizer will create a new Staging Stack in each environment the CDK App is deployed to store\nits staging resources. To use this kind of synthesizer, use `AppStagingSynthesizer.defaultResources()`.\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n\n # The following line is optional. By default it is assumed you have bootstrapped in the same\n # region(s) as the stack(s) you are deploying.\n deployment_identities=DeploymentIdentities.default_bootstrap_roles(bootstrap_region=\"us-east-1\")\n )\n)\n```\n\nEvery CDK App that uses the `DefaultStagingStack` must include an `appId`. This should\nbe an identifier unique to the app and is used to differentiate staging resources associated\nwith the app.\n\n### Default Staging Stack\n\nThe Default Staging Stack includes all the staging resources necessary for CDK Assets. The below example\nis of a CDK App using the `AppStagingSynthesizer` and creating a file asset for the Lambda Function\nsource code. As part of the `DefaultStagingStack`, an S3 bucket and IAM role will be created that will be\nused to upload the asset to S3.\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED\n )\n)\n\nstack = Stack(app, \"my-stack\")\n\nlambda_.Function(stack, \"lambda\",\n code=lambda_.AssetCode.from_asset(path.join(__dirname, \"assets\")),\n handler=\"index.handler\",\n runtime=lambda_.Runtime.PYTHON_3_9\n)\n\napp.synth()\n```\n\n### Custom Roles\n\nYou can customize some or all of the roles you'd like to use in the synthesizer as well,\nif all you need is to supply custom roles (and not change anything else in the `DefaultStagingStack`):\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n deployment_identities=DeploymentIdentities.specify_roles(\n cloud_formation_execution_role=BootstrapRole.from_role_arn(\"arn:aws:iam::123456789012:role/Execute\"),\n deployment_role=BootstrapRole.from_role_arn(\"arn:aws:iam::123456789012:role/Deploy\"),\n lookup_role=BootstrapRole.from_role_arn(\"arn:aws:iam::123456789012:role/Lookup\")\n )\n )\n)\n```\n\nOr, you can ask to use the CLI credentials that exist at deploy-time.\nThese credentials must have the ability to perform CloudFormation calls,\nlookup resources in your account, and perform CloudFormation deployment.\nFor a full list of what is necessary, see `LookupRole`, `DeploymentActionRole`,\nand `CloudFormationExecutionRole` in the\n[bootstrap template](https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/lib/api/bootstrap/bootstrap-template.yaml).\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n deployment_identities=DeploymentIdentities.cli_credentials()\n )\n)\n```\n\nThe default staging stack will create roles to publish to the S3 bucket and ECR repositories,\nassumable by the deployment role. You can also specify an existing IAM role for the\n`fileAssetPublishingRole` or `imageAssetPublishingRole`:\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n file_asset_publishing_role=BootstrapRole.from_role_arn(\"arn:aws:iam::123456789012:role/S3Access\"),\n image_asset_publishing_role=BootstrapRole.from_role_arn(\"arn:aws:iam::123456789012:role/ECRAccess\")\n )\n)\n```\n\n### Deploy Time S3 Assets\n\nThere are two types of assets:\n\n* Assets used only during deployment. These are used to hand off a large piece of data to another\n service, that will make a private copy of that data. After deployment, the asset is only necessary for\n a potential future rollback.\n* Assets accessed throughout the running life time of the application.\n\nExamples of assets that are only used at deploy time are CloudFormation Templates and Lambda Code\nbundles. Examples of assets accessed throughout the life time of the application are script files\ndownloaded to run in a CodeBuild Project, or on EC2 instance startup. ECR images are always application\nlife-time assets. S3 deploy time assets are stored with a `deploy-time/` prefix, and a lifecycle rule will collect them after a configurable number of days.\n\nLambda assets are by default marked as deploy time assets:\n\n```python\n# stack: Stack\n\nlambda_.Function(stack, \"lambda\",\n code=lambda_.AssetCode.from_asset(path.join(__dirname, \"assets\")), # lambda marks deployTime = true\n handler=\"index.handler\",\n runtime=lambda_.Runtime.PYTHON_3_9\n)\n```\n\nOr, if you want to create your own deploy time asset:\n\n```python\nfrom aws_cdk.aws_s3_assets import Asset\n\n# stack: Stack\n\nasset = Asset(stack, \"deploy-time-asset\",\n deploy_time=True,\n path=path.join(__dirname, \"deploy-time-asset\")\n)\n```\n\nBy default, we store deploy time assets for 30 days, but you can change this number by specifying\n`deployTimeFileAssetLifetime`. The number you specify here is how long you will be able to roll back\nto a previous version of an application just by doing a CloudFormation deployment with the old\ntemplate, without rebuilding and republishing assets.\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n deploy_time_file_asset_lifetime=Duration.days(100)\n )\n)\n```\n\n### Lifecycle Rules on ECR Repositories\n\nBy default, we store a maximum of 3 revisions of a particular docker image asset. This allows\nfor smooth faciliation of rollback scenarios where we may reference previous versions of an\nimage. When more than 3 revisions of an asset exist in the ECR repository, the oldest one is\npurged.\n\nTo change the number of revisions stored, use `imageAssetVersionCount`:\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n image_asset_version_count=10\n )\n)\n```\n\n### Auto Delete Staging Assets on Deletion\n\nBy default, the staging resources will be cleaned up on stack deletion. That means that the\nS3 Bucket and ECR Repositories are set to `RemovalPolicy.DESTROY` and have `autoDeleteObjects`\nor `emptyOnDelete` turned on. This creates custom resources under the hood to facilitate\ncleanup. To turn this off, specify `autoDeleteStagingAssets: false`.\n\n```python\nfrom aws_cdk.aws_s3 import BucketEncryption\n\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.default_resources(\n app_id=\"my-app-id\",\n staging_bucket_encryption=BucketEncryption.S3_MANAGED,\n auto_delete_staging_assets=False\n )\n)\n```\n\n### Staging Bucket Encryption\n\nYou must explicitly specify the encryption type for the staging bucket via the `stagingBucketEncryption` property. In\nfuture versions of this package, the default will be `BucketEncryption.S3_MANAGED`.\n\nIn previous versions of this package, the default was to use KMS encryption for the staging bucket. KMS keys cost\n$1/month, which could result in unexpected costs for users who are not aware of this. As we stabilize this module\nwe intend to make the default S3-managed encryption, which is free. However, the migration path from KMS to S3\nmanaged encryption for existing buckets is not straightforward. Therefore, for now, this property is required.\n\nIf you have an existing staging bucket encrypted with a KMS key, you will likely want to set this property to\n`BucketEncryption.KMS`. If you are creating a new staging bucket, you can set this property to\n`BucketEncryption.S3_MANAGED` to avoid the cost of a KMS key.\n\nYou can learn more about choosing a bucket encryption type in the\n[S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html).\n\n## Using a Custom Staging Stack per Environment\n\nIf you want to customize some behavior that is not configurable via properties,\nyou can implement your own class that implements `IStagingResources`. To get a head start,\nyou can subclass `DefaultStagingStack`.\n\n```python\nclass CustomStagingStack(DefaultStagingStack):\n pass\n```\n\nOr you can roll your own staging resources from scratch, as long as it implements `IStagingResources`.\n\n```python\n@jsii.implements(IStagingResources)\nclass CustomStagingStack(Stack):\n def __init__(self, scope, id, *, description=None, env=None, stackName=None, tags=None, notificationArns=None, synthesizer=None, terminationProtection=None, analyticsReporting=None, crossRegionReferences=None, permissionsBoundary=None, suppressTemplateIndentation=None):\n super().__init__(scope, id, description=description, env=env, stackName=stackName, tags=tags, notificationArns=notificationArns, synthesizer=synthesizer, terminationProtection=terminationProtection, analyticsReporting=analyticsReporting, crossRegionReferences=crossRegionReferences, permissionsBoundary=permissionsBoundary, suppressTemplateIndentation=suppressTemplateIndentation)\n\n def add_file(self, *, sourceHash, executable=None, fileName=None, packaging=None, deployTime=None):\n return FileStagingLocation(\n bucket_name=\"amzn-s3-demo-bucket\",\n assume_role_arn=\"myArn\",\n dependency_stack=self\n )\n\n def add_docker_image(self, *, sourceHash, executable=None, directoryName=None, dockerBuildArgs=None, dockerBuildSecrets=None, dockerBuildSsh=None, dockerBuildTarget=None, dockerFile=None, repositoryName=None, networkMode=None, platform=None, dockerOutputs=None, assetName=None, dockerCacheFrom=None, dockerCacheTo=None, dockerCacheDisabled=None):\n return ImageStagingLocation(\n repo_name=\"myRepo\",\n assume_role_arn=\"myArn\",\n dependency_stack=self\n )\n```\n\nUsing your custom staging resources means implementing a `CustomFactory` class and calling the\n`AppStagingSynthesizer.customFactory()` static method. This has the benefit of providing a\ncustom Staging Stack that can be created in every environment the CDK App is deployed to.\n\n```python\n@jsii.implements(IStagingResourcesFactory)\nclass CustomFactory:\n def obtain_staging_resources(self, stack, *, environmentString, deployRoleArn=None, qualifier):\n my_app = App.of(stack)\n\n return CustomStagingStack(my_app, f\"CustomStagingStack-{context.environmentString}\")\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.custom_factory(\n factory=CustomFactory(),\n once_per_env=True\n )\n)\n```\n\n## Using an Existing Staging Stack\n\nUse `AppStagingSynthesizer.customResources()` to supply an existing stack as the Staging Stack.\nMake sure that the custom stack you provide implements `IStagingResources`.\n\n```python\nresource_app = App()\nresources = CustomStagingStack(resource_app, \"CustomStagingStack\")\n\napp = App(\n default_stack_synthesizer=AppStagingSynthesizer.custom_resources(\n resources=resources\n )\n)\n```\n\n## Known Limitations\n\nSince this module is experimental, there are some known limitations:\n\n* Currently this module does not support CDK Pipelines. You must deploy CDK Apps using this\n synthesizer via `cdk deploy`. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26118)\n to indicate you want this.\n* This synthesizer only needs a bootstrap stack with Roles, without staging resources. We\n haven't written such a bootstrap stack yet; at the moment you can use the existing modern\n bootstrap stack, the staging resources in them will just go unused. You can customize the\n template to remove them if desired.\n* Due to limitations on the CloudFormation template size, CDK Applications can have\n at most 20 independent ECR images. Please upvote [this issue](https://github.com/aws/aws-cdk/issues/26119)\n if you need more than this.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Cdk synthesizer for with app-scoped staging stack",
"version": "2.170.0a0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-cdk",
"Source": "https://github.com/aws/aws-cdk.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "364afff9e58400397151c3dd78d6fbf6bc931ef9276ca1fedfdb7ee99d5d9552",
"md5": "1c52a35041caff42f748d9475d36016c",
"sha256": "ac755318532e81a1b2860611f04f25e7fc49a25657957621699dad1fd3d2ea8f"
},
"downloads": -1,
"filename": "aws_cdk.app_staging_synthesizer_alpha-2.170.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c52a35041caff42f748d9475d36016c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 131441,
"upload_time": "2024-11-22T04:41:19",
"upload_time_iso_8601": "2024-11-22T04:41:19.265692Z",
"url": "https://files.pythonhosted.org/packages/36/4a/fff9e58400397151c3dd78d6fbf6bc931ef9276ca1fedfdb7ee99d5d9552/aws_cdk.app_staging_synthesizer_alpha-2.170.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f907c91e45dce60dd0f1e2a35bf172ead31a5ee8bf95b843238d8bd44586360f",
"md5": "35dc38fb860e61d94b2ab15c8414a462",
"sha256": "69b0cc8d0783608f4e8fe1cbeec883c7754a01c18c4d448ae381b948eb6362cf"
},
"downloads": -1,
"filename": "aws_cdk_app_staging_synthesizer_alpha-2.170.0a0.tar.gz",
"has_sig": false,
"md5_digest": "35dc38fb860e61d94b2ab15c8414a462",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 133787,
"upload_time": "2024-11-22T04:42:13",
"upload_time_iso_8601": "2024-11-22T04:42:13.327045Z",
"url": "https://files.pythonhosted.org/packages/f9/07/c91e45dce60dd0f1e2a35bf172ead31a5ee8bf95b843238d8bd44586360f/aws_cdk_app_staging_synthesizer_alpha-2.170.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-22 04:42:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-cdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aws-cdk.app-staging-synthesizer-alpha"
}
JSON
