1.0.0 • Published 6 months ago

@syss/arch-cdk-patterns v1.0.0

Weekly downloads
-
License
-
Repository
-
Last release
6 months ago

Librería Patterns

La librería "Patterns" debe ser utilizada dentro del ámbito de proyecto para seguir las reglas marcadas por seguridad/arquitectura y simplificar la construcción de determinados servicios mediante CDK. Los constructores incluidos en la librería son los siguientes:

  • ApiGatewayBackL3: Construct que incluye la creación de Api Gateway REST, Lambda autorizadora y el establecimiento de un WAF con determinadas reglas por defecto para una aplicación de Backend (para API Publicas regional o Edge). La creación de los endpoints en API Gateway se realizará mediante su definición en OpenAPI3.0. Además, se validará que los endpoints creados para una ApiGatewayBackL3 estén securizados.

  • ApiGatewayBFFL3: Construct que incluye la creación de Api Gateway REST, Lambda autorizadora y el establecimiento de un WAF con determinadas reglas por defecto para una aplicación de BFF (para API Publicas regional o Edge). Los endpoints creados para una ApiGatewayBFFL3 no requieren estar securizados. Además, es posible personalizar el proceso de autenticación/autorización. Para consultar mas información sobre dicho proceso, consultar el siguiente enalce.

Todo APIGateway que se despliegue debe utilizar uno de estos constructores.

  • EcsFargatePlatformL3: Construct que genera un clúster ECS desplegado en Fargate, así como, opcionalmente, los servicios necesarios para exponer el clúster y sus microservicios.

  • EcsMicroServiceL3: Construct que genera un microservicio a partir de una imagen de Azure ACR, y al cual se le configura el clúster y los servicios de exposición del mismo.

Uso de la librería

Para el uso de la librería patterns y la posible creación de los objetos que ésta contiene, es necesario tener acceso al repositorio en el que esta contenida y, posteriormente, seguir los siguientes pasos:

  • Añadir la dependencia de la librería en el proyecto que se va a importar. Para ello, añadir la siguiente línea al archivo package.json del proyecto: arch-cdk-patterns@version

  • Descargar la dependencia de la librería: npm install arch-cdk-patterns@version

Una vez incluida y descargada la dependencia es posible el uso de la librería y, por tanto, la creación de los objetos que esta contiene, para ello, será necesario llamar al constructor del objeto a crear.

Construcción de los objetos ApiGatewayBackL3 o ApiGatewayBFFL3

Para la configuración del objeto ApiGatewayL3 se han defindo las siguientes categorías:

  • init
  • api
  • security
  • access
  • network
  • certificate
  • vpc
  • deployOptions

Valores obligatorios

A continuación se listan los parámetros obligatorios junto con su descripción, ordenados segun su categoría:

  • init
    • restApiName: indica el nombre de la api
    • projectNamespace: utilizado para la construcción unitaria del nombre para AWS
  • api
    • apiDefinition: Creado a partir del ContractPath en el método api()
    • env: Entorno del api
    • deploy: Indica si esta api va a ser desplegada
  • security
    • verifierIssuer: Parámetros de seguridad de Azure
    • verifierAudience: Parámetros de seguridad de Azure
    • verifierJwksUri: Parámetros de seguridad de Azure
    • authParameterStore: Parámetros de seguridad de Azure
  • access (*)
    • type: Tipo de acceso
    • endpointType: Tipo de endpoint
  • deployOptions
    • accessLogDestination: Obligatorio, pero se le da valor automáticamente, el destino de los logs
    • variables: Variables de Api
      • apiStage: Entorno de despliegue
      • projectName: Nombre del proyecto
      • apiName: Nombre de la API

* Ver detalle de tipo en el apartado (Configuraciónes de acceso)

Valores por defecto

Para facilitar la creación de APIs se han definido una serie de valores por defecto de algunos de los parámetros:

  • api
    • retainDeployments: false
    • cloudWatchRole: true
    • failOnWarnings: true
    • disableExecuteApiEndpoint: true
  • access
    • type: 'INTERNET'
    • endpointType: apigateway.EndpointType.REGIONAL

  • deployOptions:

    • accessLogDestination: Objeto CDK cuyo nombre se configura automáticamente con los siguientes componentes: init.projectNamespace + '-' + init.restApiName + '-AcessLogs'
    • accessLogFormat: apigateway.AccessLogFormat.custom(${apigateway.AccessLogField.contextRequestId()}${apigateway.AccessLogField.contextIdentitySourceIp()}${apigateway.AccessLogField.contextPath()}${apigateway.AccessLogField.contextErrorMessage()}${apigateway.AccessLogField.contextErrorMessageString()})
    • dataTraceEnabled: true
    • cacheClusterEnabled: false
    • cacheDataEncrypted: false
    • throttlingBurstLimit: 1000
    • throttlingRateLimit: 100
    • cachingEnabled: false
    • loggingLevel: apigateway.MethodLoggingLevel.INFO
    • cacheTtl: cdk.Duration.minutes(5)
    • metricsEnabled: true
    • tracingEnabled: true

    • methodOptions:

      {
  '/_/_': {
    throttlingRateLimit: 1000
    throttlingBurstLimit: 100
  },
},

Configuraciones de acceso

Las configuraciones que se deben utilizar del ApiGateway según el tipo de acceso (INTERNET, INTRANET, PRIVADO) y tipo de API Gateway (PUBLICOS/REGIONAL/EDGE) son las siguientes:

Tipo de AccesoAPI PRIVADOAPI PÚBLICO (regional/EDGE)
INTERNETNOSI
INTRANETSISI
PRIVADOSINO

  • El tipo de acceso define el "origen" de los clientes que van a invocar a API, pudiendo ser accesos de "INTERNET", accesos desde "INTRANET" o accesos "PRIVADO", desde dentro de la VPC de AWS. Se debe configurar con el método .access(type: string, endpointType: apigateway.EndpointType) con el valor correspondiente.

  • El tipo de API Gateway, define el tipo de API Gateway según la definición de AWS (PRIVADO, REGIONAL o EDGE). Se debe configurar con el método .access(type: string, endpointType: apigateway.EndpointType) con el valor correspondiente.

  • Cuando se configura un APIGatewayL3 de tipo privado, se configura un VPCEndpoint y se asignan las polí­ticas de acceso a subnets de la VPC y/o WhiteList asociando security group. En caso de que sea privado, se deben configurar las propiedades vpc() con el identificador de la vpc y () con las subnets a configurar.

  • Para invocación a Api Privado seguir el siguiente enlace

Ejemplo de implementación

Para crear y hacer uso de los objetos ApiGatewayBackL3 o ApiGatewayBFFL3 de la librería de patterns, dentro del stack de Integración, será necesario realizar los pasos que se indican en el escenario de Publicación de servicios REST.

Es necesario tener en cuenta que la configuración que se realice, debe cumplir con los requisitos de seguridad y utilización impuestos por la arquitectura. Para asegurar que dichos requisitos se cumplen, se utilizará librería "arch-cdk-aspects". En dicha documentación, es posible consultar las distintas reglas que se aplican para cada servicio, teniendo en cuenta que éstas son distintas en función del arquetipo con el que se esté trabajando.

Creación de objetos EcsFargateClusterL3 y EcsMicroServiceL3

EcsFargateClusterL3

Para la configuración del objeto EcsFargateClusterL3 se han defindo las siguientes categorías:

  • name
  • networking
  • exposed
  • service
  • alb
  • nlb
Valores obligatorios EcsFargateClusterL3

A continuación se listan los parámetros obligatorios junto con su descripción, ordenados segun su categoría:

  • name: Nombre del Cluster
  • networking
    • vpc: VPC del cluster
    • vpcLinkName: Nombre del Link de la VPC
    • subnets: Subnets del VPC
  • exposed
    • isExposedInALB: Indica si está expuesto el ALB
    • isExposedInALBGateway: Indica si está expuesto el ALB gateway
  • alb
    • name
    • albSecurityGroupName
  • nlb
    • name
  • service
    • securityGroupName
Valores por defecto EcsFargateClusterL3
  • exposed
    • isExposedInAPIGateway: true
    • isExposedInALB: true
Ejemplo de implementación EcsFargateClusterL3

Para crear y hacer uso de una EcsFargateClusterL3 o EcsMicroServiceL3 de la librería de patterns, será necesario realizar una llamada al constructor de dicha clase.

En el caso del clúster, props configura este y los demás servicios de exposición de clúster que se entregan con el constructor. En el siguiente enlace se puede consultar la documentación sobre dichos parámetros.

EcsMicroServiceL3

Para la configuración del objeto EcsFargateClusterL3 se han defindo las siguientes categorías:

  • micro
  • iexposed
  • scalation
  • targetGroup
  • networking
  • fargate
  • containerRegistry+
  • log
  • imageUrl
Valores obligatorios EcsMicroServiceL3

A continuación se listan los parámetros obligatorios junto con su descripción, ordenados segun su categoría:

  • fargate
    • alb
    • nlb
    • cluster
    • serviceSecurityGroup
    • subnets
  • log
    • groupName
    • streamPrefix
  • networking
    • subnets
  • containerRegistry
    • secretARN
  • imageUrl
  • exposed
    • isExposedInALB
    • isExposedInAPIGateway
  • micro
    • microserviceName
Valores por defecto EcsMicroServiceL3
  • exposed
    • isExposedInAPIGateway: true,
    • isExposedInALB: true,
    • externalPort: 8080,
    • protocol: ApplicationProtocol.HTTP,
  • micro
    • internalPort: 8080,
    • cpu: 256,
    • memoryLimitMiB: 512,
  • scalation
    • desiredCount: 2,
    • minCapacity: 2,
    • maxCapacity: 4,
    • CPUPercent: 80,
    • memoryPercent: 80,
    • targetUtilizationPercent: 80,
    • scaleInCooldown: Duration.seconds(30),
    • scaleOutCooldown: Duration.seconds(30),
  • targetGroup
    • minHealthPercent: 50,
    • maxHealthPercent: 100,
Ejemplo de implementación EcsMicroServiceL3

Para el microservicio, se configuran sus parámetros de configuración. En el siguiente enlace se puede consultar la documentación sobre dichos parámetros.

Construcción de Objetos State Machine

Para la configuración del objeto StateMachineL3 se han defindo las siguientes categorías:

  • name
  • definition
  • roleArn
  • logging
  • tracingEnabled

Valores obligatorios

A continuación se listan los parámetros obligatorios junto con su descripción, ordenados segun su categoría:

  • name: indica el nombre del StateMachineL3
  • definition: definición del StateMachineL3

Valores por defecto

Para facilitar la creación de APIs se han definido una serie de valores por defecto de algunos de los parámetros:

  • logging:
    • level: stepfunctions.LogLevel.ALL
    • includeExecutionData: true
  • tracingEnabled: true

Uso de ESLint

La revisión de código se realiza con ESLint utilizando el complemento SonarQube para adherirse a las mejores prácticas.

ESLint es una herramienta de análisis de código estático de código abierto ampliamente utilizada para JavaScript, con soporte para ECMAScript 2015 (ES6) y versiones posteriores. Está diseñada para ayudar a los desarrolladores a mantener la calidad del código, detectar posibles problemas y hacer cumplir estándares de codificación. Aquí tienes un resumen de las características clave de ESLint, junto con una mención de su compatibilidad con ECMAScript 2015 (ES6) y el complemento SonarQube:

  1. Análisis de Calidad de Código: ESLint analiza tu código JavaScript estáticamente para identificar y reportar problemas de calidad de código, posibles errores y violaciones de estilo de codificación. Ayuda a mantener un alto estándar de calidad del código en tus proyectos.

  2. Reglas Personalizables: ESLint te permite configurar y personalizar reglas basadas en las pautas específicas de codificación y preferencias de tu proyecto. Puedes habilitar, deshabilitar o modificar reglas para que coincidan con los estándares de codificación de tu equipo.

  3. Soporte ES6: ESLint admite completamente ECMAScript 2015 (ES6) y versiones posteriores, lo que lo hace compatible con la sintaxis y las características modernas de JavaScript. Puede analizar código que utiliza características como funciones de flecha, desestructuración y literales de plantilla.

  4. Sistema de Complementos: ESLint tiene un rico ecosistema de complementos y extensiones que proporcionan reglas e integraciones adicionales. El complemento SonarQube, por ejemplo, amplía las capacidades de ESLint para integrarse con SonarQube y realizar un análisis y reporte de código aún más completo.

  5. Integración con Herramientas de Construcción: ESLint se integra perfectamente con herramientas de construcción populares y entornos de desarrollo, como Webpack, Babel y Visual Studio Code, lo que te permite incorporar el análisis de código en tu flujo de trabajo de desarrollo.

  6. Formateo Automático de Código: Aunque ESLint se centra principalmente en el análisis de código, puede funcionar junto con formateadores de código como Prettier para formatear automáticamente tu código según las reglas definidas, garantizando un estilo de codificación consistente.

  7. Configuraciones Configurables: Las configuraciones de ESLint se pueden compartir entre proyectos para mantener la consistencia. Puedes crear y compartir archivos de configuración de ESLint, lo que facilita la imposición de estándares de codificación en múltiples bases de código.

  8. Integración en la Integración Continua (CI): ESLint suele integrarse en canalizaciones de Integración Continua (CI/CD) para hacer cumplir automáticamente la calidad del código y los estándares de estilo, evitando que se fusionen en la base de código código de baja calidad.

Detalles de Ejecución

Para configurar ESLint y configurarlo para que utilice el complemento "plugin:sonarjs/recommended" para las reglas de SonarQube, sigue estos pasos:

  1. Instala ESLint:

    • Si aún no has instalado ESLint, puedes agregarlo como una dependencia de desarrollo en tu proyecto utilizando npm o yarn:
    npm install --save-dev eslint

    o

    yarn add --dev eslint

  2. Crea una Configuración de ESLint:

    • Puedes crear un archivo de configuración de ESLint en la raíz de tu proyecto. Normalmente, este archivo se llama .eslintrc.js o .eslintrc.json. Aquí tienes un ejemplo de archivo de configuración .eslintrc.js que incluye el complemento "plugin:sonarjs/recommended":
    module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:sonarjs/recommended', // Incluye reglas recomendadas de SonarQube
  ],
  parserOptions: {
    ecmaVersion: 2015, // Establece tu versión de ECMAScript (ES2015 en este caso)
  },
  rules: {
    // Puedes agregar reglas específicas del proyecto de ESLint aquí
  },
};

    Personaliza las reglas de ESLint para que se ajusten a los requisitos de tu proyecto agregando o modificando reglas en la sección rules.

  3. Instala el Complemento de SonarQube:

    • Asegúrate de tener instalado el complemento "eslint-plugin-sonarjs". Si aún no está instalado, puedes agregarlo como una dependencia de desarrollo:
    npm install --save-dev eslint-plugin-sonarjs

    o

    yarn add --dev eslint-plugin-sonarjs

  4. Ejecuta ESLint:

    • Ahora puedes ejecutar ESLint para analizar tu código en función de las reglas configuradas. Utiliza

    el siguiente comando:

    npx eslint . --fix

    La bandera --fix corrige automáticamente algunos de los errores de linting si es posible.

@aws-solutions-constructs/aws-wafwebacl-apigateway@aws-solutions-constructs/core@stoplight/spectral-core@stoplight/spectral-functions@stoplight/spectral-parsers@syss/arch-nodejs-runtimeaws-cdk-libaws-jwt-verifyconstructsjsonwebtoken
@everything-registry/sub-chunk-890@syss/arch-archetype-base-backend
1.0.0

6 months ago