Observação:

Chamar a função personalizada do Oracle Cloud Infrastructure com o evento de notificação e publicar a mensagem atualizada na ferramenta de colaboração Lark

Introdução

Os clientes do Oracle Cloud Infrastructure (OCI) recebem notificações por meio de tópicos de Notificação do OCI inscritos, que abrangem eventos como eventos de instância, alarmes, anúncios da console e muito mais. Esses tópicos inscritos também suportam Funções do OCI como Alvos de Notificação, permitindo que os clientes chamem a função personalizada durante o evento de notificação e enviem detalhes de notificação atualizados para canais de comunicação que suportam a chamada de API. Neste tutorial, mostraremos como encaminhar essas notificações atualizadas para Lark, uma plataforma de colaboração empresarial com APIs de mensagens.

Usando uma Função OCI personalizada, você pode recuperar vários dados e executar ações. Veja a seguir alguns exemplos, como:

Este tutorial fornecerá um passo a passo abrangente de como acionar uma Função OCI personalizada em resposta ao evento de energia de uma instância, como STOP. Os usuários têm a flexibilidade de personalizar essa função e acioná-la com base em vários tópicos de Notificação do OCI inscritos. Para obter mais informações sobre o OCI Functions, consulte Visão Geral do OCI Functions.

Objetivo

O OCI Functions permite que você grave um código personalizado que pode ser chamado com base na notificação do OCI, no tópico de Notificação inscrito do OCI Announcement, no evento da Instância de Computação e muito mais. Neste tutorial, criamos uma função personalizada gravada em código Python que é chamada com base em um evento de Notificação e publicamos a mensagem atualizada na ferramenta de colaboração Lark usando um URL do webhook dentro do código. Isso fornece uma opção para incluir e atualizar as informações adicionais necessárias que podem ser consumidas pelo usuário final.

Pré-requisitos

Público-alvo

Este tutorial se destina a administradores e profissionais do Cloud Service Provider.

Arquitetura

Veja a seguir um exemplo de topologia de caso de uso e arquitetura de alto nível da solução.

Arquitetura de Conectividade entre Regiões de Interconexão do OCI Azure

Você pode consultar essa arquitetura quando quiser criar uma Função do OCI personalizada e chamá-la com base no evento de notificação. Você pode seguir uma série de tarefas descritas neste Tutorial para configurar e validar essa arquitetura.

Tarefa 1: Criar um Grupo Dinâmico

Os grupos dinâmicos permitem que você agrupe instâncias de computação do OCI como atores "principais" (semelhantes aos grupos de usuários).

Observação: Você precisa de privilégios de Administrador para criar grupos Dinâmicos.

  1. Acesse a conta da tenancy da Console do OCI.

  2. No menu de serviços, selecione Identidade e Segurança e, na seção Identidade, selecione Grupos Dinâmicos.

  3. Clique em Criar Grupo Dinâmico.

  4. Informe um Nome e uma Descrição significativos.

  5. Na seção Regra 1, adicione a seguinte linha:

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

    Observação:

    • Substitua o ID do compartimento pelo ID do compartimento desejado.
    • Você também pode incluir o OCID do recurso de função específico em seu grupo dinâmico.

  6. Clique em Criar e seu grupo dinâmico deverá ser criado com sucesso, conforme mostrado na imagem a seguir.

    Grupo Dinâmico Criado

Tarefa 2: Criar Política de OCI IAM de Grupo Dinâmico

O Oracle Cloud Infrastructure Identity and Access Management (OCI IAM) permite controlar quem tem acesso aos recursos de nuvem. Para que essa arquitetura funcione, precisamos conceder acesso à função como serviço faas para a computação, redes e vários outros serviços.

  1. No menu de serviços, selecione Identidade e Segurança e, na seção Identidade, selecione Políticas.

  2. Clique em Criar Política.

  3. Informe um Nome e uma Descrição apropriados e certifique-se de selecionar o compartimento correto (neste exemplo, usaremos o nome do compartimento oc-demo).

  4. Na seção Policy Builder, ative a opção Mostrar editor manual e cole as seguintes linhas:

    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>

    Observação: substitua o nome dynamic_group_name e compartment_name_path pelos valores desejados.

  5. Clique em Criar e sua política deve ser criada com sucesso no nível raiz/do seu compartimento, conforme mostrado na imagem a seguir.

    Política do Serviço IAM Criada

Tarefa 3: Criar um Repositório para armazenar a imagem de função personalizada

O serviço Container Registry permite armazenar, compartilhar e gerenciar imagens de contêiner (como imagens do Docker) em um registro gerenciado pela Oracle.

  1. Na Console, abra o menu de serviço e clique em Serviços do Desenvolvedor. Em Contêineres, clique em Serviço Container Registry.

  2. Clique em Criar Repositório.

  3. Na caixa de diálogo Criar Repositório, especifique Compartimento e Nome do Repositório de sua escolha e deixe-o Privado.

  4. Clique em Criar Repositório e seu registro de contêiner deverá ser criado com sucesso no compartimento especificado, conforme mostrado na imagem a seguir.

    Repositório de Registro de Contêiner Criado

Tarefa 4: Criar uma Rede Virtual na Nuvem com Sub-rede para armazenar a função application.

Uma rede virtual na nuvem (VCN) é uma rede que você define no OCI. Inclui sub-redes, tabelas de roteamento e gateways.

Observação: se você já tiver uma VCN, a sub-rede criada anteriormente, poderá ignorar essa tarefa e prosseguir com a Tarefa 5.

  1. Clique no menu de serviços próximo ao canto superior esquerdo da console web do OCI.

  2. Em Rede, selecione Virtual Cloud Networks.

  3. Na página Redes Virtuais na Nuvem, clique em Iniciar Assistente de VCN.

  4. Selecione Criar VCN com Conectividade de Internet e clique em Iniciar Assistente de VCN.

  5. Conclua a configuração da VCN e clique em Próximo

  6. Clique em Criar e suas redes virtuais na nuvem com sub-redes devem ser criadas com sucesso, conforme mostrado na imagem a seguir.

    Rede Virtual Criada com Sub-rede

Tarefa 5: Criar um Aplicativo para armazenar funções

  1. Abra o menu de serviço e clique em Serviços ao Desenvolvedor. Em Funções, clique em Aplicativos.

  2. Clique em Criar Aplicativo.

  3. Na janela Criar Aplicativo, selecione o Nome do aplicativo (por exemplo, function-app), selecione a VCN criada na Tarefa 4 e selecione a sub-rede pública.

  4. Clique em Criar e seu aplicativo de função deve ser criado com sucesso, conforme mostrado na imagem a seguir.

    Aplicativo de Função Criado

Tarefa 6: Implantar a função para armazenar funções

Esta etapa usará o arquivo zip que pode ser baixado na seção Pré-requisitos deste tutorial.

  1. Navegue até a console de nuvem do OCI e clique em Ferramentas de Desenvolvedor, Cloud Shell.

    Iniciar o Cloud Shell

  2. Depois que você clicar no botão Iniciar Cloud Shell, uma nova janela de shell pequena será exibida no final da página. No canto superior direito dessa janela, clique no menu de roda dentada e selecione Fazer Upload.

    Fazer Upload de Arquivo ZIP

  3. Faça upload do arquivo zip disponível na seção Pré-requisitos deste tutorial e navegue até o diretório copiado.

  4. Você verá o arquivo func.py conforme abaixo do qual criamos para garantir que possa ler o JSON de notificação e adicionar outros campos, como detalhes de Endereço IP, e usar uma mensagem atualizada para enviar a mensagem ao URL do webhook de Marca.

    • parse_message: Função ler notificação JSON e atualizar mensagem
    • get_ip_address: Função usando Computação, biblioteca do cliente de Rede para ler detalhes adicionais como endereço IP com base no OCID do recurso da instância, por exemplo.
    • make_post: Função para fazer uma publicação no canal Lark usando o URL do webhook.

    Observação:

    • Estamos usando o sdk do OCI python, mas você pode personalizar com base em outro idioma suportado usando sdks go/java.
    • Você deve atualizar o URL do webhook ou Lark ou outras ferramentas de colaboração, como o Slack.
    • Você pode personalizar essa função com base em seus requisitos. Usamos determinado payload de notificação JSON para ler valores, mas você também pode usar JSON de anúncio na console ou outro JSON de evento.
    ###
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. Implante a função usando o comando fn deploy para criar a imagem do docker da função e as dependências associadas no cloud shell. Você pode enviar a imagem ao registro especificado do Docker e implantar a função no OCI Functions no aplicativo criado anteriormente.

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

    Por exemplo:

    fn -v deploy --app function-app

    Observação: Você pode exibir o arquivo func.yaml e ver os detalhes necessários da imagem do docker da função.

  6. Uma vez implantada, sua função deverá ser criada com sucesso, conforme mostrado na imagem a seguir.

    Função Criada

Tarefa 7: Inscrever a Função em um tópico

  1. Abra o menu de serviço e clique em Serviços ao Desenvolvedor. Em Integração de Aplicativos, clique em Notificações. Certifique-se de estar no compartimento correto.

  2. Clique em Criar Tópico.

  3. Defina um nome apropriado e clique em Criar.

  4. Depois que o tópico for criado, selecione-o na lista de tópicos.

  5. Na janela Tópicos, selecione Assinaturas no lado esquerdo em Recursos e clique em Criar Assinatura.

  6. Na janela lateral Criar Assinatura, selecione o protocolo a ser Funções, selecione o compartimento, o aplicativo e a função que foram criados na Tarefa 6.

  7. Clique em Criar; sua função deve ser inscrita com sucesso em um tópico, conforme mostrado na imagem a seguir.

    Assinatura de Notificação Criada

Tarefa 8: Criar uma Instância e Regra de Evento de Notificação

Para validar a função nesta etapa, criaremos uma instância e um tópico de notificação de criação associado na Tarefa 7 para um evento como parado por instância.

  1. Na Console, navegue até Compute, Instâncias para criar uma instância de computação.

  2. Clique no ícone Criar Instância e forneça os detalhes necessários:

    • Nome da Instância
    • Compartimento da Instância
    • Selecione o AD desejado
    • Selecione a VCN de Rede e a Sub-rede Pública
    • Copie-se sua chave ssh pública
    • Clique em Criar.

  3. Aguarde a instância exibir a execução e faça log-in na instância usando o comando a seguir.

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

  4. Navegue até a janela Computação, Instâncias, Detalhes da Instância, Notificação para criar um evento de notificação.

  5. Clique em Criar Notificação e selecione um modelo QuickStart como Alteração do Status da Instância para Interrompido.

  6. Informe o Nome da Regra de Evento e selecione o tópico criado na Tarefa 7 e clique em Criar Notificação. Sua regra de evento de notificação deve ser criada com sucesso para um tópico inscrito, conforme mostrado na imagem a seguir.

    Regra de Eventos Criada

Tarefa 9: Validar Regra de Evento de Notificação

Nesta etapa, você interromperá a instância que acionará o tópico de notificação associado. Você também pode incluir seu endereço de e-mail para ver o payload de notificação.

  1. Navegue até a instância criada e clique em Parar.

  2. Depois que a instância for interrompida, você deverá obter um e-mail por meio do tópico de notificação inscrito e a função deverá ser acionada.

  3. Confirme se você recebeu um e-mail conforme mostrado na imagem a seguir.

    E-mail do Tópico de Notificação do OCI

  4. Vá para o canal Marca que você usou para incluir o URL do webhook.

    Lançamento de Notificação de Observação

    Observação: Se você notar essa mensagem de atualização com cuidado no e-mail recebido, com base na função personalizada, incluímos o endereço IP da instância usando o sdk do OCI.

  5. [Opcional] Você também pode associar este tópico de notificação aos detalhes da função de atualização de acordo com os detalhes do anúncio da console. Você pode seguir esses documentos para aprender mais.

    Observação: modifique o código de função personalizado para garantir que você esteja lendo o payload JSON correto e modifique adequadamente. Você pode usar o payload JSON de anúncio de amostra recebido das equipes de serviço.

    Assinatura de Notificação de Anúncio do OCI

Próximas Etapas

Este tutorial mostra ao usuário final como você pode usar uma função personalizada para ler o payload JSON de notificação e usar bibliotecas do OCI SDKs para atualizar esse payload e publicar mensagens em ferramentas comuns de colaboração, como Marcar. Você pode expandir essa função para adicionar mais detalhes, como Tags de Recurso, Detalhes da Rede e muito mais.

Confirmações

Mais Recursos de Aprendizagem

Explore outros laboratórios no site docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal YouTube do Oracle Learning. Além disso, visite education.oracle.com/learning-explorer para se tornar um Oracle Learning Explorer.

Para obter a documentação do produto, visite o Oracle Help Center.