Use um script pós-arranque

Este guia descreve como usar um script de pós-inicialização com o Colab Enterprise. Este guia também descreve como definir variáveis de ambiente para utilização com o script de pós-arranque.

Vista geral

Pode usar um script de pós-inicialização para realizar tarefas após o processo de inicialização do tempo de execução do Colab Enterprise. Por exemplo, pode usar um script de pós-inicialização para instalar pacotes específicos ou fazer alterações específicas à VM do seu tempo de execução.

Para usar um script de pós-arranque no Colab Enterprise, especifique o script de pós-arranque quando cria um modelo de tempo de execução. Em seguida, quando cria um tempo de execução com base nesse modelo de tempo de execução, o script de pós-início é executado no final do processo de início.

Localização do script pós-arranque

O URI do guião de pós-inicialização pode ser qualquer um dos seguintes:

  • Um URI do Cloud Storage: por exemplo, gs://BUCKET_NAME/SCRIPT_FILE_NAME. Se o script de pós-inicialização estiver armazenado no Cloud Storage, tem de usar um tempo de execução com as credenciais do utilizador final ativadas. Isto deve-se ao facto de o Colab Enterprise usar as suas credenciais de utilizador para aceder ao contentor do Cloud Storage.
  • Um URL HTTPS: por exemplo, https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME. A utilização de um URL HTTPS não é suportada quando cria o modelo de tempo de execução através da consola Google Cloud .

Comportamento do script pós-arranque

Pode especificar o comportamento do script de pós-arranque. Veja a seguinte tabela:

Comportamento Descrição
Executar uma vez (`RUN_ONCE`)

Predefinição. O Colab Enterprise executa o script de pós-arranque apenas uma vez, durante a criação do tempo de execução.

Executar a cada início (`RUN_EVERY_START`)

Após cada início, o Colab Enterprise executa o script de pós-início. Por exemplo, se o encerramento por inatividade parar o tempo de execução, o Colab Enterprise executa novamente o script de pós-inicialização quando o tempo de execução é reiniciado.

Transferir e executar a cada início (`DOWNLOAD_AND_RUN_EVERY_START`)

Após cada início, o Colab Enterprise transfere novamente o script de pós-início da respetiva origem e, em seguida, executa o script.

Variáveis de ambiente

Pode especificar variáveis de ambiente no modelo de tempo de execução e fazer referência a essas variáveis no script de pós-inicialização.

Por exemplo, pode definir o projeto de quota através de uma variável de ambiente. Pode definir o projeto de quota para um ID do projeto específico através de GOOGLE_CLOUD_QUOTA_PROJECT, uma variável comum usada nas Google Cloud bibliotecas de cliente.

Para usar um script de pós-inicialização com variáveis de ambiente, consulte o artigo Crie um modelo de tempo de execução com um script de pós-inicialização e variáveis de ambiente.

Acompanhe as alterações e recupere scripts de pós-inicialização

Para acompanhar as alterações ao seu script de pós-arranque e ativar a recuperação de uma versão específica do script de pós-arranque, armazene o script de pós-arranque num contentor do Cloud Storage com o controlo de versões de objetos ativado. A funcionalidade de controlo de versões de objetos preserva os objetos eliminados como objetos com controlo de versões e não atuais que permanecem acessíveis no seu contentor até serem removidos explicitamente.

Para especificar uma versão do script de pós-inicialização, adicione #GENERATION_NUMBER ao URI do script de pós-inicialização quando criar o modelo de tempo de execução, por exemplo, gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER. Para mais informações sobre o controlo de versões de objetos e os números de geração, consulte o artigo Controlo de versões de objetos.

Quando usa a Google Cloud consola para criar o modelo de tempo de execução, a especificação de um número de geração para o script de pós-inicialização não é suportada.

Antes de começar

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI, Dataform, and Compute Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vertex AI, Dataform, and Compute Engine APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

    Funções necessárias

    Para receber as autorizações de que precisa para criar um modelo de tempo de execução no Colab Enterprise, peça ao seu administrador para lhe conceder a função do IAM de administrador do Colab Enterprise (roles/aiplatform.colabEnterpriseAdmin) no projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

    Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

    Crie um modelo de tempo de execução que use um script de pós-inicialização

    Para criar um modelo de tempo de execução que use um script de pós-arranque, pode usar a Google Cloud consola, a Google Cloud CLI ou a API REST.

    Consola

    Para criar um modelo de tempo de execução que use um script de pós-inicialização, faça o seguinte:

    1. Na Google Cloud consola, aceda à página Modelos de tempo de execução do Colab Enterprise.

      Aceda aos modelos dos ambientes de execução

    2. Clique em  Novo modelo.

      É apresentada a caixa de diálogo Criar novo modelo de tempo de execução.

    3. Na secção Noções básicas de tempo de execução, introduza um Nome a apresentar.

    4. No menu Região, selecione a região onde quer o modelo de tempo de execução.

    5. Na secção Ambiente, no campo Script de pós-arranque, clique em Procurar e, de seguida, navegue para um script de pós-arranque localizado no Cloud Storage. Para mais informações, consulte o artigo Localização do script de pós-arranque.

    6. No URL do script de pós-inicialização, selecione o comportamento do script de pós-inicialização. O comportamento predefinido é Executar uma vez. Para mais informações, consulte o artigo Comportamento do script pós-inicialização.

    7. Na secção Rede e segurança, certifique-se de que a opção Ativar credenciais do utilizador final está selecionada.

    8. Conclua o resto da caixa de diálogo e, de seguida, clique em Criar.

      O modelo de tempo de execução é apresentado na lista no separador Modelos de tempo de execução.

    gcloud

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • DISPLAY_NAME: o nome a apresentar do seu modelo de tempo de execução.
    • PROJECT_ID: o ID do seu projeto.
    • REGION: a região onde quer o modelo de tempo de execução.
    • POST_STARTUP_SCRIPT_URI: o URI do seu script de pós-inicialização. Para mais informações, consulte o artigo Localização do script de pós-arranque.
    • POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script post-startup. Consulte o artigo Comportamento do script de pós-inicialização.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

    Windows (PowerShell)

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

    Windows (cmd.exe)

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

    Para mais informações sobre o comando para criar um modelo de tempo de execução a partir da linha de comandos, consulte a documentação da CLI gcloud.

    REST

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • REGION: a região onde quer o modelo de tempo de execução.
    • PROJECT_ID: o ID do seu projeto.
    • DISPLAY_NAME: o nome a apresentar do seu modelo de tempo de execução.
    • POST_STARTUP_SCRIPT_URI: o URI do seu script de pós-inicialização. Para mais informações, consulte o artigo Localização do script de pós-arranque.
    • POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script post-startup. Consulte o artigo Comportamento do script de pós-inicialização.

    Método HTTP e URL: 

    POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

    Corpo JSON do pedido: 

    {
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

    PowerShell

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content
    Se for bem-sucedido, o corpo da resposta contém uma instância de Operation.

    Para mais informações, consulte a notebookRuntimeTemplates.create documentação da API REST.

    Crie o tempo de execução

    Depois de criar um modelo de tempo de execução que use o seu script de pós-arranque, crie um tempo de execução com base nesse modelo de tempo de execução. O tempo de execução começa e o script de pós-inicialização é executado de acordo com o comportamento especificado. Consulte Crie um tempo de execução.

    Crie um modelo de tempo de execução com um script de pós-inicialização e variáveis de ambiente

    Para criar um modelo de tempo de execução que use um script de pós-inicialização e variáveis de ambiente, pode usar a consola, a Google Cloud CLI ou a API REST. Google Cloud

    Consola

    Para criar um modelo de tempo de execução que use um script de pós-inicialização e variáveis de ambiente, faça o seguinte:

    1. Na Google Cloud consola, aceda à página Modelos de tempo de execução do Colab Enterprise.

      Aceda aos modelos dos ambientes de execução

    2. Clique em  Novo modelo.

      É apresentada a caixa de diálogo Criar novo modelo de tempo de execução.

    3. Na secção Noções básicas de tempo de execução, introduza um Nome a apresentar.

    4. No menu Região, selecione a região onde quer o modelo de tempo de execução.

    5. Na secção Ambiente, no campo Script de pós-arranque, clique em Procurar e, de seguida, navegue para um script de pós-arranque localizado no Cloud Storage. Para mais informações, consulte o artigo Localização do script de pós-arranque.

    6. No URL do script de pós-inicialização, selecione o comportamento do script de pós-inicialização. O comportamento predefinido é Executar uma vez. Para mais informações, consulte o artigo Comportamento do script de pós-inicialização.

    7. Para adicionar uma variável de ambiente, clique em  Adicionar variável de ambiente e, de seguida, introduza um par de chave e valor. Para adicionar mais variáveis de ambiente, repita este passo.

    8. Na secção Rede e segurança, certifique-se de que a opção Ativar credenciais do utilizador final está selecionada.

    9. Conclua o resto da caixa de diálogo e, de seguida, clique em Criar.

      O modelo de tempo de execução é apresentado na lista no separador Modelos de tempo de execução.

    gcloud

    Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

    • DISPLAY_NAME: o nome a apresentar do seu modelo de tempo de execução.
    • PROJECT_ID: o ID do seu projeto.
    • REGION: a região onde quer o modelo de tempo de execução.
    • POST_STARTUP_SCRIPT_URI: o URI do seu script de pós-inicialização. Para mais informações, consulte o artigo Localização do script de pós-arranque.
    • POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script post-startup. Consulte o artigo Comportamento do script de pós-inicialização.
    • ENV_VARIABLE_NAME: o nome de uma variável de ambiente a definir para o seu tempo de execução.
    • ENV_VARIABLE_VALUE: o valor da variável de ambiente a definir para o seu tempo de execução.

    Execute o seguinte comando:

    Linux, macOS ou Cloud Shell

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR \
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

    Windows (PowerShell)

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR `
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

    Windows (cmd.exe)

    gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR ^
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

    Para mais informações sobre o comando para criar um modelo de tempo de execução a partir da linha de comandos, consulte a documentação da CLI gcloud.

    REST

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • REGION: a região onde quer o modelo de tempo de execução.
    • PROJECT_ID: o ID do seu projeto.
    • DISPLAY_NAME: o nome a apresentar do seu modelo de tempo de execução.
    • POST_STARTUP_SCRIPT_URI: o URI do seu script de pós-inicialização. Para mais informações, consulte o artigo Localização do script de pós-arranque.
    • POST_STARTUP_SCRIPT_BEHAVIOR: o comportamento do script post-startup. Consulte o artigo Comportamento do script de pós-inicialização.
    • ENV_VARIABLE_NAME: o nome de uma variável de ambiente a definir para o seu tempo de execução.
    • ENV_VARIABLE_VALUE: o valor da variável de ambiente a definir para o seu tempo de execução.

    Método HTTP e URL: 

    POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

    Corpo JSON do pedido: 

    {
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
    "env": [
      {
        "name": "ENV_VARIABLE_NAME",
        "value": "ENV_VARIABLE_VALUE"
      }
    ]
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         -d @request.json \
         "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

    PowerShell

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content
    Se for bem-sucedido, o corpo da resposta contém uma instância de Operation.

    Para mais informações, consulte a notebookRuntimeTemplates.create documentação da API REST.

    Crie o tempo de execução

    Depois de criar um modelo de tempo de execução que use o seu script de pós-arranque, crie um tempo de execução com base nesse modelo de tempo de execução. O tempo de execução começa e o script de pós-inicialização é executado de acordo com o comportamento especificado. Consulte Crie um tempo de execução.

    Limitações

    Considere as seguintes limitações quando usar scripts de pós-inicialização com o Colab Enterprise:

    • Para criar um tempo de execução com base num modelo de tempo de execução que inclua um script de pós-inicialização, tem de ser o proprietário e o criador desse modelo de tempo de execução.
    • A transmissão de variáveis de ambiente através do script de pós-arranque não é suportada. Tem de especificar variáveis de ambiente na configuração do software, conforme descrito neste guia.
    • Para usar um script de pós-inicialização localizado no Cloud Storage, tem de usar um tempo de execução com as credenciais de utilizador final ativadas e as suas credenciais de utilizador têm de ter acesso ao contentor do Cloud Storage.
    • Se usar a Google Cloud consola para criar o modelo de tempo de execução, o script de pós-arranque tem de estar localizado no Cloud Storage. Os scripts de pós-inicialização noutras localizações não são suportados quando cria o modelo de tempo de execução através da Google Cloud consola.
    • A especificação de um número de geração para o script de pós-arranque não é suportada quando usa a Google Cloud consola para criar o modelo de tempo de execução.

    O que se segue?