Escenario C: Presentación de entradas de Jira para recordatorios

Registre automáticamente un ticket de Jira cada vez que se produzca un evento de recordatorio de mantenimiento. En este escenario, siempre que Oracle Cloud Infrastructure le recuerde el próximo mantenimiento de la base de datos, se crea un ticket de Jira para el ingeniero de guardia.

Este escenario implica escribir una función en el archivo de tickets de Jira (y crear un secreto para almacenar credenciales de Jira), agregar esa función y correo electrónico opcional como suscripciones a un tema y crear una regla que envíe mensajes a ese tema cuando se produzcan eventos de recordatorio de mantenimiento (consulte Tipos de eventos de bases de datos de contenedores autónomas). El mensaje se envía a las suscripciones del tema, que incluye una dirección de correo electrónico de grupo además de la función. Al recibir el mensaje, se llama a la función.

Todo menos la función se puede configurar en la consola. También puede utilizar la CLI o API de Oracle Cloud Infrastructure, que le permite ejecutar las operaciones individuales.

Nota

El servicio de notificaciones no tiene información sobre una función una vez llamada. Para obtener detalles, consulte la información de solución de problemas en Función no llamada o no ejecutada.

En esta imagen se muestra Notifications en el contexto de un escenario que utiliza una función para archivar tickets de Jira cuando se producen eventos de recordatorio.

Para obtener más información sobre este escenario, consulte Automated Jira Ticketing using OCI Events, Notifications, and Functions y el repositorio GitHub asociado.

Política de IAM necesaria

Para utilizar Oracle Cloud Infrastructure, un administrador debe otorgarle acceso de seguridad en una política . Este acceso es necesario tanto si utiliza la Consola como la API de REST con un SDK, una CLI u otra herramienta. Si aparece un mensaje que le informa de que no tiene permiso o no tiene autorización, verifique con el administrador el tipo de acceso que tiene y en qué compartimento trabajar.

Si es miembro del grupo Administradores, ya tendrá el acceso necesario para ejecutar este escenario. De lo contrario, necesita acceso a Events, Notifications y Functions. Debe tener el permiso FN_INVOCATION en la función para poder agregar la función como suscripción a un tema. Para acceder a las credenciales de Jira, la función debe estar autorizada para leer secretos. Este escenario muestra los pasos para proporcionar esta autorización.

Tarea 1: Almacenar credenciales en un secreto

Para obtener más información sobre la creación de secretos mediante el servicio Vault, consulte Creación de un secreto en un almacén.

1. Abra el menú de navegación, haga clic en Identidad y seguridad y, a continuación, en Almacén.
2. En Ámbito de lista, en la lista Compartimento, seleccione el nombre del compartimento en el que desea crear el secreto.
3. En la lista de almacenes del compartimento, realice una de las siguientes acciones:
  
  Seleccione el nombre del almacén en el que desea crear un secreto.
  
  Cree un almacén nuevo para el secreto siguiendo las instrucciones de Para crear un almacén nuevo y, a continuación, seleccione el nombre del almacén.
4. Seleccione Secretos y, a continuación, seleccione Crear secreto.
5. En el panel Create Secret, seleccione un compartimento de la lista Create in Compartment. (Los secretos pueden existir fuera del compartimento en el que está el almacén).
6. Introduzca un nombre para identificar el secreto. Evite introducir información confidencial.
  
  Nombre de ejemplo: jira_auth_plain_text
7. Introduzca una breve descripción del secreto como ayuda para identificarlo. Evite introducir información confidencial.
  Descripción de ejemplo: jira_auth_plain_text
8. Seleccione la clave de cifrado maestra que desea utilizar para cifrar el contenido del secreto mientras se importa al almacén. (La clave debe pertenecer al mismo almacén).
9. En Plantilla de tipo secreto, seleccione Texto sin formato.
10. En Contenido secreto, introduzca las credenciales de Jira en el siguiente formato, con dos puntos que separan el correo electrónico de inicio de sesión del token de autenticación:
  <your-jira-cloud-login-email>:<your-jira-cloud-auth-token>
11. Seleccione Create Secret.
12. Observe el OCID del secreto que se utilizará en el código de función para recuperar el secreto de forma segura.
Nota

Debe especificar una clave simétrica para cifrar el secreto durante la importación al almacén. No puede cifrar secretos con claves asimétricas. Además, la clave debe existir en el almacén que especifique.

Utilice el comando oci vault secret create-base64 y los parámetros necesarios para crear un secreto que almacene las credenciales de Jira:
oci vault secret create-base64 --compartment-id <target_compartment_id> --secret-name <secret_name> --vault-id <target_vault_id> --description <secret_description_text> --key-id <encryption_key_id> --secret-content-content <base64_encoded_secret_content> --secret-content-name <unique_content_name> --secret-content-stage <secret_version_rotation_state>
Para obtener una lista completa de parámetros y valores para los comandos de la CLI, consulte la Referencia de comandos de CLI.
Ejecute la operación CreateSecret para crear un secreto.

Ejemplo:
```
POST /20180608/secrets
Host: <managementEndpoint>
<authorization and other headers>
{
  "vaultId": "<vault_OCID>",
  "compartmentId": "<compartment_OCID>",
  "secretName": "jira_auth_plain_text",
  "description": "jira_auth_plain_text",
  "keyId": "<key_OCID>",
  "secretContent": 
    {
      "content": "<base64_encoded_secret_contents>",
      "contentType": "BASE64"
    }
}
```
Nota

Cada región tiene un punto final único para las operaciones de creación, actualización y lista de secretos. Este punto final se denomina URL de plano de control o punto final de gestión de secretos. Cada región también tiene un punto final único para las operaciones relacionadas con la recuperación del contenido del secreto. Este punto final se conoce como URL de plano de datos o punto final de recuperación del secreto. Para puntos finales regionales, consulte la documentación de API.

Para obtener más información sobre el uso de la API y la firma de solicitudes, consulte la documentación de la API de REST y Credenciales de seguridad. Para obtener información sobre los SDK, consulte Los SDK y la CLI.

Tarea 2: Creación de la función

En esta sección se proporciona el ejemplo de código para crear la función y se tratan los pasos para autorizar a la función a acceder a las credenciales de Jira en el secreto creado mediante el servicio Vault.

Ejemplo de código de función

El siguiente ejemplo de código es para una función de archivo de tickets de Jira.

Agregue el OCID secreto en la línea que incluye getSecretForOcid.

Para obtener instrucciones sobre la creación y el despliegue de funciones, consulte Creación y despliegue de funciones.

public String handleRequest(CloudEvent cloudEvent) {
 
    // Json body of Cloud event from Oracle Event Service in serialized into cloudEvent object by Fn SDK implicitly
    System.err.println("Inside Java jira function with input as " + cloudEvent.getEventType() + "  " + cloudEvent.getData().getResourceName());
 
    String response = jiraCreateTicket(cloudEvent);
 
    if (response != null) return response;
 
    return null;
}
 
private String jiraCreateTicket(CloudEvent cloudEvent) {
 
    try {
        //create jira ticket body as per CloudEvent
        String jsonBodyJira = getJiraApiBody(cloudEvent);
 
        String jiraCloudEndpoint = System.getenv().get("JIRA_CLOUD_URL");
        String ocidForSecretForJiraAuthToken = System.getenv().get("JIRA_CLOUD_SECRET_OCID");
        String jiraAuthToken= getSecretForOcid(ocidForSecretForJiraAuthToken); // base64 encoded form of <YourJiraUsername:YourJiraAuthToken>
 
        // actual REST call to JIRA cloud
        OkHttpClient client = new OkHttpClient().newBuilder()
                .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, jsonBodyJira);
        Request request = new Request.Builder()
                .url(jiraCloudEndpoint)
                .method("POST", body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", "Basic "+ jiraAuthToken)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
 
    } catch (JsonProcessingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
    return null;
}

Autorice la función para acceder a los secretos

Utilice un grupo dinámico para otorgar a la función la capacidad de leer secretos. La función debe tener esta autorización para acceder a las credenciales de Jira, que se almacenan en el secreto que ha creado anteriormente.

Para autorizar a la función a acceder a secretos (consola)

Find and note your function OCID (format is ocid1.fnfunc.oc1.iad.exampleuniqueID).
Incluya la función en un grupo dinámico: en el grupo dinámico relevante, especifique la siguiente regla:
```
resource.id = '<function-ocid>'
```
También puede crear un grupo dinámico que incluya todas las funciones:
```
ALL{resource.type='fnfunc', resource.compartment.id='<compartment_OCID>'}
```
Otorgue al grupo dinámico acceso a los secretos: agregue la siguiente política :
```
allow dynamic-group <dynamic-group-name> to read secret-family in tenancy
```

A fin de autorizar la función para que pueda acceder a otros recursos de Oracle Cloud Infrastructure, como instancias informáticas, incluya la función en un grupo dinámico y cree una política para otorgar acceso al grupo dinámico a esos recursos. Para obtener más información, consulte Acceso a otros recursos de Oracle Cloud Infrastructure desde funciones en ejecución.

Para obtener más información sobre los grupos dinámicos, consulte Gestión de grupos dinámicos.

Tarea 3: Creación del tema

Para obtener ayuda con la resolución de problemas, consulte Resolución de problemas de notificaciones.

1. Abra el panel Crear Tema: en la página de lista Temas, seleccione Crear Tema. Si necesita ayuda para buscar la página de lista, consulte Lista de temas.
2. Para Nombre, escriba lo siguiente: Tema de mantenimiento
3. Haga clic en Crear.
Utilice el comando oci ons topic create y los parámetros necesarios para crear un tema:
oci ons topic create --name <name> --compartment-id <compartment_OCID>
Ejemplo:
oci ons topic create --name "Maintenance Topic" --compartment-id "<compartment-ocid>"
Para obtener una lista completa de parámetros y valores para los comandos de la CLI, consulte la Referencia de la línea de comandos para notificaciones.

Ejecute la operación CreateTopic para crear un tema.

Por ejemplo:

POST /20181201/topics
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "name": "Maintenance Topic",
  "compartmentId": "<compartment_OCID>"
}

Tarea 4: Creación de suscripciones

La función se debe desplegar antes de crear la suscripción a la función.

Para obtener ayuda con la resolución de problemas, consulte Resolución de problemas de notificaciones.

Seleccione el tema que ha creado anteriormente (el nombre de ejemplo era Tema de mantenimiento): en la página de lista Temas, seleccione el tema con el que desea trabajar. Si necesita ayuda para buscar la página de lista o el tema, consulte Lista de temas.

Cree la suscripción de función.

Abra el panel Crear suscripción: en la página de detalles del tema, seleccione Crear suscripción.
Se abrirá el panel Crear suscripción.
En Protocolo, seleccione Función.

Rellene los campos restantes.

Campo	Descripción
Compartimento de función	Seleccione el compartimento que contiene la función.
Aplicación de función	Seleccione la aplicación que contiene la función.
Función	Seleccione la función.

Haga clic en Crear.
No se necesita confirmación para las nuevas suscripciones a funciones.

Cree la suscripción de correo electrónico.
1. Abra el panel Crear suscripción: en la página de detalles del tema, seleccione Crear suscripción.
  Se abrirá el panel Crear suscripción.
2. En Protocolo, seleccione Correo electrónico.
3. Rellene los campos restantes.
  
  Campo Descripción
  Correo electrónico Escriba una dirección de correo electrónico.
4. Haga clic en Crear.
5. Confirmar la nueva suscripción de correo electrónico: abra el correo electrónico y navegue a la URL de confirmación.

Campo	Descripción
Correo electrónico	Escriba una dirección de correo electrónico.

Nota

Después de crear la suscripción de correo electrónico, confírmela.

Utilice el comando oci ons subscription create y los parámetros necesarios para crear cada suscripción:

oci ons subscription create --protocol <subscription_type> --subscription-endpoint <endpoint> --compartment-id <compartment_OCID> --topic-id <topic_OCID>

Ejemplo de suscripción de función:

oci ons subscription create --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

Ejemplo de suscripción de correo electrónico:

oci ons subscription create --protocol "EMAIL" --subscription-endpoint "maintenance.team@example.com" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

Para obtener una lista completa de parámetros y valores para los comandos de la CLI, consulte la Referencia de la línea de comandos para notificaciones.

Nota

Después de crear la suscripción de correo electrónico, confírmela.

Ejecute la operación CreateSubscription para crear cada suscripción.

Ejemplo de suscripción de función:

POST /20181201/subscriptions
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "topicId": "<topic_OCID>",
  "compartmentId": "<compartment_OCID>",
  "protocol": "ORACLE_FUNCTIONS",
  "endpoint": "<function_OCID>"
}

Ejemplo de suscripción de correo electrónico:

POST /20181201/subscriptions
Host: notification.us-phoenix-1.oraclecloud.com
<authorization and other headers>
{
  "topicId": "<topic_OCID>",
  "compartmentId": "<compartment_OCID>",
  "protocol": "EMAIL",
  "endpoint": "maintenance.team@example.com"
}

Tarea 5: Creación de la Regla de Evento

En esta sección se describe la creación de la regla que envía un mensaje al tema cada vez que el servicio Database emite un evento para un recordatorio de mantenimiento de la base de datos.
1. Abra el menú de navegación y haga clic en Observación y gestión. En Servicio de eventos, haga clic en Reglas.
2. Seleccione un compartimento en el que tenga permiso para trabajar y, a continuación, seleccione Crear regla.
  Events compara las reglas que crea en este compartimento con los mensajes de eventos emitidos desde los recursos de este compartimento y los compartimientos secundarios.
3. Introduzca lo siguiente.
  
  Nombre mostrado: especifique un nombre fácil de recordar para la regla. Puede cambiar el nombre más tarde. Evite introducir información confidencial.
  
  Ejemplo: recordatorio de mantenimiento
  
  Descripción: describa el propósito de la regla. Puede cambiar la descripción más tarde. Evite introducir información confidencial.
  Ejemplo: envía mensajes al tema de mantenimiento
4. En Condiciones de regla, cree un filtro para los eventos de recordatorio de base de datos:
  
  Para Nombre de servicio, seleccione Base de datos.
  
  En Tipo de evento, seleccione Base de datos de contenedores autónoma: recordatorio de mantenimiento.
5. En Acciones, seleccione el tema que ha creado anteriormente:
  
  Seleccione Notificaciones.
  
  Seleccione el compartimento de notificaciones.
  
  Seleccione el tema que creó anteriormente.
6. Seleccione Crear regla.
Cree una regla que se dispare mediante recordatorios de mantenimiento y que haga referencia a este tema como destino.
1. Cree un archivo, action.json, que contenga lo siguiente, que haga referencia al tema creado anteriormente.
  
  Ejemplo:
  
  { "actions": [ { "actionType": "ONS", "description": "string", "isEnabled": true, "topicId": "<topic_OCID>" } ] }
2. Abra un símbolo del sistema y ejecute el comando oci events rule create.
  
  Ejemplo:
  
  oci events rule create --display-name <friendly_name> --is-enabled true --condition "{\"eventType\":[\"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"]}" --compartment-id <compartment_OCID> --actions file://action.json
  
  Para obtener una lista completa de parámetros y valores para los comandos de la CLI, consulte la Referencia de comandos de CLI.
  
  Para obtener más información sobre la creación de reglas mediante la CLI, consulte Creación de una regla de eventos.

Ejecute la operación CreateRule para crear una regla de evento.

Ejemplo:

POST /20181201/rules
Host: events.us-phoenix-1.oraclecloud.com
<authorization and other headers>

{
  "displayName": "Maintenance Reminder",
  "condition": "{
    \"eventType\": \"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"
    }",
  "compartmentId": "<compartment_OCID>",
  "isEnabled": true,
  "actions": {
    "actions": [
      {
        "actionType": "ONS",
        "topicId": "<topic_OCID>",
        "isEnabled": true
      }
    ]
  }
}