Esta es la guía para AWS CDK desarrolladores de la versión 2. La CDK versión anterior entró en mantenimiento el 1 de junio de 2022 y finalizó el soporte el 1 de junio de 2023.
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Puede personalizar la síntesis de AWS Cloud Development Kit (AWS CDK) pilas modificando el sintetizador predeterminado, utilizando otros sintetizadores integrados disponibles o creando su propio sintetizador.
AWS CDK Incluye los siguientes sintetizadores integrados que puede utilizar para personalizar el comportamiento de la síntesis:
-
DefaultStackSynthesizer
: si no especifica un sintetizador, este se utiliza de forma automática. Admite despliegues entre cuentas y despliegues que utilicen la estructura Pipelines. CDK Su contrato de arranque requiere un depósito de Amazon S3 existente con un nombre conocido, un ECR repositorio de Amazon existente con un nombre conocido y cinco IAM funciones existentes con nombres conocidos. La plantilla de arranque predeterminada cumple con estos requisitos. -
CliCredentialsStackSynthesizer
— El contrato de arranque de este sintetizador requiere un depósito de Amazon S3 y un repositorio de Amazon existentes. ECR No requiere ningún rol. IAM Para realizar las implementaciones, este sintetizador se basa en los permisos del CDK CLI usuario y se recomienda para las organizaciones que desean restringir IAM las credenciales de implementación. Este sintetizador no admite despliegues entre cuentas ni canalizaciones. CDK -
LegacyStackSynthesizer
— Este sintetizador emula el comportamiento de síntesis de la versión 1. CDK Su contrato de arranque requiere un depósito de Amazon S3 existente con un nombre arbitrario y espera que las ubicaciones de los activos se CloudFormation transmitan como parámetros de pila. Si usa este sintetizador, debe usar el CDK CLI para realizar el despliegue.
Personalizar DefaultStackSynthesizer
El DefaultStackSynthesizer
es el sintetizador predeterminado para AWS CDK. Está diseñado para permitir el despliegue de aplicaciones entre cuentas, así como el despliegue de CDK CDK aplicaciones desde un sistema de CI/CD que no tenga soporte explícito para ello, pero que sea compatible con despliegues regulares, por ejemplo. AWS CDK CloudFormation AWS CodePipeline Este sintetizador es la mejor opción para la mayoría de los casos de uso.
Contrato de arranque de DefaultStackSynthesizer
DefaultStackSynthesizer
requiere el siguiente contrato de arranque. Estos son los recursos que se deben crear durante el arranque:
Recurso de arranque | Descripción | Nombre del recurso esperado predeterminado | Finalidad |
---|---|---|---|
Bucket de Amazon S3 |
Bucket transitorio |
|
Almacena los activos de los archivos. |
ECRRepositorio de Amazon |
Repositorio transitorio |
cdk-hnb659 - - fds-container-assets |
Almacena y gestiona Docker activos de imagen. |
Rol IAM |
Implemente el rol |
cdk-hnb659 - - fds-deploy-role |
Asumido por el CDK CLI y, potencialmente, CodePipeline para asumir otras funciones e iniciar la AWS CloudFormation implementación. La política de confianza de este rol controla quién puede realizar el despliegue AWS CDK en este AWS entorno. |
Rol IAM |
AWS CloudFormation función de ejecución |
cdk-hnb659 - - fds-cfn-exec-role |
Esta función la utiliza para realizar el despliegue AWS CloudFormation . Las políticas de este rol controlan las operaciones que puede realizar la CDK implementación. |
Rol IAM |
Rol de búsqueda |
cdk-hnb659 - - fds-lookup-role |
Esta función se utiliza cuando el CDK CLI necesita realizar búsquedas del contexto ambiental. La política de confianza de este rol controla quién puede buscar información en el entorno. |
Rol IAM |
Rol de publicación de archivos |
cdk-hnb659 - - fds-file-publishing-role |
Este rol se utiliza para cargar activos en el bucket de almacenamiento transitorio de Amazon S3. Se asume a partir del rol de implementación. |
Rol IAM |
Rol de publicación de imágenes |
cdk-hnb659 fds-image-publishing-role - |
Este rol se usa para cargar Docker imágenes al repositorio de Amazon ECR Staging. Se asume a partir del rol de implementación. |
Parámetro SSM |
Parámetro de versión de arranque |
/cdk-bootstrap/hnb659fds/ |
La versión de la plantilla de arranque. Lo utilizan la plantilla bootstrap y el CDK CLI para validar los requisitos. |
Una forma de personalizar la síntesis de CDK pilas es modificando elDefaultStackSynthesizer
. Puede personalizar este sintetizador para una sola CDK pila utilizando la synthesizer
propiedad de su Stack
instancia. También puedes modificar todas DefaultStackSynthesizer
las pilas de tu CDK aplicación mediante la defaultStackSynthesizer
propiedad de tu instancia. App
Cambie el calificador
El calificador se agrega al nombre de los recursos creados durante el arranque. De forma predeterminada, este valor es hnb659fds
. Cuando modificas el calificador durante el arranque, debes personalizar la síntesis de CDK pilas para usar el mismo calificador.
Para cambiar el calificador, configure la qualifier
propiedad del calificador DefaultStackSynthesizer
o configúrelo como clave de contexto en el archivo del proyecto. CDK cdk.json
A continuación, se muestra un ejemplo de configuración de la propiedad qualifier
de DefaultStackSynthesizer
:
new MyStack(this, 'MyStack', {
synthesizer: new DefaultStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
A continuación, se muestra un ejemplo de configuración del calificador como clave de contexto en cdk.json
:
{
"app": "...",
"context": {
"@aws-cdk/core:bootstrapQualifier": "MYQUALIFIER"
}
}
Cambio de nombres de recursos
Todas las demás propiedades DefaultStackSynthesizer
se refieren a los nombres de los recursos de la plantilla de arranque. Solo necesita proporcionar alguna de estas propiedades si modificó la plantilla de arranque y cambió los nombres de los recursos o el esquema de nomenclatura.
Todas las propiedades aceptan los marcadores de posición especiales ${Qualifier}
, ${AWS::Partition}
${AWS::AccountId}
y ${AWS::Region}
. Estos marcadores de posición se sustituyen por los valores del qualifier
parámetro y la AWS partición, el identificador de cuenta y Región de AWS los valores del entorno de la pila, respectivamente.
En el siguiente ejemplo, se muestran las propiedades más utilizadas para DefaultStackSynthesizer
junto con los valores predeterminados, como si creara una instancia del sintetizador. Para ver una lista completa, consulta DefaultStackSynthesizerProps:
new DefaultStackSynthesizer({
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
// ARN of the role assumed by the CLI and Pipeline to deploy here
deployRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-deploy-role-${AWS::AccountId}-${AWS::Region}',
deployRoleExternalId: '',
// ARN of the role used for file asset publishing (assumed from the CLI role)
fileAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-file-publishing-role-${AWS::AccountId}-${AWS::Region}',
fileAssetPublishingExternalId: '',
// ARN of the role used for Docker asset publishing (assumed from the CLI role)
imageAssetPublishingRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-image-publishing-role-${AWS::AccountId}-${AWS::Region}',
imageAssetPublishingExternalId: '',
// ARN of the role passed to CloudFormation to execute the deployments
cloudFormationExecutionRole: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-cfn-exec-role-${AWS::AccountId}-${AWS::Region}',
// ARN of the role used to look up context information in an environment
lookupRoleArn: 'arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-${Qualifier}-lookup-role-${AWS::AccountId}-${AWS::Region}',
lookupRoleExternalId: '',
// Name of the SSM parameter which describes the bootstrap stack version number
bootstrapStackVersionSsmParameter: '/cdk-bootstrap/${Qualifier}/version',
// Add a rule to every template which verifies the required bootstrap stack version
generateBootstrapVersionRule: true,
})
Uso de CliCredentialsStackSynthesizer
Para modificar las credenciales de seguridad utilizadas para conceder permisos durante CDK las implementaciones, puede personalizar la síntesis medianteCliCredentialsStackSynthesizer
: Este sintetizador funciona con los AWS recursos predeterminados que se crean durante el arranque para almacenar activos, como el bucket de Amazon S3 y el repositorio de Amazon. ECR En lugar de utilizar los IAM roles predeterminados creados CDK durante el arranque, utiliza las credenciales de seguridad del actor que inicia el despliegue. Por lo tanto, las credenciales de seguridad del actor deben tener permisos válidos para llevar a cabo todas las acciones de implementación. En el diagrama siguiente se ilustra el proceso de implementación cuando se usa este sintetizador:
Cuando se utiliza CliCredentialsStackSynthesizer
:
-
De forma predeterminada, CloudFormation realiza API llamadas en su cuenta utilizando los permisos del actor. Por lo tanto, la identidad actual debe tener permiso para realizar los cambios necesarios en los AWS recursos de la CloudFormation pila, además de los permisos para realizar CloudFormation las operaciones necesarias, como
CreateStack
oUpdateStack
. Las capacidades de implementación se limitarán a los permisos del actor. -
La publicación y el CloudFormation despliegue de los activos se realizarán con la IAM identidad actual. Esta identidad debe tener permisos suficientes para leer y escribir en el bucket de activos y en el repositorio.
-
Las búsquedas se realizan con la IAM identidad actual y están sujetas a sus políticas.
Al usar este sintetizador, puede usar una función de CloudFormation ejecución independiente especificándola mediante la opción con cualquier --role-arn
CDK CLI comando
Contrato de arranque de CliCredentialsStackSynthesizer
CliCredentialsStackSynthesizer
requiere el siguiente contrato de arranque. Estos son los recursos que se deben crear durante el arranque:
Recurso de arranque | Descripción | Nombre del recurso esperado predeterminado | Finalidad |
---|---|---|---|
Bucket de Amazon S3 |
Bucket transitorio |
cdk-hnb659fds-assets- - |
Almacena los activos de los archivos. |
ECRRepositorio de Amazon |
Repositorio transitorio |
cdk-hnb659 - - fds-container-assets |
Almacena y gestiona Docker activos de imagen. |
La cadena hnb659fds
del nombre del recurso se denomina calificador. Su valor predeterminado no tiene ningún significado especial. Puede tener varias copias de los recursos de arranque en un solo entorno siempre que tengan un calificador diferente. Tener varias copias puede resultar útil para mantener separados los activos de diferentes aplicaciones en el mismo entorno.
Puede implementar la plantilla de arranque predeterminada para cumplir con el contrato de arranque CliCredentialsStackSynthesizer
. La plantilla de bootstrap predeterminada creará IAM roles, pero este sintetizador no los usará. También puede personalizar la plantilla de arranque para eliminar los roles. IAM
Modificar CliCredentialsStackSynthesizer
Si cambia el calificador o alguno de los nombres de los recursos de arranque predeterminados durante el arranque, tendrá que modificar el sintetizador para que utilice los mismos nombres. Puede modificar el sintetizador para una sola pila o para todas las pilas de la aplicación. A continuación, se muestra un ejemplo:
new MyStack(this, 'MyStack', {
synthesizer: new CliCredentialsStackSynthesizer({
qualifier: 'MYQUALIFIER',
}),
});
En el siguiente ejemplo, se muestran las propiedades más utilizadas para CliCredentialsStackSynthesizer
junto con sus valores predeterminados. Para obtener una lista completa, consulte CliCredentialsStackSynthesizerProps:
new CliCredentialsStackSynthesizer({
// Value for '${Qualifier}' in the resource names
qualifier: 'hnb659fds',
// Name of the S3 bucket for file assets
fileAssetsBucketName: 'cdk-${Qualifier}-assets-${AWS::AccountId}-${AWS::Region}',
bucketPrefix: '',
// Name of the ECR repository for Docker image assets
imageAssetsRepositoryName: 'cdk-${Qualifier}-container-assets-${AWS::AccountId}-${AWS::Region}',
dockerTagPrefix: '',
})
Uso de LegacyStackSynthesizer
LegacyStackSynthesizer
Emula el comportamiento de las implementaciones de la CDK versión 1. Las credenciales de seguridad del actor que lleva a cabo la implementación se utilizarán para establecer los permisos. Los activos de los archivos se cargarán en un depósito que se debe crear con una AWS CloudFormation pila denominada. CDKToolkit
Con la CDK CLI creará un ECR repositorio de Amazon no gestionado llamado aws-cdk/assets
store Docker activos de imagen. Usted deberá limpiar y administrar este repositorio. Las pilas sintetizadas con el solo se LegacyStackSynthesizer
pueden implementar con el CDK CLI.
Puede usarlo LegacyStackSynthesizer
si va a migrar de la CDK versión 1 a la CDK versión 2 y no puede volver a iniciar sus entornos. Para proyectos nuevos, recomendamos no utilizar LegacyStackSynthesizer
.
Contrato de arranque de LegacyStackSynthesizer
LegacyStackSynthesizer
requiere el siguiente contrato de arranque. Estos son los recursos que se deben crear durante el arranque:
Recurso de arranque | Descripción | Nombre del recurso esperado predeterminado | Finalidad |
---|---|---|---|
Bucket de Amazon S3 |
Bucket transitorio |
cdk-hnb659fds-assets- - |
Almacena los activos de los archivos. |
CloudFormation salida |
Salida del nombre de bucket |
Pila: Nombre de salida: |
Un CloudFormation resultado que describe el nombre del depósito provisional |
LegacyStackSynthesizer
no supone la existencia de un bucket de Amazon S3 con un nombre fijo. En su lugar, la CloudFormation plantilla sintetizada contendrá tres CloudFormation parámetros para cada recurso de archivo. Estos parámetros almacenarán el nombre del bucket de Amazon S3, la clave de objeto de Amazon S3 y el hash de artefacto de cada activo de archivo.
Docker los activos de imagen se publicarán en un ECR repositorio de Amazon denominadoaws-cdk/assets
. Este nombre se puede cambiar por activo. Los repositorios se crearán si no existen.
Debe existir una CloudFormation pila con el nombre predeterminadoCDKToolkit
. Esta pila debe tener un nombre de CloudFormation exportación BucketName
que haga referencia al depósito provisional.
La plantilla de predeterminada de arranque cumple con el contrato de arranque de LegacyStackSynthesizer
. Sin embargo, solo se utilizará el bucket de Amazon S3 de los recursos de arranque de la plantilla de arranque. Puede personalizar la plantilla de bootstrap para eliminar los recursos de Amazon ECR y SSM bootstrap. IAM
Proceso de implementación de LegacyStackSynthesizer
Cuando se utiliza este sintetizador, se lleva a cabo el siguiente proceso durante la implementación:
-
Con la CDK CLI busca una CloudFormation pila con un nombre
CDKToolkit
en su entorno. A partir de esta pila, el CDK CLI lee la CloudFormation salida denominadaBucketName
. Puede usar la opción--toolkit-stack-name
mediantecdk deploy
para especificar un nombre de pila distinto. -
Las credenciales de seguridad del actor que inicia la implementación se utilizarán para establecer los permisos de implementación. Por lo tanto, el actor debe tener permisos suficientes para llevar a cabo todas las acciones de implementación. Esto incluye leer y escribir en el depósito provisional de Amazon S3, crear y escribir en el ECR repositorio de Amazon, iniciar y supervisar AWS CloudFormation las implementaciones y realizar las API llamadas necesarias para la implementación.
-
Si es necesario y si los permisos son válidos, los activos de los archivos se publicarán en el bucket transitorio de Amazon S3.
-
Si es necesario y si los permisos son válidos, Docker los activos de imagen se publican en el repositorio nombrado por la
repositoryName
propiedad del activo. El valor predeterminado es'aws-cdk/assets'
si no se proporciona un nombre de repositorio. -
Si los permisos son válidos, se realiza el AWS CloudFormation despliegue. Las ubicaciones del depósito de almacenamiento provisional y las claves de Amazon S3 se transfieren como CloudFormation parámetros.