Verificando autenticación…

Saltar al contenido principal

Documentación: Template Java Cloud Function

Propósito y Alcance​

Este proyecto sirve como una plantilla base para crear Google Cloud Functions utilizando Java 21 y Gradle. El propósito principal es proporcionar una estructura de proyecto inicial, configuración de compilación y un ejemplo funcional simple ("Hello World") que puede ser desplegado como una función HTTP.

Objetivos:

  • Ofrecer un punto de partida estandarizado para el desarrollo de Cloud Functions en Java.
  • Facilitar la configuración del entorno local y el proceso de compilación.
  • Integrar buenas prácticas básicas, como la inclusión de un header de seguridad.
  • Definir la estructura para el despliegue a través de pipelines de CI/CD.

Alcance:

  • Creación de una Cloud Function HTTP simple.
  • Configuración para compilación con Gradle y Java 21.
  • Instrucciones para ejecución local y pruebas unitarias.
  • Guía de despliegue en Google Cloud Platform.
  • No incluye, por defecto, integraciones con otros servicios como Pub/Sub, Cloud Storage, Redis, Kafka, etc., pero está diseñado para ser extensible.

Arquitectura​

El proyecto está diseñado para ser desplegado como una Google Cloud Function, que es un componente de cómputo serverless ofrecido por Google Cloud Platform (GCP). La función se ejecuta en respuesta a eventos, en este caso, una solicitud HTTP.

Visión General:

  • Serverless: No hay servidores que gestionar. GCP maneja la infraestructura subyacente.
  • Activador HTTP: La función de ejemplo (com.latam.template.java.function.Function) se invoca mediante una petición HTTP.
  • Entorno de Ejecución: Java 21 (configurado para Gen2 de Cloud Functions).
  • Escalabilidad: GCP escala automáticamente el número de instancias de la función según la demanda.

No se incluye un diagrama de arquitectura visual en esta plantilla. Un diagrama típico mostraría un cliente realizando una solicitud HTTP a un endpoint de la Cloud Function, esta procesando la solicitud y devolviendo una respuesta.

Tecnologías y Dependencias​

A continuación, se listan las principales tecnologías y librerías utilizadas en este proyecto plantilla:

  • Lenguaje de Programación: Java 21
  • Framework de Cloud Functions:
    • com.google.cloud.functions:functions-framework-api:1.1.0 (API para desarrollar funciones)
    • com.google.cloud.functions.invoker:java-function-invoker:1.3.1 (Para ejecución local)
  • Herramienta de Compilación y Gestión de Dependencias: Gradle 7.6.4 (según gradle-wrapper.properties)
  • Pruebas:
    • JUnit 4.13.2
    • Google Truth 1.1.5
    • Mockito Core 4.11.0
  • Despliegue:
    • Google Cloud Platform (Cloud Functions)
    • GitLab CI/CD (utilizando $LATAM_PIPELINE_CLOUD_FUNCTION_DEPLOY)
  • Repositorio de Artefacto: JFrog Artifactory (configurado en gradle/latam-repo.gradle)

Configuración Local​

Prerrequisitos​

  • JDK (Java Development Kit) versión 21.
  • Git.
  • Gradle (opcional, ya que el proyecto incluye un wrapper ./gradlew que descargará la versión correcta).
  • Acceso a JFrog Artifactory con credenciales válidas (usuario y contraseña/API key).
  • IDE de desarrollo (opcional, ej: IntelliJ IDEA, Eclipse).

Pasos de Configuración​

  1. Clonar el repositorio: Sigue los siguientes pasos

  2. Configurar credenciales de Artifactory: Crea un archivo gradle.properties en la raíz del proyecto (este archivo está excluido por .gitignore) con tus credenciales de JFrog Artifactory.

    ARTIFACTORY_BASE_URL=https://artifactoryrepo1.appslatam.com/artifactory/
    ARTIFACTORY_GRADLE_CORP_REPO=corp-libs-gradle-release
    ARTIFACTORY_USERNAME=<tu_usuario_artifactory>
    ARTIFACTORY_PASSWORD=<tu_api_key_artifactory_o_token>

    Estas variables también pueden ser configuradas como variables de entorno del sistema.

  3. Compilar el proyecto: Utiliza el wrapper de Gradle para compilar el proyecto. Esto descargará las dependencias y generará los artefactos necesarios.

    ./gradlew clean build

  4. Ejecutar la función localmente: Puedes ejecutar la Cloud Function en tu máquina local utilizando el invoker de Functions Framework.

    ./gradlew runFunction -Prun.functionTarget=com.latam.template.java.function.Function -Prun.port=8080

    Una vez iniciada, la función estará escuchando en http://localhost:8080. Puedes probarla accediendo a esta URL desde un navegador o una herramienta como curl.

Despliegue​

Despliegue Automatizado (GitLab CI/CD)​

El despliegue de esta Cloud Function se gestiona principalmente a través de pipelines de GitLab CI/CD.

  • El archivo .gitlab-ci.yml incluye el componente $LATAM_PIPELINE_CLOUD_FUNCTION_DEPLOY, que automatiza el proceso.
  • La configuración específica del despliegue para cada entorno (develop, cert, intg, prod) se define en los archivos YAML dentro del directorio deploy/env/.
  • Parámetros clave de la Cloud Function como el runtime, memoria, timeout y service account se definen en deploy/function/runtime-config.yaml.erb: 
    runtime: java21
    memory: 1024MB
    timeout: 540s
    region: "<%= region %>"
    trigger-http: ~
    execution-environment: gen2
    entry-point: com.latam.template.java.function.Function
    update-labels: "cmdb-<%= cmdb_it_element %>=<%= cmdb_it_element %>"
    service-account: "<%= service_account %>"
  • Variables de entorno para la función se gestionan a través de deploy/function/environment.yaml.erb y los archivos de entorno correspondientes (ej. deploy/env/dev.yaml).

Despliegue Manual (gcloud CLI)​

Si es necesario realizar un despliegue manual, se puede utilizar la herramienta gcloud CLI. El archivo readme.md del proyecto lista varias opciones de configuración disponibles para el comando gcloud functions deploy. Un ejemplo básico podría ser:

gcloud functions deploy NOMBRE_DE_LA_FUNCION \
    --runtime java21 \
    --trigger-http \
    --entry-point com.latam.template.java.function.Function \
    --region TU_REGION \
    --project TU_ID_DE_PROYECTO \
    --source . \
    --service-account TU_SERVICE_ACCOUNT_EMAIL \
    --allow-unauthenticated  # O configurar IAM según sea necesario

Asegúrate de ajustar los parámetros (NOMBRE_DE_LA_FUNCION, TU_REGION, etc.) según tus necesidades.

Endpoints de la API​

La función de ejemplo expuesta por esta plantilla es una función HTTP simple.

Método HTTPRuta esperada en Cloud FunctionDescripciónAutenticaciónEjemplo de Respuesta Esperada (Cuerpo)Headers de Respuesta Incluidos
GET (u otros métodos HTTP)/ (ruta raíz de la función)Devuelve un mensaje de saludo "Hello World!".Depende de la config. de GCP (--allow-unauthenticated o IAM)Hello World!Strict-Transport-Security: max-age=31536000; includeSubDomains

Ejemplo de Solicitud (usando curl):

curl http://localhost:8080/  # Durante ejecución local
# o la URL de la función desplegada en GCP

Respuesta de Ejemplo (200 OK):

  • Cuerpo: 
    Hello World!
  • Headers:
    • Content-Type: text/plain (o similar, puede depender de la configuración exacta del invoker/GCP)
    • Strict-Transport-Security: max-age=31536000; includeSubDomains

Componentes Específicos​

Esta es una plantilla base y, como tal, no incluye integraciones complejas con otros servicios de GCP (como Pub/Sub, Cloud Storage, Firestore, Redis, Kafka, etc.) fuera de la caja. Su objetivo es proporcionar una estructura mínima funcional.

Para agregar funcionalidades específicas:

  1. Añadir Dependencias: Incluye las librerías cliente necesarias en gradle/dependencies.gradle.
  2. Configuración: Agrega las propiedades de configuración necesarias (ej. en application.yaml si se usara Spring} Boot, o directamente como variables de entorno para la Cloud Function).
  3. Implementación: Desarrolla la lógica de negocio en tus clases Java, utilizando las APIs de los servicios correspondientes.
  4. Service Account Permissions: Asegúrate de que el Service Account utilizado por la Cloud Function tenga los permisos IAM necesarios para interactuar con los servicios de GCP que integres.

Pruebas​

El proyecto está configurado para soportar pruebas unitarias utilizando JUnit, Google Truth y Mockito.

Ejecución de Pruebas​

Para ejecutar todas las pruebas unitarias definidas en el proyecto, utiliza el siguiente comando Gradle:

./gradlew test

Los resultados de las pruebas se generarán en el directorio build/reports/tests/test/.

Escribir Pruebas​

  • Las pruebas unitarias se encuentran típicamente en el directorio src/test/java.
  • Se recomienda seguir las mejores prácticas para nombrar clases de prueba (ej., MiClaseTest.java) y métodos de prueba.

Consideraciones de Seguridad​

  • Headers de Seguridad: La función de ejemplo incluye el header Strict-Transport-Security para mejorar la seguridad en las comunicaciones HTTPS. 
    response.appendHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
  • Gestión de Credenciales:
    • Artifactory: Las credenciales (ARTIFACTORY_USERNAME, ARTIFACTORY_PASSWORD) deben ser gestionadas de forma segura. Se recomienda usar un archivo gradle.properties local (no comiteado) o variables de entorno en los sistemas de CI/CD.
    • Google Cloud Platform (GCP): La Cloud Function se ejecuta con un Service Account. Asegúrate de que este Service Account tenga los permisos mínimos necesarios (Principio de Menor Privilegio) para operar. Las credenciales del Service Account son gestionadas por GCP.
  • Autenticación de Endpoints: Por defecto, las Cloud Functions pueden ser públicas (--allow-unauthenticated) o requerir autenticación/autorización a través de IAM. Configura esto según los requisitos de seguridad de tu aplicación.
  • Dependencias: Mantén las dependencias del proyecto actualizadas para mitigar vulnerabilidades conocidas. Revisa periódicamente los informes de seguridad de las librerías utilizadas.