Como executar scripts de inicialização

Crie e execute seus próprios scripts de inicialização nas máquinas virtuais (VMs) para cumprir tarefas automatizadas toda vez que sua instância for inicializada. Os scripts de inicialização podem executar muitas ações, como instalação de software, execução de atualizações, ativação de serviços e quaisquer outras tarefas definidas no script. É possível usar scripts de inicialização para personalizar suas instâncias de VM de forma fácil e programática, inclusive em novas instâncias no momento da criação.

Veja a seguir um exemplo de um script de inicialização simples que instala e inicia um servidor Apache:

    #! /bin/bash
    apt-get update
    apt-get install -y apache2
    cat <<EOF > /var/www/html/index.html
    <html><body><h1>Hello World</h1>
    <p>This page was created from a simple startup script!</p>
    </body></html>
    

Um script de inicialização é especificado por meio do servidor de metadados. Isso é feito com o uso de chaves de metadados de script de inicialização. Use a ferramenta de linha de comando gcloud, a API ou o Console do Google Cloud para fornecer um script de inicialização.

Antes de começar

Permissões exigidas para a tarefa

Para executar esta tarefa, é preciso ter as permissões a seguir:

Execução do script de inicialização

A instância sempre executa os scripts de inicialização como raiz depois que a rede está disponível.

Um script de inicialização pode ser um arquivo de qualquer tipo. Se houver um script de inicialização presente, o Compute Engine fará o seguinte:

  1. copia o script de inicialização em um arquivo local na instância;
  2. define as permissões no arquivo para torná-lo executável;
  3. executa o arquivo.

Por exemplo, é possível fornecer um script Python em vez de um script bash. Lembre-se de que o Compute Engine executará o script na íntegra, independentemente do tipo de script.

Para executar um script que não é bash, adicione uma linha shebang na parte superior do arquivo para permitir que o sistema operacional saiba qual intérprete usar. Por exemplo, para um script Python, adicione uma linha shebang como:

#! /usr/bin/python

Como usar um script de inicialização local

Os scripts de inicialização local ficam armazenados no seu computador. Para usar um script de inicialização local, passe um arquivo de script de inicialização local para a instância ou forneça o conteúdo de um script de inicialização diretamente ao servidor de metadados. Os exemplos das subseções a seguir mostram como adicionar metadados de script de inicialização por meio de um arquivo local ou por entrada direta.

Os scripts de inicialização local estão sujeitos ao limite de comprimento do valor de metadados de 256 KB. Se o script de inicialização ultrapassar esse limite, não será possível carregá-lo localmente. Em vez disso, salve o arquivo no Cloud Storage e especifique o URL do script durante a criação da instância. Consulte Usar um script de inicialização armazenado no Cloud Storage para mais informações.

Fornecer um arquivo de script de inicialização

Você só pode passar um arquivo de script de inicialização local usando a ferramenta de linha de comando gcloud da ferramenta de linha de comando. Inclua a sinalização --metadata-from-file, seguida por um par de chaves de metadados, startup-script=path-to-file, substituindo path-to-file por um caminho relativo para o script de inicialização:

    gcloud compute instances create example-instance \
        --metadata-from-file startup-script=examples/scripts/install.sh
    

Fornecer conteúdo do script de inicialização diretamente

Como alternativa, é possível usar o console, a ferramenta de linha de comando gcloud ou a API para digitar ou colar o conteúdo do script de inicialização diretamente.

Console

No Console do Cloud, especifique um script de inicialização diretamente na seção Script de inicialização:

  1. No Console do Cloud, acesse a página Instâncias de VM.

    Acessar a página Instâncias de VM (em inglês)

  2. Clique em Criar instância.
  3. Na página Criar uma nova instância, preencha as propriedades da sua instância. Para opções avançadas de configuração, expanda a seção Gerenciamento, segurança, discos, rede, locatário único.
  4. Na seção Automação, forneça o conteúdo do script de inicialização em Script de inicialização.

    Captura de tela da configuração do script de inicialização no Console do Cloud

  5. Clique em Criar para criar a instância.

gcloud

Com a ferramenta de linha de comando gcloud, especifique a sinalização --metadata para fornecer o conteúdo do script de inicialização, usando o par de chave-valor startup-script=contents, substituindo contents pelo conteúdo do script de inicialização.

Por exemplo, o comando a seguir cria uma instância que, na inicialização, executa algumas atualizações do sistema, instala o Apache e inicia uma página da Web simples. É possível executar este comando e visitar o endereço IP externo da instância para ver o conteúdo da página index.html.

Em um computador com Linux, execute o comando da seguinte maneira:

gcloud compute instances create example-instance --tags http-server \
    --metadata startup-script='#! /bin/bash
    # Installs apache and a custom homepage
    sudo su -
    apt-get update
    apt-get install -y apache2
    cat <<EOF > /var/www/html/index.html
    <html><body><h1>Hello World</h1>
    <p>This page was created from a simple start up script!</p>
    </body></html>
    EOF'
    

Se você estiver em uma área de trabalho do Windows, execute este comando em um terminal cmd:

    gcloud compute instances create example-instance --tags http-server --metadata startup-script="
    apt-get update;
    apt-get install -y apache2;
    echo \"This page was created from a simple start up script!\" ^> /var/www/html/index.html"
    

Da mesma forma, se estiver usando o PowerShell, execute o comando usando o marcador --% para transmitir o comando exato à ferramenta gcloud:

    gcloud --% compute instances create example-instance --tags http-server --metadata startup-script="
    apt-get update;
    apt-get install -y apache2;
    echo \"This page was created from a simple start up script!\" ^> /var/www/html/index.html"
    

API

Na API, forneça um script de inicialização como parte da propriedade de metadados na solicitação, usando startup-script como chave de metadados:

POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

    {
      ...
      "metadata": {
        "items": [
          {
           "key": "startup-script",
           "value": "#! /bin/bash\n\n# Installs apache and a custom homepage\napt-get update\napt-get install -y apache2\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a simple start up script!</p>\n</body></html>"
          }
        ]
      }
      ...
    }
    

Fornecer um script de inicialização para instâncias do Windows

É possível executar scripts de inicialização em instâncias do Windows usando chaves de metadados únicas específicas desse sistema operacional. Escolha uma das chaves de metadados especializadas listadas na tabela abaixo. Cada chave de metadados deve corresponder ao tipo de script que você quer executar. Também é possível especificar vários scripts transferindo chaves de metadados diferentes para a instância. Só é possível especificar cada chave de metadados uma vez para cada instância de VM.

Se você precisar executar manualmente os scripts de inicialização em uma instância de VM depois que ela for iniciada, um administrador poderá fazer isso usando o seguinte comando:

    C:\Program Files\Google\Compute Engine\metadata_scripts\run_startup_scripts.cmd
    

A tabela a seguir mostra os tipos de scripts de inicialização compatíveis, quando eles são executados e qual chave de metadados usar para especificar o script. Para informações sobre como usar essas chaves de metadados, consulte Como usar um script de inicialização local. Esses scripts só serão executados se você preparar a imagem com o comando GCESysprep.

Tipo de script Executa:
  • Durante GCESysprep2
  • Antes da inicialização
Executa:
  • Após GCESysprep2 ser concluído
  • Em cada inicialização subsequente
Scripts de inicialização url chave de metadados:
sysprep-specialize-script-url
chave de metadados:
windows-startup-script-url
Scripts de inicialização cmd chave de metadados:
sysprep-specialize-script-cmd
chave de metadados:
windows-startup-script-cmd
Scripts de inicialização bat chave de metadados:
sysprep-specialize-script-bat
chave de metadados:
windows-startup-script-bat
ps11Scripts de inicialização chave de metadados:
sysprep-specialize-script-ps1
chave de metadados:
windows-startup-script-ps1

Como fornecer um script de inicialização armazenado no Cloud Storage

É possível armazenar o script no Cloud Storage e fornecer o URL para o script ao criar a instância. Fazendo isso, é possível acessar o script de inicialização de qualquer lugar e também ignorar o limite do servidor de metadados.

Definir permissões de acesso ao script

Antes de usar um script de inicialização do Cloud Storage, é necessário ter permissão para acessar o script. Verifique as configurações de controle de acesso no bucket e no arquivo para garantir que você tenha permissão.

Por padrão, se você for um proprietário ou editor do projeto, será possível acessar arquivos do mesmo projeto, a menos que haja controles de acesso explícitos que impeçam esse acesso.

Fornecer um script de inicialização

  1. Crie um intervalo. Crie um bucket novo ou use um existente. Para instruções sobre como criar um novo bucket, consulte Como criar um bucket no Console do Google Cloud ou Como criar um bucket no gsutil.
  2. Faça o upload do arquivo no intervalo. Siga as instruções para usar o gsutil ou o Console do Cloud para fazer upload de um objeto.
  3. Forneça o URL ao arquivo de script de inicialização ao criar uma nova instância.

    Console

    1. No Console do Google Cloud, acesse a página Instâncias de VMs.

      Acessar a página "Instâncias de VM"

    2. Clique em Criar instância.
    3. Na página Criar uma nova instância, preencha as propriedades da sua instância.
    4. Na seção Identidade e acesso à API, selecione uma conta de serviço com acesso de leitura do arquivo do script de inicialização no Cloud Storage. Por exemplo, a conta de serviço precisa ter as permissões do papel Visualizador de objetos do Storage.
    5. Expanda a seção Gerenciamento, segurança, discos, rede, locatário único.
    6. Na seção Metadados, forneça startup-script-url como a chave de metadados.
    7. Na caixa Valor, forneça um URL para o arquivo de script de inicialização, no formato gs://[BUCKET]/[FILE] ou https://storage.googleapis.com/[BUCKET]/[FILE].
      1. Clique em Criar para criar a instância.

    gcloud

    Usando a ferramenta de linha de comando gcloud, crie uma instância com os sinalizadores --scopes e --metadata e especifique a chave startup-script-url. A sinalização --scopes permite que a máquina virtual acesse o Cloud Storage para fazer o download do script de inicialização. É possível fornecer o URL do Cloud Storage para o script no formato gs://bucket/file ou https://storage.googleapis.com/bucket/file.

        gcloud compute instances create example-instance --scopes storage-ro \
            --metadata startup-script-url=gs://bucket/startupscript.sh
        

    API

    Na API, forneça um script de inicialização como parte da propriedade de metadados na solicitação, usando startup-script-url como chave de metadados. Além disso, forneça uma lista de scopes com um escopo do Cloud Storage para que a máquina virtual possa acessar o arquivo de script de inicialização:

        POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances
    
        {
          ...
          "serviceAccounts": [
            {
              "email": "default",
              "scopes": [
                "https://www.googleapis.com/auth/devstorage.read_only"
              ]
            }
          ],
          "metadata": {
            "items": [
              {
               "key": "startup-script-url",
               "value": "gs://bucket/myfile"
              }
            ]
          },
          "tags": {
            "items": []
          },
          "machineType": "zones/us-central1-a/machineTypes/n1-standard-1",
          "name": "example-instance"
        }
        

    Windows

    Usando a ferramenta de linha de comando gcloud, crie uma instância com os sinalizadores --scopes e --metadata e especifique a chave windows-startup-script-url. A sinalização --scopes permite que a máquina virtual acesse o Cloud Storage para fazer o download do script de inicialização. É possível fornecer o URL do Cloud Storage para o script no formato gs://bucket/file ou https://storage.googleapis.com/bucket/file.

        gcloud compute instances create example-windows-instance --scopes storage-ro \
            --metadata windows-startup-script-url=gs://bucket/startupscript.ps1
        

Aplicar um script de inicialização a instâncias em execução

Se houver uma instância em execução, adicione um script de inicialização a ela. Na próxima reinicialização da instância, esse script será executado. O script de inicialização também será executado em todas as reinicializações subsequentes.

Siga estas instruções para definir um script de inicialização em uma instância em execução.

Console

  1. No Console do Google Cloud, acesse a página Instâncias de VMs.

    Acessar a página "Instâncias de VM"

  2. Clique na instância para que você quer adicionar um script de inicialização. A página de detalhes da instância é aberta.
  3. Na página "Detalhes da instância", conclua as etapas a seguir:

    1. Clique no botão Editar na parte superior da página.
    2. Em Metadados personalizados, clique em Adicionar item.
    3. Adicione o script de inicialização usando uma das chaves a seguir:

      • startup-script: use essa chave para fornecer diretamente o conteúdo do script de inicialização.
      • startup-script-url: use essa chave para fornecer um URL do Cloud Storage para o arquivo de script de inicialização.

gcloud

Usando a ferramenta de linha de comando gcloud, use o instances add-metadata para adicionar metadados à instância. Use qualquer uma das chaves de script de inicialização disponíveis:

  • --metadata startup-script=CONTENTS: use essa chave para fornecer diretamente o conteúdo do script de inicialização.
  • --metadata startup-script-url=URL: use essa chave para fornecer um URL do Cloud Storage para o arquivo de script de inicialização.
  • --metadata-from-file startup-script=FILE: forneça um arquivo de script de inicialização armazenado localmente.

Exemplo:

    gcloud compute instances add-metadata example-instance \
        --metadata-from-file startup-script=path/to/file
    
    gcloud compute instances add-metadata example-instance \
        --metadata startup-script-url=gs://bucket/file
    

API

Na API, faça uma solicitação para o método instances().setMetadata fornecendo os novos metadados e um valor fingerprint.

Impressão digital é uma string de caracteres aleatória, gerada pelo Compute Engine e usada para executar o bloqueio otimista. Forneça o valor correspondente da impressão digital para realizar sua solicitação. A impressão digital muda após cada solicitação. Se você fornecer uma impressão digital incompatível, sua solicitação será rejeitada. Dessa forma, só é possível fazer uma atualização por vez, o que evita conflitos.

Para receber a impressão digital atual de uma instância, faça uma solicitação instances().get e copie o valor da impressão digital:

GET https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance
    {

     ...
     "name": "example-instance",
     "metadata": {
      "kind": "compute#metadata",
      "fingerprint": "zhma6O1w2l8="
     },
     "...
    }

Em seguida, faça uma solicitação para o método instances().setMetadata, usando uma das seguintes chaves de metadados e o valor da impressão digital:

  • startup-script: use essa chave para inserir diretamente o conteúdo do script de inicialização.
  • startup-script-url: use essa chave para fornecer um URL do Cloud Storage para o arquivo de script de inicialização.

Exemplo:

    POST https://compute.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

        {
         "fingerprint": "zhma6O1w2l8=",
         "items": [
          {
           "key": "startup-script-url",
           "value": "gs://bucket/file"
          }
         ]
        }
    

Executar um script de inicialização novamente

É possível executar novamente os scripts de inicialização na instância da VM conectando-se à instância e executando um dos seguintes comandos:

Nas imagens de Debian, CentOS, RHEL, SLES, SO otimizado para contêiner e Ubuntu

    sudo google_metadata_script_runner --script-type startup --debug

    startup-script: INFO Starting startup scripts.
    startup-script: INFO startup-script: Return code 0.
    startup-script: INFO Finished running startup scripts.
    
    

No SO otimizado pelo contêiner, também é possível usar o comando journalctl para visualizar a saída do script de inicialização.

    sudo journalctl -u google-startup-scripts.service
    

O resultado do script de inicialização é gravado nos arquivos de registro a seguir:

  • CentOS e RHEL: /var/log/messages
  • Debian: /var/log/daemon.log
  • Ubuntu: /var/log/syslog
  • SLES: /var/log/messages

Definir valores personalizados em scripts de inicialização

Pode haver situações em que é preferível usar valores personalizados no script de inicialização durante a execução desse script em instâncias. Por exemplo, pode ser útil executar um script de inicialização em instâncias diferentes e fazer com que cada instância gere uma mensagem personalizada.

Você pode especificar esses valores personalizados como pares de chave/valor de metadados personalizados no momento da criação da instância e referir-se a eles nos scripts de inicialização. Para mais informações sobre como criar chaves de metadados personalizadas, leia Definir metadados personalizados.

Depois de definir um par de chaves de metadados personalizadas, é possível modificar seu script de inicialização para consultar os novos metadados. Por exemplo, o mesmo script acima pode ser modificado da seguinte maneira:

#! /bin/bash
    VALUE_OF_FOO=$(curl http://metadata.google.internal/computeMetadata/v1/instance/attributes/foo -H "Metadata-Flavor: Google")
    apt-get update
    apt-get install -y apache2
    cat <<EOF > /var/www/html/index.html
    <html><body><h1>Hello World</h1>
    <p>The value of foo: $VALUE_OF_FOO</p>
    </body></html>
    EOF

Resolver problemas

Conectividade de rede com o servidor de metadados

Específico para máquinas virtuais Linux, o Compute Engine aguarda uma conexão com o servidor de metadados antes de tentar receber informações como um script personalizado de inicialização ou desligamento do servidor de metadados. Se o servidor de metadados não estiver respondendo ou a rede ainda não estiver configurada, a máquina virtual não concluirá a inicialização.

Específica para máquinas virtuais Linux com imagens anteriores a v20160606, a saída da porta serial mostra "Waiting for metadata server, attempt N", em que N é o número de tentativas que foram feitas.

Esse problema pode durar até sete minutos por causa de um problema de rede temporário que se resolverá sozinho. Se o problema não se resolver depois de sete minutos, recrie a instância de máquina virtual.

A seguir