🤝Integrando CodeCatalyst con GitHub y Terraform: 🚀 Desplegando AWS Cognito

Buenas de nuevo, siguiendo con el descubrimiento del servicio AWS CodeCatalyst. En este post exploraremos cómo integrar AWS CodeCatalyst con un repositorio de GitHub existente para automatizar el despliegue de infraestructura usando Terraform, en este caso específico , desplegaremos un AWS Cognito.

🚀 ¿Qué papel cumple cada uno de los actores?

Utilizaremos, AWS CodeCatalyst como plataforma de CI/CD, GitHub como repositorio de código fuente, y Terraform como Infrastructure as Code, desplegando recursos de AWS Cognito.

🛠️ Prerrequisitos

• AWS Builder ID configurado
• Cuenta de AWS (Aunque estemos en la capa gratuita necesitamos una cuenta de AWS)
• Acceso a CodeCatalyst
• Repositorio GitHub: https://github.com/olcortesb/cognito-terraform

📋 Configuración Inicial

Paso 1: Conectar repositorio GitHub a CodeCatalyst

Dentro de code catalyst: https://codecatalyst.aws/ en el espacio de trabajo que tengamos activo creamos un nuevo proyecto:

Aceptamos términos y condiciones:

Especificar el repositorio y aceptar:

# Clonar el repositorio de ejemplo
git clone  https://github.com/olcortesb/cognito-terraform.git

Paso 2: Configurar variables de Terraform

El código de Terraform es el mismo que utilizamos en un post anterior para desplegar AWS Cognito. Ver artículo

# Variables principales para Cognito
variable "user_pool_name" {
  description = "Name of the Cognito User Pool"
  type        = string
}

🔧 Implementación

Creación del Workflow de Terraform

En CodeCatalyst, creamos un workflow que automatiza el proceso de despliegue de Terraform en dos etapas: Plan y Apply. Aquí una recomendación es crear el yaml directamente dentro del código del proyecto similar a como trabajamos con GitHub Actions y GitLab. La dirección y estructura es la siguiente:

# Ruta del .yaml que define el pipeline
.codecatalyst/workflows/onPushToMainDeploymentWorkflow.yaml

Y el código dentro del yaml:

Name: onPushToMainDeploymentWorkflow
SchemaVersion: "1.0"
# ---------------------------------------------------------------------------------
# Trigger: Se activa con cada push a la rama 'main'
# ---------------------------------------------------------------------------------
Triggers:
  - Type: PUSH
    Branches:
      - main
# ---------------------------------------------------------------------------------
# Actions: Define los pasos del flujo de trabajo
# ---------------------------------------------------------------------------------
Actions:
  # -------------------------------------------------------------------------------
  # PASO 1: Inicializa Terraform y crea un plan de ejecución.
  # El plan se guarda como un artefacto para usarlo en el siguiente paso.
  # -------------------------------------------------------------------------------
  TerraformInitAndPlan:
    Identifier: aws/build@v1
    Compute:
      Type: EC2
      Fleet: Linux.x86-64.Large
    Inputs:
      Sources:
        - WorkflowSource
    Outputs:
      Artifacts:
        - Name: ART01
          Files:
            - "tfplan"
            - ".terraform.lock.hcl"
            - ".terraform/**/*"
            - ".terraform/providers/**/*"
            - ".terraform/modules/**/*"
    Configuration:
      Steps:
        - Run: |
            wget https://releases.hashicorp.com/terraform/1.9.8/terraform_1.9.8_linux_amd64.zip
            unzip terraform_1.9.8_linux_amd64.zip
            chmod +x terraform
        - Run: ./terraform init
        - Run: ./terraform plan -var="environment=dev" -var="region=eu-central-1" -out=tfplan
    Environment:
      Name: dev
      Connections:
        - Name: olcortesb-account
          Role: CodeCatalystWorkflowDevelopmentRole-olcortesb
  # -------------------------------------------------------------------------------
  # PASO 2: Aplica el plan de Terraform creado en el paso anterior.
  # Depende de que 'TerraformInitAndPlan' haya finalizado con éxito.
  # -------------------------------------------------------------------------------
  TerraformApply:
    Identifier: aws/build@v1
    DependsOn:
      - TerraformInitAndPlan
    Compute:
      Type: EC2
      Fleet: Linux.x86-64.Large
    Inputs:
      Sources:
        - WorkflowSource
      Artifacts:
        - ART01
    Configuration:
      Steps:
        - Run: cd $CATALYST_SOURCE_DIR_ART01
        - Run: |
            wget https://releases.hashicorp.com/terraform/1.9.8/terraform_1.9.8_linux_amd64.zip
            unzip terraform_1.9.8_linux_amd64.zip
            chmod +x terraform
        - Run: ./terraform apply -auto-approve tfplan
    Environment:
      Name: dev
      Connections:
        - Name: olcortesb-account
          Role: CodeCatalystWorkflowDevelopmentRole-olcortesb

Ejemplo de como se ve visualmente el pipeline que hemos implementado después de ejecutarlo:

Características del Workflow

Estructura de dos etapas:

1. TerraformInitAndPlan: Descarga Terraform, inicializa el proyecto y crea un plan
2. TerraformApply: Aplica los cambios usando el plan generado

Configuración clave:

• Compute: EC2 con Fleet: Linux.x86-64.Large para mejor rendimiento
• Environment: dev con conexión a la cuenta AWS
• Artefactos: Transfiere el plan entre etapas (con incidencia conocida)
• Variables: environment=dev y region=eu-central-1

Como trabajar con los Artifacts

💡 Agrego este apartado porque es interesante y me llevo un tiempo hacerlo andar, es necesario colocar un prefijo al nombre del artefacto, $CATALYST_SOURCE_DIR_{NAME} está en la documentación cada caso específico y colocar patrones de acceso al subirlos para que tome los subdirectorios como se ve en código del pipeline que desplegamos:

# References: https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-working-artifacts-ex.html
Actions:
  BuildActionG:
    Identifier: aws/build@v1  
    Outputs:
      Artifacts:
        - Name: ART8
          Files:
            - build-output/file8.txt
  BuildActionH:
    Identifier: aws/build@v1  
    Inputs:
      Sources:
        - WorkflowSource
      Artifacts:
        - ART8
    Configuration:
      Steps:
        - run: cd $CATALYST_SOURCE_DIR_ART8/build-output && cat file8.txt

Workaround implementado:

• Se reinstala Terraform en ambas etapas
• Se regenera el plan en la etapa Apply
• Se mantiene la estructura de dos etapas para demostración

🧪 Pruebas y Validación

Verificar el despliegue de Cognito

Una vez ejecutado el workflow, verificamos que los recursos se crearon correctamente:

# Verificar User Pool en AWS CLI

aws cognito-idp list-user-pools --max-results 10 --region eu-central-1 | \
  jq '.UserPools[] | select(.Name | contains("<your-user-pool-name>"))'

# Output
# {
#   "Id": "eu-central-1_XXXXXXXXX",
#   "Name": "<your-user-pool-name>",
#   "LambdaConfig": {},
#   "LastModifiedDate": "2025-08-26T19:42:05.460000+02:00",
#   "CreationDate": "2025-08-26T19:42:05.460000+02:00"
# }

# Verificar desde la consola AWS
# Cognito → User Pools → Buscar el pool creado

🚀 Análisis del Despliegue

Configurado para push en rama main

El despliegue se ejecuta automáticamente con cada push a la rama main:

Análisis de los elementos del .yaml

1. Trigger: Push a main activa el workflow
2. Plan Stage: Descarga Terraform, inicializa y planifica
3. Apply Stage: Aplica los cambios en AWS
4. Resultado: Recursos de Cognito desplegados

📊 Resultados y conclusiones

• ✅ Integración entre CodeCatalyst, GitHub y Terraform
• ✅ Automatización del despliegue de infraestructura
• ✅ Despliegue de AWS Cognito usando Terraform
• ✅ Pipeline de CI/CD funcional con dos etapas

Recursos creados:

• AWS Cognito User Pool
• Configuración de cliente para autenticación
• Políticas de seguridad asociadas

💡 Buenas Prácticas

• ✅ Usar Environment específico para cada etapa de despliegue
• ✅ Separar Plan y Apply en etapas diferentes para mejor control, también podemos configurar el apply manual, pero lo dejamos para otro post...
• ✅ Incluir validación antes del plan para detectar errores temprano
• ✅ Usar Fleet EC2 Large para mejor rendimiento en proyectos grandes

🔗 Referencias y Enlaces Útiles

• Post anterior: Probando AWS CodeCatalyst desde el AWS Builder ID
• Post anterior de cognito + terraform
• AWS CodeCatalyst Documentation
• CodeCatalyst Workflows
• Terraform AWS Cognito
• Repositorio de ejemplo
• GitHub Integration with CodeCatalyst
• CodeCatalyst Artifacts

Gracias por leer, Saludos…