Suggerimenti generali per lo sviluppo

Questa guida fornisce le best practice per la progettazione, l'implementazione, il test e il deployment di un servizio Cloud Run. Per ulteriori suggerimenti, consulta la sezione Migrazione di un servizio esistente.

Scrivere servizi efficaci

Questa sezione descrive le best practice generali per la progettazione e l'implementazione di un servizio Cloud Run.

Attività in background

L'attività in background è tutto ciò che accade dopo che la risposta HTTP è stata inviata. Per determinare se nel tuo servizio esiste un'attività in background che non è subito evidente, controlla nei log se viene registrato qualsiasi cosa viene registrato dopo la voce della richiesta HTTP.

Configura la CPU da allocare sempre per l'uso delle attività in background

Se vuoi supportare le attività in background nel servizio Cloud Run, imposta la CPU del servizio Cloud Run in modo che sia sempre allocata, in modo da poter eseguire attività in background al di fuori delle richieste senza rinunciare all'accesso alla CPU.

Evita attività in background se la CPU viene allocata solo durante l'elaborazione della richiesta

Se devi impostare il servizio in modo da allocare la CPU solo durante l'elaborazione delle richieste, quando il servizio Cloud Run termina di gestire una richiesta, l'accesso dell'istanza alla CPU verrà disabilitato o limitato in modo grave. Se utilizzi questo tipo di allocazione della CPU, non devi avviare thread o routine in background che vengono eseguiti al di fuori dell'ambito dei gestori delle richieste.

Esamina il codice per assicurarti che tutte le operazioni asincrone terminino prima di inviare la risposta.

L'esecuzione di thread in background con questo tipo di allocazione della CPU può causare comportamenti imprevisti, perché qualsiasi richiesta successiva alla stessa istanza di container riprende qualsiasi attività in background sospesa.

Eliminare i file temporanei

Nell'ambiente Cloud Run, l'archiviazione su disco è un file system in memoria. I file scritti su disco utilizzano memoria altrimenti disponibile per il tuo servizio e possono rimanere in sospeso tra una chiamata e l'altra. La mancata eliminazione di questi file potrebbe causare un errore di esaurimento della memoria e un successivo avvio a freddo.

Segnala errori

Gestisci tutte le eccezioni e non consentire l'arresto anomalo del servizio in caso di errori. Un arresto anomalo porta a un avvio a freddo mentre il traffico è in coda per un'istanza sostitutiva.

Per informazioni su come segnalare correttamente gli errori, consulta la guida alla segnalazione degli errori.

Ottimizzazione del rendimento

Questa sezione descrive le best practice per ottimizzare il rendimento.

Avvio rapido dei container

Poiché le istanze vengono scalate secondo necessità, il loro tempo di avvio ha un impatto sulla latenza del servizio. Mentre Cloud Run disaccoppia l'elaborazione delle richieste e l'avvio, può accadere che una richiesta attenda prima che la nuova istanza venga avviata per l'elaborazione, in particolare quando viene scalata da zero. Questo processo è chiamato "avvio a freddo".

La routine di avvio è costituita da:

  • Download dell'immagine container (utilizzando la tecnologia di flussi di dati delle immagini container di Cloud Run)
  • Avvia il container eseguendo il comando entrypoint.
  • In attesa che il container inizi ad ascoltare sulla porta configurata.

L'ottimizzazione della velocità di avvio dei container riduce al minimo la latenza di elaborazione delle richieste.

Usa il booster della CPU all'avvio per ridurre la latenza di avvio

Puoi abilitare il booster della CPU all'avvio per aumentare temporaneamente l'allocazione della CPU durante l'avvio dell'istanza in modo da ridurre la latenza di avvio.

Utilizza il numero minimo di istanze per ridurre gli avvii a freddo

Puoi configurare un numero minimo di istanze e la contemporaneità per ridurre al minimo gli avvii a freddo. Ad esempio, utilizzare un numero minimo di istanze pari a 1 significa che il servizio è pronto a ricevere fino al numero di richieste in parallelo configurate per il servizio senza dover avviare una nuova istanza.

Tieni presente che una richiesta in attesa dell'avvio di un'istanza verrà mantenuta in attesa in una coda, come indicato di seguito:

  • Se vengono avviate nuove istanze, ad esempio durante uno scale out, le richieste cadranno almeno per il tempo di avvio medio delle istanze di container di questo servizio. Questo include quando la richiesta avvia uno scale out, ad esempio quando viene scalato da zero.
  • Se il tempo di avvio è inferiore a 10 secondi, le richieste verranno sospese per un massimo di 10 secondi.
  • Se non sono presenti istanze in fase di avvio e la richiesta non avvia uno scale out, le richieste verranno sospese per un massimo di 10 secondi.

Usa le dipendenze con oculatezza

Se utilizzi un linguaggio dinamico con librerie dipendenti, ad esempio importando moduli in Node.js, il tempo di caricamento di questi moduli si aggiunge alla latenza di avvio.

Riduci la latenza di avvio nei seguenti modi:

  • Riduci al minimo il numero e la dimensione delle dipendenze per creare un servizio sottile.
  • Carica lentamente il codice usato raramente, se supportato dal tuo linguaggio.
  • Usa ottimizzazioni del caricamento del codice come l'ottimizzazione del caricatore automatico dei composer di PHP.

Utilizzare le variabili globali

In Cloud Run, non puoi presumere che lo stato del servizio venga conservato tra le richieste. Tuttavia, Cloud Run riutilizza singole istanze per gestire il traffico in corso, quindi puoi dichiarare una variabile in ambito globale per consentire il riutilizzo del relativo valore nelle chiamate successive. Non è possibile sapere in anticipo se ogni singola richiesta riceva il vantaggio di questo riutilizzo.

Puoi anche memorizzare nella cache gli oggetti che sono costosi da ricreare per ogni richiesta di servizio. Lo spostamento dalla logica di richiesta all'ambito globale consente di ottenere prestazioni migliori.

Node.js 

const functions = require('@google-cloud/functions-framework');

// TODO(developer): Define your own computations
const {lightComputation, heavyComputation} = require('./computations');

// Global (instance-wide) scope
// This computation runs once (at instance cold-start)
const instanceVar = heavyComputation();

/**
 * HTTP function that declares a variable.
 *
 * @param {Object} req request context.
 * @param {Object} res response context.
 */
functions.http('scopeDemo', (req, res) => {
  // Per-function scope
  // This computation runs every time this function is called
  const functionVar = lightComputation();

  res.send(`Per instance: ${instanceVar}, per function: ${functionVar}`);
});

Python 

import time

import functions_framework

# Placeholder
def heavy_computation():
    return time.time()

# Placeholder
def light_computation():
    return time.time()

# Global (instance-wide) scope
# This computation runs at instance cold-start
instance_var = heavy_computation()

@functions_framework.http
def scope_demo(request):
    """
    HTTP Cloud Function that declares a variable.
    Args:
        request (flask.Request): The request object.
        <http://flask.pocoo.org/docs/1.0/api/#flask.Request>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>.
    """

    # Per-function scope
    # This computation runs every time this function is called
    function_var = light_computation()
    return f"Instance: {instance_var}; function: {function_var}"

Go 


// h is in the global (instance-wide) scope.
var h string

// init runs during package initialization. So, this will only run during an
// an instance's cold start.
func init() {
	h = heavyComputation()
	functions.HTTP("ScopeDemo", ScopeDemo)
}

// ScopeDemo is an example of using globally and locally
// scoped variables in a function.
func ScopeDemo(w http.ResponseWriter, r *http.Request) {
	l := lightComputation()
	fmt.Fprintf(w, "Global: %q, Local: %q", h, l)
}

Java 


import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Arrays;

public class Scopes implements HttpFunction {
  // Global (instance-wide) scope
  // This computation runs at instance cold-start.
  // Warning: Class variables used in functions code must be thread-safe.
  private static final int INSTANCE_VAR = heavyComputation();

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    // Per-function scope
    // This computation runs every time this function is called
    int functionVar = lightComputation();

    var writer = new PrintWriter(response.getWriter());
    writer.printf("Instance: %s; function: %s", INSTANCE_VAR, functionVar);
  }

  private static int lightComputation() {
    int[] numbers = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
    return Arrays.stream(numbers).sum();
  }

  private static int heavyComputation() {
    int[] numbers = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9 };
    return Arrays.stream(numbers).reduce((t, x) -> t * x).getAsInt();
  }
}

Esegui l'inizializzazione lazy delle variabili globali

L'inizializzazione delle variabili globali avviene sempre durante l'avvio, aumentando il tempo di avvio a freddo. Usa l'inizializzazione lazy per gli oggetti usati raramente, al fine di rinviare il costo in termini di tempo e ridurre i tempi di avvio a freddo.

Node.js 

const functions = require('@google-cloud/functions-framework');

// Always initialized (at cold-start)
const nonLazyGlobal = fileWideComputation();

// Declared at cold-start, but only initialized if/when the function executes
let lazyGlobal;

/**
 * HTTP function that uses lazy-initialized globals
 *
 * @param {Object} req request context.
 * @param {Object} res response context.
 */
functions.http('lazyGlobals', (req, res) => {
  // This value is initialized only if (and when) the function is called
  lazyGlobal = lazyGlobal || functionSpecificComputation();

  res.send(`Lazy global: ${lazyGlobal}, non-lazy global: ${nonLazyGlobal}`);
});

Python 

import functions_framework

# Always initialized (at cold-start)
non_lazy_global = file_wide_computation()

# Declared at cold-start, but only initialized if/when the function executes
lazy_global = None

@functions_framework.http
def lazy_globals(request):
    """
    HTTP Cloud Function that uses lazily-initialized globals.
    Args:
        request (flask.Request): The request object.
        <http://flask.pocoo.org/docs/1.0/api/#flask.Request>
    Returns:
        The response text, or any set of values that can be turned into a
        Response object using `make_response`
        <http://flask.pocoo.org/docs/1.0/api/#flask.Flask.make_response>.
    """
    global lazy_global, non_lazy_global

    # This value is initialized only if (and when) the function is called
    if not lazy_global:
        lazy_global = function_specific_computation()

    return f"Lazy: {lazy_global}, non-lazy: {non_lazy_global}."

Go 


// Package tips contains tips for writing Cloud Functions in Go.
package tips

import (
	"context"
	"log"
	"net/http"
	"sync"

	"cloud.google.com/go/storage"
	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

// client is lazily initialized by LazyGlobal.
var client *storage.Client
var clientOnce sync.Once

func init() {
	functions.HTTP("LazyGlobal", LazyGlobal)
}

// LazyGlobal is an example of lazily initializing a Google Cloud Storage client.
func LazyGlobal(w http.ResponseWriter, r *http.Request) {
	// You may wish to add different checks to see if the client is needed for
	// this request.
	clientOnce.Do(func() {
		// Pre-declare an err variable to avoid shadowing client.
		var err error
		client, err = storage.NewClient(context.Background())
		if err != nil {
			http.Error(w, "Internal error", http.StatusInternalServerError)
			log.Printf("storage.NewClient: %v", err)
			return
		}
	})
	// Use client.
}

Java 


import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.Arrays;

public class LazyFields implements HttpFunction {
  // Always initialized (at cold-start)
  // Warning: Class variables used in Servlet classes must be thread-safe,
  // or else might introduce race conditions in your code.
  private static final int NON_LAZY_GLOBAL = fileWideComputation();

  // Declared at cold-start, but only initialized if/when the function executes
  // Uses the "initialization-on-demand holder" idiom
  // More information: https://en.wikipedia.org/wiki/Initialization-on-demand_holder_idiom
  private static class LazyGlobalHolder {
    // Making the default constructor private prohibits instantiation of this class
    private LazyGlobalHolder() {}

    // This value is initialized only if (and when) the getLazyGlobal() function below is called
    private static final Integer INSTANCE = functionSpecificComputation();

    private static Integer getInstance() {
      return LazyGlobalHolder.INSTANCE;
    }
  }

  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    Integer lazyGlobal = LazyGlobalHolder.getInstance();

    var writer = new PrintWriter(response.getWriter());
    writer.printf("Lazy global: %s; non-lazy global: %s%n", lazyGlobal, NON_LAZY_GLOBAL);
  }

  private static int functionSpecificComputation() {
    int[] numbers = new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9};
    return Arrays.stream(numbers).sum();
  }

  private static int fileWideComputation() {
    int[] numbers = new int[] {1, 2, 3, 4, 5, 6, 7, 8, 9};
    return Arrays.stream(numbers).reduce((t, x) -> t * x).getAsInt();
  }
}

Utilizza un ambiente di esecuzione diverso

Potresti riscontrare tempi di avvio più rapidi utilizzando un ambiente di esecuzione diverso.

Ottimizza la contemporaneità

Le istanze Cloud Run possono gestire più richieste contemporaneamente, "contemporaneamente", fino a una contemporaneità massima configurabile. È diverso da Cloud Functions, che utilizza concurrency = 1.

Cloud Run regola automaticamente la contemporaneità fino al massimo configurato.

La contemporaneità massima predefinita di 80 è ideale per molte immagini container. Tuttavia, devi:

  • Riduci questo valore se il container non è in grado di elaborare molte richieste in parallelo.
  • Aumentalo se il container è in grado di gestire un volume elevato di richieste.

Ottimizza la contemporaneità per il tuo servizio

Il numero di richieste in parallelo che ogni istanza può essere gestita da ogni istanza può essere limitato dallo stack tecnologico e dall'uso di risorse condivise come variabili e connessioni ai database.

Per ottimizzare il servizio per la massima contemporaneità stabile:

  1. Ottimizza le prestazioni dei servizi.
  2. Imposta il livello previsto di supporto della contemporaneità in qualsiasi configurazione di contemporaneità a livello di codice. Non tutti gli stack tecnologici richiedono un'impostazione di questo tipo.
  3. Esegui il deployment del servizio.
  4. Imposta la contemporaneità di Cloud Run per il tuo servizio su un valore uguale o inferiore a quello di qualsiasi configurazione a livello di codice. In assenza di una configurazione a livello di codice, utilizza la contemporaneità prevista.
  5. Utilizza strumenti di test del carico che supportano una contemporaneità configurabile. Devi confermare che il tuo servizio rimanga stabile, nel rispetto del carico e della contemporaneità previsti.
  6. Se il servizio funziona in modo scadente, vai al passaggio 1 per migliorare il servizio o al passaggio 2 per ridurre la contemporaneità. Se il servizio funziona, torna al passaggio 2 e aumenta la contemporaneità.

Continua a ripetere l'iterazione fino a trovare il massimo della contemporaneità stabile.

Abbina la memoria alla contemporaneità

Ogni richiesta gestita dal tuo servizio richiede una certa quantità di memoria aggiuntiva. Pertanto, quando aumenti o riduci la contemporaneità, assicurati di regolare anche il limite di memoria.

Evita stato globale modificabile

Se vuoi utilizzare lo stato globale modificabile in un contesto simultaneo, esegui passaggi aggiuntivi nel codice per assicurarti che l'operazione venga eseguita in modo sicuro. Riduci al minimo la contesa limitando le variabili globali all'inizializzazione e al riutilizzo una tantum, come descritto sopra nella sezione Prestazioni.

Se utilizzi variabili globali modificabili in un servizio che gestisce più richieste contemporaneamente, assicurati di utilizzare blocchi o mutex per evitare racecondition.

Sicurezza dei container

Molte pratiche di sicurezza del software per uso generico si applicano alle applicazioni containerizzate. Esistono alcune pratiche specifiche per i container o in linea con la filosofia e l'architettura dei container.

Per migliorare la sicurezza dei container:

  • Utilizza immagini di base gestite attivamente e sicure come immagini di base di Google o immagini ufficiali di Docker Hub.

  • Applica gli aggiornamenti della sicurezza ai tuoi servizi ricreando regolarmente le immagini dei container ed eseguendo nuovamente il deployment dei servizi.

  • Includi nel container solo ciò che è necessario per eseguire il tuo servizio. Codice, pacchetti e strumenti aggiuntivi sono potenziali vulnerabilità per la sicurezza. Vedi sopra l'impatto sul rendimento correlato.

  • Implementare un processo di compilazione deterministico che includa versioni specifiche di software e librerie. In questo modo il codice non verificato viene incluso nel container.

  • Imposta il container in modo che venga eseguito come utente diverso da root con l'istruzione Dockerfile USER. Per alcune immagini container potrebbe essere già configurato un utente specifico.

Automatizza l'analisi della sicurezza

Attiva l'analisi delle vulnerabilità per l'analisi di sicurezza delle immagini container archiviate in Artifact Registry.

Crea immagini container minime

Le immagini container di grandi dimensioni aumentano probabilmente le vulnerabilità di sicurezza perché contengono più di ciò di cui il codice ha bisogno.

A causa della tecnologia di inserimento di flussi di immagini container di Cloud Run, le dimensioni dell'immagine container non influiscono sull'avvio a freddo o sui tempi di elaborazione delle richieste. Inoltre, le dimensioni dell'immagine container non vengono conteggiate ai fini della memoria disponibile del container.

Per creare un container minimo, valuta la possibilità di lavorare da un'immagine di base sottile come:

Ubuntu ha dimensioni maggiori, ma è un'immagine di base di uso comune con un ambiente server pronto all'uso più completo.

Se il tuo servizio ha un processo di compilazione che richiede molti strumenti, valuta la possibilità di utilizzare build multifase per mantenere il container leggero in fase di esecuzione.

Queste risorse forniscono ulteriori informazioni sulla creazione di immagini container sottili: