Como executar scripts de inicialização


O Compute Engine permite criar e executar seus próprios scripts de inicialização nas instâncias de máquina virtual (VM) para realizar tarefas automatizadas sempre que a instância for inicializada. Os scripts de inicialização podem executar ações como instalar software, executar atualizações, ativar serviços e qualquer outra tarefa definida no script.

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

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

Para especificar um script de inicialização, use chaves de metadados de scripts de inicialização com o servidor de metadados. Use o Console do Google Cloud, a ferramenta de linha de comando gcloud ou a API Compute Engine 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:

Como executar um script de inicialização

A instância sempre executa scripts de inicialização como raiz após a rede ficar disponível.

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

  1. Copiará o script de inicialização em um arquivo local na instância
  2. Definirá as permissões de execução no arquivo
  3. Executará o arquivo

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

Para executar um script que não seja bash, adicione um shebang (uma linha que começa com #!) na parte superior do arquivo. Isso informa ao sistema operacional qual interpretador usar. Por exemplo, se você usar um script Python, é possível adicionar a seguinte linha de Shebang:

#! /usr/bin/python

Como usar um script de inicialização local

Os scripts de inicialização local ficam localizados 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 inserção 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 exceder 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. Para mais informações, consulte Como fornecer um script de inicialização armazenado no Cloud Storage.

Fornecer um arquivo de script de inicialização

Só é possível passar um arquivo de script de inicialização local usando a ferramenta de linha de comando gcloud. 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 do Google Cloud, a ferramenta de linha de comando gcloud ou a API do Compute Engine para digitar ou colar diretamente o conteúdo do script de inicialização.

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"

  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, em Script de inicialização, forneça o conteúdo do script de inicialização.

    Como configurar um 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, use 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. Execute esse comando e acesse 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 update
  apt -y install apache2
  cat <<EOF > /var/www/html/index.html
  <html><body><h1>Hello World</h1>
  <p>This page was created from a 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 update;
  apt -y install apache2;
  echo \"This page was created from a start up script.\" ^> /var/www/html/index.html"

Da mesma forma, se você estiver usando o PowerShell, será possível executar esse comando usando o caractere especial stop parsing (--%) para transmitir um comando exato para a ferramenta gcloud:

gcloud --% compute instances create example-instance --tags http-server \
  --metadata startup-script="
  apt update;
  apt -y install apache2;
  echo \"This page was created from a 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 update\napt -y install apache2\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a 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 exclusivas e específicas do Windows. Escolha uma das chaves de metadados especializados listadas na tabela a seguir. Cada chave de metadados precisa corresponder ao tipo de script que você quer executar. Também é possível especificar vários scripts transmitindo chaves de metadados diferentes para a instância. É possível especificar cada chave de metadados somente 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 usando o comando GCESysprep.

Tipo de script Execuções:
  • Durante GCESysprep2
  • Antes da inicialização
Execuções:
  • Depois que GCESysprep2 for 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 seu script no Cloud Storage e fornecer o URL para o script ao criar sua instância. Com 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, você precisa 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 proprietário ou editor de um projeto, será possível acessar arquivos do mesmo projeto, a menos que haja controles de acesso explícitos que proíbam o acesso.

Fornecer um script de inicialização

  1. Crie um bucket. Crie um bucket ou use um já existente. Para mais informações sobre como criar um bucket, consulte Como criar um bucket no Console do Google Cloud ou Como criar um bucket em gsutil.
  2. Faça o upload do arquivo no bucket. Siga as instruções para usar o gsutil ou o Console do Cloud para fazer upload de um objeto.
  3. Forneça o URL para o arquivo de script de inicialização ao criar uma 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.

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

    gcloud

    Com a ferramenta de linha de comando gcloud, crie uma instância com as sinalizações --scopes e --metadata e especifique a chave startup-script-url. A sinalização --scopes permite que a VM 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/FILE.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 que inclua um escopo do Cloud Storage para que a VM possa acessar o arquivo do 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/FILE"
          }
        ]
      },
      "tags": {
        "items": []
      },
      "machineType": "zones/us-central1-a/machineTypes/e2-medium",
      "name": "example-instance"
    }
    

    Windows

    Com a ferramenta de linha de comando gcloud, crie uma instância usando as sinalizações --scopes e --metadata e especifique a chave windows-startup-script-url. A sinalização --scopes permite que a VM 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/FILE.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 é executado em todas as reinicializações subsequentes.

Conclua as instruções a seguir 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 à qual você quer adicionar um script de inicialização.

  3. Na página de detalhes da instância, conclua estas etapas:

    1. Clique no botão Editar.
    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 ao arquivo de script de inicialização.

gcloud

Com a ferramenta de linha de comando gcloud, use o comando 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 ao 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 instances().setMetadata fornecendo os novos metadados e um valor fingerprint.

Uma impressão digital é uma string aleatória de caracteres gerada pelo Compute Engine que é 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 acessar a impressão digital atual de uma instância, execute uma solicitação instances().get:

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

Em seguida, copie o valor da impressão digital:

{

 ...
 "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 fornecer diretamente o conteúdo do script de inicialização.
  • startup-script-url: use essa chave para fornecer um URL do Cloud Storage ao 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 Debian, CentOS e RHEL

sudo google_metadata_script_runner startup

GCEMetadataScripts: Starting startup scripts (version YYMMDD.NN).
GCEMetadataScripts: Found startup-script in metadata.
GCEMetadataScripts: startup-script exit status 0
GCEMetadataScripts: Finished running startup scripts.

Nas imagens de SO otimizado para contêineres, Ubuntu e SLES

sudo google_metadata_script_runner --script-type startup --debug

Como visualizar registros de script de inicialização

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

Também é possível usar o comando journalctl para ver a saída do script de inicialização.

sudo journalctl -u google-startup-scripts.service

Definir valores personalizados em scripts de inicialização

Quando você executa scripts de inicialização em instâncias, pode haver situações em que se quer usar valores personalizados no script de inicialização. 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.

É possível especificar esses valores personalizados como pares de chave-valor de metadados no momento da criação da instância e fazer referência a eles nos scripts de inicialização. Para mais informações sobre como criar chaves de metadados personalizadas, consulte Como configurar metadados personalizados.

Depois de criar 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 update
apt -y install 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

Solução de problemas

Conectividade de rede com o servidor de metadados

  • Especificamente para VMs do Linux, o Compute Engine aguarda uma conexão com o servidor de metadados antes de tentar receber informações do servidor de metadados, como um script de inicialização ou desligamento personalizado. Se o servidor de metadados não estiver respondendo ou a rede ainda não estiver configurada, a VM não concluirá a inicialização.

  • Especificamente para VMs do Linux com imagens anteriores à v20160606, a saída da porta serial mostra "Waiting for metadata server, attempt N", em que N é o número de tentativas feitas.

    Esse problema pode durar até sete minutos devido a um problema temporário de rede resolvido por conta própria. Se o problema não se resolver depois de sete minutos, recrie a instância de VM.

A seguir