Observação:

Este tutorial requer acesso ao Oracle Cloud. Para se inscrever em uma conta gratuita, consulte Conceitos Básicos do Oracle Cloud Infrastructure Free Tier.
Ele usa valores de exemplo para credenciais, tenancy e compartimentos do Oracle Cloud Infrastructure. Ao concluir seu laboratório, substitua esses valores por valores específicos do seu ambiente de nuvem.

Gravar Eventos em um OCI Private Stream usando o OCI Events Service e o OCI Functions

Introdução

As regras do Serviço Oracle Cloud Infrastructure (OCI) Events rastreiam alterações de recursos na OCI usando eventos que atendem ao padrão CloudEvents da CNCF (Cloud Native Computing Foundation). Isso permite que os desenvolvedores respondam a alterações em tempo real acionando o código com o OCI Functions, gravando dados no OCI Streaming ou enviando alertas usando o OCI Notifications.

Embora o envio de eventos para fluxos públicos seja suportado nativamente, a gravação em um fluxo privado requer uma abordagem personalizada usando o OCI Functions ou código personalizado. Este tutorial demonstra o uso do OCI Functions para capturar cargas úteis de eventos de uma regra do OCI Events Service e gravá-las em um fluxo privado.

Objetivo

Automatize a configuração para processar eventos da OCI e enviá-los para um fluxo privado da OCI de maneira escalável para processamento seguro e personalizado.

Pré-requisitos

Acesso a uma tenancy do OCI.
Privilégios para gerenciar regras do OCI Events Service, Oracle Applications e serviços OCI Streaming.

Tarefa 1: Configurar as Políticas Necessárias e as Permissões do OCI IAM (Oracle Cloud Infrastructure Identity and Access Management)

Cada componente desta solução deve ter acesso aos recursos do OCI com os quais interage. Para seguir este tutorial, o desenvolvedor deve ter as seguintes permissões.

Políticas do Usuário: Gerencie regras do OCI Events Service, OCI Notifications, OCI Functions, fluxos do OCI e uso do OCI Vault (opcional) e da família de redes.
Política de Serviço: Conceda a permissão de função para gravar mensagens no fluxo privado do OCI.

Políticas detalhadas podem ser encontradas aqui:

Tarefa 2: Criar um Fluxo Privado

O OCI Streaming é um serviço da OCI totalmente gerenciado no qual os dados são criptografados em repouso e em trânsito, garantindo a integridade e a segurança das mensagens. Para maior segurança, você pode usar o serviço OCI Vault para armazenar e gerenciar suas próprias chaves de criptografia, atendendo a requisitos específicos de conformidade ou segurança. Os pontos finais privados podem ser configurados em uma VCN (Rede Virtual na Nuvem) para proteger ainda mais seus streams, associando um endereço IP privado ao pool de streams. Isso garante que o tráfego do OCI Streaming permaneça dentro da VCN, evitando totalmente a internet. No entanto, observe que os streams que usam pontos finais privados não são acessíveis pela internet, o que também limita a capacidade de exibir suas mensagens mais recentes por meio do console. Para consumir mensagens de um fluxo privado, o consumidor deve ter roteamento e acesso à rede em que o fluxo privado está hospedado.

Criar um stream e um pool de streams. Digite Stream Name e selecione Criar Novo Pool de Streams para criar o pool de streams. Na seção Configurar Pool de Streams, digite Nome do Pool de Streams, selecione Ponto Final Privado e digite VCN e Sub-rede e os detalhes da rede adequadamente. Embora opcional, recomendamos fornecer a um Grupo de Segurança de Rede uma regra de entrada para todo o tráfego dentro desse NSG. Para obter mais informações, consulte Criar Stream e Criar Pool de Streams.

Imagem da Regra do NSG

Imagem da Criação do Stream e do Pool de Streams

Você pode usar suas próprias chaves de criptografia, obtendo maior controle sobre o ciclo de vida da chave. Você tem a opção de ajustar a retenção de mensagens dentro do stream. O padrão é 1 dia e o máximo é 7 dias.

Imagem da Criptografia de Fluxo

Imagem do Pool do Stream

Anote o OCID do fluxo e o ponto final das mensagens. Precisamos passar essas informações para a função.

Tarefa 3: Criar Tópico do OCI Notifications e Regra do Serviço OCI Events

Como uma atualização, aqui está como um evento funciona. Os serviços do OCI emitem eventos para recursos ou dados. Criamos regras, que incluem um filtro para especificar os eventos de interesse. As regras devem acionar uma ação quando o filtro localizar um evento correspondente. A ação pode ser um tópico do OCI Notifications, um serviço OCI Streaming ou o OCI Functions.

Abordagem 1: Se o requisito for enviar payload de evento para um fluxo público, não haverá necessidade de uma função, pois o fluxo pode ser configurado nativamente.
Abordagem 2: Se o requisito for enviar apenas uma carga útil de evento específica para um fluxo privado, a função poderá ser fornecida como uma ação diretamente.
Abordagem 3: Se o requisito for enviar várias cargas úteis de eventos para um fluxo privado, a maneira ideal será enviar a carga útil do evento para um tópico do OCI Notifications e inscrever o OCI Functions no tópico OCI Notifications.

Neste tutorial, exploraremos a Abordagem 3, que é a mais complexa.

Crie um tópico do OCI Notifications. Para obter mais informações, consulte Criando um Tópico.
Crie uma regra de evento. Para justificar a abordagem, criaremos duas regras de evento. Para obter mais informações, consulte Criando uma Regra de Eventos.

Tarefa 4: Desenvolver e Implantar a Função

Esta função codifica o payload do evento e o publica no ponto final e no stream de mensagens fornecidos. Para obter mais informações, consulte Criando funções.

func.py:

import json
import logging
import oci
from base64 import b64encode

def handler(ctx, data):
    try:
        # Parse the incoming event payload
        body = json.loads(data.getvalue())
        cfg = ctx.Config()
        stream_ocid = cfg["stream_ocid"]
        stream_endpoint = cfg["stream_endpoint"]

        logging.getLogger().info(f'Function invoked for event: {body}')

        # Publish the event to the stream
        publish_to_stream(stream_ocid, stream_endpoint, body)

        return {"status": 200, "message": "Successfully processed event"}
    except (Exception, ValueError) as ex:
        logging.getLogger().error(f'Error processing event payload: {str(ex)}')
        return {"status": 500, "message": "Internal Server Error"}

def publish_to_stream(stream_ocid, stream_endpoint, event_data):
    signer = oci.auth.signers.get_resource_principals_signer()
    stream_client = oci.streaming.StreamClient(config={}, signer=signer, service_endpoint=stream_endpoint)

    # Convert event data to JSON string and encode
    event_payload = json.dumps(event_data).encode('utf-8')

    # Build the message list
    message_list = [
        oci.streaming.models.PutMessagesDetailsEntry(
            key=b64encode("partition-key-1".encode()).decode(),
            value=b64encode(event_payload).decode()
        ),
    ]

    try:
        logging.getLogger().info(f"Publishing {len(message_list)} messages to stream {stream_ocid}")
        put_message_details = oci.streaming.models.PutMessagesDetails(messages=message_list)
        put_message_result = stream_client.put_messages(stream_ocid, put_message_details)

        # Log publishing results
        for entry in put_message_result.data.entries:
            if entry.error:
                logging.getLogger().error(f"Error publishing message: {entry.error_message}")
            else:
                logging.getLogger().info(f"Published message to partition {entry.partition}, offset {entry.offset}")
    except Exception as ex:
        logging.getLogger().error(f"Failed to publish messages to stream: {str(ex)}")
        raise

func.yaml:

schema_version: 20180708
name: events-to-pvt-stream
version: 0.0.1
runtime: python
build_image: fnproject/python:3.9-dev
run_image: fnproject/python:3.9
entrypoint: /python/bin/fdk /function/func.py handler
memory: 256
config:
stream_ocid: ocid1.stream.123445
stream_endpoint: https://xyz.us-ashburn-1.oci.oraclecloud.com

requirements.txt:
```
fdk
oci
```

Imagem do Fn

O passo final é dizer a função onde o fluxo privado está. Esta função usa parâmetros de configuração, tornando-a reutilizável se você quiser implantar em outra tenancy.

Imagem da Configuração Fn

Nesta tarefa, inscreva a função implantada no tópico OCI Notifications. Sempre que o tópico do OCI Notifications receber uma mensagem, ele acionará a função e a função gravará o payload de evento de um stream privado.

Você pode eliminar ou aprimorar determinados campos alterando o código da função para atender aos requisitos. A confirmação não é necessária para inscrições de função. Para obter mais informações, consulte Criando uma Assinatura de Função.

Imagem da Assinatura

Imagem do Subscription2

Verificação

Há vários locais onde o fluxo de dados pode ser verificado.

Verifique a página de métricas de evento para verificar se algum evento corresponde à regra fornecida. O gráfico de falha deve estar vazio.
Verifique as métricas do tópico do OCI Notifications. Certifique-se de que todas as mensagens sejam entregues; não há dados nos gráficos de mensagens com falha.
Verifique as métricas de Chamada da função. Certifique-se de que não haja erros e que a função não seja de limitação.
Verifique se os dados estão sendo ingeridos no fluxo privado.

Imagem das Métricas do Stream

Se os dados estiverem ausentes em qualquer um dos gráficos a seguir, pare por aí e ative os logs desse serviço. Os logs explicarão por que um recurso específico está falhando ao executar a tarefa.

Próximas Etapas

Neste tutorial, você aprendeu a integrar o OCI Events Service, o OCI Notifications, o OCI Functions e o OCI Streaming para processar e publicar com segurança cargas úteis de eventos em fluxos privados. Você explorou a configuração de pontos finais seguros, o gerenciamento de chaves de criptografia e o uso do OCI IAM para controle de acesso detalhado para garantir que somente usuários e serviços autorizados possam interagir com seus dados de streaming.

Essa solução permite que as equipes capturem alterações de recursos em tempo real, mantendo padrões de segurança robustos. As organizações podem usar fluxos privados para proteger dados confidenciais, cumprir os regulamentos do setor e garantir que os fluxos de trabalho operacionais se alinhem com as metas de segurança e conformidade da organização. Essa abordagem fortalece sua postura de segurança e permite que sua equipe obtenha automação orientada a eventos integrada e segura.

Para obter mais informações sobre o uso do OCI Functions e dos recursos de fluxo privado do OCI, entre em contato com o representante da Oracle ou consulte Soluções de Segurança em Nuvem.

Confirmações

Autor - Aneel Kanuri (Arquiteto de Nuvem Distinto)

Mais Recursos de Aprendizagem

Explore outros laboratórios em docs.oracle.com/learn ou acesse mais conteúdo de aprendizado gratuito no canal Oracle Learning YouTube. 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.

Título e Informações de Copyright

Write Events to an OCI Private Stream using OCI Events Service and OCI Functions

G23237-01

December 2024

Oracle e/ou suas empresas afiliadas.