Prima di poter distribuire componenti personalizzati in Oracle Cloud Infrastructure Functions, è necessario ottenere i nomi degli artifact utilizzati per la distribuzione ed è necessario verificare di disporre dell'autorizzazione per utilizzarli.

Per impostare l'istanza per la distribuzione di Oracle Cloud Infrastructure Functions, l'amministratore della tenancy ha completato la procedura descritta in Impostazione e criteri per Oracle Functions. Nell'ambito del processo, hanno creato i seguenti artifact. Chiedere all'amministratore i nomi desiderati quando si completa la procedura descritta in Impostazione dell'account utente per Oracle Functions:

• I nomi dell'area e del compartimento da utilizzare per le funzioni.

• Nome del compartimento per la rete virtuale (VCN) dell'applicazione funzione. In genere, si tratta dello stesso compartimento utilizzato per le funzioni.

• Nome della VCN da utilizzare per l'applicazione della funzione.

Chiedere inoltre all'amministratore di verificare di appartenere a un gruppo che dispone delle autorizzazioni necessarie per gli sviluppatori di funzioni, che include l'accesso a questi artifact.

Prima di poter distribuire pacchetti di componenti personalizzati in Oracle Cloud Infrastructure Functions, è necessario completare questi passi nella console di Oracle Cloud Infrastructure:

1. Accedere alla console e, nella barra superiore, selezionare l'area in cui si trova il compartimento di sviluppo delle funzioni.

2. Verrà eseguita la distribuzione in Oracle Cloud Infrastructure Functions tramite Oracle Cloud Infrastructure Registry. Se non si dispone già di un repository del registro che è possibile utilizzare, effettuare le operazioni riportate di seguito per crearne uno.

   1. Fare clic su in alto a sinistra per aprire il menu di navigazione, fare clic su Servizi sviluppatore, fare clic su Container Registry, quindi selezionare il compartimento impostato per lo sviluppo di funzioni nella sezione Ambito lista.

   2. Fare clic su Crea repository.

   3. Assegnare un nome al repository, quindi fare clic su Crea repository.

3. Se non si dispone di un'applicazione di funzioni per i package di componenti personalizzati, sarà necessario crearne una. Nella pagina Servizi per sviluppatori fare clic su Funzioni, quindi su Crea applicazione. Fornire un nome, selezionare una VCN, selezionare almeno una subnet e fare clic su Crea.

   Se non vengono visualizzati VCN tra cui scegliere, è possibile che non ci si trovi nell'area corretta.

   Ci sono limiti al numero di applicazioni e funzioni. Per i limiti predefiniti, consulta la sezione relativa ai limiti delle funzioni nella documentazione di Oracle Cloud Infrastructure.

4. Nella pagina Applicazioni fare clic sull'applicazione utilizzata per la distribuzione delle funzioni, quindi fare clic su Guida introduttiva nella sezione Risorse e quindi su Impostazione locale.

   Come mostrato nella schermata seguente, la pagina visualizza diversi comandi che sarà necessario utilizzare per configurare il computer locale e distribuire il pacchetto di componenti personalizzati. Copiare e salvare i comandi per i passi da 3 a 7.

   Tali componenti verranno utilizzati in un secondo momento dopo aver installato il software richiesto sul computer locale e dopo essere stati pronti per la distribuzione dei componenti personalizzati. In alternativa, aggiungere un segnalibro a questa pagina in modo da poterla tornare quando è necessario utilizzare i comandi.

   Non eseguire questi comandi ora. Basta copiarli.

   
   
   Descrizione dell'illustrazione fn-local-setup-commands.png
   

5. Nel comando copiato simile al seguente, modificare [OCIR-REPO] in base al nome del repository del registro.

   fn update context registry phx.ocir.io/devdigital/[OCIR-REPO]

6. Fare clic sull'icona Profilo nell'angolo superiore destro, quindi fare clic su Impostazioni utente per andare alla pagina Dettagli utente.

7. Nel passo successivo si creerà un file PEM da memorizzare in una cartella .oci sul computer locale. Se la cartella home del computer locale non contiene questa directory, crearne una da una finestra del terminale.

   • Linux e Mac:

     cd ~
     mkdir .oci

   • Finestre:

     cd C:\Users\<your-user-name>
     mkdir .oci

8. È necessario un file PEM pubblico e privato per un accesso sicuro. Se non è stato ancora impostato un account utente, in Dettagli utente nella console fare clic su Chiavi API nella sezione Risorse, quindi fare clic su Aggiungi chiave API.

   Salvare il file di chiavi private (file PEM) nella directory .oci della cartella home.

9. Prendere nota dell'impronta associata alla chiave API. Quando si dispone di più chiavi API, è necessario sapere quale impronta digitale utilizzare per ogni file PEM privato.

10. Se non è stato ancora impostato un file config per l'impronta digitale nel computer locale, effettuare le operazioni riportate di seguito nella sezione Chiavi API.

    1. Fare clic su nella riga relativa all'impronta digitale della chiave API, quindi fare clic su Visualizza file di configurazione.

    2. Copiare il contenuto di Anteprima file di configurazione.

    3. Nella cartella .oci del computer locale (la stessa cartella in cui è stato salvato il file di chiavi private), creare un file denominato config e incollare il contenuto copiato nel file.

11. Nel file config, modificare la proprietà key_file in modo che punti alla posizione del file PEM privato. Ad esempio: key_file=/home/joe/.oci/my-private.pem

12. Se non si dispone di un token di autenticazione, fare clic su Token di autenticazione nel menu Risorse, quindi fare clic su Genera token. Copiare immediatamente il token di autenticazione in una posizione sicura da cui è possibile recuperarlo in seguito perché il token di autenticazione non verrà più visualizzato nella console. Il token di autenticazione viene utilizzato come password quando si esegue il login per eseguire il push del package di componenti personalizzati nel registro dell'infrastruttura Oracle per la distribuzione.

Dovrai installare cURL, l'interfaccia della riga di comando OCI (CLI), Fn e Docker sul tuo computer locale per abilitare la distribuzione in Oracle Cloud Infrastructure Functions. Se il computer viene eseguito su Windows, è necessario eseguire una delle seguenti opzioni per utilizzare Fn:

• Installare Fn e Docker su Linux in un Oracle VM VirtualBox seguendo i passi riportati in questo argomento.

• Installare Docker e Fn in Windows, quindi installare il sottosistema Linux per Windows, come descritto in Come eseguire il client Fn in Windows e connettersi a un server Fn remoto.

• Distribuire i componenti personalizzati da Cloud Shell. Fare riferimento alla sezione Cloud Shell nella documentazione di Oracle Cloud Infrastructure.

Per impostare il computer locale:

1. (Solo Windows on VM) Se si desidera utilizzare un guest Linux in Oracle VM VirtualBox per distribuire il pacchetto di componenti personalizzati in Oracle Cloud Infrastructure Functions, attenersi alla procedura riportata di seguito.

   1. Installare VirtualBox da https://www.virtualbox.org/.

   2. Scarica un ISO Linux. Ad esempio, per ottenere l'ISO per Ubuntu-Mate, andare a https://ubuntu-mate.org/download/ e fare clic su Pc/Mac a 64 bit.

   3. In VirtualBox, creare una macchina virtuale dall'ISO. Per istruzioni sulla creazione di una macchina virtuale Ubunto-Mate, visitare il sito https://itsfoss.com/install-linux-in-virtualbox/. Questo sarà il tuo guest Linux.

   4. Avviare il guest Linux.

   5. Da una finestra di terminale, eseguire questo comando:

      sudo apt-get update

      In questo modo vengono aggiornati gli elenchi dei pacchetti relativi ai nuovi pacchetti e pacchetti che devono essere aggiornati.

      Suggerimento

      Per aprire una finestra del terminale in Ubuntu, premere Ctrl-Alt-T.

   6. Per essere in grado di eseguire operazioni come copiare e incollare in una finestra del terminale, saranno necessarie le aggiunte degli ospiti. Scaricare http://download.virtualbox.org/virtualbox/<release>/VBoxGuestAdditions_<release>.iso e installare e configurare le aggiunte utilizzando le istruzioni disponibili all'indirizzo https://itsfoss.com/virtualbox-guest-additions-ubuntu/

      Assicurarsi di configurare Dispositivi > Trascina selezione su bidirezionale configurato.

   7. Immettere questo comando in una finestra del terminale per installare node.js e npm sul guest.

      sudo apt install npm

   8. Trascinare la cartella .oci nella directory home del computer locale nella cartella home del guest Linux.

      Poiché si tratta di un file nascosto, è necessario premere Ctrl-H o selezionare Visualizza > Mostra file nascosti nella cartella home per visualizzarlo.

   9. Dalla cartella .oci sul guest Linux, aprire il file config e modificare key_file in modo da puntare alla posizione del file nel guest Linux. Ad esempio: key_file=/home/joe/.oci/my-private.pem

   10. Completare i passi rimanenti in questo argomento dal guest Linux.

2. (Solo per Mac) Se non l'hai ancora fatto, installa Homebrew per abilitare l'installazione di cURL, CLI OCI e Fn. Vedere https://docs.brew.sh/Installation. In alternativa, è possibile utilizzare i comandi MacPorts equivalenti.

3. Se l'accesso a Internet avviene tramite una VPN, potrebbe essere necessario impostare proxy. Ad esempio:

   export http-proxy = http://<external_ip>:80
   export https-proxy = http://<external_ip>:80
   export no_proxy = localhost,127.0.0.1,<list>
   export noproxy = localhost,127.0.0.1,<list>
   export no_proxy = localhost,127.0.0.1,<list>
   # Example for apt
   nano /etc/apt/apt.conf
   Acquire::http::Proxy "http://<external_ip>:80";
   Acquire::https::Proxy "http://<external_ip>:80";

4. Eseguire il comando appropriato per aggiornare i pacchetti.

   • Linux:

     sudo apt update && sudo apt upgrade

   • Mac:

     brew update && brew upgrade

5. (Solo Linux) Verrà utilizzato cURL per installare OCI e Fn. Immettere questa combinazione in una finestra del terminale. L'ultima istruzione consiste nel verificare che sia stata installata correttamente.

   sudo apt install curl
   curl --version

6. Fn utilizza l'interfaccia CLI OCI per distribuire i componenti personalizzati in Oracle Cloud Infrastructure Functions. Eseguire il comando appropriato per installare l'interfaccia CLI e accettare tutte le impostazioni predefinite.

   • Linux:

     bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

   • Mac:

     brew update && brew install oci-cli

   • Windows (se si utilizza il sottosistema Linux su Windows): seguire i passi di Windows in Quickstart nella documentazione di Oracle Cloud Infrastructure.

7. In Impostazione dell'account utente per Oracle Functions è stato creato un file config. Ora è necessario configurare l'interfaccia CLI in modo che utilizzi tale file. Aprire una nuova finestra del terminale, eseguire questo comando, fornire la posizione del file config, quindi immettere n per le domande rimanenti (il file config dispone già delle impostazioni necessarie).

   oci setup config

   Ad esempio:

   $ oci setup config
       This command provides a walkthrough of creating a valid CLI config file.
       ...
   
   Enter a location for your config [/home/joe/.oci/config]:
   Config file: /home/joe/.oci/config already exists. Do you want add a profile here? (If no, you will be prompted to overwrite the file) [Y/n]: n
   File: /home/joe/.oci/config already exists. Do you want to overwrite (Removes existing profiles!!!)? [y/N]: n

8. È necessario disporre di Docker 17.10.0-ce o versione successiva per eseguire il push del package di componenti personalizzati nel registro.

   • Per Ubuntu, le istruzioni di installazione sono disponibili all'indirizzo https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository

   • Per Mac, le istruzioni di installazione sono disponibili all'indirizzo https://docs.docker.com/docker-for-mac/install/

   Se non si desidera utilizzare il comando docker con sudo, vedere https://docs.docker.com/engine/install/linux-postinstall/.

9. Se si utilizza la VPN, seguire le istruzioni all'indirizzo https://docs.docker.com/network/proxy/

   Se si utilizza il sottosistema Linux in Windows, è possibile impostare i proxy dalla pagina Risorse in Impostazioni di Docker Desktop.

10. Assicurarsi che il Docker sia in esecuzione. Non è possibile avviare Fn, che verrà installato in seguito, se Docker non è in esecuzione.

11. Utilizzerai Fn, una piattaforma serverless-functions leggera basata su Docker, per configurare il contesto e distribuire il pacchetto. Se non lo si è già installato, seguire le istruzioni per l'installazione di Fn, avviare il server Fn ed eseguire il test dell'installazione all'indirizzo https://fnproject.io/tutorials/install/

    Non è necessario configurare il contesto o impostare il registro in questo momento. Questa operazione verrà eseguita al completamento dei passi descritti nella sezione Distribuisci componenti personalizzati in Oracle Cloud Infrastructure Functions.

Prima di poter distribuire un pacchetto di componenti personalizzati in Oracle Cloud Infrastructure Functions, dovrai aggiungere i file func.js e func.yaml, aggiungere una dipendenza sviluppatore per fnproject FDK e installare FDK.

1. Se è stato utilizzato il comando bots-node-sdk init per creare il package di componenti personalizzati, è possibile che nella cartella superiore sia stato creato un file denominato Dockerfile. In tal caso, è necessario eliminarlo. In caso contrario, la distribuzione non riuscirà.

2. Nella cartella superiore del package di componenti personalizzati (la cartella che contiene main.js), creare un file denominato func.js, quindi aggiungere il codice seguente. Questo è il file che verrà richiamato da Oracle Cloud Infrastructure Functions.

   /***
    
     This function handles an invocation that sets the "Oracle-Bots-Fn-Path" header to determine which component to invoke or if metadata should be returned.
    
   ***/
    
   const fdk = require('@fnproject/fdk');
   const OracleBotLib = require('@oracle/bots-node-sdk/lib');
   const path = require("path");
    
   const BOTS_FN_PATH_HEADER = "Oracle-Bots-Fn-Path";
   const METADATA_PATH = "metadata";
   const COMPONENT_PREFIX = "components/";
    
   let shell;
   let componentsRegistry;
    
   const getComponentsRegistry = function (packagePath) {
       let registry = require(packagePath);
       if (registry.components) {
           return OracleBotLib.ComponentRegistry.create(registry.components, path.join(process.cwd(), packagePath));
       }
       return null;
   }
    
   componentsRegistry = getComponentsRegistry('.');
   if (componentsRegistry && componentsRegistry.getComponents().size > 0) {
       shell = OracleBotLib.ComponentShell({logger: console}, componentsRegistry);
       if (!shell) {
           throw new Error("Failed to initialize Bots Node SDK");
       }
   } else {
       throw new Error("Unable to process component registry because no components were found in package: " + packagePath);
   }
    
   const _handle = function (input, ctx) {
       let botsFnPath = ctx.getHeader(BOTS_FN_PATH_HEADER);
       if (!botsFnPath) {
           throw new Error("Missing required header " +  BOTS_FN_PATH_HEADER);
       } else if (botsFnPath === METADATA_PATH) {
           return shell.getAllComponentMetadata();
       } else if (botsFnPath.startsWith(COMPONENT_PREFIX)) {
           let componentName = botsFnPath.substring(COMPONENT_PREFIX.length);
           if (!componentName) {
               throw new Error("The component name is missing from the header " + BOTS_FN_PATH_HEADER + ": " + botsFnPath);
           }
           return new Promise((resolve) => {
               let callback = (err, data) => {
                   if (!err) {
                       resolve(data);
                   } else {
                       console.log("Component invocation failed", err.stack);
                       throw err;
                   }
               };
               shell.invokeComponentByName(componentName, input, {logger: () => console}, callback);
               });
       }
   };
    
   fdk.handle(function (input, ctx) {
       try {
           return _handle(input, ctx);
       } catch (err) {
           console.log("Function failed", err.stack);
           throw err;
       }
   });

3. Nella stessa cartella, creare un file denominato func.yaml, quindi aggiungere il contenuto seguente:

   schema_version: 20180708
   name: <custom component package name>
   version: 0.0.1
   runtime: [node11|node14]
   build_image: [fnproject/node:11-dev|fnproject/node:14-dev]
   run_image: [fnproject/node:11|fnproject/node:14]
   entrypoint: node func.js

4. Nella proprietà name, modificare <custom component package name> in base al nome del package di componenti personalizzati, quindi salvare le modifiche. In genere il nome è lo stesso specificato nel file package.json.

   Il nome non deve superare i 255 caratteri e deve contenere solo lettere, numeri, _ e -.

5. Impostare le seguenti proprietà:

   • runtime: la lingua e la versione del nodo. Specificare node11 o node14.

   • build_image: l'immagine di base build-time che contiene le librerie e gli strumenti specifici della lingua per creare funzioni eseguibili. Specificare fnproject/node:11-dev o fnproject/node:14-dev.

   • run_image: l'immagine di base runtime che fornisce l'ambiente runtime specifico della lingua in cui eseguire le funzioni eseguibili. Specificare fnproject/node:11 o fnproject/node:14.

6. In una finestra di terminale, passare alla cartella superiore del pacchetto e inserire questo comando per installare il FDK e aggiungerlo come dipendenza del pacchetto nel file package.json:

   npm install --save-dev @fnproject/fdk

7. (Opzionale: sottosistema Linux, Mac e Linux solo in ambiente Windows) Eseguire questo comando per installare le dipendenze dei pacchetti:

   npm install

   Tenere presente che se la cartella node_modules non esiste, il comando fn deploy eseguito in seguito richiamerà automaticamente npm install.

8. (Solo VM Windows) Per copiare il codice del componente personalizzato nel guest Linux per la distribuzione, attenersi alla procedura riportata di seguito.

   1. Trascinare la cartella di livello superiore nel guest Linux.

   2. In una finestra del terminale, passare alla cartella di livello superiore (quella che contiene main.js) e digitare questo comando per aggiungere le autorizzazioni di esecuzione per la cartella.

      chmod 755 components

   3. Eliminare la cartella node_modules per assicurarsi di non disporre di moduli nodo dipendenti dalla piattaforma.

   4. (Opzionale) Eseguire questo comando per reinstallare le dipendenze del modulo nodo.

      npm install

      Tenere presente che se la cartella node_modules non esiste, il comando fn deploy eseguito in seguito richiamerà automaticamente npm install.

È ora possibile completare i passi descritti nella sezione Distribuire i componenti personalizzati in Oracle Cloud Infrastructure Functions.

Dopo aver creato il file func.js, aggiunto fnproject alle dipendenze di sviluppo e installato le dipendenze come descritto in Modify the Custom Component Package for Oracle Functions, si è pronti a distribuire un'immagine Docker del package di componenti in Oracle Cloud Infrastructure Functions.

Una volta completata la procedura descritta in Impostazione dell'account utente per Oracle Functions, i comandi sono stati copiati dalla pagina Impostazione locale della pagina Guida introduttiva per i passi da 3 a 7. Questi comandi copiati verranno utilizzati per distribuire i componenti personalizzati.

Se si utilizza Cloud Shell, utilizzare invece i comandi simili mostrati nella sezione Impostazione Cloud Shell.

Per distribuire i componenti personalizzati, effettuare le operazioni riportate di seguito.

1. Assicurarsi che Docker e il server Fn siano in esecuzione.

2. In una finestra di terminale, passare alla directory principale del pacchetto di componenti personalizzati e immettere i comandi copied equivalenti per configurare il contesto.

   fn create context <context> --provider oracle
   fn use context <context>
   fn update context oracle.compartment-id <compartment-ocid>
   fn update context api-url https://functions.<region-identifier>.oci.oraclecloud.com

   Non è necessario eseguire di nuovo questi comandi finché non è necessario modificare le configurazioni del contesto.

   Se viene visualizzato l'errore "Fn: error replace file with tempfile" quando si modifica il contesto, modificare manualmente ~/.fn/config.yaml e modificare il contesto in tale file.

3. Se il file di configurazione contiene più profili, immettere questo comando per puntare al profilo creato in Impostazione dell'account utente per Oracle Functions.

   fn update context oracle.profile <profile-name>

4. Per puntare al repository di registro creato in Impostazione dell'account utente per Oracle Functions, immettere il comando copiato equivalente al seguente. Se non lo si è già fatto, modificare [OCIR-REPO] in base al nome del repository.

   fn update context registry <region-key>.ocir.io/<tenancy-namespace>/[OCIR-REPO]

   Non è necessario eseguire di nuovo questo comando finché non è necessario modificare la configurazione del repository.

5. Se non hai effettuato l'accesso a Docker nella sessione corrente, esegui il comando copiato equivalente a quello mostrato qui.

   Quando viene richiesta una password, immettere il token di autenticazione, ovvero il token ottenuto durante la procedura descritta in Impostazione dell'account utente per Oracle Functions.

   docker login -u '<tenancy-namespace>/<user-name>' <region-key>.ocir.io

6. Per distribuire i componenti personalizzati, eseguire il comando seguente:

   fn deploy --app <application>

   Se viene visualizzato il messaggio seguente, aprire il file .oci/config e verificare che fingerprint mostri l'impronta digitale corretta per il file key_file specificato. In caso contrario, andare alle impostazioni utente nella console, fare clic su Chiavi API, visualizzare il file di configurazione per l'impronta digitale corretta, quindi sostituire il contenuto del file di configurazione con il contenuto visualizzato.

   Fn: Service error:NotAuthenticated. The required information to complete
   authentication was not provided or was incorrect.. 
   http status code: 401.

I componenti personalizzati sono pronti per essere utilizzati in una competenza come descritto in Aggiungi servizio funzioni Oracle.