Nota:

Llamar a la función personalizada de Oracle Cloud Infrastructure con evento de notificación y publicar el mensaje actualizado en la herramienta de colaboración Lark

Introducción

Los clientes de Oracle Cloud Infrastructure (OCI) reciben notificaciones a través de temas de notificación de OCI suscritos, que abarcan eventos como eventos de instancia, alarmas, anuncios de consola, etc. Estos temas suscritos también soportan funciones de OCI como destinos de notificación, lo que permite a los clientes invocar una función personalizada durante el evento de notificación y enviar detalles de notificación actualizados a canales de comunicación que soportan la llamada de API. En este tutorial, le mostraremos cómo reenviar estas notificaciones actualizadas a Lark, una plataforma de colaboración empresarial con API de mensajería.

Con una función de OCI personalizada, puede recuperar varios datos y realizar acciones; a continuación, se muestran algunos ejemplos como:

En este tutorial se proporciona un completo repaso de cómo disparar una función de OCI personalizada en respuesta al evento de potencia de una instancia, como STOP. Los usuarios tienen la flexibilidad de personalizar esta función y dispararla en función de varios temas de notificación de OCI suscritos. Para obtener más información sobre OCI Functions, consulte Visión general de OCI Functions.

Objetivo

OCI Functions permite escribir código personalizado al que se puede llamar en función de la notificación de OCI, el tema Notificación suscrita del anuncio de OCI, el evento de la instancia informática y mucho más. En este tutorial hemos creado una función personalizada escrita en código Python que se llama en función de un evento de notificación y publica el mensaje actualizado en la herramienta de colaboración Lark mediante una URL de webhook dentro del código. Esto le proporciona una opción para incluir y actualizar la información adicional necesaria que puede consumir el usuario final.

Requisitos

Destinatarios

Este tutorial está dirigido a administradores y profesionales de proveedores de Cloud Service.

Arquitectura

A continuación se muestra una topología de casos de uso de ejemplo y una arquitectura de alto nivel de la solución.

Arquitectura de conectividad entre regiones de interconexión de OCI Azure

Puede consultar esta arquitectura cuando desee crear una función de OCI personalizada y llamarla en función del evento de notificación. Puede seguir una serie de tareas descritas en este tutorial para configurar y validar esta arquitectura.

Tarea 1: Creación de un grupo dinámico

Los grupos dinámicos permiten agrupar instancias informáticas de OCI como actores "principales" (de manera similar a los grupos de usuarios).

Nota: Necesita privilegios de administrador para crear grupos dinámicos.

  1. Inicie sesión en la cuenta de arrendamiento de la consola de OCI.

  2. En el menú Servicios, seleccione Identidad y seguridad y, a continuación, en la sección Identidad, seleccione Grupos dinámicos.

  3. Haga clic en Crear grupo dinámico.

  4. Introduzca un nombre y una descripción significativos.

  5. En la sección Regla 1, agregue la siguiente línea:

    ALL {resource.type = 'fnfunc', resource.compartment.id = 'ocid1.compartment.oc1', instance.compartment.id = 'ocid1.compartment.XXXXX'}

    Nota:

    • Sustituya el ID de compartimento por el ID de compartimento deseado.
    • También puede incluir un OCID de recurso de función específico en el grupo dinámico.

  6. Haga clic en Crear y el grupo dinámico se debe crear correctamente como se muestra en la siguiente imagen.

    Grupo dinámico creado

Tarea 2: Creación de política de OCI IAM de grupo dinámico

Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) le permite controlar quién tiene acceso a sus recursos en la nube. Para que esta arquitectura funcione, necesitamos otorgar acceso para la función como servicio faas a los recursos informáticos, las redes y otros servicios.

  1. En el menú Servicios, seleccione Identidad y seguridad y, a continuación, en la sección Identidad, seleccione Políticas.

  2. Haga clic en Crear política.

  3. Introduzca un nombre y una descripción adecuados y asegúrese de seleccionar el compartimento correcto (en este ejemplo, utilizaremos el nombre de compartimento oc-demo).

  4. En la sección Creador de políticas, asegúrese de activar la opción Mostrar editor manual y pegue las siguientes líneas:

    Allow dynamic-group <dynamic_group_name> to read instances in compartment <compartment_name_path>

    Allow dynamic-group <dynamic_group_name> to read vnics in compartment <compartment_name_path>

    Allow dynamic-group <dynamic_group_name> to read vnic-attachments in compartment <compartment_name_path>

    Nota: Sustituya el nombre dynamic_group_name y compartment_name_path por los valores deseados.

  5. Haga clic en Crear y la política se debe crear correctamente en el nivel de raíz/de compartimento, como se muestra en la siguiente imagen.

    Política de IAM creada

Tarea 3: Crear un repositorio para almacenar la imagen de función personalizada

Container Registry permite almacenar, compartir y gestionar imágenes de contenedor (por ejemplo, las imágenes de Docker) en un registro gestionado por Oracle.

  1. En la consola, abra el menú de servicio y haga clic en Servicios para desarrolladores. En Contenedores, haga clic en Registro de contenedor.

  2. Haga clic en Crear repositorio.

  3. En el cuadro de diálogo Crear repositorio, especifique Compartimento y Nombre de repositorio de su elección y déjelo Privado.

  4. Haga clic en Crear repositorio y el registro de contenedor se debe crear correctamente en el compartimento especificado, como se muestra en la siguiente imagen.

    Repositorio de Container Registry creado

Tarea 4: cree una red virtual en la nube con subred para almacenar la función application.

Una red virtual en la nube (VCN) es una red que se define en OCI. Incluye subredes, tablas de rutas y gateways.

Nota: Si ya tiene una VCN, la subred creada anteriormente puede omitir esta tarea y continuar con la Tarea 5.

  1. Haga clic en el menú de servicios situado cerca de la esquina superior izquierda de la consola web de OCI.

  2. En Red, seleccione Redes virtuales en la nube.

  3. En la página Redes virtuales en la nube, haga clic en Iniciar asistente de VCN.

  4. Seleccione Crear una VCN con conexión a Internet y haga clic en Iniciar asistente de VCN.

  5. Complete la configuración de la VCN y, a continuación, haga clic en Siguiente.

  6. Haga clic en Crear y las redes virtuales en la nube con subredes se deben crear correctamente, como se muestra en la siguiente imagen.

    Red virtual creada con subred

Tarea 5: Creación de una Aplicación para Almacenar Funciones

  1. Abra el menú de servicio y haga clic en Servicios para desarrolladores. En Funciones, haga clic en Solicitudes.

  2. Haga clic en Crear aplicación.

  3. En la ventana Crear aplicación, seleccione el nombre de la aplicación (por ejemplo, aplicación de función), seleccione la VCN que ha creado en la tarea 4 y seleccione la subred pública.

  4. Haga clic en Crear y la aplicación de función se debe crear correctamente como se muestra en la siguiente imagen.

    Aplicación de función de creación

Tarea 6: Desplegar la función para almacenar funciones

En este paso se utilizará el archivo zip que se puede descargar de la sección Requisitos de este tutorial.

  1. Navegue a la consola en la nube de OCI y haga clic en Herramientas de desarrollador, Cloud Shell.

    Inicie Cloud Shell

  2. Una vez que haga clic en el botón Iniciar Cloud Shell, aparecerá una nueva ventana de shell pequeña al final de la página. En la esquina superior derecha de la ventana, haga clic en el menú de rueda dentada y seleccione Cargar.

    Cargar archivo ZIP

  3. Cargue el archivo zip disponible en la sección Requisitos previos de este tutorial y navegue hasta el directorio copiado.

  4. Verá el archivo func.py como se muestra a continuación para garantizar que puede leer JSON de notificación y agregar campos adicionales como los detalles de la dirección IP y utilizar el mensaje actualizado para enviar un mensaje a la URL del webhook de marca.

    • parse_message: notificación de lectura de función JSON y mensaje de actualización
    • get_ip_address: función que utiliza recursos informáticos, biblioteca de cliente de red para leer detalles adicionales como la dirección IP basada en el OCID de recurso de la instancia, por ejemplo.
    • make_post: función para realizar una publicación en el canal Lark mediante la URL del webhook.

    Nota:

    • Estamos utilizando OCI python sdk, pero puede personalizar según otros idiomas admitidos mediante go/java sdks.
    • Debe actualizar su URL de webhook, ya sea Lark u otras herramientas de colaboración como Slack.
    • Puede personalizar esta función en función de sus requisitos. Hemos utilizado cierta carga útil de JSON de notificación para leer valores, pero también puede utilizar el anuncio de consola JSON u otro evento JSON.
    ###
This is a sample code,
End user can modify as needed
###
import io
import oci
import json
import logging
import requests

"""
Read Notification Message
Add IP address of Resource.
"""
def parse_message(body):
    notification = ""
    ocid = ""
    type = body["source"]
    description = body["eventType"]
    compartment_id = body["data"]["compartmentId"]
    compartment_name = body["data"]["compartmentName"]
    affected_resources = ""

    if len(body["data"]) > 0:
        signer = oci.auth.signers.get_resource_principals_signer()
        affected_resources = "Affected Resources: "
        ocid = body["data"]["resourceId"]
        notification_reason = body["data"]["additionalDetails"]["instanceActionType"]
        affected_resources += "\nResource OCID: " + ocid
        resource_ip_address = get_ip_address(signer, ocid)
        affected_resources += "\nResource Private IP Address: " + resource_ip_address

    notification = type + " " + "\n\n" + compartment_name + " - " + compartment_id + "\n\n" + description + "\n\n" + affected_resources + "\n\n" + notification_reason
    logging.getLogger().debug(notification)

    make_post(notification)

"""
Get Resource IP address
based of resource OCID.
"""
def get_ip_address(signer, resource_id):
    compute_client = oci.core.ComputeClient(config={}, signer=signer)
    network_client = oci.core.VirtualNetworkClient(config={}, signer=signer)
    instance_details = compute_client.get_instance(instance_id=resource_id).data
    vnic_response = compute_client.list_vnic_attachments(compartment_id=instance_details.compartment_id, instance_id=resource_id)
    vnics = vnic_response.data

    for vnic in vnics:
        vnic_details = network_client.get_vnic(vnic_id=vnic.vnic_id).data
        private_ip = vnic_details.private_ip
        return private_ip

"""
Post a Message to Lark.
You can also use OCI Vault/Secret to store Lark credentials and access them here.
"""
def make_post(post_text):
    url = "https://open.larksuite.com/open-apis/bot/v2/hook/XXXX"
    headers = {
        "Content-Type": "application/json"
    }
    req_body = {
        "msg_type": "text",
        "content": {
            "text": post_text
        }
    }
    payload = json.dumps(req_body)
    try:
        post_response=requests.post(url=url, data=payload, headers=headers)
    except Exception as e:
        logging.getLogger().error(e)
        return

    response_dict = json.loads(post_response.text)
    code = response_dict.get("StatusCode", -1)

    if code != 0:
        logging.getLogger().error("error sending post text, code: " + str(code))
    return

def to_bool(a):
    return True if a == "True" else False

"""This is the function entry point.
ctx will contain function variables defined in OCI console,
data contains the payload
"""
def handler(ctx, data: io.BytesIO = None):
    try:
        cfg = dict(ctx.Config())
        for a in cfg:
            cfg[a]=to_bool(cfg[a])

    except Exception as e:
        print('ERROR: Missing configuration keys', e, flush=True)
        logging.getLogger().debug(cfg)
        return 'error parsing config keys: ' + str(ex)

    try:
        raw_body = data.getvalue()
        body = json.loads(raw_body)
        logging.getLogger().info(body)
        parse_message(body)
    except (Exception, ValueError) as ex:
        logging.getLogger().error('error parsing json payload: ' + str(ex))
        return 'error parsing json payload: ' + str(ex)

  5. Despliegue la función con el comando fn deploy para crear la imagen del docker de funciones y las dependencias asociadas en el shell en la nube. Puede transferir la imagen al registro de Docker especificado y desplegar la función en OCI Functions en la aplicación creada anteriormente.

    fn -v deploy --app <app-name>

    Por ejemplo:

    fn -v deploy --app function-app

    Nota: Puede ver los detalles necesarios de la imagen del docker de funciones en el archivo func.yaml.

  6. Una vez desplegada, la función se debe crear correctamente como se muestra en la siguiente imagen.

    Función Creada

Tarea 7: Suscripción de la función a un tema

  1. Abra el menú de servicio y haga clic en Servicios para desarrolladores. En Integración de aplicación, haga clic en Notificaciones. Asegúrese de que está en el compartimento correcto.

  2. Haga clic en Crear tema.

  3. Defina un nombre adecuado y, a continuación, haga clic en Crear.

  4. Una vez creado el tema, selecciónelo de la lista de temas.

  5. En la ventana Temas, seleccione Suscripciones en el lado izquierdo en Recursos y haga clic en Crear suscripción.

  6. En la ventana lateral Crear suscripción, seleccione el protocolo que desea que sea Functions, seleccione el compartimento, la aplicación y la función que se crearon en la Tarea 6.

  7. Haga clic en Crear, la función se debe suscribir correctamente a un tema como se muestra en la siguiente imagen.

    Suscripción de Notificación Creada

Tarea 8: Creación de una regla de evento de instancia y notificación

Para validar la función en este paso, crearemos una instancia y el tema de notificación de creación asociado en la Tarea 7 a un evento como parada por instancia.

  1. En la consola, vaya a Recursos informáticos, Instancias para crear una instancia informática.

  2. Haga clic en el icono Crear instancia y proporcione los detalles necesarios:

    • Nombre de instancia
    • Compartimento de la instancia
    • Seleccionar el dominio de disponibilidad deseado
    • Seleccionar la VCN de red y la subred pública
    • Copie y pegue su clave ssh pública
    • Haga clic en Crear.

  3. Espere a que la instancia muestre running y, a continuación, conéctese a la instancia con el siguiente comando.

    ssh opc@<public ip> -i <private key>

  4. Vaya a la ventana Recursos informáticos, Instancias, Detalles de instancia y Notificación para crear un evento de notificación.

  5. Haga clic en Crear notificación y seleccione una plantilla QuickStart como Cambio de estado de instancia a Parado.

  6. Introduzca el nombre de la regla de evento, seleccione el tema creado en la tarea 7 y haga clic en Crear notificación. La regla de evento de notificación se debe crear correctamente en un tema suscrito, como se muestra en la siguiente imagen.

    Regla de evento creada

Tarea 9: Validar regla de evento de notificación

En este paso, detendrá la instancia que disparará el tema de notificación asociado. También puede incluir su dirección de correo electrónico para ver la carga útil de notificación.

  1. Navegue a la instancia creada y haga clic en Parar.

  2. Una vez que la instancia se haya parado, debe obtener un correo electrónico a través del tema de notificación suscrito y se debe disparar la función.

  3. Confirme que ha recibido un correo electrónico como se muestra en la siguiente imagen.

    Correo electrónico de tema de notificación de OCI

  4. Vaya al canal Marcar que ha utilizado para incluir la URL del webhook.

    Publicación de notificación de marca

    Nota: Si observa este mensaje de actualización cuidadosamente desde el correo electrónico recibido, en función de la función personalizada, hemos incluido la dirección IP de la instancia mediante el SDK de OCI.

  5. [Opcional] También puede asociar este tema de notificación a los detalles de la función de actualización según los detalles del anuncio de la consola. Puede seguir estos documentos para obtener más información.

    Nota: Debe modificar el código de función personalizado para asegurarse de leer la carga útil de JSON correcta y modificarlo según corresponda. Puede utilizar la carga útil de JSON de anuncio de ejemplo recibida de los equipos de servicio.

    Suscripción a notificación de anuncios de OCI

Pasos Siguientes

En este tutorial se muestra a un usuario final cómo puede utilizar una función personalizada para leer la carga útil de JSON de notificación y el uso de bibliotecas de SDK de OCI para actualizar esa carga útil y publicar mensajes en herramientas de colaboración comunes como Marcar. Puede ampliar esta función para agregar detalles adicionales, como Etiquetas de recurso, Detalles de red, etc.

Acuses de recibo

Más recursos de aprendizaje

Explore otros laboratorios en docs.oracle.com/learn o acceda a más contenido de aprendizaje gratuito en el canal YouTube de Oracle Learning. Además, visite education.oracle.com/learning-explorer para convertirse en un explorador de Oracle Learning.

Para obtener documentación sobre los productos, visite Oracle Help Center.